Plan Pipeline

Plan Pipeline

Formalizes the user's core working pattern: split big jobs into phased plan files, execute one phase per session, track state. Kills four recurring frictions: phase-state tracking, scaffolding re-typing, model-choice questions, and cross-tool phase verification.

Mode Detection

Parse the first word of the argument:

• Starts with dismantle → Dismantle mode
• Starts with run → Run mode
• Starts with verify → Verify mode (sub-mode of Run)
• Ambiguous → ask once

---

Mode 1: Dismantle

Input: a topic description, a rough plan, or a path to an existing document to break down.

Output: a plan file saved to ~/.claude/plans/{domain}-{intent}-{short-topic}.md.

Steps

1. If the input references a file path, read it. Otherwise work from the description.
2. Identify the atomic phases. Group trivially related items into bundles when they share the same session context. Front-load high-ROI / low-effort phases.
3. For each phase, determine:

• Model + effort using the routing table below
• Verification steps — concrete commands or checks, not vague "confirm it works"
• Required inputs — files to read, prior phase state dependencies
• The phase prompt — self-contained instructions a fresh session can execute without any prior conversation context

1. Write the plan file with the structure defined below.
2. Print the path and the exact command to start Phase 1.

Model + Effort Routing Table

| Phase type | Model | Effort | Examples | |---|---|---|---| | Mechanical edits, config changes, file moves | Sonnet | medium | renaming, adding CLAUDE.md rules, mkdir, registry rows | | Routine code changes, bug fixes, tests | Sonnet | medium–high | component edits, script fixes, test writing | | Design, architecture, skill authoring, audit | Opus or Fable | high | new skills, system design, CLAUDE.md architecture | | Complex reasoning, multi-file refactors | Opus | high–xhigh | cross-cutting refactors, migration planning | | Research, exploration, web search | Sonnet | medium + web search | library evaluation, API research | | Trivial, single-line changes | Haiku | low | typo fixes, version bumps |

Plan File Structure

First line: # {Title stating the plan's intent}

Then a ## Context section with:

• What this plan accomplishes and why
• Key facts verified during planning (paths, conventions, dependencies) so phases don't re-derive them
• Overall model/effort summary line
• Execution discipline: one phase per session, stop after each. Append State Sync after each phase.

Then one ## Phase N — {title} ({items covered}) section per phase.

Then ## State Sync at the bottom with (append after each phase).

Phase Output Format

Each phase in the plan file contains its full specification. When the user asks to SEE the phases (not when writing the plan file), present each phase to the terminal like this:

Phase N — [title] [one-sentence description] Model: ... | Effort: ... Success criteria: ... Required inputs: ...

Phase N Prompt (paste into a fresh session):

═══════════════════════════════════ [prompt text here — no nested triple-backtick fences; use 4-space indented code or inline backticks instead] ═══════════════════════════════════

Rules:

• All metadata goes ABOVE the ═══ block
• Nothing informational goes between or after the ═══ lines
• No nested triple-backtick fences inside the prompt block — use 4-space indentation for code
• The prompt inside ═══ must be self-contained: a fresh session with no prior context can execute it

---

Mode 2: Run

Input: a path to a plan file (e.g. ~/.claude/plans/agent-os-reflection-improvements.md).

Steps

1. Read the plan file entirely.
2. Parse the ## State Sync section at the bottom. Identify which phases have DONE entries.
3. Determine the next un-executed phase. If all phases are done, say so and stop.
4. Read and load:

• Any files listed in the phase's "Required inputs" or context-load instructions
• Any State Sync entries from prior phases that this phase depends on

1. Execute the phase. Follow its instructions exactly.
2. After completing all items in the phase, run the verification steps specified in the phase.
3. Append a State Sync block to the plan file:

Phase N: DONE (YYYY-MM-DD) — [what was implemented vs. planned; config values or paths the next phase needs; deviations from plan; anything left outstanding]

1. Print the exact next command:

Next: /plan-pipeline run ~/.claude/plans/{filename}.md

Or if all phases are now complete: print the end-to-end verification section if one exists.

Execution Rules

• ONE phase only. Stop after the phase is done and State Sync is appended. Do not continue to the next phase.
• Never self-trigger /loop or ScheduleWakeup. The user starts each phase manually.
• Verification is mandatory. If the phase has verification steps, run them before writing State Sync. If verification fails, fix the issue and re-verify. Do not mark DONE with failing checks.
• Deviations are fine, but document them. If you deviate from the plan (skip an item, change approach, discover something), explain in the State Sync entry.

---

Mode 3: Verify (sub-mode of Run)

Input: verify phase — verify that phase N was completed by another tool (Cursor, Codex, manual edit).

Steps

1. Read the plan file.
2. Find Phase N's specification and its verification steps.
3. Run every verification check. Report pass/fail for each.
4. If all pass: append State Sync with (verified — executed externally) notation.
5. If any fail: report what failed and what needs fixing. Do NOT append State Sync.
6. Print the next command (same as Run mode step 8).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chevis-Zhou
• Source: Chevis-Zhou/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.