aid-methodology: Instructions file for Codex

AGENTS.md

Project Overview

(pending discovery)

Tracking discipline (IMPERATIVE)

Every project, task, and deliverable is tracked in a state file — the work's .aid/works/work-NNN-*/STATE.md (plus .aid/knowledge/STATE.md for knowledge-base and cross-phase process state). Keeping it current is not optional:

• ANY and ALL changes to the state of a project, task, or deliverable — status, phase, grade, review outcome, or artifacts produced — MUST be written to the proper tracking file IMMEDIATELY, as part of the same action that made the change. Untracked work is incomplete work.
• This binds EVERY agent, without exception — whether invoked by a SKILL or by a DIRECT PROMPT, and whether on the FULL or the LITE path.
• If no tracking file exists for the work yet, create it first (from the work-state template) before doing anything else.
• Task execution is the sharpest case of this rule. During /aid-execute, a task's State MUST be written the instant it changes — In Progress at the start of EXECUTE, In Review before the reviewer is dispatched, and a terminal value (Done / Failed) at the end (Blocked is a distinct, orchestrator-assigned value for a DIFFERENT, downstream task that depends on a failed one — never self-written by the task being executed). This binds whoever executes the task — the main/orchestrator agent executing it DIRECTLY (not only a dispatched sub-agent) MUST perform these writes itself, at the same points, with no exception and no bypass. A task that sits at Pending in the dashboard for its entire execution and then jumps straight to Done is exactly the failure mode this rule exists to prevent.
• Work folders are transient. .aid/works/work-NNN-*/ holds disposable per-work pipeline state and may be pruned once the work ships. No permanent artifact — product code, canonical/ content (or its profiles/ render), tests, docs, the Knowledge Base, or these context files — may depend on the contents of a specific work folder: tests build their own fixtures, and the KB never cites a work folder as a source. Pipeline skills/scripts that create, read, or update work folders as live runtime state are exempt.
• Never name a work in the Knowledge Base. .aid/knowledge/** must contain no work id and no work-folder path — not work-042, not .aid/works/work-042-*/, not "specified by work-042" or "added in work-042" — in prose, tables, headings, or frontmatter. Two reasons, each sufficient: a work folder is pruned when its work ships, so the cite is a dangling pointer by design; and the KB states only the current state of the project's sources, whereas which work produced a change is history. Cite the durable artifact the work left on disk instead. It follows that a KB doc carries no ## Change Log / ## Revision History section and no changelog: frontmatter field — git records per-doc history with author, date, and diff, at higher fidelity and without drift. This binds .aid/knowledge/ alone: skills, templates, and pipeline scripts name works legitimately, because they operate on them.