Spec-Driven Loop

Turn an uncertain software request into an approved specification, a controlled implementation, and evidence-backed acceptance. Keep project documents in the repository's established location; otherwise use docs/spec-driven/<feature-slug>/.

When to Use

Use this skill for new products, medium-to-large features, cross-module changes, or requests that need PRD/technical design, active clarification, multi-agent execution, or a main-agent judge. Do not use it for a small single-file change, a tiny bug fix, code explanation, review-only or diagnostic work, pure research, or a simple task whose specification is already complete.

Quick Example

$spec-driven-loop Build a multi-tenant job dashboard with role-based access and evidence-backed acceptance.

Limitations

• Not intended for small isolated edits, review-only work, diagnosis, or pure research.
• Does not replace environment-specific testing or grant authorization for unrelated changes or external actions.
• Production implementation cannot start until the user explicitly approves the frozen specification and acceptance contract.

Follow repository instructions and authorization boundaries throughout. Match generated project documents to the user's language or the repository's existing documentation language; keep identifiers such as FR-001 and AC-001 stable.

Operating Invariants

• Facts are the agent's responsibility. Decisions belong to the user.
• Investigate discoverable facts before asking questions. Ask only for real product decisions or consequential technical tradeoffs.
• Never write or modify production code until the user explicitly approves the specification, scope, and acceptance contract for implementation.
• Never disguise uncertainty. Mark it TBD, ASSUMPTION, or BLOCKED.
• A subagent's completion report is evidence, not acceptance. The main agent owns integration and the final judgment.
• Freeze shared interfaces, data structures, and public types before parallel work. Assign non-overlapping file ownership; serialize overlapping work.
• Update the durable documents after every decision or implementation loop. A chat transcript is not the source of truth.
• If implementation reveals a requirement change rather than a code defect, stop affected work, revise the specification, obtain renewed user approval, and then resume.
• Preserve the user's authorization scope. A specification approval authorizes the approved implementation, not unrelated changes or external actions.

The requirements-grilling stage is informed by Matt Pocock's MIT-licensed grill-me / grilling decision-tree and frontier method.

Document Boundaries

Keep each fact in one authoritative document and reference its stable ID elsewhere:

• PRD.md: why and what the product must do; owns scope, user behavior, business rules, assumptions, and product decisions.
• TECH_DESIGN.md: how the approved product behavior will work; owns architecture, contracts, data, operations, security, and technical decisions.
• ACCEPTANCE.md: observable proof that frozen requirements are met; owns pass/fail criteria and required evidence.
• AGENT_PLAN.md: who performs approved implementation work; owns dependencies, file ownership, validation, and agent task contracts.
• LOOP.md: current recoverable execution state and append-only loop history; owns attempts, evidence, judgments, rework, risks, and next action.

Read references/document-templates.md when creating or updating these five documents. Read references/agent-and-judge-contracts.md before assigning implementation tasks, integrating agent work, judging acceptance, or issuing rework.

1. Inspect the Current System

Before asking the user questions:

1. Read applicable AGENTS.md, project instructions, existing specifications, and repository conventions.
2. Inspect the relevant architecture, modules, interfaces, database, tests, deployment method, and code conventions.
3. Identify established domain terms and documentation locations.
4. Resolve facts from code, files, tools, and documentation. Record findings and sources in the draft rather than asking the user to rediscover them.
5. Separate product choices from technical choices and note decision dependencies.

…