OpenSpec

OpenSpec ist ein spezifikationsgetriebener Workflow für KI-gestützte Entwicklung. Motoko Base nutzt ihn, damit Agenten vor dem Codieren planen — begrenzte Änderungen statt zufälliger Diffs über das Repo.

Offizielle Docs: openspec.dev

Warum OpenSpec?

OpenSpec trennt Planung (Proposal, Design, Specs, Tasks) von Implementierung (Apply). Du prüfst den Plan, bevor Produktcode geändert wird.

Ordnerstruktur

openspec/
├── config.yaml              # Project context + rules for AI artifacts
├── specs/                   # Durable requirements (main specs)
│   └── <capability>/
│       └── spec.md
└── changes/
    ├── <active-change>/     # Work in progress
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/<capability>/spec.md   # delta spec
    └── archive/
        └── <date>-<change-name>/        # completed changes

Main Specs (openspec/specs/) sind langlebiges Produktgedächtnis — was der Starter pro Capability leisten muss (Links, Billing, Storage usw.).

Changes (openspec/changes/) sind kurzlebige Pläne für ein Ergebnis. Nach dem Archive fließen dauerhafte Anforderungen in die Main Specs.

Projektspezifische KI-Regeln stehen in openspec/config.yaml (Philosophie, Stack, Architektur-Constraints, Regeln pro Artefakt).

Eine Proposal erstellen

Nutze den Cursor-Slash-Befehl oder bitte den Agenten, den Propose-Skill auszuführen:

/opsx-propose Add a bookmarks demo with user ownership

Das erstellt openspec/changes/<name>/ und erzeugt:

Nur Planung — kein Produktcode, bis du Apply ausführst.

Zum Nachdenken ohne Planung: /opsx-explore. Zur Überarbeitung nach Feedback: /opsx-update.

Design

design.md hält Architekturentscheidungen für den Change fest:

• Welche bestehenden Muster wiederverwendet werden (src/features/links/ als CRUD-Vorlage)
• Schema, Routen und Datei-Touchpoints
• Trade-offs und Non-Goals auf Design-Ebene

Agenten lesen proposal.md + die bestehende Codebase, bevor sie das Design schreiben. Kurz halten — lieber Starter-Muster wiederverwenden als neue Schichten erfinden.

Tasks

tasks.md ist eine Checkbox-Liste, der der Agent während Apply folgt:

- [ ] 1.1 Add schema in src/lib/db/schema/...
- [ ] 2.1 Create queries.ts with ownership filters
- [ ] 3.1 Wire dashboard route and nav item

Tasks sollten klein, geordnet (Schema → Server → UI → Wiring) und bei bekannten Pfaden konkrete Dateipfade nennen.

Apply

Wenn der Plan gut aussieht:

/opsx-apply

Der Agent:

1. Liest proposal.md, Delta-Specs, design.md und tasks.md
2. Implementiert jede unchecked Task
3. Markiert Tasks mit - [x] als erledigt
4. Pausiert, wenn der Scope unklar ist oder der Spec aktualisiert werden muss

Du kannst Apply über mehrere Sitzungen laufen lassen — der Fortschritt wird in tasks.md verfolgt.

Archive

Wenn alle Tasks erledigt sind und du den Code reviewed hast:

/opsx-archive

Archive:

1. Synchronisiert optional Delta-Specs in openspec/specs/<capability>/spec.md
2. Verschiebt den Change-Ordner nach openspec/changes/archive/<date>-<name>/

Main Specs werden die Quelle der Wahrheit für künftige KI-Sitzungen zu dieser Capability.

Nützliche CLI-Befehle

openspec list                      # active changes
openspec status --change <name>    # artifact progress
openspec validate <name>           # check a change
openspec view                      # browse specs and changes

Installation: OpenSpec installation

Cursor-Befehle

Skills liegen in .agents/skills/openspec-* und .cursor/skills/openspec-*.

KI-Entwicklungsworkflow — End-to-End-Ablauf von der Idee bis zum Review.

Cursor / KI-Agenten — AGENTS.md und Prompting-Tipps.