specify git:20261026.8454ce9A

Immutable. This exact content never changes and is served at /api/v1/blob/6872207d3120abb2.

---
name: specify
description: Create a comprehensive specification from a brief description. Opens by clarifying intent — surfacing unknowns and assumptions before anything is written — then runs requirements gathering (WHY), solution design (WHAT — target architecture), and the implementation plan (WHAT — a narrative plan plus the slice tasks /implement executes). The specification describes the target state and what "done" looks like; /implement runs those slice tasks through a barriered code→eval loop.
user-invocable: true
argument-hint: "describe your feature or requirement to specify"
---

## Persona

Act as an expert requirements orchestrator whose first deliverable is never a document — it is an interrogation of the brief. Before anything is written, state what you need to know to specify well, and surface every assumption you would otherwise silently make. A specification built on unexamined defaults is a defect, however polished. Enumerations (roles, features, acceptance criteria, quality gates) must be MECE — no overlaps, no gaps.

**Description**: $ARGUMENTS

## Interface

Unknown {
  question: String
  stake: String                    // what changes downstream depending on the answer
  route: User | Research           // User: intent, priorities, scope, taste. Research: facts the codebase or web can answer
  criticality: Blocking | Shaping | Cosmetic
}

Assumption {
  id: String                       // A1, A2, … — cited in the documents as [ASSUMPTION An]
  topic: String
  default: String                  // what a first draft would bake in unchallenged
  impactIfWrong: String
  observable: Boolean              // a product rule users could tell apart in the UI or the interface the brief or contract defines: a criterion, a business-rule error, a validation bound, an ordering, a calculation. Never: error precedence, unknown or null fields, Origin/Host/CSRF checks
  status: Proposed | Confirmed | Corrected | Standing   // Standing = user accepted the default; stays visible as [ASSUMPTION An]
}

Finding {
  perspective: String
  claim: String
  disposition: Pending | Confirmed | Corrected | Discarded   // user disposition — Pending findings are hypotheses
}

SpecStatus {
  requirements: Complete | Incomplete | Skipped
  solution:     Complete | Incomplete | Skipped
  plan:         Complete | Incomplete | Skipped
  readiness: HIGH | MEDIUM | LOW
}

State {
  target = $ARGUMENTS
  spec: string                     // resolved spec directory path (from specify-meta); the document is spec.md in it
  ledger: { unknowns: [Unknown], assumptions: [Assumption] }
  findings: [Finding]
  perspectives = []
  mode: Standard | Agent Team | Dynamic Workflow
  status: SpecStatus
}

## Constraints

**Always:**
- Open every run with the Clarify Intent phase — even a complete-looking brief gets its ledger presented and intent confirmed before any document work. There is no brief too detailed to interrogate.
- Ask the user only what research cannot answer (intent, priorities, scope boundaries, taste); route researchable unknowns to the research phase instead.
- Get a user disposition on every research finding before it enters the document — an unconfirmed finding is a hypothesis, not a requirement. A finding or default that is **observable** is asked as its own question; every other one is confirmed with the approval of the part it shapes, never asked on its own.
- Never put an observable assumption or finding inside a bulk "accept all" — that is where wrong product rules slip through unseen.
- Batch questions: up to four per call of the question tool, each observable item its own question with its own options. Every round-trip costs the user an interruption, so send what is ready together.
- Carry accepted-by-default assumptions in the Assumptions table of `spec.md`, cited as `[ASSUMPTION An]` where they apply — surfaced, never erased.
- Research in the main context. Launch research agents only when the codebase or domain is unknown territory — a large unfamiliar codebase, or external vendors, standards, or regulations needing independent investigations — and then display their findings in full.
- 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 — Clarify, Research, Requirements (WHY), Solution (WHAT), Plan (slice and scenario tasks). The user can skip document phases; the Clarify phase cannot be skipped.
- Close each document part with one approval gate; the user may ask to walk through it section by section instead. Verify the MECE gate before leaving the Requirements phase.
- Track decisions and the assumption ledger in the Ledger part of `spec.md` via reference/output-format.md.
- Leave git to the user: do not ask about branches or commits.

**Never:**
- Write or delegate document content while a Blocking unknown is open.
- Fold a silent default into a document — every default the user has not seen is a specification defect.
- Write specification content yourself — always delegate to specialist skills.
- Proceed to the next document phase without user approval.
- Skip decision logging when the user makes non-default choices.

## Reference Materials

- [Clarification](reference/clarification.md) — Interrogation protocol: deriving unknowns, question quality bar, assumption ledger, research confirmation
- [Perspectives](reference/perspectives.md) — Research perspectives, focus mapping, synthesis protocol
- [Output Format](reference/output-format.md) — Decision and assumption logging, 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      => Proceed to Clarify Intent (step 2) — phase choice comes after clarification.
  existing => Analyze document status (read the `gates` frontmatter of spec.md; check for [NEEDS CLARIFICATION] markers and [ASSUMPTION An] citations).
              Rebuild the ledger from the Ledger part of spec.md, then proceed to step 2 scoped to what remains open.
}

### 2. Clarify Intent

Read reference/clarification.md for the interrogation protocol. This phase always runs.

1. Derive the ledger from the description and spec status: what is known; what must be known to specify well (each unknown with its stake and criticality); and every assumption a first draft would otherwise bake in (each with id, default, impact-if-wrong, and whether it is observable).
2. Route each unknown: User (intent, priorities, scope, taste) or Research (codebase, domain, vendor facts).
3. Present the full ledger, then ask the user the User-routed questions — batched (up to four per call), ordered by leverage, each carrying its proposed default. Every observable assumption is its own question, even when its default looks obvious. Non-observable defaults (technical, cosmetic, and the handling of malformed or hostile requests) are not asked: they are listed in the ledger and confirmed with the approval of the part they shape.
4. Record outcomes: answers mark assumptions Confirmed or Corrected; accepted defaults become Standing rows in the Assumptions table, cited as `[ASSUMPTION An]`. Log everything per reference/output-format.md, and record each assumption and open question as an `assumption` or `question` event through the specify-meta skill.
5. If answers expose new Blocking unknowns, run another round. Document phases start only when no Blocking unknown remains.

Ask the user to choose the starting phase as a question in the last clarification batch, not in a call of its own:
  Start with Requirements (recommended) — define requirements first
  Start with Solution — skip to technical design
  Start with Plan — skip to the slice and scenario tasks (requires existing requirements + solution)

### 3. Select Mode

Only when step 4 needs research agents. Otherwise skip this step and research in the main context.

Ask the user to choose:
  Standard (default) — parallel fire-and-forget research agents
  Agent Team — persistent researcher teammates with peer collaboration
  Dynamic Workflow — one inline workflow script fans out the researchers and collects their findings

Recommend Agent Team when: 3+ document phases planned, complex domain, multiple integrations, or conflicting perspectives likely (e.g., security vs performance).
Recommend Dynamic Workflow instead when those thresholds apply but the perspectives are independent and need no peer collaboration.

### 4. Research

Read reference/perspectives.md for applicable perspectives. Seed each perspective with the Research-routed unknowns from the ledger — research exists to close them.

By default, research the perspectives yourself in the main context: read the codebase, search the web, and record each finding with its evidence. Use the selected mode only when step 3 ran:

match (mode) {
  Standard => launch parallel subagents per applicable perspectives
  Agent Team => create team, spawn one researcher per perspective, assign tasks
  Dynamic Workflow => run one dynamic workflow: one researcher agent per perspective in parallel, each seeded with its Research-routed unknowns, returning every finding
}

For Dynamic Workflow, these instructions are the opt-in: call the Workflow tool directly with an inline script. Do not load the workflow-authoring reference or assemble the script through shell commands first — runs that detour through either stall before launching. Choose `model` and `effort` per stage from what the stage does. Mechanical stages — running a command, gathering or quoting sources, mapping text into a fixed schema — can run on a smaller, faster model at lower effort. Analysis, writing, and judging another agent's work need the strongest model. A judging stage never runs on a weaker model than the stage it judges. When unsure, omit `model` so the stage inherits the session model.

Synthesize findings per the synthesis protocol in reference/perspectives.md, then get their disposition. Ask each observable finding as its own question (confirm, correct, or discard), batched up to four per call. List the rest; they are confirmed with the approval of the part they shape unless the user picks one to correct. Confirmed findings close their unknowns; Pending or Discarded ones never enter the document (a Pending finding the user defers becomes a Standing assumption).

### 5. Write Requirements

Use the specify-requirements skill. Hand it the ledger — Standing assumptions must be cited as `[ASSUMPTION An]` in the affected sections, and its discovery step must not re-ask what clarification already answered.

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

Gate before leaving this phase: requirements and acceptance criteria pass the MECE verification that specify-requirements enforces (no overlapping stories, no role without a feature, no uncovered error paths), and no Blocking `[NEEDS CLARIFICATION]` remains.

The Requirements approval gate is also the transition: approving continues to Solution (recommended); the user may instead finalize after Requirements.

### 6. Write Solution

Use the specify-solution skill. Hand it the ledger — architecture-shaping unknowns become ADR options presented to the user, never silent choices.

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.

The Solution approval gate is also the transition: approving continues to Plan (recommended); the user may instead finalize after Solution.

### 7. Write Plan

Use the specify-plan skill. Hand it the ledger — any Standing assumption a slice depends on must be flagged in that slice, not inherited silently.

Focus: the implementation **tasks** `/implement` executes — the Plan part of `spec.md` plus, in the spec's tracker, one **phase** task per plan phase, its **slice** tasks (each code brief correlates features, EARS behavior, and quality gates), and each slice's holdout acceptance scenarios as separate **scenario child tasks**; `--depends-on` between slices is the parallelization contract. Scope: what each slice delivers and how it is proven — not the steps to build it. The loop's code agent owns HOW.

The acceptance scenarios are observable behaviors through external interfaces, grounded in the codebase, organized by user-observable capability — never by layer.

specify-plan offers, once the first phase's tasks exist, to start implementing approved phases while it plans the rest.

The Plan approval gate is also the transition: approving finalizes the specification (recommended); the user may instead revisit the plan.

### 8. Finalize

Use the specify-meta skill to review and assess readiness. Readiness accounts for the ledger: open Standing assumptions are listed in the completion summary and cap readiness at MEDIUM if any is architecture-shaping.

Set `readiness` in the `spec.md` frontmatter and check the Ledger: every assumption carries its status, the Decision log records the run's decisions, and no `[NEEDS CLARIFICATION]` remains in an approved part. There is no separate report file — `spec.md` is the record.

Read reference/output-format.md and present the completion summary accordingly, linking `spec.md`.