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.

Field	How to fill
Branch	Current branch name
Target	Branch to merge into. Default: detected via reflog parent (see below), falling back to main. Override only when intentionally retargeting. /ship reads this field.
Created	Today's date (YYYY-MM-DD)
Status	In Progress
Threat model	See selection table below
Scope ceiling	Keep template defaults (400/6 soft, 800/10 hard)
Task	1-3 sentences: what and why
Steps	Checkbox list of concrete implementation steps
Confidence Scaffold	Required for adversarial. Recommended for complex advisory.
Outcomes & Learnings	Leave empty — populated by /archive

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

Signal	Model
Internal tooling, refactor, docs, tests, config	advisory
Auth, secrets, input validation, CI, hooks, permissions	adversarial
Unsure	adversarial

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)