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.

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

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]

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:

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_hints 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
• Skill definition — 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.