Spec-Driven Development

Spec-Driven Development (SDD) is a methodology for structured collaboration between developers and coding agents (Claude Code, Cursor, Gemini CLI, and others). Polycrate provides the infrastructure: a standard .specs/ layout, a machine-readable spec format with ID-based lifecycle management, and CLI commands for every phase. Teams can also keep a reference architecture in .specs/ARCHITECTURE.md (editable directly, not a spec document) — see Reference architecture.

After status=done comes the git-free release chain (workspace/block release, push, pull, action install): Develop and deploy. A Git tag and workspace sync are not the product process.

Why Spec-Driven Development?

Without SDD, AI-assisted workflows typically fail in these ways:

• Coding agents write code without documented context — nobody remembers why it was implemented that way
• Releases are hard to reconstruct — which changes belong to which version?
• Agents edit files directly and corrupt structures that machines must read
• There is no shared backlog between human and agent — work exists only in chat

SDD solves this with a defined process:

Concepts

Specs

A spec is a structured Markdown document that follows a change, bugfix, or feature from idea to implementation. Every spec has:

• A unique ID (integer, never reused)
• A status (draft, done, cancelled)
• A type (Conventional Commits: feat, fix, breaking, …)
• Structured sections: Context, Solution, Affected Files, Acceptance Criteria, Migration, Open Questions, Review, and more
• Optional labels for filtering
• Optional dependencies (needs) on other specs
• Optional thematic links (relates-to) — non-blocking

Specs live in .specs/.next/ (backlog) or .specs/<version>/ (assigned to a release).

Live scan (no index.yml)

From CLI ≥ 0.45.0 there is no index.yml. Specs and releases are read live from disk — folder location is state:

ID, status, type, labels, needs, and other metadata live in each spec's YAML frontmatter. polycrate spec list and related commands derive everything from that.

Reference architecture (.specs/ARCHITECTURE.md)

.specs/ARCHITECTURE.md is not a spec document and is not live-scanned. It is a recommended (should-have) reference architecture: modules, boundaries, data flows, pointers to code — kept incrementally.

Two lifecycle phases

WORK PHASE                            RELEASE PHASE
polycrate spec *                      polycrate release *
draft ↔ done                          .specs/<version>/

Language

Write spec content in the project's primary language. Keep one language per spec.

Spec scope

One problem or feature per spec. If you write "and also…", create a separate spec.

Spec lifecycle

draft ↔ done
  → cancelled (any state, set cancellation_reason)

polycrate spec update <id> --set status=done works from any status. spec review / spec verify are informative. Open Questions should be empty before status=done — that is a conversation soft-stop, not a CLI gate.

polycrate spec create --name "Login timeout" --type fix
polycrate spec update 0 --section context="..."
polycrate spec update 0 --section solution="..."
polycrate spec update 0 --set status=done

Available sections: context, solution, affected-files, acceptance-criteria, migration, open-questions, review.

Acceptance criteria

Each criterion should be verifiable and carry a code anchor (@path:LINE) where the implementation lives. Self-review findings use [minor|major|blocker].

Spec types

fix | perf | feat | refactor | chore | docs | ci | build | style | test | breaking | analysis

Family A (fix, perf, analysis): Context + analysis. Family B (features): Context + solution. Family C (breaking): Migration is required.

Labels

polycrate spec update 15 --add-label sdd --add-label agent
polycrate spec list --label sdd
polycrate spec list --blocked

Quickstart

polycrate spec init
polycrate spec create --name "Login Timeout Fix" --type fix
polycrate spec note "S3 upload fails silently on 403" --type fix --label s3
polycrate spec update 0 --section context="..."
polycrate spec update 0 --section solution="..."
polycrate spec inspect 0
polycrate spec lint 0
polycrate spec review 0
polycrate spec verify 0
polycrate spec update 0 --set status=done
polycrate spec list --format json

Code references in comments

The stable reference is the spec ID, not the file path:

// Spec: polycrate spec inspect 5     ← CORRECT (stable after release)
// Spec: .specs/.next/5-feature.md    ← WRONG (path changes on release)

Release lifecycle

polycrate release diff 1.0.0
polycrate release create 1.0.0 --spec 0 --spec 1
polycrate release create 1.0.1
polycrate release update 1.0.0 --set type=feat --set message="..."
polycrate release update 1.0.0 --note-section highlights="..."
polycrate release status 1.0.0
polycrate release finalize 1.0.0
polycrate block push <block>
polycrate block pull <registry/org/name:version>
polycrate run <block> install

--workspace / -w must be an absolute path. workspace sync is not a release step. Canonical chain: Develop and deploy.

Release notes (RELEASENOTE.md)

Each release has a structured RELEASENOTE.md in .specs/<version>/. highlights is required for finalize.

Validation

polycrate spec validate

Checks paths, frontmatter, sections, and dependencies. .specs/ARCHITECTURE.md is not a spec. Errors always include the fix command.

Agent integration

polycrate spec init and polycrate spec rules generate write instruction files:

polycrate spec manual --no-pager -w /path/to/workspace
polycrate spec rules show --no-pager -w /path/to/workspace
polycrate spec list --format json -w /path/to/workspace
polycrate spec rules generate --force

Existing CLAUDE.md / AGENTS.md with user content are not overwritten, even with --force.

Recovery

polycrate spec validate
polycrate spec lint <id>
polycrate spec format <id>

Legacy repos with index.yml:

polycrate spec index migrate
polycrate spec lifecycle migrate-v2

Sandbox and runtime directory

SDD commands start no full workspace — no Docker, no container.

polycrate spec list --runtime-dir /tmp/polycrate-run -w /path/to/project

→ CLI reference — runtime directory

Typical workflow

Developer: spec init → spec create → fill Context/Solution/Review → implement → spec verify → status=done → release create / update / finalize → block push / pull / install.

Multi-agent workflow

Each session works on exactly one spec. Parallelize only when specs have no needs links and disjoint code areas.

All commands

polycrate spec

polycrate release

See also

• Develop and deploy (git-free)
• CLI reference
• Workspaces
• Git integration
• Best practices