blueprint

Blueprint

No code until the implementation design is approved. blueprint turns a clear ticket/spec/phase into an implementation approach. It does not decide what product should exist; spec does that.

Use this when:

• Desired behavior is known
• You need to choose an implementation approach
• You need to identify files/modules/data flow/tests
• A spec or break-spec phase is ready for implementation design

Do not use this when:

• The problem, user/workflow, or success criteria are unclear — route to spec
• The work is too large for one coherent PR — route to break-spec

Do NOT write any implementation code, scaffold, or take implementation actions until you have presented an implementation design and the user has approved it. This is non-negotiable.

Process

1. Load context — if a handoff artifact exists in plans/ (spec, PRD, phase structure), read it as your primary input. Otherwise, check relevant files, docs, recent commits.
2. Requirements check — if product behavior or acceptance criteria are unclear, stop and route to spec with the missing questions. Do not patch over vague requirements with implementation guesses.
3. Scope check — if the work is too large for one coherent PR, stop and route to break-spec.
4. Ask implementation questions one at a time — prefer multiple choice. Focus on architecture, data flow, boundaries, edge cases, and tests.
5. Propose 2–3 implementation approaches — include trade-offs and your recommendation. Lead with the recommended option and say why.
6. Present the design — scale to complexity. A few sentences for simple changes, detailed sections for complex ones. Get approval section by section. Offer: "Want to stress-test this design before we finalize?" (invokes poke-holes).
7. Write design artifact — for multi-file, phase-originated, or spec-originated work, write plans/<feature>-design.md capturing current state, desired state, patterns followed, decisions resolved, open questions. Skip for small changes unless the user wants a file.
8. Transition — normally invoke implement to create the implementation plan. If invoked by kickoff, return the approved design to kickoff instead; kickoff must record discoveries and update the ticket first.

Scaling to Complexity

• Small change (config, rename, simple fix): 1–2 questions, 1 paragraph design, no artifact unless useful.
• Medium feature (new component, API endpoint): architecture + data flow + testing approach.
• Large feature (new subsystem, multi-file): route to break-spec before implementation design.

In Existing Codebases

• Explore current structure before proposing changes. Follow existing patterns.
• If existing code has problems that affect the work, include targeted improvements in the design.
• Don't propose unrelated refactoring.

Principles

• Implementation design, not product shaping — route vague product questions to spec.
• One question at a time — don't overwhelm.
• YAGNI ruthlessly — remove unnecessary features from designs.
• Explore alternatives — always propose 2–3 approaches before settling.
• Incremental validation — present design, get approval before moving on.

Terminal State

The only normal next step after design approval is implement. Do not invoke unrelated implementation skills. If kickoff invoked this skill, return control to kickoff with the approved design.