CRAFT

Das Problem & die IdeeThe problem & the idea

Vier DisziplinenFour disciplines

Der 9-Phasen-LoopThe 9-phase loop

Das methodische Rückgrat. Phase 1–2 laufen nur beim Projektstart oder Betreten einer neuen Domäne; Routine-Slices starten in Phase 3. Nach Phase 9 kehrt der Loop zu Phase 3 zurück — der nächste Slice.

The methodological backbone. Phases 1–2 run only at project start or when entering a new domain; routine slices start at Phase 3. After Phase 9 the loop returns to Phase 3 — the next slice.

Die Phasen im DetailThe phases in detail

Quickstart

So fühlt sich ein Arbeitstag mit CRAFT an — vom Onboarding bis zum geschlossenen Slice:

What a working day with CRAFT feels like — from onboarding to a closed slice:

# einmalig pro Projekt: Projektwissen aufbauen (oder bestehendes .claude/ migrieren)once per project: bootstrap project knowledge (or migrate an existing .claude/)
❯ /craft:onboard

# jede Session: Kontext laden — läuft automatisch beim Session-Startevery session: load context — auto-runs at session start
❯ /craft:prime
  ✓ Project · ✓ Tools · ✓ Rules↔State drift check · Active slices · Recommended next

# neuer Slice: die drei Fragen (Trigger? Effekt? Test?) → Plan-Dateinew slice: the three questions (trigger? effect? test?) → plan file
❯ /craft:plan user-login
  → .claude/plans/slice-001-user-login.md   Status: planning

❯ /craft:build      # Phase 4 — implementiert Sub-Tasks, Tests still im Hintergrundworks sub-tasks, tests silent
❯ /craft:test       # Phase 5 — DU probierst es aus:YOU exercise it: [W]orks / [B]ug / [U]X
❯ /craft:recap      # Phase 6 — was wurde gebaut & warumwhat was built & why
❯ /craft:refactor   # Phase 7 — optional, pro Projekt abschaltbaroptional, droppable per project
❯ /craft:review     # Phase 8 — Fresh-Context-Review, Commit-Gatefresh-context review, commit gate
❯ /craft:commit     # Phase 9 — atomare Commits, Archiv, Slice zuatomic commits, archive, slice closed

# wieder einsteigen, egal wo man stand:resume from wherever you left off:
❯ /craft:continue   # liest den Status und empfiehlt das richtige Kommandoreads Status, recommends the right command

# groß denken: Epic planen und autonom bauen lassenthink big: plan an epic and build it autonomously
❯ /craft:epic checkout-flow
❯ /craft:execute epic-001   # parallele Worktrees, ein Agent pro Sliceparallel worktrees, one agent per slice

Kontext-Hygiene — der unterschätzte Effizienz-HebelContext hygiene — the underrated efficiency lever

Hat die Session grob 300.000 Tokens verbraucht, lohnt ein beherzter Schnitt: /clear — und der SessionStart-Hook stößt /craft:prime automatisch wieder an. Weil aller relevanter Zustand in Dateien lebt (Slice-Plan mit Status-Token, Intent, Rules, Profil), landet die frische Session ohne Verlust exakt an der richtigen Stelle — genau dafür ist das Status-Token-Design gebaut. Regelmäßiges Leeren statt endlosem Weiterschleppen hält das Modell aus seiner „Dumb Zone" und bringt spürbar Effizienz.

Once a session has burned roughly 300,000 tokens, a clean cut pays off: /clear — and the SessionStart hook automatically re-triggers /craft:prime. Because all relevant state lives in files (the slice plan with its status token, intent, rules, profile), the fresh session lands exactly where you left off, losing nothing — that is precisely what the status-token design is built for. Clearing regularly instead of dragging context along keeps the model out of its "dumb zone" and is a real efficiency win.

❯ /clear          # bei ~300k verbrauchten Tokens: Kontext leerenat ~300k tokens consumed: clear the context
❯ /craft:prime    # läuft automatisch wieder an — lädt Status, empfiehlt den Wiedereinstiegauto-runs again — loads state, recommends where to resume

Der zweite Hebel ist die harte Abhängigkeit von context-mode — sie ist kein Zufall: context-mode führt große Ausgaben (Logs, Diffs, Suchläufe, Doku) in einer Sandbox aus und lässt nur die destillierte Antwort ins Kontextfenster. Das spart aktiv enorme Token-Mengen und erlaubt deutlich größere Sessions — erst dadurch läuft der 9-Phasen-Loop eines Slices in einem Rutsch.

The second lever is the hard dependency on context-mode — and it is no accident: context-mode runs large outputs (logs, diffs, searches, docs) in a sandbox and lets only the distilled answer into the context window. That actively saves enormous amounts of tokens and allows much larger sessions — it is what lets a slice's 9-phase loop run in one go.

Voraussetzungen (von /craft:prime hart geprüft): context-mode, agent-browser, git, gh. Fehlt eines, bricht Prime mit konkreten Installationsanweisungen ab.

Prerequisites (strictly verified by /craft:prime): context-mode, agent-browser, git, gh. If one is missing, prime aborts with concrete install instructions.

Der Status-Graph — und alle AbbiegemöglichkeitenThe status graph — and every branch-off

Jeder Slice-Plan trägt ein Status:-Feld — das Execution-Token des Workflows: Ein Kommando schreibt es, das nächste konsumiert es. /craft:continue liest nur den Status und routet zum richtigen Kommando. Der Graph ist maschinell geprüft (scripts/test-workflow-status-graph.sh) — kein Status ohne Konsumenten.

Every slice plan carries a Status: field — the workflow's execution token: one command writes it, the next consumes it. /craft:continue just reads the status and routes to the right command. The graph is machine-checked (scripts/test-workflow-status-graph.sh) — no status without a consumer.

Die Abbiegungen im DetailThe branch-offs in detail

Dazu kommt ein zweiter Marker-Namensraum: In Worktrees schreibt der slice-builder-Agent bei jeder menschenpflichtigen Pause eine .craft/handoff.md (awaiting-test, awaiting-protocol, awaiting-scope-decision, awaiting-refactor-decision, awaiting-rethink-decision, …) — das sind Worktree-Marker, keine Slice-Status.

There is a second marker namespace: inside worktrees the slice-builder agent writes a .craft/handoff.md on every human-required pause (awaiting-test, awaiting-protocol, awaiting-scope-decision, awaiting-refactor-decision, awaiting-rethink-decision, …) — worktree markers, not slice statuses.

Wer entscheidet was — die Autonomie-TaxonomieWho decides what — the autonomy taxonomy

Vier Stufen regeln, wie selbstständig der Agent handelt. Jede Phase hat eine Default-Stufe (siehe Loop) — aber bestimmte Aktionstypen erzwingen ihre Stufe phasenübergreifend:

Four levels govern how independently the agent acts. Each phase has a default level (see the loop) — but certain action types force their level across all phases:

Strukturell menschlich — vom Agenten nie fabriziert: UX-Feedback ([W]/[B]/[U]), Refactoring-Auswahl, Eskalations-Routing, Entscheidungs-Promotion ([K]/[I]/[R]/[D]), Scope-Änderungen, Merges. Dazu die Bündel-Disziplin: Meldung an jeder Sub-Task-Grenze, 30k-Token-Bremse (15k im Debug-Loop) gegen die „Dumb Zone", und Buchstaben-Menüs zeigen immer die volle Legende.

Structurally human — never fabricated by the agent: UX feedback ([W]/[B]/[U]), refactor selection, escalation routing, decision promotion ([K]/[I]/[R]/[D]), scope changes, merges. Plus the bundling discipline: a report at every sub-task boundary, a 30k token brake (15k inside the debug loop) against the "dumb zone", and lettered menus always render their full legend.

Regel-Konflikte: Bend / Override / RepealRule conflicts: bend / override / repeal

Will der Mensch eine Regel umgehen, biegt der Agent sie nie still — er bietet drei Stufen an: Bend (nur dieser eine Austausch), Override (slice-weit, im Plan unter Active Rule Overrides protokolliert, in Phase 9 gelöscht), Repeal (dauerhaft — rules.md wird mit Bestätigung geändert). Drift zwischen Rules und State wird von /craft:prime nur gemeldet, nie automatisch korrigiert.

When the human wants to bypass a rule, the agent never bends it silently — it offers three stages: bend (this one exchange only), override (slice-scoped, recorded in the plan under Active Rule Overrides, cleared in phase 9), repeal (permanent — rules.md edited with confirmation). Rules↔State drift is only reported by /craft:prime, never auto-corrected.

Autonome Ausführung — die drei ModiAutonomous execution — the three modes

/craft:execute <epic-NNN | slice-NNN> ist der Orchestrator: Er verwandelt einen geplanten Epic oder Slice in gebauten Code, ohne dass der Mensch jede Phase begleitet — gestoppt wird nur an den vereinbarten Review-Punkten. Welcher Modus läuft, entscheidet das CRAFT-Profil.

/craft:execute <epic-NNN | slice-NNN> is the orchestrator: it turns a planned epic or slice into built code without per-phase supervision — stopping only at the agreed review points. Which mode runs is decided by the CRAFT profile.

Alle Stellschrauben — die KonfigurationsreferenzEvery knob — the configuration reference

Das CRAFT-ProfilThe CRAFT profile — .claude/project/craft-profile.md

Das portable Betriebsprofil eines Projekts: Autonomie-, Commit-, Merge-, Sprach- und Modell-Einstellungen an einem Ort. Fehlt die Datei, gilt implizit das Preset balanced. Beim Onboarding wählbar: ein Preset übernehmen oder jede Stellschraube einzeln setzen (> Preset: custom). /craft:prime validiert das Profil jede Session — Warnungen, nie Abbruch.

A project's portable operating profile: autonomy, commit, merge, language and model settings in one place. If the file is absent, the balanced preset applies implicitly. During onboarding you either adopt a preset or set every knob individually (> Preset: custom). /craft:prime validates the profile every session — warnings, never aborts.

Optionale Blöcke inOptional blocks in .claude/project/rules.md

Die drei Persönlichkeits-EbenenThe three personality tiers

Das Wissensmodell — „Chat ist kein Speicher"The knowledge model — "chat is not storage"

CRAFT trennt drei Wissensschichten mit unterschiedlicher Ground Truth. Alles Bleibende wird im selben Zug, in dem es entsteht, in seine dauerhafte Heimat geschrieben — denn Kontext stirbt bei /clear, Compaction und Session-Ende:

CRAFT separates three knowledge layers with distinct ground truth. Anything lasting is written to its durable home in the same turn it is produced — because context dies on /clear, compaction and session end:

Routing für bleibende Erkenntnisse: Warum → intent.md · Wie → rules.md · Langfrist-Phasen → roadmap.md · Slice-Entscheidungen → Slice-Archiv · Epic-Entscheidungen → Epic-Plan · Querschnitts-Design (Domänenmodell, Szenario-Kataloge) → design/*.md. Nach Phase 9 lebt das Gedächtnis in drei Orten: Code, Commits (mit Slice:-Footer) und dem Slice-Archiv — dem Decision Log.

Routing for lasting insight: why → intent.md · how → rules.md · long-term phases → roadmap.md · slice decisions → slice archive · epic decisions → epic plan · cross-cutting design (domain model, scenario catalogs) → design/*.md. After phase 9, memory lives in three places: code, commits (with Slice: footers) and the slice archive — the decision log.

your-project/
├── CLAUDE.md                          # schlanker Index auf alles Untereslim index pointing at everything below
├── .claude/
│   ├── project/                       # DAUERHAFT — versioniertDURABLE — version-controlled
│   │   ├── intent.md                  # Warum: Vision, Ziele, Entscheidungen (≤ ~80 Zeilen)why: vision, goals, decisions (≤ ~80 lines)
│   │   ├── rules.md                   # Wie: Stack, Konventionen, Tabus (≤ ~80 Zeilen)how: stack, conventions, taboos (≤ ~80 lines)
│   │   ├── craft-profile.md           # Betriebsprofil (Presets & Stellschrauben)operating profile (presets & knobs)
│   │   ├── roadmap.md                 # optional: Backlog jenseits des Kernsoptional: backlog beyond the core
│   │   ├── design/                    # Querschnitts-Designwissen, on demandcross-cutting design knowledge, on demand
│   │   └── slices/                    # Archiv abgeschlossener Slices = Decision Logarchive of completed slices = decision log
│   ├── plans/                         # EPHEMER — lebt nur solange ein Slice offen istEPHEMERAL — lives only while a slice is open
│   │   ├── slice-001-user-login.md    # aktiver Plan — trägt das Status-Tokenactive plan — carries the status token
│   │   ├── .next-id · .next-epic-id   # ID-Zähler (getrennte Räume)ID counters (independent spaces)
│   │   └── .execute.lock              # nur während eines /craft:execute-Laufsonly during a /craft:execute run
│   ├── skills/                        # projekt-lokale Spezialisten, lazy geladenproject-local specialists, lazy-loaded
│   └── settings.local.json            # Allowlist + Worktree-Trust (gitignored)allowlist + worktree trust (gitignored)
└── research/                          # immer schreibgeschützt (PreToolUse-Hook)always write-protected (PreToolUse hook)

Command-ReferenzCommand reference

24 Commands + 4 slash-aufrufbare Skills, alle im /craft:-Namensraum (bewusst — kollidiert nicht mit reservierten Namen wie /plan). Fast alle Commands beginnen mit dem „Ensure-primed"-Gate: Ist die Session nicht geprimed, läuft /craft:prime automatisch vorweg.

24 commands + 4 slash-invocable skills, all in the /craft: namespace (deliberate — no collision with reserved names like /plan). Nearly every command starts with the "ensure-primed" gate: if the session isn't primed, /craft:prime runs first automatically.

Unter der HaubeUnder the hood

Begleitwerkzeuge (Pflicht)Companion tools (required)

Upgrade-Modell: /craft:upgrade synct nur den Marketplace-Klon (~/.claude/plugins/marketplaces/…) — die Installation in den Plugin-Cache übernimmt Claude Code beim nächsten Start. Wichtig fürs Dogfooding: Die laufende Session führt immer die Cache-Version aus, nicht den Working Tree.

Upgrade model: /craft:upgrade only syncs the marketplace clone (~/.claude/plugins/marketplaces/…) — installation into the plugin cache is Claude Code's job on next start. Dogfooding caveat: a running session always executes the cache version, not the working tree.