Feature Definition from Approved Requirements

Agents Involved

aid-define is multi-agent — different states use different agents.

State	Phase	Agent	Why
5 FEATURE-DECOMPOSITION	Feature Decomposition	aid-architect	Design work — breaking requirements into structured features
6 CROSS-REFERENCE	Cross-Reference & Refine	aid-reviewer	Adversarial validation against KB and codebase
7 DONE	DONE	(no dispatch)	Terminal state, user choice prompt

Decompose approved REQUIREMENTS.md into ### Feature NNN sections under § 11, then cross-reference the result against the Knowledge Base and codebase. Produces REQUIREMENTS.md §11 feature sections ready for /aid-specify.

Precondition: ## Interview State: Approved must be present in .aid/works/{work}/STATE.md. If requirements are not yet approved, run /aid-describe {work} first to gather and approve requirements.

Workspace structure:

.aid/
  knowledge/           <- shared KB (populated by /aid-discover)
  work-001-name/
    STATE.md           <- process (Interview State: Approved, Cross-Reference, Features State)
    REQUIREMENTS.md    <- approved requirements (/aid-describe) + §11 Features
                          (this skill) + each feature's Technical Specification
                          (/aid-specify). Features are sections; they have no
                          folders and no files of their own.

State keys. interview.state/interview.grade/interview.sections[] and features[] are real keys in work-state-template.yml -- this skill creates one features[] entry per ### Feature NNN section it appends to REQUIREMENTS.md § 11, and /aid-specify updates it as each feature advances. A per-feature "Cross-Reference" status and a Q&A-adjacent "Review History" list, as used below, do still carry no dedicated key -- they describe this skill's aspirational tracking design rather than a writable structure, and that remains an open schema gap. The Review History list now has a real target of its own, the review_history sequence, and Cross-phase Q&A entries have the qa sequence.

First run (after approval): Decompose functional requirements into REQUIREMENTS.md §11 feature sections. After cross-reference: DONE — ready for /aid-specify. Re-run decomposition: pass --features {work} to re-run even if features exist.

⚠️ Pre-flight Checks

Check 1: Verify Workspace Exists

Check if .aid/ directory exists. If it doesn't:

⚠️ AID workspace not found. Run /aid-config first to set up the project.

Exit. Do not proceed.

Check 2: Verify Not in Plan Mode

• ✅ Default or Auto-accept edits → Proceed.
• ❌ Plan mode → STOP. Tell the user to switch out of Plan Mode.

Arguments

Argument	Effect
work-NNN	Work on the specified work item.
--features work-NNN	Re-run feature decomposition for this work even if features exist.
(no argument)	Select from existing approved works (see Task Routing).

---

Task Routing

When no work ID is provided, resolve the Approved candidate set in two layers — a cross-worktree candidate set (the same source the other downstream skills use), refined by an interview.state: Approved sub-filter this skill alone needs, because the enumerate record carries no Interview-State field.

Layer 1 — cross-worktree candidate set

Enumerate works cross-worktree: run bash .aid/runtime/scripts/works/enumerate-works.sh (main tree + every git worktree; never the local .aid/works/ glob, which is empty on master), taking each record's field-1 work_id and field-4 branch_label.

Zero records on any worktree → STOP.

No approved works found. Run /aid-describe first to gather and approve requirements.

Exit.

Layer 2 — per-candidate Approved sub-filter (read-only git show)

For each (work_id, branch_label) candidate from Layer 1, determine Approved without entering any worktree:

• branch_label is the literal (detached) (a detached-HEAD worktree — not a resolvable git ref): skip the git show check for this candidate and retain it in the menu rather than drop it. Its Approved status is deferred to the authoritative post-enter ## State Detection step 2 below, which HALTs if the entered work turns out not to be Approved. Never pass a (detached) label to git show.
• Otherwise, run a read-only git show "<branch_label>:.aid/works/<work_id>/STATE.md" and check whether its ## Interview State section shows Approved:
  • Shows Approved → retain the candidate.
  • Does not show Approved (including "file not found at that ref") → drop the candidate from the menu.
• De-duplicate by work_id when the same work appears on more than one branch_label.

This git show reads the committed view only — best-effort, and it can skew in either direction against a live worktree's uncommitted STATE.md:

• False positive (committed shows Approved, a live worktree has since regressed it): the candidate is retained here; ## State Detection step 2 (post-enter, over the live file) HALTs on the non-Approved value — fail-closed, this can never route into a non-Approved work.
• False negative (a live worktree holds Approved uncommitted, the committed tip still shows pre-Approved): this pre-filter cannot see it, so the work is silently absent from the auto-generated menu below — a menu-completeness gap, not a correctness defect. Documented fallback: invoke /aid-define work-NNN directly. The argument path bypasses Task Routing (and this filter) entirely — see "Locate + Enter the Work's Worktree" below — so ## State Detection step 2 confirms Approved from the live, entered STATE.md.

No candidates survive Layer 2

No approved works found. Run /aid-describe first to gather and approve requirements.

Exit.

One or more candidates survive Layer 2

Approved works ready for feature definition:
  work-001-user-auth   [3 features, cross-reference pending]
  work-002-reporting   [no features yet]

[1] Continue work-001-user-auth
[2] Continue work-002-reporting

Wait for response and proceed to State Detection for that work.

Shortcut: If only one candidate survives Layer 2, go directly to it without asking.

---

Locate + Enter the Work's Worktree

As soon as <work-id> is known — from the work-NNN argument, or from Task Routing above — and before State Detection reads .aid/works/{work}/STATE.md, follow .aid/runtime/templates/downstream-worktree-entry.md to normalize <work-id> to its bare work-NNN branch name, locate the worktree (which always exits 0 and returns <path>\t<status>), and enter the returned path. Keep the defensive empty-path/non-zero backstop that stops rather than operate blindly — it should not fire against the real helper. Never create a new worktree — creation belongs to the work-starting skills only.

---

State Detection

State detection reads the files on disk, every run. Nothing remembered from an earlier run or from this conversation counts as state, because the files may have changed since.

All paths below are relative to .aid/works/{work}/.

Precondition: Interview State: Approved in STATE.md -- HALT if not met (see below)
State 5:  **Path:** full, Interview State: Approved,
          no § 11 feature sections                                 -> FEATURE-DECOMPOSITION
State 6:  **Path:** full, Interview State: Approved, features exist,
          cross-reference not yet done                             -> CROSS-REFERENCE
State 7:  **Path:** full, Interview State: Approved, features +
          cross-ref already complete                               -> DONE

Detection logic:

1. Read STATE.md ## Interview State **Interview State:** field.
2. If field is absent or value is NOT Approved:
   • Print: [aid-define] Requirements for {work} are not yet approved. Run /aid-describe {work} first to gather and approve requirements.
   • HALT
3. If State is Approved:
   • If --features flag provided → State 5: FEATURE-DECOMPOSITION
   • Check if REQUIREMENTS.md § 11 Features exists and contains ### Feature NNN subsections
   • If no feature sections → State 5: FEATURE-DECOMPOSITION
   • If feature sections exist:
     • Check STATE.md ## Interview State ## Cross-Reference sub-section for **State:** Complete (or check if cross-reference entries exist from a prior run)
     • If cross-reference not yet done → State 6: CROSS-REFERENCE
     • If cross-reference already complete → State 7: DONE

Print the state-entry line and "you are here" map. Examples for each state:

FEATURE-DECOMPOSITION:

[State: FEATURE-DECOMPOSITION] — Decompose approved requirements into § 11 feature sections.
aid-define  ▸ you are here
  (from /aid-describe: COMPLETION -> approved REQUIREMENTS)
  [● FEATURE-DECOMPOSITION ] → [ CROSS-REFERENCE ] → [ DONE ] → [ /aid-specify ]

CROSS-REFERENCE:

[State: CROSS-REFERENCE] — Validate REQUIREMENTS.md against KB and codebase; create Q&A for gaps.
aid-define  ▸ you are here
  [✓ FEATURE-DECOMPOSITION ] → [● CROSS-REFERENCE ] → [ DONE ] → [ /aid-specify ]

DONE:

[State: DONE] — Interview complete, approved, decomposed, and cross-referenced.
aid-define  ▸ you are here
  [✓ FEATURE-DECOMPOSITION ] → [✓ CROSS-REFERENCE ] → [● DONE ] → [ /aid-specify ]

---

Dispatch

State	Detail	Worker	Advance
FEATURE-DECOMPOSITION	references/state-feature-decomposition.md	aid-architect	→ CROSS-REFERENCE
CROSS-REFERENCE	references/state-cross-reference.md	aid-reviewer	→ DONE
DONE	references/state-done.md	inline	→ halt

On state entry, print [State: NAME] + the "you are here" map from State Detection above. When a state completes, route by its **Advance:** type (per state-machine-chaining.md):

• CHAIN → begin the next state's reference doc within the same invocation; no exit.
• HALT → print the closing summary and exit.