structured-project-execution

Structured Project Execution

Run large work against a single source of truth on disk so progress survives context loss, session boundaries, and agent handoffs. The discipline: plan → one task in flight → verify → record → repeat.

When to use

Multi-phase features, migrations, anything spanning multiple sessions or where another agent/person may pick up. Skip for single-sitting tasks — the bookkeeping costs more than it saves.

The execution file

Maintain PROGRESS.md (or the project's convention) at the repo root:

# <Project> — Progress

## Goal
<one paragraph: what done looks like>

## Plan
- [x] Phase 1: <deliverable> — verified by <check>
- [ ] Phase 2: <deliverable> — verified by <check>
- [ ] Phase 3: ...

## Now
<the single task currently in flight>

## Decisions
- <date>: chose X over Y because <reason>

## Blocked / Open
- <question or blocker, with what's needed to unblock>

This file is the contract. Update it as part of the work, not after.

Loop

1. Plan — decompose into phases that each end in a verifiable deliverable. Front-load the riskiest phase.
2. Pick one — exactly one task in ## Now. No parallel half-done work; it doesn't survive a context reset.
3. Execute — implement the smallest slice that satisfies the phase.
4. Verify — run the phase's stated check (tests, build, manual repro). Not "looks done" — the check passes.
5. Record — tick the box, clear ## Now, log any decision or new blocker. Commit-worthy state.
6. Repeat from the plan; re-plan if reality diverged.

Resuming (new session / handoff)

Read PROGRESS.md first. ## Now + last unchecked box = exactly where to continue. If ## Now is non-empty, that task was interrupted mid-flight — re-verify its state before proceeding (it may be partially done).

Quality bar

• Anyone can resume from PROGRESS.md alone with no chat history.
• Every checked box was verified by its stated check, not assumed.
• At most one task in flight at any time.
• Decisions are logged with their reason, so they aren't relitigated.

Anti-patterns

• Plan in chat only — gone on context reset, unusable for handoff.
• Marking a phase done without running its verification.
• Five phases "in progress" at once → unrecoverable state after interruption.
• Re-deriving a past decision because the reason was never written down.
• Updating PROGRESS.md "later" — later is after the context is gone.