pantheon-org/plan-execute

Plan Execute — Checklist-Driven Implementation with Honest Proof

Execute an implementation plan through its phases, validating every task with verifiable proof before marking it done. If proof is missing or falsified, the agent goes back and completes the work. No exceptions.

Core Principle

HONESTY IS NON-NEGOTIABLE. A checked item without proof is a lie. A plan with lies is not done. Broken trust means the implementation cannot be trusted and must be redone.

At a Glance

1. Baseline — run all gates before touching code.
2. Checklist — create .context/plans/<slug>/CHECKLIST.md with every task.
3. Per-task — work, quick-gate after 1-3 file ops, full-gate at task end.
4. Per-phase — all tasks done → phase gate suite → domain invariant → commit.
5. Final — full gates + global audit + checklist integrity audit → DONE.

If any step fails: stop, fix, re-run, record proof. No exceptions.

Position in the Workflow

plan-create / implementation-planner → plan-review → plan-execute → commit / merge
     (design)              →   (audit)   →   (implement)  →  (ship)

Prerequisites

• A .context/plans/*.md plan file with valid frontmatter, phases, and tasks
• The plan has been reviewed (status: ACTIVE or DRAFT with explicit go-ahead)
• opencode.json has subAgents configured for large-phase delegation
• A working branch exists or can be created per the plan's branch workflow

Inputs

• Plan path — .context/plans/<plan-slug>/README.md
• Phase files — .context/plans/<plan-slug>/phases/phase-*/README.md
• Task files — .context/plans/<plan-slug>/phases/phase-*/tasks/*.md
• Branch name — from the plan or user
• Gate commands — from AGENTS.md, package.json, or CI config

Outputs

• CHECKLIST.md — living checklist at .context/plans/<plan-slug>/CHECKLIST.md
• Commits — one per phase, with evidence in message body
• Execution Report — appended to the plan's README.md
• Updated plan frontmatter — status: DONE (only when fully validated)

When to Use

• The user says "implement this plan", "execute the plan", "start working on it"
• A reviewed plan is ready and the user wants to begin coding
• A phase needs to be picked up and completed
• The user wants to "do the work" described in a .context/plans/ file

When NOT to Use

• The plan has not been reviewed — use plan-review first
• The user only wants a single file edited with no plan context — just edit it
• The work is exploratory or speculative — plans are for known scope
• The plan is stale (months old) — re-review it before executing

The Checklist System

The checklist is a living contract between the agent and the plan. It lives at .context/plans/<plan-slug>/CHECKLIST.md alongside the plan.

Every checklist entry must contain:

1. Task — what was supposed to be done
2. Verification — the exact command(s) run to prove it
3. Expected — what the output should be
4. Actual — the real output (copied verbatim)
5. Status — PENDING, IN_PROGRESS, VALIDATED, or BLOCKED

Status Definitions

• PENDING — not started yet
• IN_PROGRESS — work begun, not yet validated
• VALIDATED — work done, verification run, proof recorded
• BLOCKED — cannot proceed, reason documented

RULE: An item marked VALIDATED without Actual output is a lie. The agent must go back, run the verification, and record the output before proceeding.

Workflow

1. Pre-Flight: Create the Checklist

1a. Read the plan

Read the plan README.md and all phase README.md files. Extract every task from every phase. Read all task files under tasks/.

1b. Discover the gates

Find the project's verification commands from AGENTS.md, package.json, CI config, or by asking the user. Record them:

Typecheck:  <command>  (e.g., vue-tsc --noEmit)
Build:      <command>  (e.g., npm run build)
Test:       <command>  (e.g., npm test)
Lint:       <command>  (e.g., npm run lint)

1c. Run the Baseline

Run all gates against the current branch before touching any code. Record the output verbatim in the checklist under a "Baseline" section.

## Baseline (before any changes)
- [ ] Typecheck
  - Command: <typecheck>
  - Expected: exit 0
  - Actual: <paste full output>
  - Status: VALIDATED

- [ ] Build
  - Command: <build>
  - Expected: exit 0
  - Actual: <paste full output>
  - Status: VALIDATED

- [ ] Tests
  - Command: <test>
  - Expected: all pass
  - Actual: <paste full output including counts>
  - Status: VALIDATED

- [ ] Lint
  - Command: <lint>
  - Expected: clean
  - Actual: <paste full output>
  - Status: VALIDATED

CRITICAL: If the baseline has failures, document them. They are your regression reference. Any new failure after your changes is a regression you introduced.

1d. Write the Checklist File

Create .context/plans/<plan-slug>/CHECKLIST.md with all tasks from all phases, in order. See references/checklist-templates.md for the full CHECKLIST.md template and a worked example from a real phased run.

2. Per-Task Execution

For each task, in order:

2a. Work the task

Implement the task per its instructions. Create/modify/delete files as specified.

2b. Quick validation after atomic changes

After every 1-3 file operations, run the quick gate (typically typecheck):

### P<NN>T<NN> — Quick Validation
- Command: <typecheck>
- Actual: <paste output>
- Status: <VALIDATED if pass, IN_PROGRESS if fail>

If it fails: Stop. Fix the issue. Re-run the command. Record the new output. Do not proceed to the next file operation until this passes.

2c. Task-level validation

After all file operations for the task are complete, run the full gate suite:

### P<NN>T<NN> — Task Validation
- Command: <typecheck> && <build> && <test> && <lint>
- Actual: <paste full output>
- Status: <VALIDATED or IN_PROGRESS>

If it fails: Stop. The task is not done. Fix the issue. Re-run. Update the checklist with the new output. Do not proceed to the next task until this passes.

2d. Structural audit (if applicable)

If the task involves mechanical changes (import path changes, file splitting, naming conventions), run the structural audit and record the output:

### P<NN>T<NN> — Structural Audit
- Command: <audit command>
- Expected: <zero / empty / nothing>
- Actual: <paste output>
- Status: <VALIDATED if matches expected, IN_PROGRESS if not>

If it fails: The task is not done. The mechanical standard is not met. Go back and fix the files. Re-run the audit. Record the new output.

2e. Update the checklist

After the task passes all validations, update its checklist entry:

### P01T01 — <Task Name>
- [x] Task: <description>
- [x] Files created: <list>
- [x] Files modified: <list>
- [x] Files deleted: <list>
- [x] Quick gate after atomic changes
  - Command: <command>
  - Actual: <output>
  - Status: VALIDATED
- [x] Full gate suite at task end
  - Command: <command>
  - Actual: <output>
  - Status: VALIDATED
- [x] Structural audit
  - Command: <command>
  - Expected: <expected>
  - Actual: <output>
  - Status: VALIDATED
- [x] Status: VALIDATED

RULE: You may only mark an item with [x] after recording the Actual output. An [x] without Actual output is a lie.

3. Per-Phase Validation

After all tasks in a phase are validated, validate the phase as a whole:

3a. Phase gate suite

Run the full gate suite for the entire phase:

## Phase 01 — Validation
- Command: <typecheck> && <build> && <test> && <lint>
- Actual: <paste full output>
- Status: <VALIDATED or IN_PROGRESS>

If it fails: One or more tasks have an interaction bug. Stop. Diagnose which task caused it. Fix it. Re-validate the affected task(s). Re-run the phase suite.

3b. Domain invariant

Run the phase-specific domain invariant check (e.g., byte-identical output, benchmark comparison, integration test):

- Domain invariant: <description>
- Command: <command>
- Expected: <expected result>
- Actual: <output>
- Status: <VALIDATED or IN_PROGRESS>

If it fails: The phase broke something the generic gates cannot detect. Stop. Fix it. Re-run.

3c. Regression diff

Compare the phase result to the baseline:

- Baseline tests: <X pass, Y fail>
- Phase tests: <X pass, Y fail>
- New failures: <count>
- Status: <VALIDATED if no new failures, IN_PROGRESS if any>

If new failures exist: You introduced a regression. Stop. Fix it. Re-run.

3d. Commit the phase

Commit with evidence in the message:

git add -A
git commit -m "feat(scope): phase N — <phase-name>

<one-line summary>

Checklist evidence:
- Typecheck: <paste result line>
- Build: <paste result line>
- Tests: <paste result line>
- Lint: <paste result line>
- Domain invariant: <paste result line>
- Regression: no new failures (or: fixed N pre-existing)"

Record the commit hash in the checklist.

3e. Phase checklist update

## Phase 01 — <Phase Name>
- [x] All tasks validated
- [x] Phase gate suite passes
  - Command:
  - Actual:
- [x] Domain invariant holds
  - Command:
  - Actual:
- [x] Regression diff: no new failures
- [x] Committed as: <hash>
- [x] Status: VALIDATED

4. Between-Phase Rules

• If Phase N+1 depends on Phase N: Phase N must be VALIDATED before starting Phase N+1. No exceptions.
• If a phase is independent: It may be delegated to a subagent in parallel, but the subagent must produce its own checklist evidence.

5. Plan Divergence Handling

If reality diverges from the plan during implementation:

1. Stop. Do not continue.
2. Document the divergence in the checklist under a "Divergence" section:

   ## Divergence — Phase 02, Task 03
   - Expected: <what the plan said>
   - Actual: <what reality required>
   - Reason: <why>
   

3. Amend the plan using plan-create amendment pattern.
4. Re-review if the amendment is significant (new tasks, changed gates, altered scope).
5. Update the checklist with the amended tasks.
6. Continue from where you stopped.

Never implement something not in the plan (or its amendment) without updating the checklist and plan first.

6. Final Verification

After all phases are validated and committed:

6a. Full gate suite

Run all gates one final time on the complete branch:

## Final Verification
- Command: <typecheck> && <build> && <test> && <lint>
- Actual: <paste full output>
- Status: <VALIDATED>

6b. Global structural audit

Run the plan's global success criteria:

- Criterion 1: <description>
  - Command: <command>
  - Expected: <expected>
  - Actual: <output>
  - Status: <VALIDATED>

- Criterion 2: <description>
  ...

6c. Checklist completeness audit

Scan the checklist for any item that is:

• Marked [x] but has no Actual output → LIE. Go back.
• Marked [-], [ ], or IN_PROGRESS → INCOMPLETE. Go back.

# Example: find unchecked items
grep -n "\[ \|IN_PROGRESS\|BLOCKED" CHECKLIST.md
# Must return nothing

If any item is unchecked or lacks proof: The plan is NOT done. Go back to the offending item. Complete it. Record the proof. Re-run the final verification.

7. Final Report

Write a final report in the checklist file:

The final report captures summary, evidence, regressions, divergences, and checklist integrity. See references/checklist-templates.md for the full Final Report template.

8. Update the Plan File

Append the final report to the plan's README.md under a new ## Execution Report section. Update the plan frontmatter:

---
status: DONE  # or ACTIVE if not fully done
date: <original date>  # do not change
---

If the plan is NOT done (unchecked items, missing proof, new regressions), set status: ACTIVE and document why in the Execution Report.

A plan with status: DONE and a lying checklist is worse than a plan with status: ACTIVE. Honesty is the only path to DONE.

Anti-Patterns

NEVER — Mark a checklist item [x] without recording the Actual output. SYMPTOM: The checklist looks complete but cannot be verified. Broken trust. FIX: Every [x] must have a verbatim command output below it.

NEVER — Skip the pre-flight baseline. SYMPTOM: Cannot distinguish your regressions from pre-existing issues. FIX: Baseline is mandatory. No exceptions.

NEVER — Mark a phase VALIDATED when a task inside it is still IN_PROGRESS. SYMPTOM: A task has an unvalidated interaction bug that only shows at phase level. FIX: Every task must be VALIDATED before the phase can be validated.

NEVER — Claim the plan is DONE with unchecked items. SYMPTOM: Residual work, broken trust, plan appears complete but is not. FIX: The final checklist completeness audit must return zero unchecked items.

NEVER — Falsify proof to make a checklist item pass. SYMPTOM: Command output is invented, truncated, or from a different run. FIX: Copy output verbatim. If it does not match Expected, fix the code and re-run. Do not edit the output.

NEVER — Squash phases or skip the per-phase commit. SYMPTOM: Cannot bisect which phase introduced a regression. Cannot roll back a single phase. FIX: Commit after every phase. Record the hash in the checklist.

NEVER — Accept a subagent's output without running your own gate. SYMPTOM: Subagent claims all tests pass, but you never verify. A hidden regression leaks into the branch. FIX: After the subagent returns, run at least one gate yourself. Compare its claimed output to your actual output. If they differ, send the subagent back to fix it before marking the phase VALIDATED.

Honesty Checklist (Meta)

Before declaring the plan DONE, ask yourself:

• [ ] Did I run every verification command I claim to have run?
• [ ] Is every Actual output verbatim, not edited or invented?
• [ ] Are there any [x] marks without proof below them?
• [ ] Did I re-run any command that failed until it passed?
• [ ] Did I document every divergence from the original plan?
• [ ] If I delegated to a subagent, did I verify its proof myself?
• [ ] Am I willing to show this checklist to another agent for audit?

If any answer is NO, the plan is NOT DONE. Go back and fix it.

References

• references/checklist-templates.md — full CHECKLIST.md template, worked example, and Final Report template
• plan-create skill — upstream: creates the plan this skill executes
• plan-review skill — upstream: audits the plan before execution
• implementation-planner skill — upstream: decomposes PRDs into phased plans
• .context/findings/proof-of-work-methodology.md — the 7-step verification sequence extracted from a real 6-phase implementation
• .context/plans/<plan-slug>/CHECKLIST.md — the living checklist for this plan