owainlewis-blueprint

Blueprint

Agentic coding best practices without the complexity.

The Problem with Agentic Coding Frameworks

Every week there's a new Claude Code plugin with 50 skills, 16 review agents, multi-stage orchestration pipelines, and anti-rationalization tables. They look impressive in a demo. In practice, you spend more time configuring the framework than writing software.

These frameworks are built on a flawed assumption: that AI agents are unreliable and need to be constrained with hundreds of lines of rules. So they add guardrails on guardrails — specialized agents watching other agents, complex routing logic, permission matrices — until the tooling itself becomes the bottleneck.

Blueprint takes the opposite stance: agents are smart. Treat them that way.

A clear 50-line skill outperforms a 500-line skill full of warnings and iron laws. The agent spends its attention on your work instead of navigating rules. As models get more capable, heavy frameworks fight the model. Simple workflows ride the improvement curve.

What Blueprint Actually Is

The software development lifecycle, encoded as executable commands:

graph LR
    A[Requirements] --> B[Architecture]
    B --> C[Plan]
    C --> D[Execute]
    D --> E[Refactor / Coverage]
    E --> F[Review]
    F --> G[Ship]

That's it. No agent swarms. No orchestration layer. No configuration files. Ten commands that map to what good engineering teams already do — just faster.

You can read every skill in 10 minutes. Try that with the alternatives.

Install

/plugin marketplace add owainlewis/blueprint
/plugin install blueprint@owainlewis-blueprint

Commands

All document commands take explicit file paths — you decide where things live.

1. Requirements

Turn rough notes into a structured requirements document. The agent acts as a technical PM — it will ask clarifying questions before producing the doc.

/blueprint:requirements REQUIREMENTS.md I need a CLI tool that parses markdown and generates HTML

2. Architecture

Turn a requirements doc into a technical architecture design. Covers system design, components, data flow, key decisions, and file structure.

/blueprint:architecture REQUIREMENTS.md ARCHITECTURE.md

3. Plan

Break an architecture into phased, executable tasks. Each task is self-contained — written so an agent (or engineer) with zero prior context can pick it up and start working.

/blueprint:plan REQUIREMENTS.md ARCHITECTURE.md TASKS.md

4. Task

Pick up a single task and execute it. Accepts a ticket ID from any tracker (Linear, Jira, GitHub) or a plain description. Creates a branch, does the work, verifies the acceptance criteria, and commits.

/blueprint:task LIN-123
/blueprint:task "add rate limiting to the API"

5. Refactor

Refactor code like a senior engineer — simplify, remove dead code, improve clarity. No behavior changes, no new abstractions. The goal is less code, not different code.

/blueprint:refactor
/blueprint:refactor src/api/routes.py

6. Coverage

Evaluate test coverage and fill gaps — but only with tests worth having. Every test must catch a realistic bug. No testing constructors, no mocking for the sake of mocking, no padding coverage numbers.

/blueprint:coverage
/blueprint:coverage src/auth/

7. TDD

Build a feature test-first. Write failing tests that define the behavior, implement the minimum to make them pass, then simplify.

/blueprint:tdd "retry logic for API client"
/blueprint:tdd "user registration endpoint"

8. Review

Review your changes like a senior engineer before shipping. Checks correctness, security, simplicity, and robustness.

/blueprint:review
/blueprint:review src/auth.py
/blueprint:review security

If your project has a REVIEW.md in the root, those concerns are automatically included in every review. This is optional — the review works fine without one, but it's a good way to encode things your team has learned the hard way:

# Review Concerns
- All database queries must use parameterized statements
- API responses must include a request_id for tracing
- No synchronous HTTP calls inside request handlers

Claude Code's built-in /review is designed for reviewing remote PRs, not local changes. The built-in /simplify is heavily JavaScript-oriented. /blueprint:review fills the gap — a language-agnostic local code review that works on your uncommitted changes, in any language, with optional project-specific concerns.

9. Branch

Create a feature branch with conventional naming.

/blueprint:branch feature markdown-parser
/blueprint:branch fix login-redirect

10. Commit

Stage and commit with a conventional commit message. Reviews the diff and writes the message for you.

/blueprint:commit

Philosophy