blueprint

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. Address PR feedback with judgment. The practices excellent engineering teams have always followed, distilled into focused skills an agent can execute reliably.

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

Phase	Skill	What it does
Design	design-doc	Explore architecture, alternatives, and tradeoffs
Define	spec	One document with requirements and design
Plan	plan	Break work into agent-sized tasks
Build	implement / tdd	Execute one task; tests prove acceptance
Improve	refactor	Simplify changed code without changing behavior
Review	review	Correctness, security, simplicity before merge
Feedback	address-pr-feedback	Triage and fix valid GitHub PR feedback
Browser	browser-verify	Check rendered UI, HTML, and visual docs in a real browser

The Flow

flowchart TD
    Start([Feature or task]) --> Architecture{Architecture ambiguous?}
    Architecture -->|Yes| Design[design-doc<br/>architecture, alternatives,<br/>tradeoffs]
    Architecture -->|No| Choice{Needs spec first?}
    Design --> Spec
    Choice -->|Yes| Spec[spec<br/>requirements + technical design<br/>one document]
    Choice -->|No| Implement[implement<br/>do the scoped work]
    Spec --> Plan[plan<br/>write portable task list]
    Plan --> Task[select a planned task]
    Plan -. optional .-> Destination[Push tasks to<br/>the team's issue tracker]
    Destination -.-> Task
    Task --> Implement
    Implement --> Tests[tests pass<br/>tests prove acceptance criteria]
    Tests --> Review[review<br/>correctness, security, simplicity]
    Review --> Decision{instructions still right?}
    Decision -->|Yes| Ship[PR or merge]
    Decision -->|No, drifted| Update[update spec, plan,<br/>or task]
    Update --> Choice
    Ship --> More{More planned tasks?}
    More -->|Yes| Task
    More -->|No| Done([Done])

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.

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.

Some plugin hosts expose namespaced slash commands such as /blueprint:spec. Those commands are aliases for the same skill names; the standalone skill name is the stable vocabulary.