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, approved Work Contract, 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
• scope_classification.kind is multi_slice, project, or unknown without an approved selected phase/slice — route to break-spec or spec refinement as appropriate

If the repo declares custom lifecycle hooks, read ../lifecycle-hooks.md and honor any phase-boundary hooks before and after blueprint.

When beislid:agent_isolation is configured, design discussion remains read-only, but before the first repo artifact write load ../implement/workspace-placement-protocol.md plus the current host adapter and run ensure_orchestrator_workspace. Require a clean source and acknowledged destination for a requested top-level transition; stop with manual-transition-required before lifecycle writes when the host cannot prove it.

Process

1. Load context — if the handoff includes an explicit Work Contract, spec/PRD, or phase artifact path, read it as your primary input. Otherwise, if the matching spec_approved or break_spec_approved latest pointer entry for the current ticket/branch resolves to a readable artifact, read that artifact as your primary input; if not, use the workflow-configured artifact path template when present, then if a handoff artifact exists in plans/ (Work Contract, spec, PRD, phase structure), read it as your primary input. Otherwise, check relevant files, docs, recent commits. Optional visual routing: only when repo-level beislid:visual_surfaces config exists and the effective blueprint mode is active, load visual-surface-protocol.md; it mirrors canonical .beislid/visual-surface-protocol.md for copied installs.
2. Requirements check — if product behavior or acceptance criteria are unclear, stop and route to spec with the missing questions. When a Work Contract is present, proceed only when Status is approved; route draft or needs-human-decision back to spec. Treat unknowns as blocking when they affect implementation approach or acceptance criteria. Verify scope_classification has the seven #56 keys (kind, confidence, rationale, recommended_route, requires_human_approval, requires_split, split_reason), proof_requirements is a list (possibly empty), and reserved slots still match defaults (slice_plan: null, children: []) unless later tickets explicitly populated them. Broad/project work should not jump directly to scaffolding by default. Do not patch over vague requirements with implementation guesses.
3. Scope check — use scope_classification when present. atomic and single_pr may proceed. multi_slice must route to break-spec unless a selected phase/slice is already provided. project must route to spec refinement/project boundary approval first in P0, then slice planning; do not scaffold by default. unknown or low-confidence high-consequence classifications route back to spec for refinement.
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, but keep progress prose context-only and ask the blocking question only once in the final response. Offer the stress-test option only as a final-response action when appropriate; choosing it invokes poke-holes. Optional Lavish design surface: if Step 1 found active beislid:visual_surfaces routing, apply visual-surface-protocol.md at this approval/choice/revision boundary when a visual plan, comparison, architecture/data-flow diagram, option table, or risk/test matrix materially improves understanding. Keep small/linear designs Markdown-first, but for large changes comparable to work that benefits from walk-the-diff, lean toward suggesting or prompting for the surface rather than skipping it. Respect suggest/prompt/auto exactly; absent config or off must not mention or invoke Lavish. Use the protocol's plan, comparison, diagram, and input guidance with a typed BEISLID_VISUAL_FEEDBACK_V1 gate for workflow: blueprint, action approve_revise_or_choose_blueprint, and decisions approve, revise, or choose (choose requires selected_option). Copy accepted visual approvals, revisions, or choices into the canonical Markdown/chat design record before proceeding; visual controls never bypass explicit blueprint approval before implement.
7. Run blueprint_approved lifecycle actions - after the design is approved and any configured orchestrator placement gate passes, execute configured artifact and CLI lifecycle actions for the approved design. Do not auto-write design files or run ad-hoc side effects outside this lifecycle behavior in configured repos.
8. Transition — normally invoke implement to create the implementation plan and include any lifecycle status/path. If invoked by kickoff, return the approved design plus lifecycle status/path to kickoff instead; kickoff must record discoveries and update the ticket first.