Planning & Execution

Part 1: Writing the Plan

Write comprehensive implementation plans assuming the engineer has zero codebase context and questionable taste. Document everything: which files to touch, complete code, testing, verification commands.

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

Plan Document Header

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies]

---

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• •"Write the failing test" — step
• •"Run it to confirm it fails" — step
• •"Implement minimal code to pass" — step
• •"Run tests to confirm pass" — step
• •"Commit" — step

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py`
- Test: `tests/exact/path/to/test.py`

**Step 1: Write the failing test**
[Complete code]

**Step 2: Run test to verify it fails**
Run: `exact command`
Expected: FAIL with "specific message"

**Step 3: Write minimal implementation**
[Complete code]

**Step 4: Run test to verify it passes**
Run: `exact command`
Expected: PASS

**Step 5: Commit**

Plan Requirements

• •Exact file paths always
• •Complete code in plan (not "add validation")
• •Exact commands with expected output
• •DRY, YAGNI, TDD, frequent commits

Part 2: Executing the Plan

Setup

1. •Create a todo list from the plan:

Use the todo tool:
  action: create, name: "[Feature Name]"

Then batch add all tasks:
  action: batch, items: [{ text: "Task 1: ...", group: "Phase 1" }, ...]

1. •Review plan critically — identify questions or concerns before starting

Execution Loop

For each task:

1. •Mark as in_progress: todo start #N
2. •Follow each step exactly (plan has bite-sized steps)
3. •Run verifications as specified
4. •Self-review (see checklist below)
5. •Mark as completed: todo done #N

After every 3 tasks, STOP and report:

• •What was implemented
• •Verification output
• •Any concerns
• •Say: "Ready for feedback."

Wait for human response before continuing.

Self-Review Checklist (per task)

After completing each task, before marking done:

Spec compliance:

• •Did I implement everything requested?
• •Did I build anything NOT requested? (Remove it)
• •Did I interpret requirements correctly?

Code quality:

• •Names clear and accurate?
• •Code clean and maintainable?
• •Following existing codebase patterns?
• •No over-engineering (YAGNI)?

Testing:

• •Tests verify behavior, not mocks?
• •TDD followed (test-first)?
• •Edge cases covered?

When to Stop

STOP executing immediately when:

• •Hit a blocker (missing dependency, unclear instruction)
• •Verification fails repeatedly
• •Plan has critical gaps

Ask for clarification rather than guessing.

Completion

After all tasks verified:

1. •Run full test suite
2. •Present status using todo summary
3. •Use the git-workflow skill for merge/PR options

Red Flags

• •Skipping verifications
• •Guessing when blocked instead of asking
• •Not tracking progress with todo tool
• •Implementing on main/master without consent
• •Marking tasks done without running verification