H·AI·K·U Run

H·AI·K·U Run

Name

haiku:resume - Advance an H·AI·K·U intent through its stages.

Synopsis

/haiku:resume [intent-slug]

Description

User-facing command — Drives an intent through the studio's stage sequence. The MCP orchestrator (haiku_run_next) tells you what to do at each step. You execute, then ask again. Repeat until the intent completes.

Pre-checks

1. Reject cowork mode: The agent MUST NOT run this skill in cowork mode. If CLAUDE_CODE_IS_COWORK=1, the agent MUST stop with an error.
2. Context window preflight: The agent MUST verify sufficient context for meaningful work.

Implementation

The Loop

The entire execution model is a loop:

1. Call haiku_run_next { intent: slug }
2. Read the returned action
3. Execute the action
4. Repeat from step 1

The orchestrator handles ALL state logic — which stage is active, which phase it's in, which unit is ready, whether the gate passed. The agent MUST follow the action returned by the orchestrator and MUST NOT attempt to manage state independently.

Resolving the Intent

If a slug was provided as an argument, use it. Otherwise:

haiku_intent_list → find the active intent

If no active intent: error, suggest /haiku:new.

Action Reference

The orchestrator returns one of these actions. Follow the instructions for each:

start_stage

A new stage is beginning. The orchestrator provides the stage name and hat list.

{ "action": "start_stage", "intent": "...", "studio": "...", "stage": "...", "hats": [...], "follows": "parent-slug", "parent_knowledge": ["DISCOVERY.md", ...] }

Do:

1. haiku_stage_start { intent, stage } — marks the stage as active
2. If follows is present (this intent iterates on a previous one), load the parent intent's knowledge artifacts via haiku_knowledge_read { intent: follows, name: ... } for each file in parent_knowledge. Copy relevant knowledge to this intent's knowledge directory as a starting point.
3. Call haiku_run_next again — it will return the elaboration action (decompose)

decompose

Elaborate on the stage: research the problem space, produce knowledge artifacts, then break the stage's work into units.

{ "action": "decompose", "intent": "...", "studio": "...", "stage": "..." }

Do:

1. Read the stage's STAGE.md for inputs, unit types, criteria guidance, and elaboration: mode (collaborative or autonomous)

   • collaborative — the agent MUST engage the user as a multi-turn conversation (steps 9-10 below are REQUIRED)
   • autonomous — the agent MAY drive elaboration independently. The agent SHOULD still present the final plan via open_review but MAY skip iterative questions if the upstream specs are clear and complete

2. Read the stage's discovery/ definitions (in the studio directory: stages/{stage}/discovery/*.md) to understand what knowledge artifacts this stage must produce

3. Load resolved input artifacts from upstream stages — each discovery definition specifies a location: field indicating where the artifact lives (.haiku/knowledge/ for project-wide, .haiku/intents/{slug}/knowledge/ for intent-specific). Check freshness metadata — if inputs are stale or code has drifted, use /haiku:refine stage:{upstream} for a scoped side-trip

4. Research and write discovery artifacts to their specified locations. These are knowledge artifacts — analysis, inventories, specs, threat models — that capture what you learned about the problem space. Write each artifact to the location: specified in its discovery definition

5. Elaborate the work into units with completion criteria and a dependency DAG

6. For each unit, populate refs: in frontmatter — an array of paths to upstream artifacts relevant to that unit.

7. Write unit files to .haiku/intents/{slug}/stages/{stage}/units/

8. ELABORATE COLLABORATIVELY. Elaboration is a multi-turn conversation between the agent and the user. The agent MUST NOT treat elaboration as a single pass where it researches, writes units, and presents a finished plan. Instead:

   • The agent MUST engage the user iteratively — ask questions, get answers, refine, ask more questions
   • The agent MUST ask about architecture preferences, constraints, priorities, unknowns
   • The agent MUST probe for edge cases and non-obvious requirements
   • The agent MUST validate assumptions with the user before writing them into units
   • The agent MUST present options and tradeoffs when decisions are needed
   • The agent MUST NOT silently make design decisions — if there's a choice, present it to the user
   • The agent SHALL continue the conversation until both the agent and user are confident the plan is solid

   Simple questions → the agent MUST ask in the terminal as natural conversation. Rich content (wireframes, diagrams, multi-option comparisons, design directions, formatted specs) → the agent MUST use ask_user_visual_question. The visual tool renders markdown, supports images, and provides structured input. Any time the agent is presenting something the user needs to SEE to evaluate, the visual tool is REQUIRED.

9. PRESENT THE FINAL PLAN for approval using a visual review tool. Once units are written, the agent MUST call open_review { intent_dir, review_type: "intent" } in a background subagent to present the complete plan visually. The tool blocks until the user submits their decision. The agent MUST run it in a subagent so the main conversation remains responsive:

   Agent { prompt: "Call open_review for intent ..., wait for decision, return result", run_in_background: true }
   

   Tell the user the review is open and wait for the subagent to return.

10. After user approval: haiku_stage_set { intent, stage, field: "phase", value: "execute" }

11. Call haiku_run_next again

User Interaction Tools (RFC 2119)

The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED" in this section are to be interpreted as described in RFC 2119.

Three interaction modes — when to use each:

1. Natural conversation (terminal text)

• USE FOR: Simple yes/no questions, brief clarifications, status updates, error messages, asking the user to describe something
• The agent MUST use natural terminal conversation for questions that need a free-text answer
• The agent MUST NOT use AskUserQuestion for free-text prompts — it renders as a clunky select form

2. ask_user_visual_question (rich HTML page in browser)

• USE FOR: Any content the user needs to SEE to evaluate — specs, wireframes, multi-option comparisons, formatted tables, design decisions, elaboration questions with context
• The agent MUST use this for all rich content during elaboration
• The agent MUST use this in /haiku:new Step 9 (intent direction review)
• The tool opens a styled page in the browser with markdown rendering, images, radio/checkbox options
• It blocks until the user submits — returns structured answers

3. open_review (full review page in browser, run in background subagent)

• USE FOR: Formal plan review (elaboration complete), gate approval, stage review
• The agent MUST use this for the final elaboration plan presentation (step 10)
• The agent MUST use this for all gate_ask approvals
• The agent MUST run it in a background subagent — it blocks until the user decides
• It shows the full intent/unit with inline commenting, annotation canvas, decision form

4. pick_design_direction (design archetype picker)

• USE FOR: Presenting 2+ design alternatives with visual previews
• The agent MUST use this when the design stage needs a direction choice

Prohibited:

• The agent MUST NOT use AskUserQuestion (the Claude Code built-in select/form tool) — it produces ugly select dropdowns. Use ask_user_visual_question instead for structured questions, or natural conversation for free-text.
• The agent MUST NOT present unit lists, criteria tables, stage summaries, or specs as plain terminal text when a visual tool exists.
• The agent MUST NOT advance from elaboration to execute without having used open_review for the plan.
• The agent MUST NOT approve a gate without having used open_review.

Discovery vs. Output artifacts: Stages define two artifact directories:

• stages/{stage}/discovery/ — knowledge artifacts produced during elaboration (research, analysis, specs)
• stages/{stage}/outputs/ — work products produced during execute (code, configs, deliverables)

start_units (parallel)

Multiple units are ready with no blocking dependencies. Execute them in parallel using agent teams.

{ "action": "start_units", "intent": "...", "stage": "...", "units": ["unit-01", "unit-02", ...], "first_hat": "...", "hats": [...] }

Do:

1. For each unit in units, spawn an Agent (subagent) using the Agent tool:
   • Set isolation: "worktree" so each agent works on an isolated copy of the repo
   • The prompt should include: intent slug, stage, unit name, hat, the unit's refs, and the stage's artifact definitions
   • Each agent runs the full hat sequence for its unit autonomously (start → hats → complete)
   • haiku_unit_start { intent, stage, unit, hat: first_hat } at the beginning
   • haiku_unit_complete { intent, stage, unit } when criteria are met
2. The agent MUST launch all agents in a single message (parallel tool calls) — the agent MUST NOT run them sequentially
3. Wait for all agents to complete
4. Call haiku_run_next again — it will return the next batch of ready units or advance the phase

Each agent's prompt should include:

• The hat definition from stages/{stage}/hats/{hat}.md
• The unit's content and completion criteria
• The unit's refs: artifacts
• Instruction to work ONLY on this unit's scope — the agent MUST NOT modify files outside the unit's responsibility
• The H·AI·K·U MCP tools needed: haiku_unit_start, haiku_unit_advance_hat, haiku_unit_complete, haiku_unit_increment_bolt

start_unit

A single unit is ready (no other units can run in parallel). Execute it directly.

{ "action": "start_unit", "intent": "...", "stage": "...", "unit": "...", "first_hat": "...", "hats": [...] }

Do:

1. haiku_unit_start { intent, stage, unit, hat: first_hat }
2. Load the hat definition from stages/{stage}/hats/{hat}.md
3. Load the unit's refs: from frontmatter — read each referenced artifact. These are the upstream designs, specs, and knowledge docs that inform this unit's work. For image/binary refs, note their existence and what they represent (from the design brief). For text refs, read and use their content.
4. Load the stage's artifact definitions — discovery/*.md and outputs/*.md
5. Execute the hat's work using the referenced artifacts as source material. The implementation should match what the design mockups show, satisfy the behavioral specs, and follow the architectural patterns from discovery.
6. Call haiku_run_next again

continue_unit

An active unit — resume where you left off.

{ "action": "continue_unit", "intent": "...", "stage": "...", "unit": "...", "hat": "...", "bolt": N, "hats": [...] }

Do:

1. Load the current hat definition
2. Load the unit's refs: — the upstream artifacts that inform this unit (same as start_unit step 3)
3. Continue the hat's work using the referenced artifacts — write outputs to the locations specified in the stage's artifact definitions
4. When the hat's work is done, advance to the next hat: haiku_unit_advance_hat { intent, stage, unit, hat: next_hat }
5. After all hats complete, check unit completion criteria
6. If criteria met: haiku_unit_complete { intent, stage, unit }
7. If not met: haiku_unit_increment_bolt { intent, stage, unit } — starts a new bolt cycle
8. Call haiku_run_next again

CRITICAL: The agent MUST NOT ask questions during execution. The bolt loop is fully autonomous. If the agent encounters ambiguity, the agent MUST make a reasonable decision. The agent MUST document assumptions in the unit's ## Notes section.

advance_phase

The orchestrator is moving to the next phase within a stage.

{ "action": "advance_phase", "intent": "...", "stage": "...", "from_phase": "...", "to_phase": "..." }

Do:

1. haiku_stage_set { intent, stage, field: "phase", value: to_phase }
2. Call haiku_run_next again

review

Run adversarial review agents for the stage.

{ "action": "review", "intent": "...", "studio": "...", "stage": "..." }

Do:

1. Load review agents from stages/{stage}/review-agents/ (own agents)
2. Load included agents from review-agents-include in the stage's STAGE.md
3. Spawn one subagent per review agent, in parallel — each gets the mandate, the diff, and the stage outputs
4. Collect findings. If HIGH severity findings: fix them, then repeat review (up to 3 cycles)
5. haiku_stage_set { intent, stage, field: "phase", value: "gate" }
6. haiku_stage_set { intent, stage, field: "gate_entered_at", value: NOW }
7. Call haiku_run_next again

Note: Artifacts are persisted (committed to git) automatically during execution — haiku_unit_start, haiku_unit_complete, haiku_stage_start, and haiku_stage_complete all auto-commit. There is no separate "persist" step.

gate_ask

The stage's review gate requires human approval.

{ "action": "gate_ask", "intent": "...", "stage": "...", "next_stage": "..." }

The visual review MUST open. When haiku_run_next returns gate_ask, the agent MUST call open_review in a background subagent (the tool blocks until the user submits). If haiku_run_next auto-opened it (check for review_url in the response), the subagent MUST call get_review_status to wait for the decision instead.

Do:

1. Spawn a background subagent that calls open_review { intent_dir, review_type: "intent" } and waits for the user's decision. Tell the user the review is open.
2. If approved: haiku_gate_approve { intent, stage } then call haiku_run_next
3. If changes_requested: analyze the annotations to determine which stage needs the fix:
   • Read each annotation's location field (file path or section name)
   • Comments on design artifacts (e.g., stages/design/artifacts/..., DESIGN-BRIEF.md) → /haiku:refine stage:design
   • Comments on behavioral specs (BEHAVIORAL-SPEC.md, DATA-CONTRACTS.md) → /haiku:refine stage:product
   • Comments on discovery/architecture docs → /haiku:refine stage:inception
   • Comments on code or implementation → fix in the current stage (create a new unit or increment bolt)
   • If multiple stages are implicated, start with the most upstream one
   • If unclear, ask the user which stage to revisit
   • After the refine side-trip completes, return to the current gate and call haiku_run_next again

gate_external

Push for external review.

{ "action": "gate_external", "intent": "...", "stage": "...", "next_stage": "..." }

Do:

1. Push the branch and commit stage artifacts
2. Generate the browse URL: https://{site}/browse/{host}/{project}/intent/{slug}/{stage}/
3. Share the URL with the reviewer (via comms provider if configured, otherwise output to terminal)
4. The reviewer opens the browse page, reviews the artifacts, and clicks "Approve Stage"
5. The approval writes directly to the repo via git API
6. /haiku:triggers picks up the approval on next poll and advances the gate
7. haiku_stage_complete { intent, stage, gate_outcome: "blocked" } — blocks until approval

gate_await

Waiting for an external event.

{ "action": "gate_await", "intent": "...", "stage": "...", "next_stage": "..." }

Do:

1. Report what is being awaited
2. haiku_stage_complete { intent, stage, gate_outcome: "awaiting" }
3. Stop. The user runs /haiku:resume when the event occurs.

advance_stage

Gate passed — moving to the next stage (continuous mode).

{ "action": "advance_stage", "intent": "...", "stage": "...", "next_stage": "...", "gate_outcome": "advanced" }

Do:

1. haiku_stage_complete { intent, stage, gate_outcome: "advanced" }
2. haiku_intent_set { slug, field: "active_stage", value: next_stage }
3. Commit stage artifacts
4. Call haiku_run_next again — it will return start_stage for the next stage

stage_complete_discrete

Stage done but discrete mode — stop and wait for user.

{ "action": "stage_complete_discrete", "intent": "...", "stage": "...", "next_stage": "..." }

Do:

1. haiku_stage_complete { intent, stage, gate_outcome: "advanced" }
2. haiku_intent_set { slug, field: "active_stage", value: next_stage }
3. Report: "Stage complete. Run /haiku:resume for the next stage."

intent_complete

All stages are done.

{ "action": "intent_complete", "intent": "...", "studio": "..." }

Do:

1. haiku_intent_set { slug, field: "status", value: "completed" }
2. haiku_intent_set { slug, field: "completed_at", value: NOW }
3. Report completion summary. Suggest /haiku:review then PR creation.

blocked

Units are blocked on dependencies or need intervention.

{ "action": "blocked", "intent": "...", "stage": "...", "blocked_units": [...] }

Do:

1. Report which units are blocked and why
2. Ask the user for guidance

composite_run_stage

For composite intents — a specific studio:stage is ready.

{ "action": "composite_run_stage", "intent": "...", "studio": "...", "stage": "...", "hats": [...] }

Do: Same as start_stage, but for a composite intent. The orchestrator handles sync points.

error

Something is wrong.

{ "action": "error", "message": "..." }

Do: Report the error to the user.

Relationship to Other Skills

• /haiku:new — Creates the intent that /haiku:resume advances
• /haiku:composite — Creates composite intents with sync points
• /haiku:refine — Amend specs mid-execution or refine upstream stages
• /haiku:review — Pre-delivery code review
• /haiku:reflect — Post-completion analysis
• /haiku:operate — Post-delivery operational tasks