Diff v1 → v2

- ---
- slug: agentic-feature-workflow
- title: "The Agentic-Feature Workflow"
- category: practice
- ---
- 
  # The Agentic-Feature Workflow
  
- The [[Spec-Driven Workflow]] as prose is a sequence a human runs by hand: `specify`, then `clarify`, then `plan`, then `tasks`, then a review — five separate invocations, five copy-pastes, five chances to drift. This is that same pipeline collapsed into **one runnable artifact**: a background workflow that fans out, routes itself by model tier, and returns a single approval packet. It plans; it never edits the repo. It stops at the human gate.
+ The [[Spec-Driven Workflow]] as prose is a sequence a human runs by hand: `/speckit.specify`, then `/speckit.clarify`, then `/speckit.plan`, then `/speckit.tasks`, then a review — five separate invocations, five copy-pastes, five chances to drift. This is that same pipeline collapsed into **one runnable artifact**: a background workflow that fans out, routes itself by model tier, and returns a single approval packet. It plans; it never edits the repo. It stops at the human gate.
  
  It is the planning engine that runs autonomously *between* the human gates — the practical answer to "what does spec-driven actually look like when you wire it up".
  
  ## What it produces
  
  One call in, one packet out:
  
  ```
  Workflow({ name: "agentic-feature", args: "<one-paragraph feature description>" })
  ```
  
  Returns `{ verdict, packet_markdown, spec, clarify, plan, tasks, review }`. The `packet_markdown` is the human-readable artifact: spec + open questions + plan + tier-tagged waved tasks + an adversarial readiness review with a PASS/FAIL verdict. Nothing is written to the repo. The human reads the packet, answers the open questions, and approves before a single line is implemented.
  
  ## The five stages
  
  ```mermaid
  flowchart TD
      F[Feature description] --> S[Specify · Opus]
      S --> C[Clarify · Opus]
      C --> P{Plan · Opus, parallel}
      P --> P1[research]
      P --> P2[data-model]
      P --> P3[contracts]
      P --> P4[quickstart]
      P --> P5[risks]
      P1 & P2 & P3 & P4 & P5 --> T[Tasks · Opus or Sonnet]
      T --> R[Review · Opus, adversarial]
      R --> G[/Human gate/]
      G -.approve.-> I[Implementation: separate, supervised]
  ```
  
  | # | Stage | Model | Output |
  |---|-------|-------|--------|
  | 1 | **Specify** | Opus | Structured, tech-agnostic spec: priority-ordered scenarios, testable FRs, measurable success criteria, edge cases, entities. No HOW. |
  | 2 | **Clarify** | Opus | ≤5 open questions ranked by impact × uncertainty, each with a recommended answer. *Not auto-answered* — they go to the human. |
  | 3 | **Plan** | Opus (parallel) | Five artifacts fanned out at once: `research` · `data-model` · `contracts` · `quickstart` · `risks`/constitution-check. |
  | 4 | **Tasks** | Opus *or* Sonnet | Dependency-ordered, `@haiku`/`@sonnet`/`@opus`-tagged, waved tasks with pre-fetch context hints. |
- | 5 | **Review** | Opus (adversarial) | Five-dimension readiness check + task-tiering audit. Verdict PASS iff zero BLOCKER. |
+ | 5 | **Review** | Opus (adversarial) | Readiness check across the [[Trust but Verify]] dimensions + task-tiering audit. Verdict PASS iff zero BLOCKER. |
  
  ## Three details that make it work
  
  **Structured output, not prose.** Each stage is forced to emit a JSON schema — the spec has `functional_requirements` and `clarification_markers`; tasks carry `tier`, `wave`, `deps`, `context_hint`. The model retries on a schema mismatch at the tool layer, so the orchestrator never parses freeform text. The shape *is* the contract between stages.
  
  **The tasks tier routes itself.** Decomposition is usually fine on Sonnet — but getting the decomposition *right* is itself a judgment call, so the workflow escalates to Opus when the feature is complex:
  
  ```js
  const complexDecomposition =
    spec.functional_requirements.length > 6 ||
    spec.key_entities.length > 5 ||
    spec.edge_cases.length > 6 ||
    /security|isolation|auth|concurren|race|migrat|crypto|tenant|permission|rollback|distributed/
      .test(`${risksText} ${spec.summary.toLowerCase()}`)
  const tasksTier = complexDecomposition ? 'opus' : 'sonnet'
  ```
  
  A security-heavy, cross-cutting, or many-entity slice decomposes on Opus; a straightforward one stays cheap on Sonnet. This is [[Model Routing: Haiku, Sonnet, Opus]] applied to the *planner itself*, not just the executors — push work down the tree, but only as far down as it stays correct.
  
  **The reviewer is adversarial and runs before code.** The fifth stage is prompted to find what is *missing*, not validate what is present — a different lens than the planners, by design (see [[Trust but Verify]]). It audits five dimensions — spec-divergence, missing-coverage, security, correctness, contract-risk — *and* re-checks the task tiering (demote `@opus` trivia, escalate cross-file `@sonnet`). The verdict is PASS only with zero BLOCKER findings. Catching a gap here, at the sketch, costs ~1/10 of catching it in the diff.
  
  ## Why it stops
  
  The workflow does not implement. That is the whole point. It encodes the non-negotiable that the human holds intent and approves every spec and plan — so the engine plans autonomously, then hands a reviewable packet back and waits.
  
  After approval, implementation is a *separate, human-supervised* step: an Opus manager dispatches the `@tier`-tagged tasks to Sonnet/Haiku sub-agents (with the `context_hint`s pre-fetched — see [[Subagents and Context Injection]]), then an Opus reviewer verifies the diff, and the run feeds a retrospective (see [[The Compounding Layer]]).
  
  > The workflow plans; it never writes code. Specs are the source of truth; code is a build artifact of the spec.
  
  This is the same loop as the [[Spec-Driven Workflow]] — only it runs in the background and arrives as one packet instead of five prompts.
  
  ## Get the source
  
  The complete, runnable workflow is published verbatim so others (and AI agents) can fetch and adapt it:
  
  - **Workflow script** — [`agentic-feature/agentic-feature.js`](agentic-feature/agentic-feature.js)
  - **Skill definition** — [`agentic-feature/SKILL.md`](agentic-feature/SKILL.md)
  
  Drop `agentic-feature.js` into `.claude/workflows/` and `SKILL.md` into `.claude/skills/agentic-feature/` in any Spec-Kit-style repo, then invoke it with a feature description as `args`. It is self-contained — no project-specific paths — so it ports across repos unchanged.