Bleu

Bleu

Turn an idea into a fully thought-through, deeply structured system plan - from architecture down to file-level execution - before any code is written. The output is a navigable knowledge base, not a single document: raw inputs compiled by an LLM into an interlinked markdown wiki, with lint passes to heal gaps. No RAG, no vector store, no embeddings - the whole plan fits in a modern context window and every claim is traceable to a file a human can open, edit, or delete.

The goal: by the end, the user can visualize the entire execution flow, catch expected-vs-actual mismatches early, and start implementation with zero ambiguity.

Why this skill exists

Most "planning" with an LLM is one-shot: ask for an architecture, get a wall of text, lose it next session. This skill replaces that with a persistent, LLM-maintained planning wiki that grows, lints itself, and survives context resets. It's deliberately heavy on structure because the failure mode of light planning is discovering the architectural hole in week three.

The strongest single argument for the skill, worth memorizing:

> The tedious part of maintaining a knowledge base is not the reading or the thinking - it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass.

That's the bet. Every other design choice in this skill serves it. Frontliner teams that have adopted spec-driven workflows (PubNub, Effloow, EPAM) report that the safe delegation window expands from 10–20 minute tasks to multi-hour feature delivery once a real plan exists in files the agent can re-read. That's the value proposition: planning before code is what makes long-running autonomous work safe enough to actually leave running.

It also assumes the user wants ~38 action points (or thereabouts) - meaning the plan must be decomposed deeply enough that each AP is an executable unit with named files, named functions, and explicit dependencies. Anything vaguer than that and the skill isn't done yet. The number is a granularity guideline, not a quota - small projects should have fewer APs. The Phase 0 intake sizes the workflow to the project. Don't sledgehammer a nut.

For the deeper context behind every design choice, including citations to the frontliner research that informed this skill, see references/landscape-research.md.

Operating principles

Hold these the entire time. They override any instinct to move faster.

• Plan, don't code. No implementation until the blueprint is signed off. If the user drifts toward "just start coding," remind them once, then comply if they insist.
• Be proactively suggestive, not reactive. Think like a system architect, a senior engineer, and a product thinker simultaneously. Challenge the user's assumptions where they're weak. If you spot a better approach, surface it with a comparison and a recommendation - don't wait to be asked.
• Continuous web research is mandatory. Not a one-time pass. Every phase researches what's relevant to that phase. Every claim that came from research gets a citation. See references/research-and-citations.md.
• Files outlast context. Everything goes into the planning workspace as markdown. The conversation is ephemeral; the workspace is the deliverable.
• Treat the chat as stateless and the workspace as stateful. Chats die - context windows fill, the user runs /clear, terminals crash. Anthropic's own Agent SDK docs are explicit on this: don't rely on session resume, capture results to disk and rehydrate from disk in fresh sessions. Every session ends with the persistence ritual (Phase R): journal entry, ADRs for any new architectural decisions, rewritten SESSION.md and NEXT.md. Every session starts by reading those same files first. See references/session-persistence.md.
• Lint relentlessly. Iterate until gaps, edge cases, and architectural flaws are surfaced and either resolved or explicitly logged as open questions. "Done" means the user agrees it's near-perfect, not that you ran out of ideas.
• Adversarial evaluation, not self-evaluation. Anthropic's harness research surfaced the canonical pitfall: "agents tend to respond by confidently praising the work - even when, to a human observer, the quality is obviously mediocre." Whenever this skill spawns a separate validator (Auditor, Linter, evaluator hook), it must be a different agent from the one that produced the work. Same agent both proposing and approving = self-praise. Production teams from Anthropic to PubNub enforce this strictly.
• Write for the gap, not the overview. ETH Zurich's AGENTbench paper (Feb 2026) found that LLM-generated CLAUDE.md files actively reduce coding agent success rates by ~3% and inflate cost by 20+%, because they restate things the agent could already infer from package.json and the README. The same principle applies inside the blueprint: when the Curator writes a plan file, every line should encode something the reader couldn't infer from the raw inputs. Every restated fact is taking attention away from a missing one.
• Audit your harness as models improve. From Anthropic's harness post: "Are you running complex context management because the model actually needs it, or because you designed the system six months ago when the model did need it?" When the user upgrades models, revisit which scaffolding is still load-bearing and which is dead weight. Sonnet 4.5 needed context resets; Opus 4.6 dropped them. Don't carry yesterday's workarounds into tomorrow's runs.
• Contamination control. Keep human-curated artifacts (README.md, ADRs, the actual codebase) separate from blueprint/. The blueprint is the LLM's domain - high volume, agent-edited, safe to rewrite. Mixing the two leads to either silent overwrites of human work or the agent treating its own output as ground truth.
• Start simpler than you think you need to. Across every frontline source, the loudest message is the same. Anthropic's "Building Effective Agents" post: "Most tasks need Pattern 1 (single specialist). Add complexity only when it demonstrably improves results." The Claude Code best-practices catalogue: "Despite multi-agent systems being all the rage, Claude Code has just one main thread. I highly doubt your app needs a multi-agent system." The base file-only workflow in this skill is the path for most blueprints. references/claude-code-integration.md and references/advanced-architecture.md exist for the cases where they actually pay off - substantial blueprints that will be revisited frequently - not as defaults.
• Match granularity to scope. From Augment's research, multi-file tasks accuracy is ~19% versus single-function tasks at ~87%. Smaller scope dramatically improves agent success rate. Anthropic's harness research adds: doubling task duration quadruples the failure rate, and every agent degrades after ~35 minutes of human time. The ~38 action point target assumes a substantial system; the Phase 0 intake explicitly chooses coarse decomposition (3–5 APs) for small jobs and fine decomposition (~38 APs) for greenfield systems. Don't sledgehammer a nut, and don't tweezer a tree.
• Ground truth beats LLM opinion. From the Anthropic agent-patterns catalog: "Use test results, compiler output, linters - not just LLM self-evaluation - to validate work." Whenever the Linter or Auditor runs, it should consult .claude/rules/blueprint-schema.md and the actual filesystem state, not vibe-check the proposals. Same applies to research: cite the source, don't paraphrase from memory.
• The Curator owns the wiki, not you. The core rule: you rarely ever write or edit the wiki manually - it's the domain of the LLM. If you ever find yourself writing blueprint/plan/ files directly instead of using the Curator (or being the Curator yourself), something's gone wrong with the workflow. The user should be sourcing inputs and asking questions; the agent should be doing the bookkeeping.

The workspace

This skill organizes the plan as a markdown knowledge base on disk - an evolving markdown library compiled and maintained by the LLM, with no vector DB, no chunking, no embeddings. Read references/knowledge-base-pattern.md before creating the workspace - it explains the layout and why it's shaped this way.

Default layout:

blueprint/
├── README.md                  ← entry point + how to navigate
├── SESSION.md                 ← current snapshot - read this FIRST on resume
├── NEXT.md                    ← imperative next actions - read SECOND on resume
├── journal.md                 ← append-only session history
├── index.md                   ← compact summary of every file (the "wiki index")
├── decisions/                 ← MADR-style ADR log, append-only
│   ├── README.md              ← ADR index with status table
│   ├── ADR-001-.md
│   ├── ADR-002-.md
│   └── ...
├── raw/                       ← raw inputs: user transcript, research dumps, code excerpts, links
├── plan/
│   ├── 00-vision.md           ← problem, goals, non-goals, success criteria
│   ├── 01-architecture.md     ← system diagram, layers, data flow, key decisions
│   ├── 02-pipelines.md        ← every pipeline/flow end-to-end
│   ├── 03-components/         ← one file per component
│   │   ├── component-name.md  ← logic, responsibilities, dependencies, interfaces
│   │   └── ...
│   ├── 04-data-model.md       ← entities, schemas, storage, migrations
│   ├── 05-integrations.md     ← external services, APIs, auth, rate limits
│   ├── 06-non-functional.md   ← perf, security, observability, cost, scaling
│   └── 07-risks-open-questions.md
├── action-points/             ← ~38 APs, one file each (AP-01-.md … AP-38-.md)
├── research/                  ← web research notes with citations, one file per topic
└── outputs/                   ← query responses and synthesized reports the user asked for

You don't have to materialize every folder upfront - create files as you go. But the structure should converge on this shape.

Session persistence is non-negotiable. SESSION.md, NEXT.md, journal.md, and decisions/ exist so the workspace survives /clear, terminal crashes, and context-window resets. Treat the chat as stateless and the workspace as the source of truth - Anthropic's own Agent SDK docs recommend this over relying on built-in session resume. Every session ends with the persistence ritual (see Phase R below). Read references/session-persistence.md for the full pattern, ADR template, and resume protocol.

outputs/ is the third top-level directory in the canonical raw/ → wiki/ → outputs/ layout. The Curator never writes here. The user does - every time they ask "explain this component to me" or "give me a one-page summary for the team", that response gets saved as a markdown file in outputs/ so every query has a persistent, auditable record. This is how queries become artifacts instead of evaporating with the conversation.

The phased workflow

The phases are sequential by default, but loop back freely. Lint is not a final step; it runs after every phase.

Phase 0 - Intake and framing

The user gives you the idea. Before doing anything else:

1. Restate the idea in your own words in 3–5 sentences. Force the user to confirm or correct. Most plans fail here, not later.
2. Surface the unknowns. What don't you know yet that you'd need to plan well? Users, scale, stack constraints, deadlines, team size, deployment target, budget, regulatory context. List them.
3. Ask 2–4 sharp questions to fill the biggest gaps. Use yes/no or pick-one format where possible. Don't drown the user.
4. Confirm scope. Is this a greenfield system? A redesign? A feature inside an existing codebase? The blueprint shape changes based on this.

Output of Phase 0: blueprint/raw/intake.md with the restated idea, the user's clarifications, and the agreed scope.

Phase 1 - Initial research pass (web + code, if a codebase exists)

Now ground yourself. This is the first of many research passes.

Web research (mandatory): For the domain, the stack, and the architectural pattern, find current best practices, known gotchas, recent shifts, and reference implementations. Prioritize primary sources (official docs, RFCs, repos, well-known engineering blogs) over content farms. Save findings to blueprint/research/.md with citations. See references/research-and-citations.md for the citation format.

Code research (only if a codebase already exists): Read the relevant files. Capture real names, paths, patterns, and dependencies into blueprint/raw/codebase-notes.md. The grounding rule from prompt-forge applies: every file path or symbol that ends up in the blueprint must come from actually reading the code, not guessing.

Before moving on, write a 1-paragraph synthesis at the top of each research file: what did you learn, and how does it change the plan you're about to draft?

Phase 2 - Vision, architecture, pipelines

Research before drafting, not after. Every architectural decision in this phase makes a claim about how something works in the current ecosystem (which queue, which file watcher, which storage, which library, which pattern). Each claim needs grounding. Before you write 01-architecture.md:

1. List the architectural choices you're about to make (queue mechanism, concurrency model, storage, file-watching, deployment, etc.).
2. For each one you can't already cite from a research/*.md file, run a targeted web search and write the findings into research/.md with the citation format from references/research-and-citations.md.
3. Then draft the architecture file, with each decision linking back to its research/ file.

If you find yourself writing "I'll use X because [reasoning from training knowledge]," stop and search. Training knowledge is stale on tooling. The whole point of the skill's continuous-research principle is that no architectural claim survives Phase 6 lint without a citation - so you may as well do the research now, when it can shape the decision, instead of later, when it can only invalidate it.

Draft these in order. Each file should be tight and opinionated, not a list of options.

• 00-vision.md - Problem statement, target users, goals, explicit non-goals, success criteria (measurable where possible).
• 01-architecture.md - High-level system. Include an ASCII or mermaid diagram. Name every layer and every major component. State the key architectural decisions and the alternatives you rejected (with reasoning). Each decision links to its research/ file.
• 02-pipelines.md - For every flow in the system (e.g., "user signs up", "ingest job runs", "report generates"), write the end-to-end sequence: trigger → components touched → data transformations → outputs → failure modes. Don't skip the boring ones.

After drafting, lint (see "Linting" section below) and update index.md.

Phase 3 - Component breakdown

For every component identified in 01-architecture.md, create plan/03-components/.md containing:

• Purpose - one sentence
• Responsibilities - bulleted, exhaustive, scoped narrowly enough that two components don't overlap
• Logic - how it actually works inside; the algorithm or state machine in prose
• Inputs / Outputs - exact shapes (types, schemas)
• Dependencies - what it calls, what calls it; link to other component files
• Failure modes - what can go wrong, how it's handled
• Open questions - anything unresolved

If two components have unclear ownership of a responsibility, that's a lint failure. Resolve it before moving on.

Phase 4 - Data model, integrations, non-functional

• `

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nirvaan05
• Source: Nirvaan05/Bleu-Plugin
• License: MIT
• Homepage: https://github.com/Nirvaan05/Bleu-plugin#install

Install and usage instructions live in the source repository linked above.