aid-specify

Technical Specification — Conversational Refinement

Specify the technical implementation of a single feature through conversational refinement with the user.

The agent is a tech lead, not an interviewer. It proposes concrete solutions grounded in the existing architecture. The user validates, redirects, or deepens the discussion.

One feature at a time. The feature path is a required argument.

The Loop:

Every section follows the same cycle:

1. PROPOSE  → agent proposes (grounded in KB, codebase, SPEC)
2. DISCUSS  → user and agent refine together
3. WRITE    → save what was agreed into REQUIREMENTS.md §11 / Feature NNN
4. REVIEW   → grade what was written against KB/codebase reality
             → pass? next section. fail? back to 1.

Re-run = enter at step 4 with existing content.

Workspace:

.aid/
  knowledge/               ← shared KB
  work-NNN-{name}/
    STATE.yml              ← process (features sequence, qa sequence)
    REQUIREMENTS.md        ← product: §11 Features holds one section per
                              feature (decomposition from /aid-define +
                              Technical Specification from here). Features have
                              no folders and no files of their own.

Accuracy note. Features State is AUTHORED, and it now has a real target: the features: sequence in work-state-template.yml, one entry per feature, created by /aid-define at decomposition and updated here as each feature advances. It carried no key and was documented as a read-only DERIVED view for as long as this note said so, which was wrong twice over -- nothing derives it, and the mislabel made the STATE.md -> STATE.yml converter treat a real row as proof that a work predated the per-unit hierarchy, so it refused every work that had been through /aid-define. Cross-phase Q&A's qa key is AUTHORED only at the delivery level (delivery-state-template.yml) or, on the flattened Lite path, at the work level (work-state-template.yml) -- a full-path work has no qa key at the work level at all (full-layout omission rule), and /aid-specify runs before any delivery exists (Specify precedes Plan), so a full-path work has no delivery yet to hold one either -- that half of the gap is unchanged and is still a candidate follow-up. The Features State half is closed: write features[] entries for real.