/blueprint

name: blueprint
description: |
  "/blueprint", "blueprint", "task graph", "contract derivation", "execution plan",
  "plan tasks from requirements", "contract-first planning"
  Turn requirements.md into an executable blueprint (plan.json + contracts.md).
  Five phases: Contracts → Tasks → Journeys → Verify Plan → Commit.
  Sits between /specify and /execute. Scope-adaptive (greenfield → bugfix).
  Uses hoyeon-cli (plan.json only; requirements.md is read as-is via Read tool).

blueprint: Requirements → Executable Plan

Overview

Transform `<spec_dir>/requirements.md` (from /specify) into an executable blueprint that /execute can run without rework:

1. **Contract Synthesis** — derive cross-module agreements (types, interfaces, invariants) that keep parallel work safe 2. **Task Graph** — layered DAG (L0 Foundation → L1 Feature → L2 Integration → L3 Deploy) where every sub-requirement has ≥1 fulfilling task 3. **Journey Detection** — identify multi-sub-req user flows that need end-to-end coverage 4. **Verify Plan** — assign verification gates (1=machine, 2=agent_semantic, 3=agent_e2e, 4=human) per sub-req and per journey 5. **Commit** — run cross-ref validation and hand off to /execute

**Contract-first principle**: lock "how modules talk" before anyone writes code. Parallel workers can't break each other's shapes; required invariants are called out explicitly.

**Ask-only-when-owned principle**: prompt the user **only** at decisions they actually own — missing inputs (no spec_dir), conflicting signals with no safe default (meta.type conflict), or real commitments they must make (G4 playtests, flagged `time`/`confidence` ambiguities). Task-graph correctness and final summaries are not user decisions: the coverage gate (2.2) and cross-ref validator (5.1) enforce them mechanically. Print, don't ask.

**Not blueprint's job**: writing source code, running tests, interviewing for missing requirements. If requirements are incomplete, run /specify first.

Runtime Surface

Claude Code

• Use `Agent(subagent_type="...")` for Hoyeon logical subagents such as

`code-explorer`, `contract-deriver`, and `taskgraph-planner`.

• Use `AskUserQuestion` only for user-owned decisions described by this skill.
• Claude hooks may add session context, but blueprint must still leave a valid

`plan.json` on disk through `hoyeon-cli`.

Codex

• Use the same Hoyeon logical subagent names in prompts, but dispatch through

Codex adapters when installed: `hoyeon-code-explorer`, `hoyeon-worker`, `hoyeon-verifier`, and `hoyeon-code-reviewer`.

• Use Bash-first state operations. Do not use MCP in v1.
• Mutate `plan.json` only through `hoyeon-cli plan init|merge|validate`.
• Prefer temporary JSON payload files or fixture files over inline complex JSON.
• Do not rely on hooks for session guards or stop transitions.

Input / Output

Input

• `<spec_dir>/requirements.md` — required (produced by /specify)
• Optional: existing `plan.json` — treated as prior state, patched additively

Output

<spec_dir>/
├── requirements.md   # unchanged (input)
├── plan.json         # NEW/UPDATED: tasks + journeys + verify_plan + contracts summary
└── contracts.md      # NEW: cross-module surface (markdown). Optional for trivial bugfix.

Only those three files. No rendered view file, no language-specific stubs.

File role separation

• **requirements.md** — specify owns. Human-editable markdown with sub-requirements (GWT).
• **plan.json** — blueprint owns. Machine state. Schema: `plan/v1` (see `cli/schemas/plan.schema.json`).
• **contracts.md** — blueprint creates. Sibling artifact referenced by `plan.contracts.artifact`. Markdown, language-agnostic.

---

Prerequisite: cli

All `plan.json` operations go through `hoyeon-cli` (NOT legacy `hoyeon-cli`):

| Command | Purpose | |---|---| | `hoyeon-cli plan init <spec_dir> --type <t>` | Create empty stub (if missing) | | `hoyeon-cli plan merge <spec_dir> --json '<payload>' [--patch\|--append]` | Merge JSON with schema validation | | `hoyeon-cli plan get <spec_dir> --path <dotted>` | Read field | | `hoyeon-cli plan validate <spec_dir>` | Schema + internal cross-ref integrity |

**cli never parses requirements.md.** Reading the markdown is the blueprint agent's job (via Read tool). cli only validates plan.json self-consistency. Coverage against requirements.md is enforced semantically by the LLM (Phase 2 / Phase 4 of this skill).

---

Scope Adaptation (`meta.type`)

| `meta.type` | Contract artifact shape (when written) | Task graph | |---|---|---| | `greenfield` | Full surface: types + interfaces + invariants (~50-200 lines) | L0-L3, parallel L1 | | `feature` | Delta only: new types/interfaces this feature adds (~10-50 lines) | L0-L2, parallel if multi-module | | `refactor` | Pin-style: `## Frozen Public API` + `## Allowed Churn` + `## Invariants` | Flat list with invariant guards | | `bugfix` | Minimal: typically just an `## Invariants` section | Single chain (1-3 tasks) |

Approval is not `meta.type`-scaled anymore — the ask-only-when-owned rule governs every type uniformly (see top-level principle).

**`contracts.md` is content-driven, not type-driven.** Write it whenever `contract-deriver` finds any cross-module content (≥1 invariant or interface) — regardless of `meta.type`. Skip the file (return `artifact: null`) only when the agent genuinely has nothing to pin. A bugfix with 3 load-bearing invariants gets a file; a feature that only adds a config flag may not. `meta.type` decides the template shape, not the file's existence.

`meta.type` normally comes from `/specify` (written into requirements.md frontmatter). If the field is missing — manual authoring, legacy spec, etc. — infer it using this priority (stop at the first matching rule):

1. **Keywords in `goal`** (highest signal, author's stated intent)

• Contains `refactor` / `migrate` / `restructure` / `rewrite` → `refactor`
• Contains `fix` / `bug` / `regression` / `broken` → `bugfix