diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index ea7ac8fd8b..fdc1dfbec1 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -121,10 +121,18 @@ Implementer subagents report one of four statuses. Handle each appropriately: ## Prompt Templates -- `./implementer-prompt.md` - Dispatch implementer subagent +- `./implementer-prompt.md` - Dispatch implementer subagent (uses two-commit strategy: checkpoint after impl, final after reviews) - `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent - `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent +## Commit Strategy + +Each task produces **two commits** to balance traceability with conflict avoidance: +1. **Checkpoint commit** — immediately after implementation and self-test pass +2. **Final commit** — after both spec and code quality reviews approve + +During review fix rounds, implementers use `git commit --amend` to squash fixes rather than creating separate commits. This avoids the ~25+ commits typical of large plans while preventing long-running uncommitted code that risks merge conflicts. + ## Example Workflow ``` @@ -148,14 +156,17 @@ Implementer: "Got it. Implementing now..." - Implemented install-hook command - Added tests, 5/5 passing - Self-review: Found I missed --force flag, added it - - Committed + - Committed (checkpoint commit #1) [Dispatch spec compliance reviewer] Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra -[Get git SHAs, dispatch code quality reviewer] +[Dispatch code quality reviewer] Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved. +[Implementer creates final commit #2] +Implementer: All reviews passed, final commit + [Mark Task 1 complete] Task 2: Recovery modes @@ -168,15 +179,15 @@ Implementer: - Added verify/repair modes - 8/8 tests passing - Self-review: All good - - Committed + - Committed (checkpoint commit #1) [Dispatch spec compliance reviewer] Spec reviewer: ❌ Issues: - Missing: Progress reporting (spec says "report every 100 items") - Extra: Added --json flag (not requested) -[Implementer fixes issues] -Implementer: Removed --json flag, added progress reporting +[Implementer fixes issues with --amend] +Implementer: Removed --json flag, added progress reporting, amended checkpoint commit [Spec reviewer reviews again] Spec reviewer: ✅ Spec compliant now @@ -184,12 +195,15 @@ Spec reviewer: ✅ Spec compliant now [Dispatch code quality reviewer] Code reviewer: Strengths: Solid. Issues (Important): Magic number (100) -[Implementer fixes] -Implementer: Extracted PROGRESS_INTERVAL constant +[Implementer fixes with --amend] +Implementer: Extracted PROGRESS_INTERVAL constant, amended checkpoint commit [Code reviewer reviews again] Code reviewer: ✅ Approved +[Implementer creates final commit #2] +Implementer: All reviews passed, final commit + [Mark Task 2 complete] ... diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index 400c103479..1d208e61e5 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/skills/subagent-driven-development/implementer-prompt.md @@ -32,7 +32,7 @@ Task tool (general-purpose): 1. Implement exactly what the task specifies 2. Write tests (following TDD if task says to) 3. Verify implementation works - 4. Commit your work + 4. **Commit your work** (`git add` + `git commit`) — this is the first checkpoint commit 5. Self-review (see below) 6. Report back @@ -41,6 +41,28 @@ Task tool (general-purpose): **While you work:** If you encounter something unexpected or unclear, **ask questions**. It's always OK to pause and clarify. Don't guess or make assumptions. + ## Commit Strategy (Two Commits Per Task) + + Each task produces exactly **two commits** to balance traceability with conflict avoidance: + + **Commit 1 — Implementation checkpoint** (after step 4 above): + - Commit immediately after implementation and self-test pass + - This ensures code doesn't sit uncommitted for long periods, reducing merge conflict risk + + **During review fix rounds** (if reviewers request changes): + - Use `git add` + `git commit --amend --no-edit` to squash fixes into Commit 1 + - Do NOT create separate commits for each review fix + - This keeps the task's WIP as a single evolving commit + + **Commit 2 — Final** (after all reviews pass): + - When both spec compliance and code quality reviewers approve, create the final commit + - Use `git commit --amend` if only minor fixes were added, or a new `git commit` if + significant changes accumulated since the last amend + - Use a meaningful commit message summarizing the complete task + + **Exception:** If the task touches 5+ files or spans multiple subsystems, you may create + additional intermediate commits at natural checkpoints. Report this in your status. + ## Code Organization You reason best about code you can hold in context at once, and your edits are more