Plan Ad-hoc Skill

Create detailed execution runbooks suitable for weak orchestrator agents using a formalized 4-point planning process. This skill transforms high-level tasks into structured runbooks that haiku or sonnet agents can execute with minimal judgment.

Workflow Context: Part of general workflow (design → planning → execution). Contrast with /plan-tdd (TDD feature dev emphasis).

When to Use

Use this skill when:

•Creating execution runbooks for multi-step tasks
•Delegating work to weak orchestrator agents (haiku/sonnet)
•Complex tasks need explicit design decisions documented
•Tasks require clear error escalation and validation criteria
•Ad-hoc one-off work (vs iterative feature development)

Do NOT use when:

•Task requires user input or interactive decisions
•Plan already exists and just needs execution
•Feature development requiring TDD approach (use /plan-tdd when available)

Three-Tier Assessment

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

Assessment Criteria

Analyze the task and produce explicit assessment output:

code

**Tier Assessment:**
- Files affected: ~N
- Open decisions: none / [list]
- Components: N (sequential / parallel / mixed)
- Model requirements: single / multiple
- Session span: single / multi

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

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

Tier 1: Direct Implementation

Criteria:

•Design complete (no open decisions)
•All edits straightforward (<100 lines each)
•Total scope: <6 files
•Single session, single model
•No parallelization benefit

Sequence:

•Implement changes directly using Read/Write/Edit tools
•Delegate to vet agent for review
•Apply critical/major priority fixes from vet review
•Tail-call /handoff --commit

Tier 2: Lightweight Delegation

Criteria:

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

Sequence:

•Delegate work via Task(subagent_type="quiet-task", model="haiku", prompt="...") with relevant context from design included in prompt (file paths, design decisions, conventions). Single agent for cohesive work; break into 2-4 components only if logically distinct.
•After delegation complete: delegate to vet agent for review
•Apply critical/major priority fixes from vet review
•Tail-call /handoff --commit

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

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

Sequence: 4-point process (see below) — existing pipeline unchanged.

4-Point Planning Process (Tier 3 Only)

Use this process only after assessment determines Tier 3 is needed.

Point 0.5: Discover Codebase Structure (REQUIRED)

Before writing any runbook content:

•Read documentation perimeter (if present):

If design document includes "Documentation Perimeter" section:

•Read all files listed under "Required reading"
•Note Context7 references (may need additional queries)
•Factor knowledge into step design

This provides designer's recommended context. Still perform discovery steps 1-2 below for path verification and memory-index scan.

•
Discover relevant prior knowledge:
- •Scan memory-index.md for entries related to the task domain
- •Read referenced files for relevant matches
- •Factor known constraints into step design and model selection
•
Verify actual file locations:
- •Use Glob to find source files referenced by the design
- •Use Glob to find test files: tests/test_*.py, tests/**/test_*.py
- •Use Grep to find specific functions, classes, or patterns mentioned in the design
- •Record actual file paths for use in runbook steps
- •NEVER assume file paths from conventions alone — always verify with Glob/Grep
- •STOP if expected files not found: report missing files to user

Why: Runbooks with fabricated file paths fail immediately at execution. This is a complete blocker.

Point 1: Evaluate Script vs Direct Execution

For each task in the runbook, decide on execution approach:

1.1 Small Tasks (≤25 lines): Write complete script inline

Criteria:

•Script is short and standalone
•Logic is straightforward
•No complex dependencies

Example:

bash

#!/usr/bin/env bash
# Compare two files and output diff
diff -u /path/to/file1 /path/to/file2 > output.patch || true
echo "Diff size: $(wc -c < output.patch) bytes"

1.2 Medium Tasks: Provide prose description of implementation

Criteria:

•Implementation requires 25-100 lines
•Logic is clear but too long for inline script
•Steps are sequential and well-defined

Example:

code

Implementation:
1. Verify source files exist (provide error if missing)
2. Read both files using Read tool
3. Compare content line-by-line
4. Document differences in structured format
5. Write analysis to specified output path

1.3 Large/Complex Tasks: Separate planning session required

Criteria:

•Task requires >100 lines or complex logic
•Multiple design decisions needed
•Significant architectural choices
•Requires human review before implementation

Action: Mark task as requiring separate planning session. Delegate planning to sonnet or opus depending on complexity.

Point 2: Include Weak Orchestrator Metadata

Every runbook MUST include this metadata section at the top:

markdown

## Weak Orchestrator Metadata

**Total Steps**: [N]

**Execution Model**:
- Steps X-Y: Haiku (simple file operations, scripted tasks)
- Steps A-B: Sonnet (semantic analysis, judgment required)
- Steps M-N: Opus (only if explicitly required for complex design)

**Step Dependencies**:
- Sequential | Parallel | [specific dependency graph]

**Error Escalation**:
- Haiku → Sonnet: [triggers]
- Sonnet → User: [triggers]

**Report Locations**: [pattern for where reports go]

**Success Criteria**: [overall runbook success, not per-step]

**Prerequisites**:
- [Prerequisite 1] (✓ verified via [method])
- [Prerequisite 2] (path: /absolute/path/to/resource)

Critical Requirements:

•Total Steps: Exact count for tracking
•Execution Model: Match model capability to task complexity
•Step Dependencies: Enable orchestrator to parallelize when possible
•Error Escalation: Clear triggers for when to escalate
•Success Criteria: Overall runbook success (step-level criteria go in step sections)
•Prerequisites: Verified before execution starts
•Report Locations: Where execution reports will be written

What DOES NOT belong in orchestrator metadata:

•Inline scripts or prose step descriptions (those go in step sections)
•Objective/expected outcome for each step (those go in step sections)
•Per-step validation/error handling (those go in step sections)
•Per-step success criteria (those go in step sections)

Key Principles:

•Orchestrator metadata is coordination info only - not execution details
•Orchestrator trusts agents to report accurately - no inline validation logic
•Validation is delegated - if needed, it's a separate plan step
•Planning happens before execution - orchestrator doesn't make decisions during execution

Point 3: Plan Review by Vet Agent

Before finalizing the runbook, delegate review to the vet agent.

Why vet agent:

•Fresh eyes: Sub-agent reviews with no orchestrator bias
•Autonomous fixing: Agent applies high/medium fixes directly (not just reports)
•Quiet execution: Writes detailed review to file, returns terse result
•Specialized: Dedicated agent with vet review protocol built-in

Delegation Pattern:

code

Task(
  subagent_type="vet-agent",
  model="sonnet",
  prompt="Review the runbook at [runbook-path] for completeness, correctness, and executability.

  CRITICAL: Also validate all file paths referenced in the runbook exist in the codebase.
  Use Glob to verify each path. Flag missing files as critical issues.

  Write detailed review to: [review-path]

  Return only the filepath on success, or 'Error: [description]' on failure."
)

Agent responsibilities:

•Review runbook file using vet protocol
•Validate all referenced file paths exist
•Write review report to specified path
•Return filepath or error to orchestrator

Orchestrator receives:

•Filepath: plans/foo/reports/runbook-review.md (success)
•Error: Error: Runbook file not found at [path] (failure)

Revision Loop:

•Read review report from filepath
•Check assessment status (Ready / Needs Minor Changes / Needs Significant Changes)
•
If "Needs Minor Changes" or "Needs Significant Changes":
- •REQUIRED: Apply all critical and major priority fixes
- •Update runbook with fixes
- •Delegate re-review if changes are significant
- •Iterate until assessment is "Ready"
•
If "Ready":
- •Proceed to Point 4 (artifact preparation)
•
If error returned:
- •Escalate to user

Fix Application Policy:

•Critical and major priority issues MUST be fixed before proceeding
•Minor priority issues are optional (document as future improvements if skipped)
•Never proceed with unaddressed critical/major issues

Point 4: Prepare Runbook Artifacts

CRITICAL: This step is MANDATORY. Use prepare-runbook.py to create execution artifacts.

Why artifact preparation is fundamental:

The entire point of the plan-specific agent pattern is context isolation. Each step gets a fresh agent invocation with ONLY:

•Common context (metadata, prerequisites, design decisions)
•The specific step to execute
•NO execution transcript from previous steps

Benefits of preparation:

•Prevents context bloat from accumulating across steps
•Each step starts with clean slate (no noise from previous steps)
•Execution logs stay in report files, not in agent context
•Enables plan-specific agent pattern with context caching
•Sequential steps ESPECIALLY need splitting (to prevent cumulative bloat)

When NOT to prepare:

•Never. Always prepare. This is not negotiable.

After runbook is reviewed and ready, use the preparation script to create artifacts.

Use prepare-runbook.py Script:

The script is located at: agent-core/bin/prepare-runbook.py

Script Features:

•Parses runbook with optional YAML frontmatter
•Extracts Common Context section
•Extracts individual Step sections (## Step N: or ## Step N.M:)
•Creates plan-specific agent (baseline + common context)
•Generates step files for execution
•Creates orchestrator plan
•Validates structure and reports errors clearly

Usage:

bash

agent-core/bin/prepare-runbook.py <runbook-file.md>

Example:

bash

agent-core/bin/prepare-runbook.py plans/oauth2-auth/runbook.md

Script automatically derives paths:

•Runbook name: From parent directory (e.g., oauth2-auth from plans/oauth2-auth/runbook.md)
•Plan-specific agent: .claude/agents/<runbook-name>-task.md
•Step files: plans/<runbook-name>/steps/step-N.md or step-N-M.md
•Orchestrator plan: plans/<runbook-name>/orchestrator-plan.md

Runbook Format Requirements:

Optional YAML frontmatter:

yaml

---
name: custom-name  # Override derived name
model: sonnet      # Default model for plan-specific agent
---

Required sections:

•Steps: ## Step N: or ## Step N.M: headings
•At least one step must be present

Optional sections:

•
## Common Context - Shared context for all steps
- •Output optimization: Factorize repetitive content (stop conditions, dependencies, conventions) to Common Context
- •Reduces planner token output by eliminating per-step boilerplate
- •Steps inherit context automatically during runbook compilation
•## Orchestrator Instructions - Custom orchestrator guidance

Benefits of prepare-runbook.py:

•Automatic path derivation (no manual file creation)
•Validation (fails on missing baseline, duplicate steps, etc.)
•Idempotent (re-runnable after runbook updates)
•Consistent artifact structure
•Plan-specific agent with cached context

4.1: Automated Post-Processing

After prepare-runbook.py succeeds, perform these steps automatically.

Step 1: Run prepare-runbook.py with sandbox bypass:

bash

agent-core/bin/prepare-runbook.py plans/{name}/runbook.md
# MUST use dangerouslyDisableSandbox: true (writes to .claude/agents/)

•If script fails: STOP and report error to user

Step 2: Copy orchestrate command to clipboard:

bash

echo -n "/orchestrate {name}" | pbcopy

Step 3: Tail-call /handoff --commit

As the final action of this skill, invoke /handoff --commit. This:

•Hands off session context (marks planning complete, adds orchestration as pending)
•Then tail-calls /commit which commits everything and displays the next pending task

The next pending task (written by handoff) will instruct: "Restart session, switch to haiku model, paste /orchestrate {name} from clipboard."

Why restart: prepare-runbook.py creates a new agent in .claude/agents/. Claude Code only discovers agents at session start.

Critical Constraints

Tool Usage:

•Use Task to delegate review and complex steps
•Use Read to check existing files
•Use Write to create runbook files
•Use Bash for mkdir and python3 script execution
•Use Edit if modifying existing runbooks

Model Selection:

•Haiku: Simple execution, scripted tasks, file operations
•Sonnet: Default for planning and review, semantic analysis
•Opus: Only when explicitly required for complex architecture

Error Handling:

•Report all errors explicitly
•Never suppress errors with || true unless intentional
•Define clear escalation triggers
•Document recovery protocol

Output Locations:

•Runbook: plans/[runbook-name]/runbook.md or [name]-plan.md
•Execution logs: plans/[runbook-name]/reports/
•Step files: plans/[runbook-name]/steps/ (created by script)
•Plan-specific agent: .claude/agents/[runbook-name]-task.md (created by script)
•Orchestrator plan: plans/[runbook-name]/orchestrator-plan.md (created by script)

Validation:

•Success criteria must be measurable
•Use specific file paths (absolute)
•Include size/count checks
•Specify required sections/format

Example Execution Flow

Example 1: Direct Implementation (Point 0 Bypass)

User: /plan-adhoc for learnings consolidation

Agent:

Point 0: Orchestration Assessment

Analyzing task:

•Design complete: plans/learnings-consolidation/design.md
•Components: 4 files (directory, script, 2 skill updates)
•All straightforward (<100 lines each)
•No complex coordination
•Can implement + test in single session

Assessment: Implement directly (orchestration overhead not justified)

Proceeding with direct implementation...

[Agent implements components directly] [Agent delegates to vet agent for review]

Example 2: Runbook Creation (Orchestration Needed)

User: /plan-adhoc for implementing authentication feature

Agent:

Point 0: Orchestration Assessment

Analyzing task:

•Multiple independent components (config, routes, session, profile, tests)
•Steps could be parallelized
•Tests require separate planning session
•Long-running execution across multiple phases

Assessment: Create runbook (orchestration justified)

Point 1: Evaluating Tasks

Let me break this down:

•Setup OAuth2 configuration (small - inline script)
•Implement auth routes and handlers (medium - prose description)
•Add session management (medium - prose description)
•Create user profile integration (medium - prose description)
•Write integration tests (large - separate planning needed)

Point 2: Creating Runbook with Metadata

Creates initial runbook draft with orchestrator metadata

Point 3: Runbook Review

Delegates to sonnet task agent for review Receives: "Review complete - 2 critical issues, 3 major issues - NEEDS_REVISION"

Addresses issues and requests re-review Receives: "Re-review complete - All critical issues resolved - READY"

Point 4: Prepare Artifacts

Runs prepare-runbook.py to create execution artifacts

bash

agent-core/bin/prepare-runbook.py plans/oauth2-auth/runbook.md

Artifacts created:

•Plan-specific agent: .claude/agents/oauth2-auth-task.md
•Steps: plans/oauth2-auth/steps/step-{1,2,3,4}.md
•Orchestrator plan: plans/oauth2-auth/orchestrator-plan.md
•Note: Step 5 (tests) marked for separate planning session

Ready for execution. Use /orchestrate to execute the runbook."

Runbook Template Structure

Main Runbook File:

markdown

---
name: runbook-name  # Optional: override directory-based name
model: haiku        # Optional: default model for plan-specific agent
---

# [Runbook Name]

**Context**: [Brief description of what this runbook accomplishes]

**Source**: [Reference to requirements, design docs, or parent plan]
**Design**: [Reference to design decisions document if applicable]

**Status**: [Draft / In Review / Ready / Complete]
**Created**: YYYY-MM-DD
**Reviewed**: YYYY-MM-DD ([reviewer], [assessment])
**Revised**: YYYY-MM-DD (if applicable)

---

## Weak Orchestrator Metadata

[Metadata section as defined in Point 2]

---

## Common Context

[Shared information for all steps]

**Key Constraints:**
- [Constraint 1]
- [Constraint 2]

**Project Paths:**
- [Path 1]: [Description]
- [Path 2]: [Description]

**Conventions:**
- [Convention 1]
- [Convention 2]

---

## Step 1: [Step Name]

**Objective**: [Clear, concise objective]

**Script Evaluation**: [Direct execution / Small script / Prose description / Separate planning]

**Execution Model**: [Haiku / Sonnet / Opus]

**Implementation**:
[Inline script OR prose steps OR reference to separate plan]

**Expected Outcome**: [What should happen when successful]

**Unexpected Result Handling**:
- If [condition]: [Action to take]

**Error Conditions**:
- [Error type] → [Escalation action]

**Validation**:
- [Validation check 1]
- [Validation check 2]

**Success Criteria**:
- [Measurable criterion 1]
- [Measurable criterion 2]

**Report Path**: [Absolute path to execution log]

---

[Repeat for each step]

---

## Orchestrator Instructions

[Optional: Custom instructions for weak orchestrator]

Default behavior if omitted:
- Execute steps sequentially using [runbook-name]-task agent
- Stop on error and escalate to sonnet

---

## Design Decisions

[Document key decisions made during planning]

---

## Dependencies

**Before This Runbook**:
- [Prerequisite 1]
- [Prerequisite 2]

**After This Runbook**:
- [What can be done next]
- [Artifacts available for downstream work]

---

## Revision History

**Revision 1 (YYYY-MM-DD)** - [Summary of changes]
**Revision 2 (YYYY-MM-DD)** - [Summary of changes]

**Review report**: [Path to review report]

---

## Notes

[Additional context, assumptions, or important details]

Common Pitfalls

Avoid:

•Creating runbooks when direct implementation is better (skipping Point 0)
•Assuming file paths from conventions without Glob/Grep verification (skipping Point 0.5)
•Assuming prerequisites are met without verification
•Assigning semantic analysis tasks to haiku
•Leaving design decisions for "during execution"
•Vague success criteria ("analysis complete" vs "analysis has 6 sections with line numbers")
•Writing success criteria that only check structure ("file exists", "exit code 0") when the step should produce functional output. Verify content/behavior, not just existence.
•Missing error escalation triggers
•Conflating execution logs and analysis artifacts
•Using relative paths instead of absolute
•Deferring validation to future phases
•Forgetting to run prepare-runbook.py after review

Instead:

•Verify prerequisites explicitly
•Match model to task complexity
•Make all decisions during planning
•Define measurable success criteria
•Document clear escalation triggers
•Separate execution logs from output artifacts
•Use absolute paths consistently
•Include validation in each step
•Always run prepare-runbook.py to create artifacts

References

Example Runbook: /Users/david/code/claudeutils/plans/unification/phase2-execution-plan.md Example Review: /Users/david/code/claudeutils/plans/unification/reports/phase2-plan-review.md Preparation Script: /Users/david/code/claudeutils/agent-core/bin/prepare-runbook.py Baseline Agent: /Users/david/code/claudeutils/agent-core/agents/quiet-task.md

These demonstrate the complete 4-point process in practice.

Integration with General Workflow

Workflow stages:

•/design - Opus creates design document
•/plan-adhoc - Sonnet creates execution runbook (THIS SKILL) → auto-runs prepare-runbook.py → tail-calls /handoff --commit
•/handoff updates session.md → tail-calls /commit
•/commit commits everything → displays next pending task (restart instructions)
•User restarts session, switches to haiku, pastes /orchestrate {name} from clipboard
•/orchestrate - Haiku executes runbook steps
•vet-fix-agent - Review and fix changes before commit
•Complete job

Handoff:

•Input: Design document from /design skill
•Output: Ready-to-execute artifacts (agent, steps, orchestrator plan), committed and handed off
•Next: User restarts session and pastes orchestrate command from clipboard