Bleu - a Claude Code plugin for living blueprints

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](https://docs.claude.com/en/docs/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.

flowchart LR
    A[Your idea] --> B[Bleu]
    B --> C[blueprint/<br/>workspace on disk]
    C --> D[Handoff to executor<br/>GSD / Superpowers / Claude Code]
    D --> E[Code, written from a real plan]

    style B fill:#cfe8ff,stroke:#0066cc,color:#000
    style C fill:#fff4cf,stroke:#cc9900,color:#000
    style E fill:#d4f5d4,stroke:#2d8f2d,color:#000

Install

/plugin marketplace add Nirvaan05/Bleu-plugin
/plugin install bleu@bleu

Restart your Claude Code session.

Trigger phrases

At a glance

The phased workflow

Eight phases. Sequential by default, lint after each one, free to loop back.

flowchart TD
    P0[Phase 0<br/>Intake & framing] --> P1[Phase 1<br/>Research pass<br/>web + code]
    P1 --> P2[Phase 2<br/>Vision · Architecture · Pipelines]
    P2 --> P3[Phase 3<br/>Component breakdown]
    P3 --> P4[Phase 4<br/>Data · Integrations · Non-functional]
    P4 --> P5[Phase 5<br/>Action point expansion]
    P5 --> P6[Phase 6<br/>Lint · Challenge · Iterate]
    P6 -->|gaps found| P2
    P6 --> P7[Phase 7<br/>Sign-off & handoff]

    PR[Phase R<br/>Resume / Persist]
    PR -.->|runs at session start| P0
    PR -.->|runs at session end| P7

    style P0 fill:#e8f4ff,color:#000
    style P1 fill:#e8f4ff,color:#000
    style P2 fill:#fff4cf,color:#000
    style P3 fill:#fff4cf,color:#000
    style P4 fill:#fff4cf,color:#000
    style P5 fill:#ffe0cc,color:#000
    style P6 fill:#ffd4d4,color:#000
    style P7 fill:#d4f5d4,color:#000
    style PR fill:#e8d4ff,color:#000

The workspace anatomy

blueprint/
├── README.md                    entry point + navigation
├── SESSION.md                   current snapshot, read FIRST on resume
├── NEXT.md                      imperative next actions, read SECOND
├── journal.md                   append-only session history
├── index.md                     compact summary of every file
├── decisions/                   MADR-style ADR log
│   ├── README.md                ADR index with status table
│   └── ADR-NNN-<slug>.md
├── raw/                         raw inputs: transcripts, dumps, code excerpts
├── plan/
│   ├── 00-vision.md             problem, goals, non-goals, success criteria
│   ├── 01-architecture.md       diagram, layers, data flow, key decisions
│   ├── 02-pipelines.md          every flow end to end
│   ├── 03-components/           one file per component
│   ├── 04-data-model.md
│   ├── 05-integrations.md
│   ├── 06-non-functional.md
│   └── 07-risks-open-questions.md
├── action-points/               one file per AP + dep graph in README
├── research/                    web research notes with citations
└── outputs/                     answers to your queries, persisted

Read order on resume

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.

sequenceDiagram
    actor You
    participant Bleu
    participant Disk as blueprint/

    Note over Bleu,Disk: Session start
    You->>Bleu: "where did we leave off"
    Bleu->>Disk: read SESSION.md, NEXT.md, index.md, ADR index, journal tail
    Bleu->>You: "You are in Phase N. Last did X. Next is Y. OK?"
    You->>Bleu: confirm

    Note over Bleu,Disk: Working
    Bleu->>Disk: write plan/, action-points/, research/
    Bleu->>Disk: mini-persistence at end of each phase

    Note over Bleu,Disk: Session end (before /clear)
    Bleu->>Disk: append journal entry
    Bleu->>Disk: write any new ADRs
    Bleu->>Disk: rewrite SESSION.md + NEXT.md
    Bleu->>Disk: update index.md coverage tags
    Bleu->>You: "Workspace persisted. Safe to /clear."

Action points

flowchart LR
    AP01[AP-01<br/>Foundation] --> AP02[AP-02]
    AP01 --> AP03[AP-03]
    AP01 --> AP04[AP-04]
    AP02 --> AP05[AP-05]
    AP03 --> AP05
    AP04 --> AP06[AP-06]
    AP05 --> AP07[AP-07<br/>Integrate]
    AP06 --> AP07

    classDef parallel fill:#cfe8ff,stroke:#0066cc,color:#000
    class AP02,AP03,AP04 parallel

Bleu builds a dependency graph at the bottom of action-points/README.md showing execution order and parallelizable groups (highlighted above).

AP file template

Granularity scales to project size

Augment Code's research: multi-file tasks succeed at ~19% versus single-function tasks at ~87%. Smaller scope dramatically improves agent success rate. Anthropic's harness research adds: doubling task duration quadruples failure rate. Every agent degrades after ~35 minutes of human time.

Adversarial linting (proposer-validator separation)

Bleu enforces this strictly: the same agent never both proposes and approves a change.

flowchart LR
    User[You] -->|asks for plan| Curator[Curator agent<br/>writes plan files]
    Curator -->|drops proposals| Proposals[.reflection/proposals/]
    Proposals --> Auditor[Auditor agent<br/>different from Curator]
    Auditor -->|approves| Schema[blueprint/ canonical state]
    Auditor -.->|rejects| Curator

    style Curator fill:#cfe8ff,stroke:#0066cc,color:#000
    style Auditor fill:#ffd4d4,stroke:#cc0000,color:#000
    style Schema fill:#d4f5d4,stroke:#2d8f2d,color:#000

Why: Anthropic's harness research found that agents tend to confidently praise mediocre work when reviewing themselves. Different agent = honest review.

Continuous research with citations

flowchart LR
    Decision[Architectural<br/>claim] -->|search web<br/>before drafting| Sources[Primary sources<br/>docs · RFCs · repos]
    Sources --> ResearchFile[research/topic.md<br/>+ citation block]
    ResearchFile --> PlanFile[plan/01-architecture.md<br/>links to research file]
    PlanFile -->|Phase 6 lint| Density[Citation density<br/>check]
    Density -->|gap found| Decision

    style Sources fill:#fff4cf,color:#000
    style Density fill:#ffd4d4,color:#000

If Bleu catches itself thinking "I just knew that," the lint pass forces it to stop and search instead. Training knowledge is stale on tooling.

Operating principles

The 14 constraints Bleu holds for the entire session.

Handoff to your executor

flowchart TD
    Locked[Phase 7<br/>Blueprint locked] --> Choose{Pick executor}
    Choose -->|1| GSD["/gsd:new-milestone<br/>Get Stuff Done"]
    Choose -->|2| SP["/superpowers<br/>plans + checkpoints"]
    Choose -->|3| CC[Raw Claude Code<br/>direct execution]
    Choose -->|4| List[Just the AP list<br/>drive yourself]

    GSD --> Artifact[handoff/gsd.md<br/>references blueprint files]
    SP --> Artifact2[handoff/superpowers.md]
    CC --> Artifact3[handoff/claude-code.md]
    List --> Artifact4[handoff/ap-list.md]

    Artifact --> Auto{Slash command<br/>available?}
    Artifact2 --> Auto
    Artifact3 --> Auto
    Auto -->|yes| Invoke[Bleu offers<br/>to invoke directly]
    Auto -->|no| Manual[You run it yourself]

The handoff artifact references blueprint files by relative path (e.g. @blueprint/plan/01-architecture.md) instead of paraphrasing the whole blueprint into one giant prompt. The blueprint is the source of truth.

Claude Code integration (optional)

When Bleu detects it is running inside Claude Code, it offers four integrations as a menu (never silently).

Bleu always shows you the files it would create before writing them.

Advanced architecture (opt in, layered on top)

Beyond the base wiki and Claude Code integration, the workspace can become a self-improving system. Each capability is independent. Pick any subset.

Recommended adoption order

flowchart LR
    A[Base workflow] --> B[Reflection loop<br/>+ schema-as-code]
    B --> C[Observability]
    C --> D[Agent team]
    D --> E[Graph + memory split]
    E --> F[Multimodal]
    F --> G[External<br/>integrations]

    style A fill:#d4f5d4,color:#000
    style G fill:#e8d4ff,color:#000

Do not take all seven on day one.

Reference files

Eight reference files at references/. Loaded lazily, only when relevant.

When to use Bleu

Why Bleu makes long-running autonomous work safe

Frontliner teams that adopted spec-driven workflows (PubNub, Effloow, EPAM) report:

The safe delegation window expands from 10 to 20 minute tasks to multi-hour feature delivery once a real plan exists in files the agent can re-read.

Plan in files, not chat. Cite primary sources. Lint relentlessly. Survive context resets. Hand off cleanly.

Repository layout

Bleu-plugin/
├── .claude-plugin/
│   └── marketplace.json              marketplace catalog
├── plugins/
│   └── bleu/                         the distributed plugin (this is what installs)
│       ├── .claude-plugin/
│       │   └── plugin.json           plugin manifest
│       └── skills/
│           └── bleu/
│               ├── SKILL.md          the skill itself
│               └── references/       eight reference files
├── scripts/bleu/                     dogfood: deterministic Python core + tests
├── .claude/                          dogfood: hook adapters + example settings (not active)
├── blueprint/                        dogfood: the workspace Bleu built for itself
├── README.md
├── LICENSE                           MIT
└── .gitignore

Only plugins/bleu/ ships when someone installs Bleu. The scripts/, .claude/, and blueprint/ trees are this repo dogfooding the skill (Bleu used to plan and build its own advanced architecture); they are not part of the installed plugin.

License

MIT. See LICENSE.

Author

Nirvaan Lagishetty (@Nirvaan05)

Core Contributors & Maintainers

• Nirvaan Lagishetty (@Nirvaan05) - creator, maintainer
• Hill Patel (@STiFLeR7) - core contributor, maintainer

Contributing

Open an issue or PR. Version bumps go in both marketplace.json and plugin.json and must agree.