iterativeimplementing

# 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