execution-planning

name	execution-planning
description	Takes a spec phase and generates an execution plan with parallel stages, agent routing, review gates, and verification criteria. Use before dispatching implementation work. Triggers on "plan execution", "generate execution plan", "how should we execute this", or internally when the orchestrator is about to implement a spec phase.

Execution Planning

Generate an execution plan from a spec phase. The plan decomposes work into parallel stages with agent routing, dependencies, review gates, and verification criteria.

Announce at start: "I'm using the execution-planning skill to create the execution plan for this phase."

When to Use

Before implementing any spec phase that involves 2+ subtasks or 2+ agents. Skip for trivial single-agent tasks.

Inputs

1. The spec file — check for docs/specs/<name>/spec.md first, fall back to docs/specs/<name>.md for specs created before the folder convention
2. The codebase state — understand what exists now
3. The routing table — know which agents handle what

Process

Step 1: Read the spec phase

Read the spec and extract:

• What must be produced (deliverables)
• What files are created/modified/deleted
• What verification is required

Step 2: Decompose into subtasks

Break the phase into the smallest independent units of work. Each subtask should:

• Have a single agent owner
• Touch a distinct set of files (no overlap with other subtasks)
• Be verifiable independently

Also scan for related metadata that may have drifted: test counts, version numbers, coverage targets, tool names in prose. Include these as additions to the most relevant task or as a separate "drift fixes" task.

Step 3: Identify dependencies

For each subtask, determine:

• Can it start immediately? (no dependencies)
• Does it depend on another subtask's output?
• Does it share files with another subtask? (forces sequencing)

Step 4: Assign agents

Route each subtask using the orchestrator's routing table:

• Code changes → devops-python, devops-shell, or devops-refactor
• Config/docs/markdown → devops-docs
• Review → devops-reviewer
• Research/web lookups → orchestrator (pre-gather for subagents)

Step 5: Build the stage map

Group subtasks into stages:

• Stage 1: All subtasks with no dependencies (run in parallel)
• Stage 2: Subtasks that depend on Stage 1 outputs
• Stage N: Continue until all subtasks are placed
• Review stage: Always the last stage before commit

Step 6: Define verification

For each subtask and for the phase overall:

• What command proves it worked?
• What grep/check proves no regressions?
• What the reviewer should focus on

Output Format

Save to: docs/specs/<spec-name>/execution/phase-N.plan.md

Use whatever phase identifier the spec uses. If the spec says "Phase 2", the file is phase-2.plan.md. If it says "Migration Step A", use migration-step-a.plan.md. Match the spec, don't force numeric naming.

# Phase N Execution Plan

> Generated from: `docs/specs/<spec-name>/spec.md` — Phase N
> Date: YYYY-MM-DD

## Goal

One sentence from the spec.

## Stage 1 (parallel)

### Task 1.1: [name]
- **Agent:** devops-python
- **Objective:** [one sentence]
- **Files:** create/modify/delete list
- **Briefing context:** [file paths the agent needs to read]
- **Constraints:** [what NOT to touch]
- **Done when:** [concrete criteria]
- **Skill triggers:** "implement with tests", "verify before completing"

### Task 1.2: [name]
- **Agent:** devops-docs
- **Objective:** [one sentence]
- **Files:** create/modify list
- **Briefing context:** [file paths]
- **Constraints:** [scope limits]
- **Done when:** [concrete criteria]

## Stage 2 (after Stage 1)

### Task 2.1: [name]
- **Agent:** devops-reviewer
- **Depends on:** Task 1.1, Task 1.2
- **Objective:** Review all changes from Stage 1
- **Files to review:** [list from Stage 1]
- **Focus areas:** [what matters most]
- **Done when:** approved or issues listed

## Verification

- [ ] [test command and expected result]
- [ ] [grep check for stale references]
- [ ] [any other concrete check]

## Commit

After all stages pass verification:
- **Type:** feat/refactor/fix
- **Scope:** [what changed]

Plan Quality Requirements

A good execution plan is self-contained — a new session reads only the plan, not the spec. Every task must be mechanical — subagents execute, they don't design.

For each task, include:

1. Current state snapshot — exact file content or line numbers being changed. Don't say "update references" — show the exact before/after strings.
2. Before → after for every change — literal string replacements so the subagent can do mechanical find-and-replace without re-reading files.
3. Per-task verification — a specific grep, diff, or command that proves this individual task is correct. Don't rely only on the global check.
4. Dependency proof — if tasks are marked parallel, explain WHY they're independent (no shared files, no output dependencies).

The test: could a subagent execute this task with ZERO judgment calls? If not, the plan needs more detail.

Rules

• Every plan must have at least one review stage
• Subtasks in the same stage must not share files
• The orchestrator handles git operations — never assign commit to a subagent
• Load-bearing ordering → atomic dispatch. When the spec marks task ordering as "load-bearing" or warns that half-done is worse than status quo, dispatch those tasks as a single unit to one subagent. No intermediate test gates between them — the test gate runs once at the end of the atomic unit.
• If a subtask needs web_search, use_aws, grep, or glob, mark it as "orchestrator pre-work" — the orchestrator gathers that data before dispatching the subagent
• Keep subtasks focused — if a subtask touches more than 10 files, consider splitting it
• Include the briefing context (file paths) so the orchestrator can construct the delegation without re-reading the spec
• Before marking tasks as parallel-safe, cross-check file lists across all tasks in the same stage. If any file appears in two tasks within the same parallel stage, move one task to a later stage. This is a hard gate — do not rely on "the agents will coordinate"

Proportionality

Match plan detail to task complexity. Not every phase needs 500 lines.

• Bulk find-and-replace (rename paths, update references): a replacement table + file list is sufficient. Don't enumerate every individual instance. Example: "Replace eam-ecs-bounce with eam ecs bounce in these 7 files" — not 50 lines of before/after per file.
• New feature implementation: detailed specs with file structure, function signatures, test requirements, and acceptance criteria.
• Mechanical file moves: file list with source → destination. No per-file before/after strings needed.

Rule of thumb: if the execution plan is longer than the actual diff would be, it's over-specified.

Stage Completion Tracking

After each stage completes, update the execution plan file immediately — not at the end:

• Mark completed stages using checkbox syntax: - [ ] → - [x]
• Add the completion date as a note: - [x] Stage 1 — completed YYYY-MM-DD
• If a stage was skipped or reordered, note why in the plan file
• If new tasks were added mid-execution, add them to the plan before continuing

The execution plan file is a live document during implementation. It should reflect current reality at all times, not just the original plan.

Anti-patterns

• Planning a single-subtask phase (just dispatch directly)
• Putting dependent tasks in the same parallel stage
• Skipping the review stage
• Assigning orchestrator-only tools (grep, web_search) to subagents
• Making the plan so detailed it duplicates the spec
• DoD grep patterns that match filenames containing the old name (e.g., docs/tools/eam-ecs-bounce.md is a filename, not a stale ref). List expected false positives explicitly in the DoD.

Related Skills

• writing-plans — Creates the implementation plan this skill decomposes into parallel stages. writing-plans defines what tasks exist; execution-planning defines how to run them (parallelism, agents, gates).
• subagent-driven-development — Executes individual tasks with TDD and review loops. Use within a stage when tasks need test-driven implementation. execution-planning handles the stage-level orchestration above it.
• Delegation format — The orchestrator prompt's Delegation Format section defines the 5-section briefing template for each task in the execution plan.
• dispatching-parallel-agents — General-purpose parallel dispatch. execution-planning is the structured version that produces a plan file and integrates with the spec workflow.