owainlewis/blueprint

Blueprint helps agents decide what to build, make focused changes, test them, get an independent review, and open pull requests.

Start with the work, not the process

Choose the first skill based on what you need.

Small, decided work can go straight to /task-to-pr. Use /architecture for the system as it works now. Use /design to write a proposal and /architecture-review to challenge important technical choices before implementation. The proposal may be in a design, RFC, ADR, architecture document, or issue. Use /plan only when the work needs splitting.

How Blueprint fits together

flowchart TB
    Existing([Implemented system]) --> Architecture["/architecture"]
    Architecture --> Current["Current architecture"]

    subgraph Decide["Decide only as much as needed"]
        Idea([Idea or problem]) --> Design["/design"]
        Idea -->|already decided| Tasks([Tasks])
        Current -.-> Design
        Design --> Proposal["Technical proposal"] --> ArchitectureReview["/architecture-review"]
        ArchitectureReview -->|findings| Design
        ArchitectureReview -->|approved, one task| Tasks
        ArchitectureReview -->|approved, needs splitting| Plan["/plan"] --> Tasks
    end

    subgraph Deliver["Deliver with /task-to-pr"]
        Tasks --> Order["order and plan"] --> Task["each task"] --> Code["write code"] --> Test["test"] --> Review["subagent review"]
        Review -->|finding| Code
        Review -->|approved| PR["open or update PR"] --> Automated["CI + automated review"]
        Automated -->|finding| Code
        Automated -->|clean| Done([Task done])
    end

Use /architecture when you need to understand or document existing code. Use /improve to simplify code without changing what it does. Not every change needs either skill.

The model has two layers:

1. Repository instructions define policy. AGENTS.md says what good work means in a codebase.
2. Skills define each kind of work. Each skill produces one clear result and has a clear stopping point. /task-to-pr joins the steps needed to deliver code.

The seven phase skills

Writing code is a basic agent ability, not a separate skill. Branching, committing, debugging, browser checks, and feedback are steps inside a workflow.

Tasks to pull requests

skills/task-to-pr/SKILL.md is the single authority for delivery. It accepts one or more tasks, tickets, pull requests, or a milestone. It waits for prerequisite pull requests to merge, can run independent tasks at the same time, and creates one pull request for each task.

For each task, it:

1. creates or reuses a branch and worktree from the latest default branch;
2. writes and tests the code;
3. asks a fresh subagent that did not write the code to review it;
4. opens or updates a pull request with a short summary and proof;
5. waits for configured CI and automated code review, then fixes, reviews, and replies to every finding.

It leaves pull requests open unless the user asks to merge them.

Install

Install all eight skills:

npx skills add owainlewis/blueprint

Upgrading from the older set of skills? Follow the migration guide. A normal update may leave removed skills installed, so the cleanup step matters.

Read the changelog for notable changes.

Repository map

skills/                 seven phase skills and one delivery workflow skill
AGENTS.md                portable repository policy
CLAUDE.md                Claude Code adapter
REVIEW.md                review standard for Blueprint itself
MIGRATION.md             clean upgrade from the old skill set
CHANGELOG.md             notable changes to Blueprint
examples/                reviewed design and planning examples

Examples

The RAG chatbot example follows one idea through the decision flow:

1. rough project notes
2. reviewed design
3. captured chat plan

For a larger system-part specification, read the Dispatch local control-plane design.

Principles

• Give agents the goal and the rules. Give agents outcomes, constraints, and proof. Trust them with local mechanics.
• One skill per phase or delivery outcome. Skills share one installation and invocation model.
• Separate current state from proposals. Architecture documents describe verified implemented reality. Design documents specify future changes.
• Keep changes reviewable. Deliver one focused outcome and its proof. A reviewer should not need to separate unrelated work. Keep refactoring separate when it would hide the behavior change.
• Review choices before code. Surface material ambiguity and ask for a simpler design when it can deliver the same result with less state, indirection, duplication, or operational work.
• Review implementation independently. Check correctness and proof. Do not block on personal taste.
• Proof is part of the work. Test changed behavior and affected failure paths. Test behavior that a refactor must preserve. If automated tests cannot exercise the behavior, explain why and give other evidence.
• Use the real surface. Browser behavior is checked in a browser. Live PR feedback is read from the PR.
• Fix the original instruction. If implementation exposes a bad requirement, update the task or design before continuing.
• Prefer less. Keep the smallest complete change, shortest useful instruction, and no duplicate ways to start the same work.
• Keep irreversible judgment human. Agents prepare the decision. Humans review designs and merge pull requests unless they explicitly delegate it.

Blueprint is not an issue tracker, agent framework, release system, or reviewer-persona library. It is a compact engineering process for capable coding agents.