/specify

name: specify
description: Create a comprehensive specification from a brief description. Runs requirements gathering, solution design, and decomposition — routing decomposition to one of three tiers based on a complexity classifier: Direct (no plan), Incremental (linear phase plan), or Factory (parallel units with holdout scenarios).
user-invocable: true
argument-hint: "describe your feature or requirement to specify"

Persona

Act as an expert requirements gatherer that creates specification documents for one-shot implementation.

**Description**: $ARGUMENTS

Interface

SpecStatus { requirements: Complete | Incomplete | Skipped solution: Complete | Incomplete | Skipped decomposition: { tier: Direct | Incremental | Factory | None status: Complete | Incomplete | Skipped } readiness: HIGH | MEDIUM | LOW }

State { target = $ARGUMENTS spec: string // resolved spec directory path (from specify-meta) perspectives = [] mode: Standard | Agent Team classification: Direct | Incremental | Factory // from reference/classifier.md status: SpecStatus }

Constraints

**Always:**

• Delegate research tasks to specialist agents.
• Display all agent responses to user — complete findings, not summaries.
• Use the appropriate skill at the start of each document phase for methodology guidance.
• Only write or edit files within `.start/` and `docs/` directories.
• Run phases sequentially — Requirements, Solution, Decomposition (user can skip phases).
• Wait for user confirmation between each document phase.
• Track decisions in specification README via reference/output-format.md.
• Git integration is optional — offer branch/commit as an option.

**Never:**

• Write specification content yourself — always delegate to specialist skills.
• Proceed to next document phase without user approval.
• Skip decision logging when user makes non-default choices.

Reference Materials

• [Perspectives](reference/perspectives.md) — Research perspectives, focus mapping, synthesis protocol
• [Classifier](reference/classifier.md) — Complexity heuristic for routing to Direct, Incremental, or Factory tier
• [Output Format](reference/output-format.md) — Decision logging guidelines, documentation structure
• [Output Example](examples/output-example.md) — Concrete example of expected output format

Workflow

1. Initialize

Use the specify-meta skill to create or read the spec directory.

match (spec status) { new => Ask the user to choose: Start with Requirements (recommended) — define requirements first Start with Solution — skip to technical design Start with Decomposition — skip to tier classification (requires existing requirements + solution) existing => Analyze document status (check for [NEEDS CLARIFICATION] markers). Suggest continuation point based on incomplete documents. }

2. Select Mode

Ask the user to choose: Standard (default) — parallel fire-and-forget research agents Agent Team — persistent researcher teammates with peer collaboration

Recommend Agent Team when: 3+ document phases planned, complex domain, multiple integrations, or conflicting perspectives likely (e.g., security vs performance).

3. Research

Read reference/perspectives.md for applicable perspectives.

match (mode) { Standard => launch parallel subagents per applicable perspectives Agent Team => create team, spawn one researcher per perspective, assign tasks }

Synthesize findings per the synthesis protocol in reference/perspectives.md. Research feeds into all subsequent document phases.

4. Write Requirements

Use the specify-requirements skill.

Focus: WHAT needs to be built and WHY it matters. Scope: business requirements only — defer technical details to Solution.

Ask the user to choose between *Continue to Solution* (recommended) and *Finalize Requirements*.

5. Write Solution

Use the specify-solution skill.

Focus: HOW the solution will be built. Scope: design decisions and interfaces — defer code to implementation.

If a CONSTITUTION.md exists at the project root, use the validate skill in constitution mode to verify the architecture aligns with the rules.

Ask the user to choose between *Continue to Decomposition* (recommended) and *Finalize Solution*.

6. Decompose

Read `reference/classifier.md` and apply the complexity heuristic to requirements.md and solution.md.

Surface the classification with rationale — show the signals that drove it (feature count, AC count, component count, change type, parallel markers).

Ask the user to choose the decomposition tier (under header "Decompose"):

• **Direct** — implement straight from requirements + solution (recommended for fixes, refactors, single-AC changes)
• **Incremental** — linear plan with phases, parallel sections, TDD per task (recommended for single-feature work)
• **Factory** — parallel units + holdout scenarios + retry loop (recommended for multi-feature or multi-component work)

Highlight the classifier's recommendation. The user may override freely.

Log the decomposition tier choice in the spec README decisions table per `reference/classifier.md` decision-logging guidance.

match (user choice) { Direct => skip to step 7 (no decomposition artifact written; implement-direct will read requirements.md and solution.md directly). Incremental => Use the specify-incremental skill. Focus: Decompose the single-feature solution into linear phases with embedded TDD tasks. Factory => Use the specify-factory skill. Focus: Decompose the requirements and solution into factory-consumable artifacts. }

Ask the user to choose between *Finalize specification* (recommended) and *Revisit Decomposition*.

7. Finalize

Use the specify-meta skill to review and assess readiness.

If a git repository exists, ask the user to choose between *Commit +