Blueprint

/blueprint

Write the canonical ai-env blueprint (plan file) for the current task. Requires /orient to have run first.

Sequence

1. Check prerequisites. Confirm a worktree exists and /orient has identified the task. If not, stop and tell the user. 2. Brainstorm (one round). Invoke /brainstorming with the task description. One round only — capture direction, do not iterate. 3. Read the template. Read ai-workspace/plans/TEMPLATE.md from the repo root. 4. Write the plan. Create ai-workspace/plans/<branch-slug>.md with ALL template fields. For complex plans, read references/planning-quality.md and apply its checklist without copying the whole reference into the plan.

5. Commit the plan. Stage and commit the plan file before handing off to /review:

   git -C "$WORKTREE" add ai-workspace/plans/<name>.md
   git -C "$WORKTREE" commit -m "blueprint: <name>"

Required because /review works against committed state. A session crash or /clear after writing the plan but before /review runs loses the brainstorming work otherwise. See ADR-008 (refs/wip/checkpoints/<branch> Stop-hook backstop) for the recovery path if this step is skipped.

Detecting the Target

The default Target is the branch this branch was cut from, read from the reflog:

TARGET=$(
  git reflog show HEAD --pretty=format:'%gs' \
    | grep "^branch: Created from" \
    | head -1 \
    | sed 's/branch: Created from //' \
    | sed 's|^origin/||'
)
TARGET=${TARGET:-main}

Falls back to main when the reflog is empty (web sessions, detached-HEAD creation). Use this whenever the user hasn't explicitly named a Target. Pure git — works in any environment without tool installs.

Threat model selection

Guardrails

• Do NOT review the blueprint. That is /review (Step 4).
• Do NOT start implementation. The blueprint is the deliverable.
• Do NOT skip any template field.
• Do NOT proceed to /review without committing the blueprint file first.
• If brainstorming reveals the task is one-sentence scope, say so and skip.
• Scope ceiling values are fixed — do not change them.
• Steps must be concrete actions with checkboxes, not vague phases.
• Include test steps explicitly. When tests need a separate author (TDD contract), list them as distinct tasks from implementation so /build dispatches test-writer and implementer separately.
• Do NOT invoke another planning skill; this skill owns ai-env plan writing.

Output

After writing, report:

Plan written: ai-workspace/plans/<name>.md
Threat model: advisory|adversarial
Steps: <count>
Next step: /review (Step 4)

Planning Quality Reference

Use this reference when /blueprint needs more detail than the base template captures. Keep the active /blueprint skill small; this file holds the reusable quality checks.

Before Writing

• Confirm the task is one coherent workset. If it spans independent subsystems, split it into separate plans before implementation.
• Map the files or surfaces that will change and state what each owns.
• Prefer existing project boundaries. Refactor only when it directly lowers risk for the current work.
• Make each plan step produce reviewable, testable progress.

Step Quality

Good implementation steps are concrete enough for another agent to execute without rediscovering intent.

• Name exact files or directories when they are known.
• Separate test-authoring from implementation when the TDD contract needs a distinct RED/GREEN handoff.
• Include exact validation commands and expected success criteria.
• Avoid placeholders such as TBD, TODO, handle edge cases, or write tests for this.
• Do not use "similar to previous step"; repeat the necessary details so steps can be read independently.

File Structure

• Keep files focused on one responsibility.
• Co-locate files that change together when the repo already supports that shape.
• Follow established local patterns before introducing new structure.
• When touching an oversized or tangled file, include only the split that serves the task.

Self-Review

Before handing off to /review, check the plan against the original request.

• Every requirement maps to a step.
• Every step has enough context to execute.
• Types, command names, file paths, and skill names are consistent throughout.
• Test and validation steps cover the changed behavior.
• The plan contains no placeholders or vague implementation instructions.

Handoff

/blueprint writes and commits the plan, then hands off to /review. Do not offer a separate planning skill choice from this reference.