Spec-Driven Development¶

Spec-Driven Development (SDD) ist eine Entwicklungsmethodik für die strukturierte Zusammenarbeit zwischen Entwicklern und Coding Agents (Claude Code, Cursor, Gemini CLI, etc.). Polycrate stellt die technische Infrastruktur bereit: ein standardisiertes .specs/-Verzeichnis-Layout, ein maschinenlesbares Spec-Format mit ID-basiertem Lifecycle-Management sowie vollständige CLI-Commands für alle Phasen. Optional pflegen Teams zusätzlich eine Referenzarchitektur in .specs/ARCHITECTURE.md (direkt editierbar, nicht index-getrieben) — siehe Referenzarchitektur.

Warum Spec-Driven Development?¶

Ohne SDD entstehen in AI-gestützten Entwicklungsworkflows typische Probleme:

• Coding Agents schreiben Code ohne dokumentierten Kontext — niemand weiß mehr, warum etwas so implementiert wurde
• Releases sind schwer nachvollziehbar — welche Änderungen gehören zu welcher Version?
• Agents bearbeiten Dateien direkt und korrumpieren dabei Strukturen, die Maschinen lesen müssen
• Kein gemeinsames "Backlog" zwischen Mensch und Agent — Aufgaben existieren nur im Chat-Kontext

SDD löst diese Probleme durch einen definierten Prozess:

Konzepte¶

Specs¶

Eine Spec ist ein strukturiertes Markdown-Dokument, das eine Änderung, einen Bugfix oder ein Feature von der Idee bis zur Implementierung begleitet. Jede Spec hat:

• Eine eindeutige ID (ganzzahlig, nie wiederverwendet)
• Einen Status (draft, approved, done, cancelled)
• Einen Typ (Conventional Commits: feat, fix, breaking, …)
• Strukturierte Sektionen: Context, Solution, Affected Files, Acceptance Criteria, Migration, Open Questions, Review und weitere (siehe Sektionsschema)
• Optionale Labels für Filterung und Grouping
• Optionale Abhängigkeiten (needs) zu anderen Specs — blockierend
• Optionale thematische Links (relates-to) — nicht blockierend

Specs liegen in .specs/.next/ (Backlog) oder .specs/<version>/ (einem Release zugewiesen).

Index¶

Die Datei .specs/index.yml ist die einzige Quelle der Wahrheit für alle Specs. Sie enthält ID, Name, Status, Typ, Labels, Needs, Datei-Pfad und Version jeder Spec sowie den next_id-Counter.

Referenzarchitektur (.specs/ARCHITECTURE.md)¶

Die Datei .specs/ARCHITECTURE.md ist kein Spec-Dokument und nicht in index.yml eingetragen. Sie dient als empfohlene (should-have, nicht Pflicht für Finalize oder Release) Referenzarchitektur der verwalteten Software: Module, Grenzen, Datenflüsse, Verweise auf Code-Pfade — fortlaufend und inkrementell gepflegt.

Zwei Lifecycle-Phasen¶

ARBEITSPHASE                          RELEASE-PHASE
polycrate spec *                      polycrate release *
────────────────────────────          ────────────────────────────────────
Tage bis Wochen                       Minuten, nach abgeschlossener Arbeit

Specs erstellen, ausarbeiten,         Specs einer Version zuweisen
einreichen, reviewen,                 CHANGELOG.poly schreiben
implementieren, verifizieren          Release Notes (RELEASENOTE.md) füllen
"Was machen wir, und warum?"          workspace.poly version setzen
                                      Git-Tag erstellen
                                      "Dokumentation, dass etwas fertig ist"

Verzeichnisstruktur¶

my-workspace/
├── .specs/
│   ├── index.yml           # Einzige Quelle der Wahrheit (nie direkt bearbeiten!)
│   ├── ARCHITECTURE.md     # Referenzarchitektur (optional, direkt editierbar)
│   ├── .rules.md           # Projekt-spezifische Regeln für Agents (optional)
│   ├── .next/              # Backlog — noch keiner Version zugewiesen
│   │   ├── 0-login-timeout-fix.md
│   │   └── 1-api-integration.md
│   ├── 1.0.0/              # Released
│   │   └── 2-initial-setup.md
│   └── 1.1.0/              # In Vorbereitung
│       └── 3-neue-funktion.md
├── workspace.poly
└── CHANGELOG.poly

.specs/.rules.md¶

Optionale Datei mit projektspezifischen Regeln für Agents in Prosaform. Wird von polycrate spec rules show ausgegeben und in die generierten Agent-Rules-Dateien integriert.

# Projekt-Regeln

## Sprache
Alle Specs auf Deutsch verfassen.

## Spec-Scope
Jede Spec deckt genau ein Problem ab.

.specs/.invariants.md¶

Optionale Datei mit maschinenlesbaren Kerninvarianten für das Projekt. Eine Invariante pro Zeile, max. 25 Zeilen. Wird als eigener INVARIANTS-Block in die generierten Agent-Rules-Dateien eingebettet — immer an erster Stelle, damit Agents sie als nicht verhandelbare Regeln interpretieren.

# Repo invariants — my-project
# One hard, checkable rule per line. Keep it short (max 25 lines).

- LANG: all user-facing output in English
- DB: use ORM only; no raw SQL
- SDD: never edit .specs/ except ARCHITECTURE.md

Der Unterschied zu .rules.md: Invarianten sind kurz, präzise, prüfbar — keine Prosa. Agents kennen den Unterschied: Invarianten-Verstöße sind Bugs, .rules.md-Regeln sind Konventionen.

Spec-Lifecycle¶

Status-Übergänge¶

draft ──► approved ──► done
  │                      │
  └──────────────────────┤
                         │
                   cancelled (jederzeit)

Cancelled Specs¶

Wenn ein Feature abgelehnt oder durch eine andere Spec ersetzt wird, kann es nicht-destruktiv archiviert werden:

polycrate spec update <id> --set status=cancelled --set cancellation_reason="Replaced by spec #18"

• spec list blendet cancelled per Default aus; --all zeigt alle inkl. cancelled
• spec validate ignoriert cancelled Specs
• release diff ignoriert cancelled Specs

Abhängigkeiten (needs) und thematische Links (relates-to)¶

Needs sind blockierende Abhängigkeiten. Der Übergang zu done wird verhindert, solange Abhängigkeiten nicht done sind:

# Spec 5 kann erst auf done gesetzt werden, wenn Specs 3 und 4 done sind
polycrate spec link 5 --needs 3 --needs 4

# Äquivalent via spec update
polycrate spec update 5 --add-needs 3 --add-needs 4

# Abhängigkeit entfernen
polycrate spec update 5 --remove-needs 3

spec list zeigt [BLOCKED] wenn mindestens eine needs-Spec nicht implemented ist.

Validierung: Das System verhindert self-references und Zirkularitäten — direkte wie transitive.

Relates-to sind nicht-blockierende thematische Verknüpfungen. Sie dokumentieren Zusammenhänge, ohne den Lifecycle zu beeinflussen:

# Spec 5 ist thematisch verwandt mit Spec 8
polycrate spec link 5 --relates-to 8

# Äquivalent via spec update
polycrate spec update 5 --add-relates-to 8

# Link entfernen
polycrate spec update 5 --remove-relates-to 8

Gates: Qualitätssicherung durch die CLI¶

polycrate erzwingt beim Einreichen und Abschließen von Specs mehrere Gates — automatische Prüfpunkte, die sicherstellen, dass Specs ausreichend dokumentiert und verifiziert sind. Gates können nicht durch Weglassen umgangen werden; sie müssen explizit erfüllt oder mit --force (protokolliert, siehe Force-Audit) überbrückt werden.

Grounding Gate — spec submit¶

Beim spec submit prüft das Grounding Gate, ob die Spec ausreichend im Codebase verankert ist:

• Affected Files: Mindestens ein Pfad in ## Affected Files muss im Repository existieren
• Anchors: ## Context und ## Solution müssen mindestens einen @path/to/file:LINE-Anker enthalten — oder eine Architektur-Referenz auf .specs/ARCHITECTURE.md (oder spezifische Chunk-Dateien)

spec lint gibt diese Prüfungen als nicht-blockierende Hinweise aus — nützlich während der Ausarbeitung.

polycrate spec lint <id>   # zeigt Grounding-Hinweise (informativ, kein Fehler)

Grounding-Opt-out¶

Falls die Spec genuinen Grund hat, keine Code-Referenzen zu enthalten (z. B. reine Dokumentations-Specs):

<!-- no-architecture-reference -->

Dieser Kommentar im Spec-Body deaktiviert den Architektur-Referenz-Check. Er muss im ## Review als [major]-Finding anerkannt werden.

Self-Review Gate — spec submit¶

Bevor spec submit durchläuft, muss ## Review mindestens einen strukturierten Fund enthalten:

Finding 1 [minor|major|blocker] @path/to/file:LINE: Beschreibung
- resolved: yes|no

• Jeder Fund benötigt einen @path:LINE-Anker (oder [no-code] nur für reine Docs-Specs)
• [blocker]-Funde mit resolved: no blockieren den Submit
• Pauschalaussagen wie „alles OK" werden abgelehnt

Acceptance Criteria Gate — spec update <id> --set status=done¶

Vor dem Übergang auf done müssen alle strukturierten Akzeptanzkriterien erfüllt sein:

## Acceptance Criteria

- [x] verify:@cmd/spec_verify.go:42 Feature ist implementiert
- [x] verify:@pkg/specdev/acceptance.go:15 Gate greift bei fehlenden Checkboxen
- [ ] Unerfülltes Kriterium — blockiert done

• Nur - [x]-Zeilen mit verify:@path:LINE-Anker zählen als strukturierte Kriterien
• Alle strukturierten Kriterien müssen checked sein
• Alle verify:-Anker müssen auf existierende Dateipfade zeigen
• polycrate spec verify <id> prüft den aktuellen Stand ohne Status-Übergang

polycrate spec verify <id>              # listet Kriterien + Status
polycrate spec verify <id> --format json
polycrate spec verify <id> --with-agent  # generiert strukturierten Prompt für Subagenten

Force-Audit¶

Jede Nutzung von --force (z. B. spec submit --force, release finalize --force) wird protokolliert:

• Eintrag in .specs/.force-audit.log mit Zeitstempel, Command und Pflicht---force-reason
• spec list zeigt [forced]-Badge bei betroffenen Specs
• release status zeigt Anzahl der Force-Bypasses

polycrate spec submit <id> --force --force-reason "Grounding gap akzeptiert: Docs-only Spec"
polycrate spec force-audit              # Audit-Log anzeigen

Coding Agents: Submit, Open Questions und Staging¶

polycrate spec submit prüft u. a., dass die Sektion Open Questions leer ist. Das ist kein Freibrief, die Sektion zu leeren, nur um die Prüfung zu bestehen: Leer heißt „es gibt keine offenen Designfragen mehr“, weil die Antworten in Solution / Context stehen — nicht „wir haben die Fragen gelöscht“.

Für Arbeitsstil (sparsam mit Kontext/Tools, gezielte Edits statt Voll-Rewrites) gelten dieselben Hinweise wie im polycrate spec manual und in den generierten Agent-Rules (polycrate spec rules show).

Spec-Typen¶

Jede Spec hat einen Typ nach Conventional Commits. Der Typ steuert, welche Platzhalter-Hints beim spec create in die ## Context-Sektion geschrieben werden.

polycrate spec create --name "Fix login bug" --type fix
polycrate spec create --name "Add dark mode" --type feat   # Default wenn --type fehlt
polycrate spec create --name "Drop v1 API"   --type breaking
polycrate spec update <id> --set type=refactor

Gültige Typen: fix | perf | feat | refactor | chore | docs | ci | build | style | test | breaking | analysis

Sektionsschema¶

Alle Specs verwenden ein einheitliches Sektionsschema mit der zentralen Sektion ## Context:

Der Typ steuert den Scaffold-Hint in ## Context:

• fix, perf, analysis: „Symptom, analysis steps, confirmed root cause."
• feat, refactor, chore, docs, …: „Background, requirements, scope boundaries."
• breaking: „Background, requirements, why breaking change is necessary." + ## Migration ist Pflicht

Heading-Level-Regel¶

Innerhalb von Spec-Sektionen sind nur H3 (###) und tiefere Überschriften erlaubt. H1 (#) und H2 (##) sind verboten, da H2 als Sektionsgrenze reserviert ist.

• Schreibzeit: Content mit H1/H2 wird von spec update mit einem Error abgelehnt
• Lesezeit: spec inspect gibt eine Warnung auf stderr aus, wenn bestehender Content H1/H2 enthält

# Dies wird abgelehnt:
polycrate spec update 5 --section context="## Bad heading"
# Error: section "Context": line 1 contains H1/H2 heading...

# H3+ ist erlaubt:
polycrate spec update 5 --section context="### Subsection\nContent here"

Labels¶

Labels ermöglichen freies Tagging von Specs für Filterung und Grouping:

# Labels hinzufügen und entfernen
polycrate spec update <id> --add-label sdd --add-label agent
polycrate spec update <id> --remove-label sdd

# Filtern
polycrate spec list --label sdd
polycrate spec list --label sdd --type fix

Quickstart¶

1. SDD initialisieren¶

polycrate spec init

Legt .specs/, index.yml und .specs/.rules.md an. Generiert außerdem Agent-Rules-Dateien im Workspace-Root (siehe Agent-Integration).

2. Spec anlegen¶

# Mit explizitem Typ — steuert den Scaffold-Hint in ## Context
polycrate spec create --name "Login Timeout Fix" --type fix
# → Erstellt .specs/.next/0-login-timeout-fix.md mit Context (Fix-Hints)
# → Registriert in index.yml mit ID 0, Status: draft

polycrate spec create --name "Dark Mode" --type feat
# → Erstellt .specs/.next/1-dark-mode.md mit Context (Feature-Hints)

3. Quick-Capture für neue Observations¶

Wenn während der Implementierung ein neues Problem auffällt — ohne den aktuellen Kontext zu unterbrechen:

polycrate spec note "S3 upload schlägt still fehl bei 403" --type fix --label s3
# → Erstellt draft Spec sofort, gibt ID zurück
# → Weiterarbeiten am aktuellen Task

4. Spec ausarbeiten¶

# Context füllen — inline
polycrate spec update 0 --section context="Nach 30 Minuten Inaktivität werden Nutzer ausgeloggt. SESSION_COOKIE_AGE ist auf 1800s gesetzt."
polycrate spec update 0 --section solution="Erhöhe auf 28800s, aktiviere Sliding-Window."

# Sektionen aus Datei (für längeren Content) — Staging außerhalb .specs/, z. B.:
# mkdir -p /tmp/.polycrate/spec-sections
polycrate spec update 0 --section-file solution=/tmp/.polycrate/spec-sections/spec-0-solution.md

# Sektionen aus Stdin (für Pipes und Scripte)
polycrate spec inspect 0 --section context | process.py | \
  polycrate spec update 0 --section-stdin solution

Verfügbare Sektionen: context, solution, affected-files, acceptance-criteria, migration, open-questions, review

5. Spec lesen¶

polycrate spec inspect 0
polycrate spec inspect 0 --section solution   # Nur eine Sektion

6. Spec einreichen¶

polycrate spec submit 0
# Grounding Gate: affected-files + @path:LINE-Anker vorhanden?
# Self-Review Gate: structured findings mit Ankern im ## Review?
# Open Questions: leer?
# Setzt status: approved

7. Review, Implementierung, Verifikation¶

# Nach Implementierung: Acceptance Criteria prüfen
polycrate spec verify 0              # listet Kriterien + Erfüllungsstatus
polycrate spec verify 0 --with-agent # Prompt-Vorlage für Subagenten generieren

# Wenn alle Kriterien erfüllt: auf done setzen
# (needs-Check: alle Abhängigkeiten müssen done sein)
polycrate spec update 0 --set status=done

# Review-Sektion für Self-Review Gate befüllen (vor submit)
polycrate spec update 0 --section review="Finding 1 [minor] @cmd/main.go:42: ..."

8. Überblick behalten¶

# Kompakte Tabelle (Default)
polycrate spec list

# Filter
polycrate spec list --open             # Nicht done, nicht cancelled
polycrate spec list --status approved
polycrate spec list --status draft --status approved
polycrate spec list --status draft,approved
polycrate spec list --exclude-status done,cancelled
polycrate spec list --label sdd
polycrate spec list --type fix
polycrate spec list --blocked          # Nur Specs mit nicht-done Abhängigkeiten
polycrate spec list --all              # Inkl. cancelled Specs

# Sortierung (Default: id aufsteigend)
polycrate spec list --sort name
polycrate spec list --sort created:desc

# Maschinenlesbar / ohne TUI
polycrate spec list --format json
polycrate spec list --format tsv --columns id,status,name
polycrate spec list --format csv --no-header

# Releases (gleiche Idee für Formate und Sortierung)
polycrate release list --sort version:desc --format tsv

Code-Referenzen in Kommentaren¶

Wenn eine Spec in einem Code-Kommentar referenziert wird, ist die stabile Referenz die Spec-ID, nicht der Dateipfad:

// Spec: polycrate spec inspect 5     ← KORREKT (stabil, funktioniert nach Release)
// Spec: .specs/.next/5-feature.md    ← FALSCH (Pfad ändert sich beim Release)

Der Dateipfad ist ein Implementierungsdetail. polycrate spec inspect <id> funktioniert unabhängig von Status und Speicherort.

Release-Lifecycle¶

Release erstellen¶

# Vorschau: welche Specs sind bereit?
polycrate release diff 1.0.0

# Release erstellen und Specs zuweisen
polycrate release create 1.0.0 --spec 0 --spec 1
# → Verschiebt Spec-Dateien von .next/ nach 1.0.0/
# → Aktualisiert index.yml
# → Erstellt automatisch RELEASENOTE.md (Scaffold)

Changelog und Release Notes schreiben¶

# Changelog-Eintrag
polycrate release update 1.0.0 \
  --set type=feat \
  --set message="Login Timeout Fix + API Integration" \
  --changelog-item "FIX: Session-Timeout auf 8h erhöht, Sliding-Window aktiviert" \
  --changelog-item "FEAT: Neue REST-API Integration für Kundendaten"

# Dokumentations-Link setzen (erscheint als Warning in release status wenn fehlend)
polycrate release update 1.0.0 \
  --set docs_url="https://docs.ayedo.de/polycrate/releases/cli/1.0.0/"

# Release Notes schreiben (RELEASENOTE.md)
polycrate release update 1.0.0 \
  --note-section highlights="Highlights der Version 1.0.0" \
  --note-section changes="Detaillierte Änderungen"

# Release Notes aus Datei
polycrate release update 1.0.0 \
  --note-section-file highlights=/tmp/.polycrate/spec-sections/highlights.md

Release Notes (RELEASENOTE.md)¶

Jedes Release hat eine strukturierte RELEASENOTE.md im Versionsverzeichnis (.specs/<version>/RELEASENOTE.md). Sie wird automatisch beim release create als Scaffold angelegt.

# Release Note Status prüfen
polycrate release note status 1.0.0

# Release Note anzeigen
polycrate release note inspect 1.0.0
polycrate release note inspect 1.0.0 --section highlights

# Release Note manuell erstellen (falls nicht via release create geschehen)
polycrate release note create 1.0.0

Die gleiche Heading-Level-Regel wie für Specs gilt auch für Release Notes: nur H3 und tiefer innerhalb von Sektionen.

Release abschließen¶

Vor release finalize führt Polycrate automatisch Guards durch:

polycrate release status 1.0.0    # Zeigt Warnings und Checklist

polycrate release finalize 1.0.0
# → Setzt workspace.poly version: 1.0.0
# → Erstellt Git-Tag v1.0.0
# → Führt Pre/Post-Actions aus (falls konfiguriert)

# Danach committen und pushen
polycrate workspace sync

Release-Übersicht¶

polycrate release list
polycrate release status 1.0.0

Validation¶

polycrate spec validate

Prüft alle Specs auf Konsistenz (Index, Dateipfade, Sektionen, Abhängigkeiten). .specs/ARCHITECTURE.md ist kein Spec und wird von der Validierung nicht als solches behandelt. Fehlermeldungen sind aktionierbar — sie zeigen immer den Fix-Command:

WARNING: spec 5 [feat]: both 'Context' and 'Solution' are empty
  → Fix: polycrate spec update 5 --section context="Background and requirements."

ERROR: spec 12 [breaking]: 'Migration' section is empty — required for type=breaking
  → Fix: polycrate spec update 12 --section-file migration=/tmp/.polycrate/spec-sections/spec-12-migration.md

ERROR: spec 7 cannot move to done — blocked by:
  #3 "Volume Discovery" [draft]
  → Fix: implement spec #3 first

Agent-Integration¶

SDD ist für die Arbeit mit Coding Agents konzipiert. polycrate spec init und polycrate spec rules generate erzeugen automatisch Instruktionsdateien im Workspace-Root:

Was die Agent-Rules-Dateien enthalten¶

• INVARIANTS-Block (an erster Stelle): maschinenlesbare Kernregeln aus .specs/.invariants.md — Verstöße sind Bugs, nicht Konventionsfragen
• Strikte Regeln für .specs/: Direkte Edits für Spec-Dateien, index.yml und index-getriebenen Release-Zustand sind verboten — dokumentierte Ausnahme: .specs/ARCHITECTURE.md
• Gate-Referenz: Grounding Gate, Self-Review Gate, Acceptance Criteria Gate, Force-Audit
• Agent discipline: Kein vorschnelles spec submit; Open Questions nicht leeren, um das Gate zu umgehen; Staging-Dateien für --section-file unter /tmp/.polycrate/spec-sections/
• Session-Start-Protokoll: Manual lesen, Stand sehen, ARCHITECTURE.md überfliegen
• Vollständige Command-Referenz inkl. spec verify, spec arch, spec lint, spec force-audit, release block-finalize
• Recovery-Commands für Index-Inkonsistenzen
• Projektspezifische Regeln aus .specs/.rules.md
• Versionsheader: Zeigt mit welcher Polycrate-Version die Rules generiert wurden

Agent-Workflow (Session-Start)¶

# 1. Manual lesen (LLM-optimiert)
polycrate spec manual --no-pager -w /path/to/workspace

# 2. Projektspezifische Regeln lesen
polycrate spec rules show --no-pager -w /path/to/workspace

# 3. Aktuellen Stand sehen
polycrate spec list --format json -w /path/to/workspace

# 4. (Empfohlen) Wenn .specs/ARCHITECTURE.md existiert: kurz lesen für Abgleich mit aktueller Arbeit

Agent-Rules aktualisieren¶

# Nach Polycrate-Upgrade (enthält Versionsheader für Erkennung)
polycrate spec rules generate --force

# Vorschau ohne Schreiben
polycrate spec rules show --no-pager

Recovery¶

Wenn der Index durch externe Eingriffe inkonsistent geworden ist (z. B. manuelle Bearbeitung von Spec-Dateien oder fehlgeschlagene Operationen — nicht durch reine Pflege von .specs/ARCHITECTURE.md):

# Index aus Dateisystem neu aufbauen
# Erkennt automatisch Legacy-Formate und vergibt stabile IDs via Dateiname-Hash
polycrate spec index rebuild

# Konsistenz prüfen
polycrate spec validate

Sandbox und Runtime-Verzeichnis¶

SDD-Commands (polycrate spec *, polycrate release *) starten keinen vollständigen Workspace — kein Docker, kein Container. Sie sind leichtgewichtig und funktionieren auch in eingeschränkten Umgebungen.

In Sandbox-Umgebungen (z. B. eingeschränkte Schreibrechte auf HOME):

polycrate spec list --runtime-dir /tmp/polycrate-run -w /pfad/zum/projekt

→ Details: CLI-Referenz — Runtime-Verzeichnis

Typischer Workflow (Gesamtübersicht)¶

sequenceDiagram
    participant Dev as Entwickler
    participant CLI as polycrate spec
    participant Agent as Coding Agent
    participant Rel as polycrate release

    Dev->>CLI: spec init
    CLI-->>Dev: .specs/ + Agent-Rules-Dateien

    Dev->>CLI: spec create --name "Feature X" --type feat
    CLI-->>Dev: ID 0, status: draft

    Dev->>CLI: spec update 0 --section context="..."
    Dev->>CLI: spec update 0 --section solution="..."
    Dev->>CLI: spec update 0 --section review="Finding 1 [minor] @cmd/main.go:5: ..."

    Agent->>CLI: spec lint 0
    CLI-->>Agent: Grounding hints (informativ)
    Dev->>CLI: spec submit 0
    CLI-->>Dev: Status: approved (Grounding + Self-Review Gates bestanden)

    Agent->>Agent: Implementierung
    Agent->>CLI: spec note "Neues Problem entdeckt" --type fix
    Agent->>CLI: spec verify 0
    CLI-->>Agent: Acceptance Criteria Status
    Dev->>CLI: spec update 0 --set status=done

    Dev->>Rel: release create 1.0.0 --spec 0
    Dev->>Rel: release update 1.0.0 --set type=feat ...
    Dev->>Rel: release status 1.0.0
    Dev->>Rel: release finalize 1.0.0
    Rel-->>Dev: workspace.poly version=1.0.0, Git-Tag v1.0.0

Multi-Agent-Workflow¶

SDD unterstützt Workflows mit mehreren parallelen Subagenten. Jede Rolle hat eine klar definierte Aufgabe:

Parallelisierung¶

Mehrere Specs können gleichzeitig in verschiedenen Sessions bearbeitet werden. Jede Session arbeitet an genau einer Spec. Parallelisierung lohnt sich wenn:

• Specs keine needs-Abhängigkeiten zueinander haben
• Die betroffenen Code-Bereiche überlappungsfrei sind
• Die Verifikation pro Spec isoliert durchführbar ist

# Agent 1 (Spec A):
polycrate spec verify 10 --with-agent   # generiert Verifikations-Prompt

# Agent 2 (Spec B, parallel):
polycrate spec verify 11 --with-agent

Invariants im Multi-Agent-Kontext¶

Jeder Subagent liest die generierten sdd.mdc-Regeln automatisch via Cursor. Der INVARIANTS-Block steht immer an erster Stelle — Verstöße sind keine Konventionsfragen, sondern Bugs.

Alle Commands im Überblick¶

polycrate spec¶

polycrate release¶

Siehe auch¶

• CLI-Referenz
• Workspaces
• Git-Integration
• Best Practices