executing-plans

Executing plans

Phase 0: branch + context guard (mandatory)

Before any file write or reasoning-heavy step:

1. Branch: run git branch --show-current. If on a baseline branch (main, master, test per orchestrator-manifest.yaml), STOP and create a working branch first per the prefix rules in skills/git-workflow/SKILL.md:

   • fix/ for bugs
   • chore/ for maintenance, docs, tooling
   • release/ for version lines
   • feature/ otherwise

   Do NOT proceed on a baseline branch.

2. Deep context (always): dispatch the context-loader subagent via the Agent tool, passing the user's verbatim prompt. Wait for the returned context pack. Treat its excerpts as your working knowledge-base context for the rest of this skill.

   The dispatch is unconditional. The skip decision belongs to context-loader itself — its triviality gate (agents/context-loader.md, Step 1: ≤5 words + no action keyword, or pure acknowledgment, or pure meta-question) returns a Trivial: yes pack cheaply when warranted. Do not pre-judge triviality from the caller side; "I already loaded context earlier in the session" or "this seems like a small change" is not valid grounds to skip. If the returned pack is marked Trivial: yes, proceed without KB context.

Overview

Purpose: Provide disciplined, single-session execution of implementation plans. Follow the plan step by step, track progress visibly, and resist the temptation to improvise.

Core principle: The plan already absorbed the decision-making cost. Execution should be mechanical. Creativity during execution is a smell — it means the plan was incomplete.

Announce at start: "I'm using the executing-plans skill to work through this plan step by step."

When to use

• A plan exists under docs/plans/ and has been reviewed
• Resuming work on a partially-executed plan
• Single-agent execution (no parallel sub-agents needed)

When NOT to use

• No plan exists yet (use writing-plans first)
• The work requires parallel execution across multiple worktrees (consider sub-agent orchestration)
• The plan is clearly wrong or outdated — update the plan first, then execute

Workflow

1. Load and assess

1. Read the full plan document
2. Read the linked spec for context
3. Identify which tasks are already complete (check for progress markers, existing files/code)
4. Confirm the starting task with the user: "Tasks T1-T3 appear complete. Starting from T4. Correct?"

2. Execute task-by-task

For each task:

1. Announce — "Starting T4: Create webhook handler types"
2. Read — Review the files listed in the task; understand current state
3. Implement — Make exactly the changes described. If the task specifies tests, write them (follow test-driven-development discipline if applicable)
4. Verify — Run relevant tests, linter, or build checks. The project must remain in a working state after each task.
5. Mark done — Update the plan document: add [x] or DONE marker to the completed task with a timestamp
6. Commit — One commit per task (or per logical group of 2-3 small tasks). Commit message references the task ID: T4: create webhook handler types

3. Handle deviations

Reality will diverge from the plan. Handle it honestly:

Situation	Response
Task is smaller than expected	Complete it, note it, move on
Task is larger than expected	Split it into sub-tasks (T4a, T4b) in the plan, then execute them
Task reveals a missing prerequisite	Insert a new task before the current one, document why
Task contradicts the spec	Stop. Flag the contradiction to the user. Do not guess which is correct.
Task is no longer needed	Mark as SKIPPED with reason, move on

Never silently skip a task or combine tasks without updating the plan document.

4. Progress tracking

Keep a running status at the top of the plan document:

## Progress
- [x] T1: Define types — 2026-04-07 14:30
- [x] T2: Core handler — 2026-04-07 14:35
- [ ] T3: Route wiring
- [ ] T4: Integration tests

This makes resumption trivial if the session is interrupted.

5. Completion

When all tasks are marked done:

1. Run the full test suite — not just the tests you wrote, but all tests
2. Verify the build passes
3. Review all acceptance criteria from the spec — each must be demonstrably met
4. Transition to branch completion: apply skills/verification-before-completion and then the branch finishing workflow

Rules

1. TDD by default. Every task that produces code MUST follow test-driven-development: write a failing test → make it pass → refactor. Load the test-driven-development skill if not already loaded.
2. Follow the plan order. Task dependencies exist for a reason. Do not skip ahead because a later task looks easier.
3. One task at a time. Do not "batch" multiple tasks unless they are trivially small (< 1 minute each) and independent.
4. Commit after each task. This creates a clean history that can be bisected, reviewed, and reverted per-task.
5. Do not refactor outside the plan. If you spot something that needs cleanup but is not in the plan, note it as a follow-up. Do not mix unplanned refactoring with planned execution.
6. Keep the plan document updated. The plan is the single source of truth for progress. If it does not reflect reality, it is useless.

Anti-patterns

• "I'll just do T3 and T5 together since they touch the same file" — This hides progress and makes rollback harder. Execute them separately.
• Abandoning the plan mid-execution — If the plan is wrong, fix the plan first. Switching to ad-hoc coding means you lose tracking, ordering, and the ability to resume.
• Skipping verification between tasks — "I'll test at the end" is how you discover at task T8 that task T2 was wrong.
• Gold-plating during execution — The plan says "add error handling for timeout." Do that. Do not also add retry logic, circuit breakers, and observability unless the plan calls for it.
• Forgetting to commit — Uncommitted work across multiple tasks is unrecoverable if the session fails.

Integration

Receives from:

• skills/writing-plans — the plan document to execute

Transitions to:

• skills/verification-before-completion — final check before claiming done
• skills/compound-retrospective — capture lessons after execution completes