feat: implement per-task atomic commits for better AI observability

- Each task commits immediately after completion (feat/fix/test/refactor)
- Plan completion commits metadata only (docs: SUMMARY + STATE + ROADMAP)
- Git history becomes primary context source for future Claude sessions
- Better bisect granularity, failure recovery, and revert capabilities

Changes:
- execute-phase.md: Added <task_commit> protocol and per-task commit flow
- execute-plan.md: Updated commit rules and success criteria
- git-integration.md: New task-completion format, strategy rationale
- tdd.md: Aligned TDD commits with standard task commit pattern
- summary.md: Added Task Commits section with commit hashes
- README.md: Rewrote git history section with atomic commit benefits
- scope-estimation.md: Clarified commit counts per plan
- principles.md: Added <atomic_commits> section explaining strategy

Each plan now produces 3-4 commits (2-3 task commits + 1 metadata commit)
instead of single monolithic commit. Optimizes observability for solo
developer + Claude Code workflow.
This commit is contained in:
Lex Christopherson
2026-01-05 16:09:14 -06:00
parent a6df00ab2a
commit 875ac900a2
8 changed files with 430 additions and 79 deletions

View File

@@ -440,8 +440,8 @@ Execute each task in the prompt. **Deviations are normal** - handle them automat
**If `type="auto"`:**
**Before executing:** Check if task has `tdd="true"` attribute:
- If yes: Follow TDD execution flow (see `<tdd_execution>`) - RED → GREEN → REFACTOR cycle with multiple atomic commits
- If no: Standard implementation with single commit
- If yes: Follow TDD execution flow (see `<tdd_execution>`) - RED → GREEN → REFACTOR cycle with atomic commits per stage
- If no: Standard implementation
- Work toward task completion
- **If CLI/API returns authentication error:** Handle as authentication gate (see below)
@@ -449,7 +449,8 @@ Execute each task in the prompt. **Deviations are normal** - handle them automat
- Continue implementing, applying rules as needed
- Run the verification
- Confirm done criteria met
- Track any deviations for Summary documentation
- **Commit the task** (see `<task_commit>` below)
- Track task completion and commit hash for Summary documentation
- Continue to next task
**If `type="checkpoint:*"`:**
@@ -860,8 +861,118 @@ After TDD task completion, ensure:
- All tests pass
- Test coverage for the new behavior exists
- No unrelated tests broken
**Note:** TDD tasks produce 2-3 commits (test/feat/refactor). Non-TDD tasks produce 1 commit after task completion.
</tdd_execution>
<task_commit>
## Task Commit Protocol
After each task completes (verification passed, done criteria met), commit immediately:
**1. Identify modified files:**
Track files changed during this specific task (not the entire plan):
```bash
git status --short
```
**2. Stage only task-related files:**
Stage each file individually (NEVER use `git add .` or `git add -A`):
```bash
# Example - adjust to actual files modified by this task
git add src/api/auth.ts
git add src/types/user.ts
```
**3. Determine commit type:**
| Type | When to Use | Example |
|------|-------------|---------|
| `feat` | New feature, endpoint, component, functionality | feat(08-02): create user registration endpoint |
| `fix` | Bug fix, error correction | fix(08-02): correct email validation regex |
| `test` | Test-only changes (TDD RED phase) | test(08-02): add failing test for password hashing |
| `refactor` | Code cleanup, no behavior change (TDD REFACTOR phase) | refactor(08-02): extract validation to helper |
| `perf` | Performance improvement | perf(08-02): add database index for user lookups |
| `docs` | Documentation changes | docs(08-02): add API endpoint documentation |
| `style` | Formatting, linting fixes | style(08-02): format auth module |
| `chore` | Config, tooling, dependencies | chore(08-02): add bcrypt dependency |
**4. Craft commit message:**
Format: `{type}({phase}-{plan}): {task-name-or-description}`
```bash
git commit -m "{type}({phase}-{plan}): {concise task description}
- {key change 1}
- {key change 2}
- {key change 3}
"
```
**Examples:**
```bash
# Non-TDD task
git commit -m "feat(08-02): create user registration endpoint
- POST /auth/register validates email and password
- Checks for duplicate users
- Returns JWT token on success
"
# TDD task - RED phase
git commit -m "test(07-02): add failing test for JWT generation
- Tests token contains user ID claim
- Tests token expires in 1 hour
- Tests signature verification
"
# TDD task - GREEN phase
git commit -m "feat(07-02): implement JWT generation
- Uses jose library for signing
- Includes user ID and expiry claims
- Signs with HS256 algorithm
"
# TDD task - REFACTOR phase
git commit -m "refactor(07-02): extract JWT config to constants
- Moved expiry time to constant
- Centralized algorithm selection
- No behavior changes
"
```
**5. Record commit hash:**
After committing, capture hash for SUMMARY.md:
```bash
TASK_COMMIT=$(git rev-parse --short HEAD)
echo "Task ${TASK_NUM} committed: ${TASK_COMMIT}"
```
Store in array or list for SUMMARY generation:
```bash
TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
```
**Atomic commit benefits:**
- Each task independently revertable
- Git bisect finds exact failing task
- Git blame traces line to specific task context
- Clear history for Claude in future sessions
- Better observability for AI-automated workflow
</task_commit>
<step name="checkpoint_protocol">
When encountering `type="checkpoint:*"`:
@@ -1181,16 +1292,11 @@ ROADMAP_FILE=".planning/ROADMAP.md"
- Add completion date
</step>
<step name="git_commit_plan">
Commit plan completion (SUMMARY + PROJECT-STATE + ROADMAP + modified code files):
<step name="git_commit_metadata">
Commit plan metadata (SUMMARY + STATE + ROADMAP):
**Critical: Stage only files this plan actually modified.**
NEVER use:
- `git add .`
- `git add -A`
- `git add src/` or any broad directory add
**Note:** All task code has already been committed during execution (one commit per task).
This final commit captures plan completion metadata only.
**1. Stage planning artifacts:**
@@ -1203,45 +1309,73 @@ git add .planning/STATE.md
**2. Stage roadmap file:**
```bash
if [ -f .planning/ROADMAP.md ]; then
git add .planning/ROADMAP.md
else
git add .planning/ROADMAP.md
fi
git add .planning/ROADMAP.md
```
**3. Stage only code files from the modified-files list**
**4. Verify staging before commit:**
**3. Verify staging:**
```bash
git status
# Confirm only expected files are staged
# Should show only planning artifacts, no code files
```
**5. Commit:**
**4. Commit metadata:**
```bash
git commit -m "$(cat <<'EOF'
feat({phase}-{plan}): [one-liner from SUMMARY.md]
docs({phase}-{plan}): complete [plan-name] plan
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Key accomplishment 3]
Tasks completed: [N]/[N]
- [Task 1 name]
- [Task 2 name]
- [Task 3 name]
SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
EOF
)"
```
For commit message conventions and git workflow patterns, see ~/.claude/get-shit-done/references/git-integration.md
**Example:**
```bash
git commit -m "$(cat <<'EOF'
docs(08-02): complete user registration plan
Tasks completed: 3/3
- User registration endpoint
- Password hashing with bcrypt
- Email confirmation flow
SUMMARY: .planning/phases/08-user-auth/08-02-registration-SUMMARY.md
EOF
)"
```
**Git log after plan execution:**
```
abc123f docs(08-02): complete user registration plan
def456g feat(08-02): add email confirmation flow
hij789k feat(08-02): implement password hashing with bcrypt
lmn012o feat(08-02): create user registration endpoint
```
Each task has its own commit, followed by one metadata commit documenting plan completion.
For commit message conventions, see ~/.claude/get-shit-done/references/git-integration.md
</step>
<step name="update_codebase_map">
**If .planning/codebase/ exists:**
Check what changed in this plan:
Check what changed across all task commits in this plan:
```bash
git diff --name-only HEAD~1 2>/dev/null
# Find first task commit (right after previous plan's docs commit)
FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
# Get all changes from first task through now
git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
```
**Update only if structural changes occurred:**
@@ -1265,7 +1399,7 @@ Make single targeted edits - add a bullet point, update a path, or remove a stal
```bash
git add .planning/codebase/*.md
git commit --amend --no-edit # Include in plan commit
git commit --amend --no-edit # Include in metadata commit
```
**If .planning/codebase/ doesn't exist:**