# Iterative:implementing

> Execute a tech plan with dependency-aware batching, TDD, code review, and PR creation. Triggers: "implement the plan", "start building", "start implementing", "execute the plan".

- Skill: `tmchow/iterative-implementing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tmchow/iterative-implementing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tmchow/iterative-implementing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tmchow (https://skillmd.com/u/tmchow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tmchow/iterative-implementing

---


# Executing Work

Read the plan critically, create tasks, and implement with TDD, code review, and continuous testing. The plan is your guide — it contains the decisions, patterns, and test scenarios that drive implementation.

## When to Use

- After `iterative:tech-planning` skill completes a plan
- When a plan document exists and is ready to implement
- When tasks already exist from a prior session
- Can be invoked standalone with a plan document path

## Key Principles

1. **The plan is your guide** — Read referenced files and patterns, use the plan's decisions to drive implementation
2. **Clarify before building** — Ask questions now, not after building the wrong thing
3. **Test as you go** — Run tests after each change, not at the end
4. **Commit as you go** — One commit per completed subtask, never batch commits at the end
5. **Review at the right scope** — Section review after each plan section, final review of all branch changes, user chooses which severities to fix
6. **Stop when blocked** — Ask for help rather than guessing

## Workflow

### Phase 0: Detect Resume

1. Check for in-progress tasks related to this plan.
2. If tasks exist and work is in progress: load the plan document, summarize current state, show completed vs remaining subtasks, continue from next incomplete subtask (skip to Phase 2).
3. If no tasks exist: proceed to Phase 1 — **even if you have prior conversation context.** Having discussed the plan in a previous session is not the same as having set up tasks and workspace. Phase 1 setup (task creation, workspace isolation) must run before any implementation begins.

### Phase 1: Understand and Setup

1. **Find and read the plan document completely.** Check conversation context for referenced plans, scan `docs/plans/` for recent plan files. If no plan found, ask user for path. If no plan exists, ask the user: A) Create a tech plan first (recommended), B) I'll provide the plan path. If tech plan: invoke `iterative:tech-planning` skill.
2. **Review critically.** If anything is unclear or ambiguous, ask now. Do not skip this — better to clarify now than build the wrong thing.
3. **Workspace isolation.** See Workspace Setup section.
4. **Create tasks from the plan.** See Task Creation section.
5. **Execution preference.** Present an interactive choice to the user — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex): A) Execute all tasks, report when done (default), B) Pause after each plan section for feedback, C) Pause after each subtask for feedback.

### Phase 2: Execute (repeat per plan section)

1. **Record section baseline.** Before starting each plan section, capture the current commit: `git rev-parse HEAD`. This SHA is the section's baseline — used to scope reviews to only this section's changes.
2. **Analyze dependency graph.** Using the plan's `**Depends on:**` and `**Files:**` fields, group the section's subtasks into execution batches — subtasks with no unmet dependencies form the next batch.
3. **Execute batch.** For each batch, spawn subagents for all subtasks (concurrently when multiple). Always use subagents, even for single-subtask batches — this keeps implementation detail out of the orchestrator's context, preserving capacity for reviews, phase transitions, and user interaction. Each subagent receives:
   - Path to the tech plan document
   - Subtask number and title
   - Parent task context
   - Task ID
4. Worker reads subtask from plan, loads referenced patterns, implements with TDD (tests first), commits, and updates task status (see task-worker agent for details).
5. **Wait for batch completion.** All subagents in the batch must finish before the next batch starts.
6. **Test verification gate.** After each batch completes, verify that feature subtasks produced test files. For each completed feature subtask, check: does the test file listed in the plan's `**Files:**` field exist, and does it contain tests matching the plan's `**Test scenarios:**`? If a feature subtask committed without tests, flag it immediately — do not continue to the next batch until resolved.
7. **Repeat** steps 3-6 for remaining batches.
8. Update plan document progress (mark completed items).
9. Mark section complete in task system.
10. **Section code review.** Run after all subtasks in the plan section are complete (see When to Review table for trivial exceptions). **Skip if this is the only section in the plan** — Phase 3's final review will cover the same code plus simplification changes, so a section-level review would be redundant. For multi-section plans: scope to `git diff <section-baseline-sha>..HEAD`. Pass the baseline SHA and plan context to the `code-review` skill. **Wait for the review to complete and fixes to land before moving on.** Do not run anything else in parallel with code review — it needs to see the final code. **Placeholder exclusion:** When the review returns findings targeting code that is an acknowledged placeholder for a later plan section, exclude those findings from severity acceptance — they will be addressed in a later section and caught by the final review. Note excluded count and reasons in the review summary (e.g., "Excluded 1 finding — placeholder for section 3").

### Phase 3: Finish

**Phase 3 steps are strictly sequential. Do not parallelize them** — each step depends on the output of the previous one.

1. Verify: all tasks complete, all section-level code reviews passed.
2. **Detect base branch.** `git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master`. Use this for all branch-level scoping in Phase 3.
3. **Simplification pass.** If `/simplify` is available, invoke it to review and clean up changed code. Otherwise, do a manual review of changed files (`git diff --name-only $(git merge-base HEAD <base>)..HEAD`) and apply behavior-preserving simplifications: flatten nesting, remove dead code, simplify expressions, collapse single-use variables. This is a single bounded pass — not a refactor. **Wait for simplification to complete before proceeding** — the final review must see simplified code.
4. **Final review offer.** Present an interactive choice to the user: A) Full code review of complete work (recommended), B) Skip to finish.
5. If review: invoke `code-review` skill with scope `git diff $(git merge-base HEAD <base>)..HEAD` (all branch changes including simplification).
6. **Severity acceptance (separate prompt).** If the review found issues at any severity, present severity acceptance (see Severity Acceptance section). This is its own prompt — do not combine it with next-step options, and do not skip it even when all issues are Medium/Low. "Clean" means zero findings at any severity. If no findings, skip to step 7.
7. **Next steps (separate prompt, after fixes land or user skipped fixes).** Present an interactive choice to the user: A) Another review round, B) Wrap up and create PR, C) I'll handle PR/merge myself (exit). Do not recommend wrap-up if fixes were just applied — recommend **another round** to verify. Recommend **wrap up** only when zero findings or user chose to skip all fixes.
8. Repeat steps 5-7 if user chooses another round.

## Workspace Setup

Ensure the agent has an isolated workspace before creating tasks or writing code.

**First: sync with remote**
Pull the latest from the default branch before creating any branch or worktree.

**Then: check current state**

| Situation | Action |
|-----------|--------|
| Already in a worktree | Confirm it's for this feature, then proceed |
| On default branch | Ask the user: A) Create worktree (recommended), B) Create branch, C) Continue on main (requires explicit consent) |
| On a feature branch | Ask the user: A) Continue on this branch, B) Create new worktree |

Invoke the `git-worktree` skill if a worktree is needed.

## Task Creation

Task creation happens inside Phase 1, after the plan is read and clarified. This ensures the implementer understands the plan before tasks are locked in.

### Task Tracking

Use built-in task tracking for all plans. Tasks are lightweight and session-scoped.

**Platform mapping:** Claude Code provides task objects (`TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`) — use these directly. Codex composes equivalent tracking from `update_plan` (plan steps as task state) + `spawn_agent`/`wait`/`close_agent` (delegation). The workflow is the same: create tasks from the plan, track status, and mark complete — only the tool names differ.

### Parsing the Plan

The plan's standardized subtask format (numbered, with dependencies and files) maps directly to tasks:
- Plan sections → parent tasks
- Numbered subtasks → child tasks
- `Depends on` fields → task dependencies
- `Files` fields → description references in tasks

Show the proposed task structure to the user for approval before creating.

### Parent Task Descriptions

- Always link to the technical plan document — include the plan file path in the description
- **Single parent:** description includes the plan overview — what's being built and why
- **Multiple parents:** each describes its relationship to the feature and what subset of work it covers

### Subtask Descriptions

- Copy relevant plan prose into description
- Include file paths from the plan's `**Files:**` fields
- If very complex: summarize, reference section by name

## Commit Pattern

- 1 commit per completed subtask (default)
- Commit only when tests pass — never commit with failing tests
- Heuristic: can you write a meaningful commit message? If yes, commit. If it would be "WIP", group with the next related subtask.

## Code Review

### When to Review

| Trigger | Review Level |
|---------|-------------|
| **Section review** (after all subtasks in a plan section complete) | Full review via `code-review` skill. **Skip if single-section plan** — Phase 3 final review covers it |
| **Trivial section** (config, single-line, renaming only) | Skip review — note in progress report |

### Severity Acceptance

**This is its own prompt — do not combine it with next-step options.** Present severity acceptance whenever the review has findings at ANY severity, including Medium/Low-only reviews. Do not interpret "no Critical/High" as "clean" — clean means zero findings. **Use the platform's interactive question tool** — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex) — for all severity acceptance prompts. Do not print options as text. Both platforms provide an automatic "Other" free-form option — do not add one manually.

Present a **single prompt** listing all severity levels with findings. No intermediate "choose which..." step.

**Claude Code** — use `AskUserQuestion` with `multiSelect: true`:

When Critical or High issues exist, pre-check the Critical+High option:
- ☑ **Critical + High (Recommended)** — N Critical, N High
- ☐ **Medium** — N issues
- ☐ **Low** — N issues

When only Medium/Low issues exist, nothing pre-checked:
- ☐ **Medium** — N issues
- ☐ **Low** — N issues

Only include severity levels that have findings.

**Codex** — use `request_user_input` (single-select, build combined options):

When Critical or High issues exist:
- **Fix Critical + High (Recommended)** — N issues
- **Fix Critical + High + Medium** — N issues
- **Fix all** — N issues
- **Skip fixes**

When only Medium/Low issues exist:
- **Fix Medium only** — N issues
- **Fix Medium + Low** — N issues
- **Skip fixes**

Only include options where findings exist at those levels. Omit options that would duplicate another (e.g., if no Low, omit "Fix all" since it equals the line above).

### Applying Fixes

Fix only the selected severities. Spawn a **single subagent** to apply all selected fixes — do not fix in the main thread (preserves context for subsequent review rounds and wrapup).

The subagent receives:
- The filtered findings list (only selected severities)
- The affected file paths
- Instruction to apply all fixes, run tests, and commit

One subagent (not one per finding) because findings can interact — a security fix and a correctness fix in the same function need to see each other. This mirrors the simplification pattern: one bounded pass, specific scope, commits separately.

Wait for the subagent to complete before proceeding. Next-step options come AFTER fixes land, as a separate prompt (Phase 3 step 7).

By the time implementing hands off to `implementation-wrapup`, all code reviews are complete. Wrapup skips its own review offer and handles verification, PR, and cleanup.

## Plan Adjustment

If reality diverges from the plan during implementation:

- **Minor adjustments** (different file path, small API change): update the plan document in place and continue. Note the change in the progress report.
- **Significant divergence** (missing requirement, wrong approach): stop and report the divergence. Present an interactive choice: A) Update the plan and continue, B) Continue as-is, C) Stop execution. If the divergence contradicts the PRD (not just the tech plan), update the PRD as well — it's the requirements source of truth for downstream validation.
- **Blocked by external dependency**: mark the subtask as blocked, skip to next unblocked subtask, and report.

## When Things Go Wrong

**Stop and ask for clarification (plain text, not structured options) when:**
- Subtask instructions are unclear — explain what's ambiguous
- Tests fail and fix isn't obvious — describe the failure and what was tried
- Missing dependency or blocker — report what's missing
- Verification fails repeatedly (3x) — report what was attempted
- Human comment on task requires response

**If a subtask fails:**
1. Report the failure clearly — what was attempted and what went wrong
2. Present an interactive choice: A) Retry with a different approach, B) Skip and continue to next subtask, C) Stop execution

## Anti-Patterns to Avoid

| Anti-Pattern | Better Approach |
|--------------|-----------------|
| Jumping to code without reading plan context | Read each subtask's referenced files and patterns first |
| Skipping clarification to start faster | Ask questions now — building the wrong thing is slower |
| Creating tasks before understanding the plan | Read and clarify the plan, then create tasks |
| Committing with failing tests | Only commit when tests pass |
| Committing feature subtask without writing tests | TDD: write tests first from plan's test scenarios, then implement |
| Skipping Phase 1 because of prior conversation context | Prior context ≠ setup complete. If no tasks exist, run Phase 1 — task creation, workspace isolation |
| Pushing through when blocked | Stop and ask for help |
| Running code review in parallel with simplification or other code changes | Code review must see final code. Simplify → wait → review. Never parallelize steps that change code with steps that review it |
| Full code review on trivial changes | Scale review to complexity — skip for config changes |
| Modifying the plan silently | Report divergence and get user agreement |
| Applying TDD rigidly to config/refactoring subtasks | TDD for feature work, verify for non-feature work |

## Transition Points

**Always present options to the user at transition points using the platform's interactive question tool** — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex). Never print options as text or end the turn without presenting a choice.

After simplification pass completes (Phase 3 step 4), present options:
- Full code review of complete work (recommended)
- Skip to finish

After review (or skip), present options:
- Another review round (recommended if Critical/High issues were just fixed)
- Wrap up and create PR (recommended otherwise)
- I'll handle PR/merge myself (exit)

## Additional Resources

### Reference Files

For templates and detailed guidelines, consult:
- **`references/progress-template.md`** — Execution progress report format