Blueprint

World-class software engineering and agentic engineering, encoded as a workflow agents can follow.

Blueprint is the SDLC done right for AI coding agents. Design when architecture is ambiguous. Spec when decisions matter. Plan when work needs splitting. Test before ship. Refactor when code needs simplifying. Review before merge. Drive PR feedback to merge-ready with judgment. The practices excellent engineering teams have always followed, distilled into focused skills an agent can execute reliably — as single steps you drive yourself, or as loops that run a whole ticket end to end.

It is the deliberate opposite of guardrail-heavy frameworks that try to constrain agents into producing good work. Blueprint bets on the model and encodes the workflow. Every model improvement makes that bet pay off more, not less.

Principles

• Encode process, not knowledge. Skills are workflows. Reference material lives elsewhere.
• Verification is non-negotiable. Tests prove the requested behavior. Browser-rendered work is checked in a real browser. Review checks the proof is real.
• Bet on the model. Smart agents, not heavy guardrails. Every model improvement makes guardrails less necessary and more likely to conflict with the model's own judgment.
• Density over length. Skills are as short as they can be while remaining clear.
• Focused skills, not sprawling catalogues. Saying no is the discipline.

The Shape

The Flow

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, ui-sans-serif, system-ui", "fontSize": "18px", "primaryTextColor": "#f8fafc", "tertiaryTextColor": "#f8fafc", "lineColor": "#94a3b8", "edgeLabelBackground": "#020617"}}}%%
flowchart TD
    Request([Feature, bug, or brief])

    Ambiguous{Architecture<br/>ambiguous?}
    Design["design-doc<br/>options + tradeoffs<br/>chosen direction"]
    SpecGate{Decisions,<br/>contracts,<br/>or invariants?}
    Spec["spec<br/>requirements + design<br/>human review"]
    Split{Needs<br/>splitting?}
    Plan["plan<br/>agent-sized tasks<br/>acceptance criteria"]
    Direct["one scoped task<br/>acceptance criteria"]
    Handoff["tasks / tickets<br/>reviewable handoff"]

    Count{How many<br/>tickets?}
    Single["task-to-pr<br/>branch -> implement<br/>review -> pr"]
    Multi["multitask<br/>classify, isolate<br/>coordinate workers"]
    PRs["draft PRs<br/>tests, review<br/>evidence"]
    Ready["pr-to-ready<br/>feedback to merge-ready<br/>never merge"]

    Request --> Ambiguous
    Ambiguous -->|yes| Design --> Spec
    Ambiguous -->|no| SpecGate
    SpecGate -->|yes| Spec
    SpecGate -->|no| Split
    Spec --> Split
    Split -->|yes| Plan --> Handoff
    Split -->|no| Direct --> Handoff
    Handoff --> Count
    Count -->|one| Single --> PRs
    Count -->|many| Multi --> PRs
    PRs --> Ready

    classDef start fill:#0f172a,stroke:#38bdf8,stroke-width:3px,color:#f8fafc,font-size:18px;
    classDef decision fill:#431407,stroke:#fb923c,stroke-width:3px,color:#ffedd5,font-size:18px;
    classDef decide fill:#172554,stroke:#60a5fa,stroke-width:3px,color:#eff6ff,font-size:18px;
    classDef handoff fill:#4c1d95,stroke:#a78bfa,stroke-width:3px,color:#faf5ff,font-size:18px;
    classDef deliver fill:#052e16,stroke:#4ade80,stroke-width:3px,color:#f0fdf4,font-size:18px;
    classDef feedback fill:#831843,stroke:#f472b6,stroke-width:3px,color:#fdf2f8,font-size:18px;

    class Request start;
    class Ambiguous,SpecGate,Split,Count decision;
    class Design,Spec,Plan,Direct decide;
    class Handoff handoff;
    class Single,Multi,PRs deliver;
    class Ready feedback;

If implementation reveals the instructions are wrong, stop. Update the task, spec, or plan, then continue from the updated source. Do not push through stale instructions. Clarifying costs minutes; pushing through wrong instructions costs the rest of the feature.

Tests are the default verification. Blueprint does not run a separate "did the implementation match the instructions?" pass. The request or spec defines the testing strategy. The implementation produces tests that prove the requirements. Browser-rendered work also gets checked with browser-verify. Review checks the proof is real and not theatre. If you want stronger verification, write the additional concerns into REVIEW.md; the review skill will pick them up.

The Loops

The skills above are steps: one phase, one human checkpoint. Three skills chain the steps into end-to-end loops:

Loops keep the ticket updated as they work — status moves, comments with verification evidence, PR links — and stop at human checkpoints. Merging is always a human decision.

task-to-pr is the single-ticket loop: it resolves the ticket, creates a branch, implements the acceptance criteria, reviews the diff, opens a draft PR, and writes evidence back to the ticket.

multitask is the coordinator-worker loop for several tickets at once:

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, ui-sans-serif, system-ui", "fontSize": "18px", "primaryTextColor": "#f8fafc", "tertiaryTextColor": "#f8fafc", "lineColor": "#94a3b8", "edgeLabelBackground": "#020617"}}}%%
flowchart TD
    Tickets["ticket list<br/>LIN-101<br/>LIN-102<br/>LIN-103"]
    Coordinator["multitask coordinator<br/>read tickets + touched code<br/>classify independence"]
    Decision{Independent?}
    Parallel["parallel lanes<br/>separate worktrees<br/>separate branches"]
    Sequential["sequential lane<br/>shared files, schema<br/>or assumptions"]

    WorkerA["worker A<br/>task-to-pr LIN-101"]
    WorkerB["worker B<br/>task-to-pr LIN-102"]
    WorkerC["worker C<br/>task-to-pr LIN-103"]
    WorkerD["worker<br/>task-to-pr in order"]

    Fleet["fleet report<br/>ticket, branch, PR<br/>status, evidence"]
    Human["human review<br/>merge decision stays human"]

    Tickets --> Coordinator --> Decision
    Decision -->|yes| Parallel
    Decision -->|overlap| Sequential
    Parallel --> WorkerA
    Parallel --> WorkerB
    Parallel --> WorkerC
    Sequential --> WorkerD
    WorkerA --> Fleet
    WorkerB --> Fleet
    WorkerC --> Fleet
    WorkerD --> Fleet
    Fleet --> Human

    classDef input fill:#0f172a,stroke:#38bdf8,stroke-width:3px,color:#f8fafc,font-size:18px;
    classDef coordinator fill:#4c1d95,stroke:#a78bfa,stroke-width:3px,color:#faf5ff,font-size:18px;
    classDef decision fill:#431407,stroke:#fb923c,stroke-width:3px,color:#ffedd5,font-size:18px;
    classDef lane fill:#172554,stroke:#60a5fa,stroke-width:3px,color:#eff6ff,font-size:18px;
    classDef worker fill:#052e16,stroke:#4ade80,stroke-width:3px,color:#f0fdf4,font-size:18px;
    classDef report fill:#831843,stroke:#f472b6,stroke-width:3px,color:#fdf2f8,font-size:18px;

    class Tickets input;
    class Coordinator coordinator;
    class Decision decision;
    class Parallel,Sequential lane;
    class WorkerA,WorkerB,WorkerC,WorkerD worker;
    class Fleet,Human report;

Each worker still runs the full task-to-pr workflow for exactly one ticket: branch -> implement -> review -> pr -> ticket update. The coordinator does not edit code; it partitions work, starts isolated lanes, monitors failures, and reports the fleet.

The loops can also run unattended: agents file labeled issues, a scheduled agent claims ready work and runs task-to-pr, and your involvement narrows to approving specs and reviewing PRs. See guides/loops.md.

Invoking Skills

The supported install path is npx skills add owainlewis/blueprint. That installs standalone skills; invoke them by skill name (spec, plan, implement, etc.) or by the skill picker/natural-language flow your agent supports.

Branching and committing are mechanical, but they are still skills so the installer can expose the full workflow consistently.

Removed entry points are not maintained as aliases: requirements is now spec; architecture is now design-doc for architecture docs or spec for implementation instructions; task and build are now implement; coverage is handled through implement when adding tests or review when evaluating them; address-pr-feedback is now pr-to-ready; codex-run-loop is now task-to-pr for one ticket or multitask for several tickets.

Install

npx skills add owainlewis/blueprint

Install Blueprint with the skills CLI. This is the supported setup path; Blueprint does not maintain per-tool skill installation guides.

browser-verify requires Chrome DevTools MCP:

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Update

npx skills update

Run this to update Blueprint and your installed skills to the latest version.

Skills

Agent Instructions

Blueprint creates instructions for agents. Sometimes that instruction is a one-sentence prompt. Sometimes it is an issue tracker item. Sometimes it is a design doc or markdown spec in the repo. The format should match the work.

Design docs default to docs/<design-slug>/design.md: a lightweight architecture artifact for ambiguous decisions, alternatives, tradeoffs, and cross-cutting concerns.

One spec lives at docs/<feature-slug>/spec.md. External requirements flow into it; the spec is the artifact that brings context into the codebase.

Plans are transport, not durable artifacts. They go to exactly one destination: tracker issues when you ask or the repo runs an unattended loop, docs/<feature-slug>/plan.md when there is a feature directory, or chat. When tasks go to the tracker, no plan doc is written; the issues are the plan.

Use the full pipeline for work that touches contracts, schemas, multiple files, or invariants. For trivial changes, just do them. For exploration, explore without manufacturing fake specs, plans, or issue tracker entries.

Philosophy

Specs are prompts with weight. A spec is an instruction with enough structure to make decisions reviewable. Once the code is right, the spec's job is done.

Do not confuse planning with prompting. Professional teams do planning in the systems they already use: issue trackers, docs, design reviews, meetings, and PRs. Blueprint turns that context into the distilled instruction an agent needs.

Compress context. Every word competes for attention. Cut restated rules, overlap, padding, and preamble. Keep constraints, exact names, commands, paths, schemas, and examples that carry meaning.

Agent inputs only. Blueprint is not an issue tracker, architecture review board, or release process. It turns external context into high-quality instructions for coding agents. That's the entire job.

Example

The examples/ folder shows sample Blueprint artifacts.

Design doc example:

• dispatch-control-plane/design.md: a design doc for Dispatch's local agent control plane architecture

Spec and plan examples for a Python RAG chatbot API:

1. input.md: rough project notes
2. spec.md: the spec
3. plan.md: ordered tasks

Learn More

https://www.skool.com/aiengineer