{
  "markdown": "# Bleu - a Claude Code plugin for living blueprints\n\n> Turn an idea into a deeply structured, file-backed system plan **before** writing any code.\n\n[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-cfe8ff?style=flat-square)](https://docs.claude.com/en/docs/claude-code/plugins)\n[![Install](https://img.shields.io/badge/install-/plugin%20install%20bleu-0066cc?style=flat-square)](#install)\n[![Spec-driven](https://img.shields.io/badge/workflow-spec--driven-d4f5d4?style=flat-square)](#the-phased-workflow)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)\n\n**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](https://github.com/gsd-build/get-shit-done), [Superpowers](https://github.com/obra/superpowers), or raw Claude Code when it's time to execute.\n\n```mermaid\nflowchart LR\n    A[Your idea] --> B[Bleu]\n    B --> C[blueprint/<br/>workspace on disk]\n    C --> D[Handoff to executor<br/>GSD / Superpowers / Claude Code]\n    D --> E[Code, written from a real plan]\n\n    style B fill:#cfe8ff,stroke:#0066cc,color:#000\n    style C fill:#fff4cf,stroke:#cc9900,color:#000\n    style E fill:#d4f5d4,stroke:#2d8f2d,color:#000\n```\n\n## Install\n\n```\n/plugin marketplace add Nirvaan05/Bleu-plugin\n/plugin install bleu@bleu\n```\n\nRestart your Claude Code session. \n\n## Trigger phrases\n\n| Intent | Say something like |\n|---|---|\n| 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` |\n| Resume an existing blueprint | `where did we leave off`, `continue this plan`, `resume my blueprint` |\n\n## At a glance\n\n| Property | Value |\n|---|---|\n| Output | A `blueprint/` directory of markdown files in your working dir |\n| Storage | Plain markdown. No vector DB, no embeddings, no chunking |\n| Survives | `/clear`, terminal crashes, context-window resets |\n| Hands off to | GSD, Superpowers, raw Claude Code, or a flat AP list |\n| Granularity | 3 to 5 APs (tiny task) up to ~38 APs (greenfield system) |\n| Research | Continuous, web-based, primary sources, every claim cited |\n| Lint | Runs after every phase, not only at the end |\n\n## The phased workflow\n\nEight phases. Sequential by default, lint after each one, free to loop back.\n\n```mermaid\nflowchart TD\n    P0[Phase 0<br/>Intake & framing] --> P1[Phase 1<br/>Research pass<br/>web + code]\n    P1 --> P2[Phase 2<br/>Vision · Architecture · Pipelines]\n    P2 --> P3[Phase 3<br/>Component breakdown]\n    P3 --> P4[Phase 4<br/>Data · Integrations · Non-functional]\n    P4 --> P5[Phase 5<br/>Action point expansion]\n    P5 --> P6[Phase 6<br/>Lint · Challenge · Iterate]\n    P6 -->|gaps found| P2\n    P6 --> P7[Phase 7<br/>Sign-off & handoff]\n\n    PR[Phase R<br/>Resume / Persist]\n    PR -.->|runs at session start| P0\n    PR -.->|runs at session end| P7\n\n    style P0 fill:#e8f4ff,color:#000\n    style P1 fill:#e8f4ff,color:#000\n    style P2 fill:#fff4cf,color:#000\n    style P3 fill:#fff4cf,color:#000\n    style P4 fill:#fff4cf,color:#000\n    style P5 fill:#ffe0cc,color:#000\n    style P6 fill:#ffd4d4,color:#000\n    style P7 fill:#d4f5d4,color:#000\n    style PR fill:#e8d4ff,color:#000\n```\n\n| # | Phase | Goal | Output |\n|---|---|---|---|\n| 0 | Intake & framing | Restate the idea, surface unknowns, confirm scope | `raw/intake.md` |\n| 1 | Research pass | Ground in primary sources before drafting anything | `research/<topic>.md`, `raw/codebase-notes.md` |\n| 2 | Vision · Architecture · Pipelines | Three opinionated documents with cited decisions | `plan/00-vision.md`, `01-architecture.md`, `02-pipelines.md` |\n| 3 | Component breakdown | One page per component, clear ownership | `plan/03-components/<name>.md` |\n| 4 | Data · Integrations · Non-functional | Schemas, APIs, performance, security, scaling | `plan/04`, `05`, `06`.md |\n| 5 | Action point expansion | Decompose to executable units with deps | `action-points/AP-NN-<slug>.md` + dep graph |\n| 6 | Lint · Challenge · Iterate | Find gaps, contradictions, edge cases, flaws | `plan/07-risks-open-questions.md` |\n| 7 | Sign-off & handoff | Lock in, generate handoff artifact for executor | `handoff/<target>.md` |\n| R | Resume / Persist | Survive context resets | `SESSION.md`, `NEXT.md`, journal entry, ADRs |\n\n## The workspace anatomy\n\n```\nblueprint/\n├── README.md                    entry point + navigation\n├── SESSION.md                   current snapshot, read FIRST on resume\n├── NEXT.md                      imperative next actions, read SECOND\n├── journal.md                   append-only session history\n├── index.md                     compact summary of every file\n├── decisions/                   MADR-style ADR log\n│   ├── README.md                ADR index with status table\n│   └── ADR-NNN-<slug>.md\n├── raw/                         raw inputs: transcripts, dumps, code excerpts\n├── plan/\n│   ├── 00-vision.md             problem, goals, non-goals, success criteria\n│   ├── 01-architecture.md       diagram, layers, data flow, key decisions\n│   ├── 02-pipelines.md          every flow end to end\n│   ├── 03-components/           one file per component\n│   ├── 04-data-model.md\n│   ├── 05-integrations.md\n│   ├── 06-non-functional.md\n│   └── 07-risks-open-questions.md\n├── action-points/               one file per AP + dep graph in README\n├── research/                    web research notes with citations\n└── outputs/                     answers to your queries, persisted\n```\n\n### Read order on resume\n\n| Order | File | Tokens (approx) | Why |\n|---|---|---|---|\n| 1 | `SESSION.md` | ~300 | Current snapshot |\n| 2 | `NEXT.md` | ~200 | Imperative next actions |\n| 3 | `index.md` | ~500 | File map with coverage tags |\n| 4 | `decisions/README.md` | ~200 | Status of every ADR |\n| 5 | `journal.md` (last 1-2 entries) | ~800 | Recent context |\n\nTotal: ~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.\n\n## Session persistence\n\nFive files keep the workspace alive across context resets. `SESSION.md` and `NEXT.md` are rewritten every session. `journal.md` and `decisions/` are append-only.\n\n```mermaid\nsequenceDiagram\n    actor You\n    participant Bleu\n    participant Disk as blueprint/\n\n    Note over Bleu,Disk: Session start\n    You->>Bleu: \"where did we leave off\"\n    Bleu->>Disk: read SESSION.md, NEXT.md, index.md, ADR index, journal tail\n    Bleu->>You: \"You are in Phase N. Last did X. Next is Y. OK?\"\n    You->>Bleu: confirm\n\n    Note over Bleu,Disk: Working\n    Bleu->>Disk: write plan/, action-points/, research/\n    Bleu->>Disk: mini-persistence at end of each phase\n\n    Note over Bleu,Disk: Session end (before /clear)\n    Bleu->>Disk: append journal entry\n    Bleu->>Disk: write any new ADRs\n    Bleu->>Disk: rewrite SESSION.md + NEXT.md\n    Bleu->>Disk: update index.md coverage tags\n    Bleu->>You: \"Workspace persisted. Safe to /clear.\"\n```\n\n| File | Lifecycle | Purpose |\n|---|---|---|\n| `SESSION.md` | Rewritten every session | Current phase, status, blockers, where to read first on resume |\n| `NEXT.md` | Rewritten every session | Imperative next steps + \"Already done, do not redo\" list |\n| `journal.md` | Append-only | One entry per session: goal, outcome, decisions, deferrals, blockers |\n| `decisions/ADR-NNN.md` | Append-only, MADR format | One file per architectural decision with status lifecycle |\n| `decisions/README.md` | Updated when ADR added | Status table for fast scanning |\n\n## Action points\n\n```mermaid\nflowchart LR\n    AP01[AP-01<br/>Foundation] --> AP02[AP-02]\n    AP01 --> AP03[AP-03]\n    AP01 --> AP04[AP-04]\n    AP02 --> AP05[AP-05]\n    AP03 --> AP05\n    AP04 --> AP06[AP-06]\n    AP05 --> AP07[AP-07<br/>Integrate]\n    AP06 --> AP07\n\n    classDef parallel fill:#cfe8ff,stroke:#0066cc,color:#000\n    class AP02,AP03,AP04 parallel\n```\n\nBleu builds a dependency graph at the bottom of `action-points/README.md` showing execution order and parallelizable groups (highlighted above).\n\n### AP file template\n\n| Field | Content |\n|---|---|\n| **Title** | One-sentence summary |\n| **Depends on** | Other AP IDs that must complete first |\n| **Files involved** | Exact paths, tagged create / modify / delete |\n| **Code flow** | What happens, function by function, in prose |\n| **Interfaces touched** | Function signatures, API contracts, schema changes |\n| **Interactions** | How it talks to other components (named refs) |\n| **Verification** | How you know this AP is done correctly |\n| **Complexity** | S / M / L / XL with reasoning |\n| **Open questions / risks** | Anything unresolved |\n\n### Granularity scales to project size\n\n| Project type | AP count | Why |\n|---|---|---|\n| Tiny task (bugfix, doc tweak) | 0 | Skip Bleu, just do it |\n| Small task (new feature in existing code) | 3 to 5 | Coarse decomposition is enough |\n| Medium project (subsystem rewrite) | 10 to 20 | Need explicit deps, no need for full vision |\n| Greenfield system | ~38 | Full Phase 0 to 7, fine-grained APs, all integrations |\n\n> 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.\n\n## Adversarial linting (proposer-validator separation)\n\nBleu enforces this strictly: the same agent never both proposes and approves a change.\n\n```mermaid\nflowchart LR\n    User[You] -->|asks for plan| Curator[Curator agent<br/>writes plan files]\n    Curator -->|drops proposals| Proposals[.reflection/proposals/]\n    Proposals --> Auditor[Auditor agent<br/>different from Curator]\n    Auditor -->|approves| Schema[blueprint/ canonical state]\n    Auditor -.->|rejects| Curator\n\n    style Curator fill:#cfe8ff,stroke:#0066cc,color:#000\n    style Auditor fill:#ffd4d4,stroke:#cc0000,color:#000\n    style Schema fill:#d4f5d4,stroke:#2d8f2d,color:#000\n```\n\nWhy: Anthropic's harness research found that agents tend to confidently praise mediocre work when reviewing themselves. Different agent = honest review.\n\n## Continuous research with citations\n\n```mermaid\nflowchart LR\n    Decision[Architectural<br/>claim] -->|search web<br/>before drafting| Sources[Primary sources<br/>docs · RFCs · repos]\n    Sources --> ResearchFile[research/topic.md<br/>+ citation block]\n    ResearchFile --> PlanFile[plan/01-architecture.md<br/>links to research file]\n    PlanFile -->|Phase 6 lint| Density[Citation density<br/>check]\n    Density -->|gap found| Decision\n\n    style Sources fill:#fff4cf,color:#000\n    style Density fill:#ffd4d4,color:#000\n```\n\n| What counts | What does not |\n|---|---|\n| Official docs (anthropic.com, mdn, rfc-editor.org) | Random Medium articles |\n| Primary repos (github.com/owner/repo source) | SEO blog farms |\n| Well-known engineering blogs | LLM training memory |\n| RFCs and standards | Paraphrased recall |\n| Conference talks with slides or transcripts | \"I think\" claims |\n\nIf Bleu catches itself thinking \"I just knew that,\" the lint pass forces it to stop and search instead. Training knowledge is stale on tooling.\n\n## Operating principles\n\nThe 14 constraints Bleu holds for the entire session.\n\n| # | Principle | The bet |\n|---|---|---|\n| 1 | Plan, do not code | No implementation before sign-off |\n| 2 | Be proactively suggestive | Challenge weak assumptions, propose alternatives |\n| 3 | Continuous research is mandatory | Cite the source, never paraphrase from memory |\n| 4 | Files outlast context | The conversation is ephemeral; the workspace is the deliverable |\n| 5 | Treat chat as stateless, workspace as stateful | Anthropic Agent SDK's own guidance |\n| 6 | Lint relentlessly | Done = you say it is near perfect |\n| 7 | Adversarial evaluation | Different agent for proposing and validating |\n| 8 | Write for the gap, not the overview | Every line earns its place |\n| 9 | Audit the harness as models improve | Yesterday's workarounds are today's dead weight |\n| 10 | Contamination control | Human-curated artifacts stay outside `blueprint/` |\n| 11 | Start simpler than you think you need | Most blueprints do not need advanced features |\n| 12 | Match granularity to scope | 3 APs for small, ~38 for greenfield |\n| 13 | Ground truth beats LLM opinion | Tests, compilers, linters, the filesystem |\n| 14 | The Curator owns the wiki | You source inputs, the agent does the bookkeeping |\n\n## Handoff to your executor\n\n```mermaid\nflowchart TD\n    Locked[Phase 7<br/>Blueprint locked] --> Choose{Pick executor}\n    Choose -->|1| GSD[\"/gsd:new-milestone<br/>Get Stuff Done\"]\n    Choose -->|2| SP[\"/superpowers<br/>plans + checkpoints\"]\n    Choose -->|3| CC[Raw Claude Code<br/>direct execution]\n    Choose -->|4| List[Just the AP list<br/>drive yourself]\n\n    GSD --> Artifact[handoff/gsd.md<br/>references blueprint files]\n    SP --> Artifact2[handoff/superpowers.md]\n    CC --> Artifact3[handoff/claude-code.md]\n    List --> Artifact4[handoff/ap-list.md]\n\n    Artifact --> Auto{Slash command<br/>available?}\n    Artifact2 --> Auto\n    Artifact3 --> Auto\n    Auto -->|yes| Invoke[Bleu offers<br/>to invoke directly]\n    Auto -->|no| Manual[You run it yourself]\n```\n\nThe 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.\n\n## Claude Code integration (optional)\n\nWhen Bleu detects it is running inside Claude Code, it offers four integrations as a menu (never silently).\n\n| Integration | What it does | Trigger | Cost |\n|---|---|---|---|\n| **Hooks** | `SessionStart` loads index + health into context. `FileChanged` queues raw inputs for the Curator. `PreCompact` backs up the transcript. `Stop` runs git auto-commit | Configured in `.claude/settings.json` | Negligible |\n| **KB Curator subagent** | Three modes (compile, lint, index). Hooks scoped to its own lifecycle. Tools whitelisted. `memory: project` for persistent learnings. Optional `isolation: worktree` for destructive lint passes | `.claude/agents/kb-curator.md` | One file |\n| **Git auto-commits** | `Stop` and `SubagentStop` hooks stage `blueprint/` and commit asynchronously. Loop-protected. Distinct author. `git log -- blueprint/` recovers any phase | `.claude/hooks/git-autocommit.sh` | One shell script |\n| **MCP servers** | Filesystem scoped to `blueprint/`, git, docs-fetch (e.g. context7), domain MCPs. Inline-scoped to the Curator so tool descriptions do not pollute the parent context | `.claude/.mcp.json` or inline in Curator frontmatter | Optional |\n\nBleu always shows you the files it would create **before** writing them.\n\n## Advanced architecture (opt in, layered on top)\n\nBeyond the base wiki and Claude Code integration, the workspace can become a self-improving system. Each capability is independent. Pick any subset.\n\n| # | Capability | What it gives you |\n|---|---|---|\n| 1 | **Reflection loop** | Linter agent nominates new rules. Auditor agent (different agent) validates before they enter the schema. Self-improving wiki, human steers the rules |\n| 2 | **Structure layers** | Knowledge graph at `.graph/graph.json` overlaid on markdown for backlinks. Episodic memory (`raw/`) split from semantic memory (`plan/`, `research/`) with bidirectional links |\n| 3 | **Agent team** | Four locked-tool subagents: Researcher, Curator, Linter, Auditor. Hand off through files via hook-driven transitions. Proposer-validator enforced |\n| 4 | **Schema as code** | Rules in `.claude/rules/blueprint-schema.md`, auto-loaded when any `blueprint/` file is accessed. ERROR violations block sign-off. Co-evolves via reflection loop |\n| 5 | **Multimodal ingest** | PDFs, images, screenshots dropped in `raw/` get described and compiled. Generated diagrams live in `derived/` (regenerable, gitignored) |\n| 6 | **Observability** | `.telemetry/events.jsonl` + wiki health score (0 to 100) in `.telemetry/health.md`. Computed from coverage, linkage, citation density, lint debt, reflection freshness. Surfaced on every `SessionStart` |\n| 7 | **External integrations** | MCP servers ingest GitHub PRs/issues, Linear/Jira tickets, meeting transcripts, web search results into `raw/` automatically |\n\n### Recommended adoption order\n\n```mermaid\nflowchart LR\n    A[Base workflow] --> B[Reflection loop<br/>+ schema-as-code]\n    B --> C[Observability]\n    C --> D[Agent team]\n    D --> E[Graph + memory split]\n    E --> F[Multimodal]\n    F --> G[External<br/>integrations]\n\n    style A fill:#d4f5d4,color:#000\n    style G fill:#e8d4ff,color:#000\n```\n\nDo not take all seven on day one.\n\n## Reference files\n\nEight reference files at `references/`. Loaded lazily, only when relevant.\n\n| File | When Bleu reads it |\n|---|---|\n| `knowledge-base-pattern.md` | Phase 0/1, before creating workspace files |\n| `session-persistence.md` | First session of any new blueprint, every resume |\n| `action-point-template.md` | Phase 5, before writing APs |\n| `research-and-citations.md` | Phase 1, every research pass |\n| `handoff-formats.md` | Phase 7, when packaging for executor |\n| `claude-code-integration.md` | When inside Claude Code and user wants automation |\n| `advanced-architecture.md` | When user asks for any of the 7 capabilities |\n| `landscape-research.md` | When justifying design choices, citing frontliner teams (PubNub, Effloow, EPAM, Anthropic Labs, ETH Zurich) |\n\n## When to use Bleu\n\n| Use it when | Skip it when |\n|---|---|\n| Starting a substantial system | One-off bugfix or 5-line tweak |\n| Long project across multiple sessions | You already have a complete spec, just want to execute |\n| Want every decision cited and ADR'd | Throwaway prototype where plan = code |\n| Need a clean handoff to GSD/Superpowers/CC | Single afternoon of pair programming |\n| Want to survive `/clear` and crashes | The whole task fits in one chat turn |\n\n## Why Bleu makes long-running autonomous work safe\n\nFrontliner teams that adopted spec-driven workflows (PubNub, Effloow, EPAM) report:\n\n> 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.\n\nPlan in files, not chat. Cite primary sources. Lint relentlessly. Survive context resets. Hand off cleanly.\n\n## Repository layout\n\n```\nBleu-plugin/\n├── .claude-plugin/\n│   └── marketplace.json              marketplace catalog\n├── plugins/\n│   └── bleu/                         the distributed plugin (this is what installs)\n│       ├── .claude-plugin/\n│       │   └── plugin.json           plugin manifest\n│       └── skills/\n│           └── bleu/\n│               ├── SKILL.md          the skill itself\n│               └── references/       eight reference files\n├── scripts/bleu/                     dogfood: deterministic Python core + tests\n├── .claude/                          dogfood: hook adapters + example settings (not active)\n├── blueprint/                        dogfood: the workspace Bleu built for itself\n├── README.md\n├── LICENSE                           MIT\n└── .gitignore\n```\n\nOnly `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.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n\n## Author\n\nNirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05))\n\n## Core Contributors & Maintainers\n\n- Nirvaan Lagishetty ([@Nirvaan05](https://github.com/Nirvaan05)) - creator, maintainer\n- Hill Patel ([@STiFLeR7](https://github.com/STiFLeR7)) - core contributor, maintainer\n\n## Contributing\n\nOpen an issue or PR. Version bumps go in **both** `marketplace.json` and `plugin.json` and must agree.\n",
  "bytes": 20179,
  "sha": "62bcbc3318697182ac2534ada302dd776983b849cea178a671abc37c13e195b9",
  "repo_slug": "nirvaan05/bleu-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nirvaan05_bleu_plugin_bleu_b198f81c/readme"
}