Runbook

Type does NOT affect: Tier assessment, outline generation, consolidation gates, assembly (prepare-runbook.py auto-detects), checkpoints.

Phase type tagging format in outlines:

### Phase 1: Core behavior (type: tdd)
- Cycle 1.1: Load configuration
- Cycle 1.2: Parse entries

### Phase 2: Skill definition updates (type: general)
- Step 2.1: Update SKILL.md frontmatter
- Step 2.2: Add new section

### Phase 3: Contract updates (type: inline)
- Add inline type row to pipeline-contracts.md type table
- Update eligibility criteria in workflow-optimization.md

prepare-runbook.py auto-detects per-file via headers (## Cycle X.Y: vs ## Step N.M:). Inline phases have no step/cycle headers — detected by (type: inline) tag in phase heading. prepare-runbook.py skips step-file generation for inline phases and marks them Execution: inline in orchestrator-plan.md.

Model Assignment

Default heuristic: Match model to task complexity.

• Haiku: File operations, scripted tasks, mechanical edits
• Sonnet: Semantic analysis, judgment, standard implementation
• Opus: Architecture, complex design decisions

Artifact-type override: Steps editing architectural artifacts require opus regardless of task complexity:

• Skills (plugin/skills/)
• Fragments (plugin/fragments/)
• Agent definitions (plugin/agents/)
• Workflow decisions (agents/decisions/workflow-*.md)

These are prose instructions consumed by LLMs — wording directly determines downstream agent behavior. "Simple" edits to these files require nuanced understanding that haiku/sonnet cannot reliably provide.

This override applies to Tier 2 delegation (model parameter), Tier 3 step assignment (Execution Model field), and the Execution Model in Weak Orchestrator Metadata.

Two-Tier Assessment

Evaluate implementation complexity before proceeding. Assessment runs first, before any other work.

Assessment Criteria

Analyze the task and produce explicit assessment output:

**Tier Assessment:**
- Files affected: ~N
- Artifact destination: [production / agentic-prose / exploration / investigation / ephemeral]
- Open decisions: none / [list]
- Components: N (sequential / parallel / mixed)
- Cycles/steps estimated: ~N (rough count from design)
- Model requirements: single / multiple
- Session span: single / multi

**Tier: [2/3] — [Lightweight Delegation / Full Runbook]**
**Rationale:** [1-2 sentences]

Destination-aware file counting: Artifact destination (from Phase 0 classification or design) determines which convention set applies to file counting:

A single-file prototype assessed against exploration conventions → minimal scope (Tier 2 may suffice). Same script assessed against production conventions → inflated count from test mirrors, lint setup, module structure.

When uncertain between tiers, prefer the lower tier (less overhead). Ask user only if genuinely ambiguous.

Tier 2: Lightweight Delegation

Criteria:

• Design complete, scope moderate (6-15 files or 2-4 logical components) (file thresholds ungrounded — needs calibration)
• Work benefits from agent isolation but not full orchestration
• Components are sequential (no parallelization benefit)
• No model switching needed

Implementation recall (D+B anchor — tool call required):

1. Read agents/memory-index.md (skip if already in context). Select implementation-domain triggers — patterns for building this, not classifying it. Upstream triage recall (from /design) uses different triggers and does not satisfy this gate.
2. If plans/<job>/recall-artifact.md exists: edify _recall resolve plans/<job>/recall-artifact.md — artifact mode resolves all entry keys in one call.
3. Resolve additional triggers from memory-index not in artifact: edify _recall resolve "when <trigger>" ...
4. No relevant entries (no artifact, no triggers selected): edify _recall resolve null — proves gate was reached.

Include relevant entries in each delegation prompt — format per consumer model tier (constraint format for haiku, rationale for sonnet/opus). Include review-relevant entries in corrector prompt.

Prerequisites check (D+B anchor): Check plan directory for design-stage artifact: outline.md, inline-plan.md, or design.md. Absent → STOP. /runbook without prior /design gating is an error — scope was not user-validated.

Generate runbook outline:

1. Write plans/<job>/runbook-outline.md using Tier 2 outline format (below)
2. Review: Delegate to runbook-outline-corrector (fix-all mode). Specify Tier 2 format in prompt — no requirements mapping table required.
3. Proof: Invoke /proof plans/<job>/runbook-outline.md
4. After /proof approval: follow §Continuation (prepends /inline plans/<job> execute)

Tier 2 outline format:

## Phase N: [title] (type: [tdd|general|inline])
- Item N.1: [target file] — [concrete action]
- Item N.2: [target file] — [concrete action]
  Depends on: Item N.1

No requirements mapping table (scope too small for traceability). Type tags required. Per-item: concrete action + target file. Dependencies noted where relevant.

Execution: /inline executes from the approved runbook-outline.md. No runbook.md generated.

Sequence: Follow §Continuation (prepends /inline plans/<job> execute).

Design constraints are non-negotiable:

When design specifies explicit classifications (tables, rules, decision lists):

1. Include them LITERALLY in the delegation prompt
2. Delegated agents must NOT invent alternative heuristics
3. Agent "judgment" means applying design rules to specific cases, not creating new rules

Artifact-type model override: When delegated work edits architectural artifacts (skills, fragments, agents, workflow decisions), use model="opus" in the Task call. See Model Assignment section.

Key distinction from Tier 3: No prepare-runbook.py, no orchestrator plan, no plan-specific agent. The planner acts as ad-hoc orchestrator.

Handling agent escalations:

When delegated agent escalates "ambiguity" or "design gap":

1. Verify against design source — Re-read the design document section
2. If design provides explicit rules: Resolve using those rules, do not accept the escalation
3. If genuinely ambiguous: Resolve using architectural principles from design context, or ask user
4. Re-delegate with clarification if agent misread design

Tier 3: Full Runbook

Criteria:

• Multiple independent steps (parallelizable)
• Steps need different models
• Long-running / multi-session execution
• Complex error recovery

• 15 files or complex coordination (file threshold ungrounded — needs calibration)

• 10 TDD cycles with cross-component dependencies (cycle threshold ungrounded — needs calibration)

Prerequisites check (D+B anchor): Check plan directory for design-stage artifact: outline.md, inline-plan.md, or design.md. Absent → STOP. /runbook without prior /design gating is an error — scope was not user-validated.

Sequence: Read references/tier3-outline-process.md for the planning process overview and outline generation (Phases 0.5-0.95). (Verb-oriented name: action the agent takes, not the plan artifact produced.)

Continuation

As the final action of this skill:

1. Read continuation from additionalContext (first skill in chain) or from [CONTINUATION: ...] suffix in Skill args (chained skills)
2. Prepend entries based on tier:
   • Tier 2: prepend /inline plans/<job> execute
   • Tier 3: no prepend (Phase 4 prepares artifacts; orchestration requires session restart)
3. If continuation present: peel first entry from (possibly modified) continuation, tail-call with remainder
4. If no continuation: default-exit — /handoff → /commit

CRITICAL: Do NOT include continuation metadata in Task tool prompts.

On failure: Abort remaining continuation. Record in session.md Blockers: which phase failed, error category, remaining continuation orphaned.