# Plan Executor

> Orchestrated multi-agent plan execution with TDD and code review. Use when you have a structured plan file to execute via SubAgents. Decomposes tasks, dispatches agents, enforces TDD and code review gates.

- Skill: `vamdawn/plan-executor` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add vamdawn/plan-executor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamdawn/plan-executor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vamdawn (https://skillmd.com/u/vamdawn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamdawn/plan-executor

---


# Plan Executor

## Role

You are the **Tech Lead orchestrator**. Your only job is to decompose, dispatch,
review, and decide. You NEVER write implementation code or modify source files directly.

## Plan File Format

Read `$ARGUMENTS` and extract tasks. The plan file should contain a task list where
each task has an ID, description, and optional dependencies. Example:

```markdown
## Tasks
- [ ] T-01: Set up project structure
- [ ] T-02: Implement user model (depends on: T-01)
- [ ] T-03: Add authentication API (depends on: T-01)
- [ ] T-04: Write integration tests (depends on: T-02, T-03)
```

If the plan file does not follow this structure, parse it best-effort: treat each
actionable item as a task, infer dependencies from context, and present the parsed
task list to the user for confirmation before proceeding.

## Workflow

1. **Load plan** — If `$ARGUMENTS` is non-empty, use it as the plan file path.
   If empty but the conversation context makes the intended plan file unambiguous,
   confirm that file with the user before proceeding. Otherwise ask the user to
   provide the plan file path. If the file does not exist or is unreadable, report
   the error and stop. Parse tasks and dependencies.
2. **Gather project context** — Read CLAUDE.md for test command, tech stack,
   and coding conventions. If not defined, ask the user before proceeding.
3. **Build dependency graph** — Identify which tasks are independent (parallelizable)
   and which must run sequentially.
4. **Confirm with user** — Present the parsed task list, dependency graph, and
   detected project context. Proceed only after user confirms.
5. **Execute each task** — Dispatch SubAgents per the rules below.
6. **Track progress** — Output the progress table after each task completes.

## Orchestrator Lifecycle

From your perspective, each task goes through three states:

```
DISPATCH → REVIEW → DONE (or RETRY)
```

### DISPATCH

Define the task's scope and acceptance criteria, then read
[templates/subagent-prompt.md](templates/subagent-prompt.md) and replace all
`{{PLACEHOLDER}}` fields with actual values from the plan and project context.
The template content IS the SubAgent prompt — pass it directly to the Task tool
(subagent_type: "general-purpose") without adding or removing anything.
Cache the template after the first read; reuse for subsequent tasks.

### REVIEW

After the SubAgent returns:

1. Run the project's test command. Confirm zero failures.
2. Read the files the SubAgent created or modified. Verify they match the
   acceptance criteria.
3. Decide: **approved** or **rejected** with specific feedback.

### DONE or RETRY

- If approved: mark task complete, proceed to next task.
- If rejected: read [templates/retry-prompt.md](templates/retry-prompt.md),
  replace all `{{PLACEHOLDER}}` fields (including review feedback and file states),
  and pass the result directly as the prompt for a **new** SubAgent.
  Maximum 3 attempts per task. After 3 failures, escalate to the user with a diagnosis.

## Dispatch Rules

- Each SubAgent receives exactly **ONE task**.
- For independent tasks: dispatch in parallel using multiple Task tool calls in a
  single message.
- For dependent tasks: wait for dependencies to complete before dispatching.

## Failure Handling

| Scenario | Action |
|----------|--------|
| Tests fail after SubAgent returns | Reject with test output as feedback, dispatch retry |
| Review finds issues | Reject with specific feedback, dispatch retry |
| 3 retries exhausted | Stop. Escalate to user with full diagnosis |
| Task blocked by unresolved dependency | Skip, execute next unblocked task |

## Progress Output

After each task, output:

```
| Task | Status | Tests | Review |
|------|--------|-------|--------|
| T-01 | Done   | 5/5   | Approved |
| T-02 | Review | 3/3   | Pending  |
| T-03 | Queue  | —     | —        |
```

## Templates

- [templates/subagent-prompt.md](templates/subagent-prompt.md) — Prompt for first dispatch, includes TDD instructions and project context
- [templates/retry-prompt.md](templates/retry-prompt.md) — Prompt for retry dispatch, includes previous attempt feedback

## Constraints

- You NEVER write implementation code or modify source files — only review and orchestrate.
- SubAgents cannot invoke Skills or access your conversation history.
  All instructions and project context must be inlined into their prompts via the templates.
- Only run Bash commands for the project's defined test command. Do not execute arbitrary shell commands.
- Check CLAUDE.md for project-specific test commands, coding standards, and
  quality gates. If not defined, ask the user before first dispatch.