bleu

> Turn an idea into a deeply structured, file-backed system plan **before** writing any code.
**Bleu is a planning plugin for Anthropic's Claude Code.** It grows your idea into a navigable markdown wiki - vision, architecture, components, action points, research, citations, ADRs - with a session-persistence layer that survives /clear. The blueprint is the source of truth; the Claude Code plugin hands it off cleanly to GSD, Superpowers, or raw Claude Code when it's time to execute.
Install
Restart your Claude Code session.
Trigger phrases
| Intent | Say something like |
|---|---|
| Start a new blueprint | help me blueprint this system, plan before coding, design the architecture for X, break this idea into components, expand into action points, full implementation plan |
| Resume an existing blueprint | where did we leave off, continue this plan, resume my blueprint |
At a glance
| Property | Value |
|---|---|
| Output | A blueprint/ directory of markdown files in your working dir |
| Storage | Plain markdown. No vector DB, no embeddings, no chunking |
| Survives | /clear, terminal crashes, context-window resets |
| Hands off to | GSD, Superpowers, raw Claude Code, or a flat AP list |
| Granularity | 3 to 5 APs (tiny task) up to ~38 APs (greenfield system) |
| Research | Continuous, web-based, primary sources, every claim cited |
| Lint | Runs after every phase, not only at the end |
The phased workflow
Eight phases. Sequential by default, lint after each one, free to loop back.
| # | Phase | Goal | Output |
|---|---|---|---|
| 0 | Intake & framing | Restate the idea, surface unknowns, confirm scope | raw/intake.md |
| 1 | Research pass | Ground in primary sources before drafting anything | research/ .md, raw/codebase-notes.md |
| 2 | Vision · Architecture · Pipelines | Three opinionated documents with cited decisions | plan/00-vision.md, 01-architecture.md, 02-pipelines.md |
| 3 | Component breakdown | One page per component, clear ownership | plan/03-components/ .md |
| 4 | Data · Integrations · Non-functional | Schemas, APIs, performance, security, scaling | plan/04, 05, 06.md |
| 5 | Action point expansion | Decompose to executable units with deps | action-points/AP-NN- .md + dep graph |
| 6 | Lint · Challenge · Iterate | Find gaps, contradictions, edge cases, flaws | plan/07-risks-open-questions.md |
| 7 | Sign-off & handoff | Lock in, generate handoff artifact for executor | handoff/ .md |
| R | Resume / Persist | Survive context resets | SESSION.md, NEXT.md, journal entry, ADRs |
The workspace anatomy
Read order on resume
| Order | File | Tokens (approx) | Why |
|---|---|---|---|
| 1 | SESSION.md | ~300 | Current snapshot |
| 2 | NEXT.md | ~200 | Imperative next actions |
| 3 | index.md | ~500 | File map with coverage tags |
| 4 | decisions/README.md | ~200 | Status of every ADR |
| 5 | journal.md (last 1-2 entries) | ~800 | Recent context |
Total: ~2k tokens to fully orient. Then and only then does Bleu load specific plan/ or research/ files for the next action. Progressive disclosure all the way down.
Session persistence
Five files keep the workspace alive across context resets. SESSION.md and NEXT.md are rewritten every session. journal.md and decisions/ are append-only.
| File | Lifecycle | Purpose |
|---|---|---|
| SESSION.md | Rewritten every session | Current phase, status, blockers, where to read first on resume |
| NEXT.md | Rewritten every session | Imperative next steps + "Already done, do not redo" list |
| journal.md | Append-only | One entry per session: goal, outcome, decisions, deferrals, blockers |
| decisions/ADR-NNN.md | Append-only, MADR format | One file per architectural decision with status lifecycle |
| decisions/README.md | Updated when ADR added | Status table for fast scanning |
Action points
Bleu builds a dependency graph at the bottom of action-points/README.md showing execution order and parallelizable groups (highlighted above).