Spec-Driven Development

Spec-Driven Development mit Polycrate: Specs planen, implementieren, dokumentieren und versionieren. Kanonischer Flow für Workspace- und Block-Releases, exakte Gate-Tabelle, Agent-Integration.

Spec-Driven Development (SDD) ist der Prozess, mit dem Änderungen an Polycrate-Workspaces und Blocks geplant, umgesetzt, dokumentiert und versioniert werden. Polycrate liefert dafür ein standardisiertes .specs/-Layout, ein maschinenlesbares Spec-Format mit ID-basiertem Lifecycle und die CLI-Commands polycrate spec * und polycrate release *. SDD ist für die Zusammenarbeit mit Coding Agents (Cursor, Claude Code, Codex, …) ausgelegt, funktioniert aber genauso ohne.

Diese Seite beschreibt genau das, was die CLI prüft — nicht mehr. Die Single Source of Truth ist polycrate spec manual (Sektion CANONICAL FLOW); diese Seite, die generierte .cursor/rules/sdd.mdc und Entwickeln und deployen spiegeln sie.

Warum Spec-Driven Development?

Der kanonische Flow

Es gibt genau einen Flow. Alles Weitere auf dieser Seite erklärt seine Bausteine.

A. Workspace-Änderung (Spec → Release)

W=/abs/pfad/zum/workspace   # -w muss absolut sein — oder weglassen, wenn cwd der Workspace ist

# 1. Planen — ein Problem oder Feature pro Spec
polycrate spec create --name "Hub-Token rotieren" --type feat -w $W
#    → .specs/.next/<id>-<slug>.md, status: draft (IDs beginnen bei 1)

# 2. Schreiben — Sektionskörper direkt editieren (nur H3+) oder per Flag
polycrate spec update <id> --section-file solution=/tmp/.polycrate/spec-sections/spec-<id>-solution.md -w $W

# 3. Struktur prüfen — Drift blockiert jede Status- und Release-Operation
polycrate spec lint <id> -w $W      # melden
polycrate spec format <id> -w $W    # reparieren, Inhalte bleiben erhalten

# 4. Implementieren. Informative Checks (blockieren nie):
polycrate spec verify <id> -w $W    # Acceptance-Checkboxen + @pfad:ZEILE-Anker
polycrate spec review <id> --no-pager -w $W

# 5. Abschließen — Open Questions MÜSSEN leer sein (in Solution/Context auflösen, nicht löschen)
polycrate spec update <id> --set status=done -w $W

# 6. Release — Specs optional; ein reiner Versions-Bump mit Release Note ist gültig
polycrate release create 1.4.0 --spec <id> -w $W
polycrate release update 1.4.0 --set type=feat --set message="Hub-Token-Rotation" \
  --changelog-item "Feature: Hub-Token werden automatisch rotiert" \
  --note-section highlights="- Hub-Token-Rotation ohne Downtime" -w $W
polycrate release status 1.4.0 --no-pager -w $W   # zeigt, was finalize prüfen wird

# 7. Finalisieren — setzt workspace.poly version, führt pre_actions/post_actions aus. Kein Git.
polycrate release finalize 1.4.0 -w $W

B. Block-Änderung (Blocks haben keine Specs)

Blocks tragen kein .specs/-Verzeichnis. Ein Block-Release besteht aus dem CHANGELOG.poly-Eintrag, der block.poly-Version und dem Registry-Tag.

• Logikänderung im Block → eine Workspace-Spec im Repository, das den Block hostet, mit Label block:<name>. Ihr Lifecycle ist A.1–A.5.
• Reiner Versions-Bump (Dependency, Image-Tag, kein Verhaltensunterschied) → keine Spec; der Changelog-Eintrag dokumentiert ihn.

# 0. Nur bei Logikänderung: Spec im Host-Workspace, Label setzen
polycrate spec update <id> --add-label block:hardening -w $W

# 1. Changelog-Eintrag (idempotent; legt den Eintrag an, falls er fehlt)
polycrate release --block hardening update 0.5.6 --set type=fix \
  --set message="Konfigurierbare OpenSSH PerSourcePenalties" \
  --changelog-item "Fix: exempt list für PerSourcePenalties" \
  [--set app_version=A.B.C] -w $W

# 2. Finalisieren — setzt block.poly version, validiert, pusht in die Registry (idempotent)
polycrate release block-finalize hardening 0.5.6 [--app-version A.B.C] [--no-push] -w $W

# 3. Downstream konsumieren — schreibt from: auf jede Instanz dieses Blocks im Workspace
polycrate block pull cargo.ayedo.cloud/ayedo/linux/hardening:0.5.6 -w /abs/pfad/zum/downstream-workspace
polycrate run hardening install -w /abs/pfad/zum/downstream-workspace

release --block <name> create, spec --block, release --block update --spec und --note-section* mit --block existieren nicht mehr und brechen mit einem Hinweis auf diesen Flow ab.

C. Gates — was tatsächlich fehlschlägt (Exit ≠ 0)

--force ist eine auditierte Notbremse (--force-reason Pflicht, Protokoll in .specs/.force-audit.log): bei status=done umgeht sie Drift und Open Questions; bei release finalize umgeht sie nur highlights — message, Drift und Open Questions zugewiesener Specs bleiben hart.

Keine Gates (Warnung oder stumm): Ergebnisse von spec verify, fehlendes spec review, unerfüllte needs:, 0 Specs an einem Release, der Git-Zustand (Dirty Tree, vorhandenes Tag, ungepushte Commits).

D. Git ist kein Prozessschritt

Ob ein Workspace oder Block released werden kann, hängt nicht vom Zustand eines Git-Repositories ab. release finalize erzeugt kein Tag und keinen Commit; nichts prüft den Working Tree. Released heißt: CHANGELOG.poly-Eintrag + Versionsdatei (workspace.poly/block.poly) bzw. Registry-Tag (Block). Agents führen git commit/tag/push/stash/reset oder polycrate workspace sync nie als Spec- oder Release-Schritt aus. Wer Git-Historie will, committet selbst — siehe Git-Integration.

Konzepte

Specs

Eine Spec ist ein Markdown-Dokument mit YAML-Frontmatter, das eine Änderung von der Idee bis zur Implementierung begleitet:

• ID — ganzzahlig, stabil, nie wiederverwendet; polycrate spec inspect <id> findet sie unabhängig vom Speicherort
• Status — draft, done, cancelled
• Typ — Conventional Commits: fix perf feat refactor chore docs ci build style test breaking analysis
• Sektionen — festes Schema (siehe unten)
• Labels — frei, z. B. block:<name>
• needs / relates-to — Abhängigkeiten (Warnung bei done, kein Gate) bzw. thematische Links

Ordnerposition ist der Zustand

Es gibt kein index.yml. Specs und Releases werden live aus dem Dateisystem gelesen:

mein-workspace/
├── .specs/
│   ├── ARCHITECTURE.md     # Referenzarchitektur — frei editierbar
│   ├── .rules.md           # Projektregeln für Agents — von spec init geschrieben, repo-lokal erweiterbar
│   ├── .invariants.md      # Harte, prüfbare Repo-Regeln — eine pro Zeile
│   ├── .next/
│   │   ├── 7-hub-token-rotieren.md
│   │   └── 8-login-timeout.md
│   └── 1.4.0/
│       ├── RELEASENOTE.md
│       └── 5-s3-bucket-provisioning.md
├── .cursor/rules/sdd.mdc   # generiert: polycrate spec rules generate
├── blocks/<name>/          # block.poly + CHANGELOG.poly — kein .specs/
├── workspace.poly
└── CHANGELOG.poly

Was direkt editiert werden darf

Nach direkten Body-Edits polycrate spec lint <id> ausführen; spec format repariert Drift und erhält die Inhalte.

Sektionsschema

Innerhalb der Sektionen sind nur H3 (###) und tiefer erlaubt; H1/H2 werden beim Schreiben abgelehnt, weil H2 die Sektionsgrenze ist.

.specs/.rules.md und .specs/.invariants.md

• .rules.md — Prozessregeln in Prosa. polycrate spec init --force schreibt den aktuellen Default neu (Specs bleiben unberührt); repo-lokale Zusätze als eigene ##-Sektion anhängen und nach dem Neuschreiben wieder ergänzen.
• .invariants.md — eine harte, prüfbare Regel pro Zeile (max. 25). Steht im generierten sdd.mdc an erster Stelle: Verstöße sind Bugs, keine Konventionsfragen.

# Repo invariants — my-project
- LANG: all user-facing output in English
- DB: use ORM only; no raw SQL
- SDD: in .specs/ only section bodies and ARCHITECTURE.md are hand-editable
- SDD: git is not a process step — never commit/tag/stash/reset/sync as part of spec or release work
- SDD: blocks have no .specs/ — block-related specs live in the workspace with label block:<name>

Referenzarchitektur (.specs/ARCHITECTURE.md)

Kein Spec-Dokument, wird nicht gescannt, frei editierbar. Empfohlen als kompaktes, lebendes Architekturdokument (Überschriften, Tabellen, Code-Verweise). polycrate spec arch list|search <query>|show <slug> liefert gezielt einzelne Abschnitte — Agents lesen vor dem Planen nur die relevanten.

Spec-Lifecycle

draft ◄──────────────► done      Gates: kein Drift, Open Questions leer
  └──────────┬──────────┘
         cancelled                jederzeit, kein Gate (cancellation_reason setzen)

polycrate spec update 7 --set status=done
polycrate spec update 7 --set status=draft                       # wieder öffnen
polycrate spec update 7 --set status=cancelled --set cancellation_reason="Ersetzt durch Spec 9"

• spec list blendet cancelled standardmäßig aus (--all zeigt sie); spec validate und release diff ignorieren sie.
• Deprecated Statusnamen werden beim Lesen gemappt: planned/pending-approval/approved/pending-verification/in-progress/ready → draft, implemented → done.
• spec submit / spec finalize sind deprecated Aliase für --set status=done.

Open Questions — das eine Workflow-Gate

Eine offene Frage ist eine fehlende Entscheidung. Damit ein Agent sie nicht still „während der Implementierung“ trifft, verweigert die CLI status=done, solange ## Open Questions Text enthält (HTML-Kommentare zählen als leer). Beantwortete Fragen gehören in solution/context — die Sektion wird aufgelöst, nicht geleert.

● spec 7: Open Questions is not empty — resolve or clear the section before status=done

Abhängigkeiten und Links

polycrate spec link 5 --needs 3 --needs 4      # 5 setzt 3 und 4 voraus — Warnung bei done, kein Gate
polycrate spec link 5 --relates-to 8           # thematischer Link, ohne Wirkung auf den Lifecycle
polycrate spec update 5 --remove-needs 3
polycrate spec list --blocked                  # Specs mit nicht-done needs

Selbstreferenzen und Zyklen werden abgelehnt.

Informative Checks

Quick-Capture

polycrate spec note "S3-Upload schlägt bei 403 still fehl" --type fix --label s3
# → draft-Spec sofort angelegt, ID zurückgegeben, aktueller Task geht weiter

Überblick

polycrate spec list                               # kompakte Tabelle / TUI
polycrate spec list --open                        # nicht done, nicht cancelled
polycrate spec list --version .next --status done # Backlog: fertig, aber ohne Release
polycrate spec list --label block:hardening
polycrate spec list --format json                 # Feld heißt "version" (leer = Backlog), nicht "release"
polycrate spec inspect 7 --section solution

Release-Lifecycle

Workspace-Release

polycrate release diff 1.4.0                        # Vorschau: welche Specs sind done und unzugewiesen?
polycrate release create 1.4.0 --spec 7 --spec 8    # verschiebt die Dateien nach .specs/1.4.0/, scaffoldet RELEASENOTE.md
polycrate release create 1.4.0 --spec-status done   # Bulk: alle done-Specs aus .next/
polycrate release create 1.4.1                      # ohne Specs — reiner Bump

polycrate release update 1.4.0 --set type=feat --set message="Kurzfassung" \
  --changelog-item "Feature: …" --changelog-item "Fix: …" \
  --set docs_url=https://ayedo.de/docs/polycrate/releases/
polycrate release update 1.4.0 --note-section highlights="- …" --note-section-file changes=/tmp/.polycrate/spec-sections/changes.md

polycrate release status 1.4.0 --no-pager           # Guards, Warnungen, Checkliste
polycrate release finalize 1.4.0                    # Version setzen, pre_actions → post_actions

release finalize setzt workspace.poly → version, führt die in workspace.poly unter config.release.pre_actions / post_actions konfigurierten Actions aus (z. B. Build, Image-Push, Hub-Upload) und schreibt nichts nach Git. Schlägt eine pre_action fehl, stoppt finalize — auch mit --force.

Release Notes (RELEASENOTE.md)

polycrate release note status 1.4.0
polycrate release note inspect 1.4.0 --section highlights

Auch hier: nur H3 und tiefer innerhalb der Sektionen.

Block-Release

Siehe Flow B. Zwei Versionen in block.poly, beide CLI-only:

Erneutes block-finalize mit gleichem Stand ist ein sicherer No-Op: existiert das Tag in der Registry, wird der Push übersprungen und der Zustand bestätigt (--force pusht erneut).

polycrate release --block hardening status 0.5.6 --no-pager   # Changelog, Versionsdatei, Registry-Tag

Validierung und Recovery

polycrate spec validate                 # alle Specs: Frontmatter, Sektionen, needs, Migration bei breaking
polycrate release validate 1.4.0        # Specs im Verzeichnis done, Changelog-Eintrag, Versionsdatei
polycrate spec format <id>              # Drift reparieren
polycrate spec force-audit              # alle --force-Nutzungen

Legacy-Repos mit index.yml und 5-Status-Lifecycle: einmalig polycrate spec index migrate, dann polycrate spec lifecycle migrate-v2.

Agent-Integration

Polycrate generiert genau eine Agent-Datei: .cursor/rules/sdd.mdc. Sie enthält die Invariants, die absoluten Regeln, den kanonischen Flow mit Gate-Liste, die Key Commands und den Inhalt von .specs/.rules.md. AGENTS.md, CLAUDE.md oder andere IDE-Dateien werden nicht geschrieben.

polycrate spec init -w $W                     # legt .specs/ und .specs/.rules.md an (einmalig)
polycrate spec init --force -w $W             # schreibt nur .rules.md auf den aktuellen Default neu
polycrate spec rules generate --force -w $W   # schreibt .cursor/rules/sdd.mdc
polycrate spec rules show --no-pager -w $W    # zeigt .specs/.rules.md

Beides nach jedem CLI-Upgrade in jedem Repo mit .specs/ ausführen. Repo-lokale Prozessregeln gehören in .specs/.rules.md, prüfbare Konventionen in .specs/.invariants.md; fachliche Coding-Standards bleiben in eigenen .cursor/rules/*.mdc. Für IDEs ohne Cursor-Rules reicht polycrate spec manual --no-pager als Einstieg.

Session-Start

polycrate spec manual --no-pager -w $W        # einmal pro Session, nicht pro Turn
polycrate spec list --open --format tsv -w $W
polycrate spec arch list -w $W                # dann search/show für die berührten Themen

Agent-Disziplin

Multi-Agent

Vier Rollen pro Spec, sequenziell: Grounding (spec arch), Author (spec create/update, spec lint), Reviewer (spec review), Verifier (spec verify --with-agent). Specs ohne offene needs sind unabhängig und können parallel bearbeitet werden; spec list --version .next zeigt [BLOCKED] für wartende Specs.

Sandbox und Runtime-Verzeichnis

polycrate spec * und polycrate release * starten keinen Container. In eingeschränkten Umgebungen:

polycrate spec list --runtime-dir /tmp/polycrate-run -w $W

Alle Commands im Überblick

polycrate spec

polycrate release

Siehe auch

• Entwickeln und deployen — der Flow als Prozesskarte inkl. MCP-Ops
• MCP Server — die sechs Tool-Familien für Agents
• CLI-Referenz
• Blöcke · Workspaces
• Git-Integration — optional, kein Teil des Prozesses