Spec-Driven Development

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, kein Spec-Dokument) — 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, 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 — needs-check warnt bei nicht-done Abhängigkeiten
• Optionale thematische Links (relates-to) — nicht blockierend

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

Live-Scan (kein index.yml)

Ab CLI ≥ 0.45.0 gibt es kein index.yml mehr. Specs und Releases werden live aus dem Dateisystem gelesen — die Ordnerposition ist der Zustand:

ID, Status, Typ, Labels, Needs und weitere Metadaten stehen im YAML-Frontmatter jeder Spec-Datei. polycrate spec list und verwandte Commands leiten alles daraus ab.

Referenzarchitektur (.specs/ARCHITECTURE.md)

Die Datei .specs/ARCHITECTURE.md ist kein Spec-Dokument und wird nicht live-gescannt. 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 (optional)
reviewen, implementieren,            CHANGELOG.poly schreiben
verifizieren, auf done setzen         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/
│   ├── ARCHITECTURE.md     # Referenzarchitektur (optional, direkt editierbar)
│   ├── .rules.md           # Projekt-spezifische Regeln für Agents (optional)
│   ├── .invariants.md      # Maschinenlesbare Kernregeln (optional)
│   ├── .next/              # Backlog — noch keiner Version zugewiesen
│   │   ├── 0-login-timeout-fix.md
│   │   └── 1-api-integration.md
│   ├── 1.0.0/              # Released
│   │   ├── RELEASENOTE.md
│   │   └── 2-initial-setup.md
│   └── 1.1.0/              # In Vorbereitung
│       ├── RELEASENOTE.md
│       └── 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 ◄────────────────────────────► done
  │                                    │
  └────────────────────────────────────┤
                                       │
                                 cancelled (jederzeit)

Der Übergang draft ↔ done hat keine Pflicht-Gates. polycrate spec update <id> --set status=done funktioniert von jedem Status aus. Informative Checks (spec review, spec verify, needs-check) geben Warnings, blockieren aber nicht.

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 deklarierte Abhängigkeiten zwischen Specs. Beim Setzen auf done warnt der needs-check, solange Abhängigkeiten nicht done sind (informativ, nicht blockierend):

# Spec 5 sollte erst auf done gesetzt werden, wenn Specs 3 und 4 done sind (needs-check warnt sonst)
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 done 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

Informative Checks (optional, nicht blockierend)

polycrate bietet mehrere informative Prüfungen, die Qualität und Vollständigkeit einer Spec unterstützen — ohne den Übergang auf done zu blockieren. Sie geben Warnings aus, wenn Erwartungen nicht erfüllt sind; mit --force (protokolliert, siehe Force-Audit) lassen sich verbleibende Warnungen dokumentiert überbrücken.

Grounding — spec lint / spec verify

Während der Ausarbeitung prüft spec lint, ob die Spec ausreichend im Codebase verankert ist:

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

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

Grounding-Opt-out (zwei Schritte)

Falls keine Architektur-Sektion greift (z. B. reine Docs-Specs), sind beide Schritte nötig:

1. Direktive im Body von ## Context oder ## Solution:

no-architecture-reference: <Begründung, warum kein Arch-Abschnitt greift>

2. Als [major]-Finding in ## Review anerkennen:

Finding N [major] [no-code]: no-architecture-reference: <gleiche Begründung> - resolved: yes

Fehlt einer der Schritte, gilt Grounding als nicht erledigt (Disziplin-Konvention; seit Spec 248 kein CLI-Hard-Gate).

Self-Review — spec review

polycrate spec review <id> setzt reviewed_at und prüft optional die Sektion ## Review auf strukturierte Funde:

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

• Jeder Fund braucht @path:LINE (oder [no-code] nur für reine Docs-Specs)
• Pauschalaussagen wie „alles OK“ zählen nicht
• Workflow-Gate: informativ (Warning bei fehlendem/veraltetem reviewed_at) — blockiert status=done nicht

Acceptance Criteria — spec verify

polycrate spec verify <id> prüft strukturierte Akzeptanzkriterien ohne Status-Übergang:

## Acceptance Criteria

- [x] Feature ist implementiert - verify: @cmd/spec_verify.go:42
- [x] Prüfung greift bei fehlenden Checkboxen - verify: @pkg/specdev/acceptance.go:15
- [ ] Unerfülltes Kriterium — Warning in spec verify

• Format: - [x] <Text> - verify: @path:LINE (Leerzeichen nach verify:)
• Unerfüllte Kriterien → Warnings, kein Hard-Block für status=done

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

Deprecated: spec submit / spec finalize

polycrate spec submit und polycrate spec finalize sind deprecated Aliase für polycrate spec update <id> --set status=done. Sie führen dieselben informativen Checks aus, setzen aber direkt done — nicht approved. Für neue Workflows direkt status=done verwenden.

Force-Audit

Jede Nutzung von --force (z. B. 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 release finalize 1.0.0 --force --force-reason "Highlights manuell nachgetragen"
polycrate spec force-audit              # Audit-Log anzeigen

Coding Agents: Spec Handoff, Soft-Stop und Staging

Agents sollen offene Designfragen nicht leeren, um Checks zu umgehen. Leere Open Questions bedeuten: Antworten stehen in Solution / Context.

Spec Handoff (Spec 257 / 280, SSOT: polycrate spec manual → AGENT DISCIPLINE): Die Chat-Antwort ist der primäre Handoff — nicht annehmen, dass der Nutzer .specs/-Dateien öffnet. Compact Rules (.cursor/rules/sdd.mdc) tragen nur einen kurzen Reminder.

Nach Authoring im Chat:

1. Spec-Identität (ID, Name, Typ, Status)
2. Strukturierte Zusammenfassung (Warum + Was/Wie)
3. Open Questions ausformuliert — oder explizit „No open questions.“
4. Nächster Schritt für den Nutzer

Soft-Stop (MUST): Solange echte Open Questions offen sind: pausieren, nicht implementieren, nicht status=done setzen (kein CLI-Gate — Konversationsdisziplin).

Arbeitsstil: wie im polycrate spec manual und in 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/ 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)
# → Status: draft (Frontmatter in der Spec-Datei)

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

Sektions-Inhalte können auch direkt mit Editor- oder Agent-Dateiwerkzeugen bearbeitet werden (Text zwischen ##-Grenzen). Frontmatter und Sektions-Überschriften bleiben CLI-only.

5. Spec lesen

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

6. Qualität prüfen (optional)

polycrate spec lint 0          # Grounding-Hinweise (informativ)
polycrate spec review 0        # Self-Review-Zeitstempel + Review-Sektion prüfen
polycrate spec verify 0        # Acceptance Criteria (informativ)

7. Implementierung und Abschluss

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

# Auf done setzen — funktioniert von jedem Status aus
# (needs-check: warnt bei nicht-done Abhängigkeiten, blockiert nicht)
polycrate spec update 0 --set status=done

# Review-Sektion für Self-Review befüllen (optional, vor Implementierung)
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 draft
polycrate spec list --status draft --status done
polycrate spec list --status draft,done
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 — Specs optional zuweisen
polycrate release create 1.0.0 --spec 0 --spec 1
# → Verschiebt Spec-Dateien von .next/ nach 1.0.0/
# → Erstellt automatisch RELEASENOTE.md (Scaffold)

# Reine Version-Bump ohne Specs ist ebenfalls gültig:
polycrate release create 1.0.1

# Bulk-Zuweisung nach Status oder Typ
polycrate release create 1.1.0 --spec-status done
polycrate release create 1.1.0 --spec-type fix --spec-type feat

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 (Dateipfade, Frontmatter, 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

WARNING: spec 7 has open needs dependencies:
  #3 "Volume Discovery" [draft]
  → Fix: implement spec #3 first or remove needs link

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
• Regeln für .specs/: Frontmatter und Sektions-Überschriften nur via CLI; Sektions-Inhalte direkt editierbar; RELEASENOTE.md / Workspace-CHANGELOG.poly nur via release * — Ausnahme: .specs/ARCHITECTURE.md
• Informative Checks: spec lint, spec review, spec verify, needs-check — Warnings; struktureller Drift (Spec 185) bleibt hart
• Agent discipline: Kein vorschnelles status=done; Open Questions nicht leeren; Spec Handoff (Chat primär, Spec 257/280) + Soft-Stop; Staging unter /tmp/.polycrate/spec-sections/; -w absolut
• 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 Spec-Inkonsistenzen und Legacy-Migration
• 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

Bei Inkonsistenzen im .specs/-Baum (z. B. fehlgeschlagene Operationen, manuelle Frontmatter-Edits):

# Konsistenz prüfen (primärer Recovery-Schritt)
polycrate spec validate

# Strukturelle Drift in einer Spec reparieren
polycrate spec lint <id>      # Drift anzeigen
polycrate spec format <id>    # Drift auto-fixen (Sektions-Inhalte bleiben erhalten)

Migration von Legacy-Repos (mit index.yml)

Repos mit altem 5-Status-Lifecycle und index.yml:

# 1. Legacy-Statuses und Sektionen auf Disk umschreiben (nur bei index.yml-Repos)
polycrate spec index migrate

# 2. Auf Spec 248 migrieren: index.yml entfernen, Status-Remap abschließen
polycrate spec lifecycle migrate-v2

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)
    Agent->>CLI: spec review 0
    CLI-->>Agent: Review-Zeitstempel (optional)

    Agent->>Agent: Implementierung
    Agent->>CLI: spec note "Neues Problem entdeckt" --type fix
    Agent->>CLI: spec verify 0
    CLI-->>Agent: Acceptance Criteria Status (Warning wenn offen)
    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