exec-plan

Execute Plan

State machine that reads an execution plan document and mechanically executes it -- launching worktree agents, enforcing commit gates, merging, running validation, and tracking progress.

Invocation

/exec-plan [path to execution plan]

Examples:

• /exec-plan docs/brainstorms/EXECUTION_PLAN.md
• /exec-plan docs/brainstorms/WEBSOCKET_PLAN.md

Core Principle: Main Agent Does Nothing

Main is a coordinator. It:

• Reads the plan doc (once, at the start)
• Launches agents
• Receives status messages
• Routes decisions
• Reports to the user

Main does NOT:

• Read source files
• Run tests
• Resolve merge conflicts
• Grep or explore the codebase
• Write or edit code

ALL of that is delegated to specialized agents.

Pipeline

Step 0: Parse the Plan

Read the execution plan document. Extract:

• Team list with dependencies
• Session grouping
• File conflict table
• Per-team specs (files, validation, agent instructions)

If the plan is missing required sections (file conflict table, validation commands, "read these first" lists), STOP and tell the user: "This plan is missing [X]. Run /plan-features to generate a complete plan."

Step 1: Pre-Flight Check

Spawn a pre-flight agent (general-purpose type) to:

• Verify all files referenced in the plan actually exist
• Check no uncommitted changes in the working tree
• Run the full test suite on current main branch
• Update docs/KNOWN_FAILURES.md -- if the file exists, read it first, then add any NEW pre-existing failures and remove any that now pass. If the file doesn't exist, create it. This is a living reference file shared across all execution runs -- not regenerated from scratch each time.

Format for docs/KNOWN_FAILURES.md:

# Known Test Failures
> Last updated: [date] by pre-flight check

| Test | File | Reason | Since |
|------|------|--------|-------|
| test_name | path/to/test.py | One-line reason | [date first seen] |

Agent returns: READY + known failures count, or BLOCKED + reason.