Agentic SDD Playbook

A public playbook and starter kit for running coding agents through a Spec-Driven Development workflow with phase boundaries, durable artifacts, quality gates, and adversarial review.

This repository is intentionally generic. It shows the architecture and operating model without assuming a specific company, codebase, product domain, deployment platform, or private engineering process.

Why This Exists

Coding agents are most useful when they are not asked to hold every concern in one long conversation. This workflow keeps the main thread thin and delegates bounded work to phase-specific agents:

• Explore the code before proposing changes.
• Write specs before designing implementation.
• Convert design into small tasks before coding.
• Challenge the implementation before verifying it.
• Archive artifacts so future work can recover context.

Workflow

flowchart LR
  Explore[sdd-explore<br/>read-only analysis] --> Propose[sdd-propose<br/>scope and intent]
  Propose --> Spec[sdd-spec<br/>behavioral requirements]
  Propose --> Design[sdd-design<br/>technical plan]
  Spec --> Tasks[sdd-tasks<br/>implementation checklist]
  Design --> Tasks
  Tasks --> Apply[sdd-apply<br/>code changes]
  Apply --> Simplify[sdd-simplify<br/>behavior-preserving cleanup]
  Simplify --> Challenge[sdd-challenge<br/>adversarial review]
  Challenge --> Verify[sdd-verify<br/>evidence against specs]
  Verify --> Archive[sdd-archive<br/>persist final state]

Loading

The important separation is challenge vs. verify:

• challenge asks: "How could this fail?"
• verify asks: "Does this meet the written specs with evidence?"

Keeping those phases separate reduces confirmation bias.

Repository Map

docs/                 Explanation of the architecture and workflow
starter-kit/          Generic agents, skills, and artifact templates
examples/             Neutral examples that show the workflow end-to-end
assets/diagrams/      Optional rendered diagrams

Quick Start

1. Read docs/workflow.md.
2. Copy starter-kit/ into your own private project or agent configuration repo.
3. Replace placeholders such as {PROJECT_NAME}, {TEST_COMMAND}, and {PROJECT_STANDARDS}.
4. Add your project-specific standards privately. Do not put sensitive rules, product details, credentials, or internal paths in a public fork.
5. Try the flow on a small bugfix before using it for a larger feature.

What To Adapt

The starter kit is a pattern, not a universal drop-in package. Adapt:

• Artifact root, for example openspec/changes/{change-name}/.
• Test command and lint command.
• Project standards injected into phase agents.
• Model assignments and tool names for your agent runtime.
• Review bars for correctness, security, performance, and maintainability.

What Not To Publish

See docs/sanitization.md. In short, keep private:

• Company names and private repository names.
• Real business workflows and customer concepts.
• Internal paths, infrastructure, vendors, credentials, and deployment commands.
• Project-specific compliance or operational policies.

Starter Kit Contents

• starter-kit/agents/ contains generic agent role definitions.
• starter-kit/skills/ contains reusable phase instructions.
• starter-kit/templates/ contains artifact templates.

Example Flows

• examples/generic-feature: a neutral feature planning example.
• examples/bugfix-flow: a smaller fix-oriented example.

License

MIT. Use it, adapt it, and keep your project-specific material private.