diff --git a/README.md b/README.md index 5858b35a7..f89dcf32a 100644 --- a/README.md +++ b/README.md @@ -171,9 +171,24 @@ GSD prevents this. Each plan is maximum 3 tasks. Each plan runs in a fresh subag No degradation. Walk away, come back to completed work. -### Clean Git History +### Atomic Git Commits -Every task: atomic commit, clear message, summary documenting outcomes. Maintainable history you can trace. +Each task gets its own commit immediately after completion. Plans produce 2-4 commits total: + +```bash +abc123f docs(08-02): complete user registration plan +def456g feat(08-02): add email confirmation flow +hij789k feat(08-02): implement password hashing +lmn012o feat(08-02): create registration endpoint +``` + +**Benefits:** +- Git bisect finds exact failing task +- Each task independently revertable +- Clear history for Claude in future sessions +- Better observability in AI-automated workflow + +Every commit is surgical, traceable, and meaningful. ### Modular by Design diff --git a/commands/gsd/execute-plan.md b/commands/gsd/execute-plan.md index db01cb904..18550517d 100644 --- a/commands/gsd/execute-plan.md +++ b/commands/gsd/execute-plan.md @@ -14,10 +14,13 @@ allowed-tools: --- -Execute a PLAN.md file, create SUMMARY.md, update project state, commit. +Execute a PLAN.md file with per-task atomic commits, create SUMMARY.md, update project state. + +Commit strategy: +- Each task → 1 commit immediately after completion (feat/fix/test/refactor) +- Plan completion → 1 metadata commit (docs: SUMMARY + STATE + ROADMAP) Uses intelligent segmentation: - - Plans without checkpoints → spawn subagent for full autonomous execution - Plans with verify checkpoints → segment execution, pause at checkpoints - Plans with decision checkpoints → execute in main context @@ -88,23 +91,38 @@ Only rule 4 requires user intervention. -**Critical: Stage only files this plan actually modified.** +**Per-Task Commits:** -NEVER use: +After each task completes: +1. Stage only files modified by that task +2. Commit with format: `{type}({phase}-{plan}): {task-name}` +3. Types: feat, fix, test, refactor, perf, chore +4. Record commit hash for SUMMARY.md +**Plan Metadata Commit:** + +After all tasks complete: +1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md +2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan` +3. NO code files (already committed per-task) + +**NEVER use:** - `git add .` - `git add -A` - `git add src/` or any broad directory -Stage each file individually from the modified-files list. +**Always stage files individually.** + +See ~/.claude/get-shit-done/references/git-integration.md for full commit strategy. - [ ] All tasks executed -- [ ] SUMMARY.md created with substantive content +- [ ] Each task committed individually (feat/fix/test/refactor) +- [ ] SUMMARY.md created with substantive content and commit hashes - [ ] STATE.md updated (position, decisions, issues, session) - [ ] ROADMAP updated (plan count, phase status) -- [ ] Changes committed with feat({phase}-{plan}): [summary] +- [ ] Metadata committed with docs({phase}-{plan}): complete [plan-name] plan - [ ] User informed of next steps diff --git a/get-shit-done/references/git-integration.md b/get-shit-done/references/git-integration.md index 3fd8e21a4..2c554470a 100644 --- a/get-shit-done/references/git-integration.md +++ b/get-shit-done/references/git-integration.md @@ -11,14 +11,15 @@ The git log should read like a changelog of what shipped, not a diary of plannin -| Event | Commit? | Why | -| ----------------------- | ------- | ------------------------------------- | -| BRIEF + ROADMAP created | YES | Project initialization | -| PLAN.md created | NO | Intermediate - commit with completion | -| RESEARCH.md created | NO | Intermediate | -| DISCOVERY.md created | NO | Intermediate | -| **Phase completed** | YES | Actual code shipped | -| Handoff created | YES | WIP state preserved | +| Event | Commit? | Why | +| ----------------------- | ------- | ------------------------------------------------ | +| BRIEF + ROADMAP created | YES | Project initialization | +| PLAN.md created | NO | Intermediate - commit with plan completion | +| RESEARCH.md created | NO | Intermediate | +| DISCOVERY.md created | NO | Intermediate | +| **Task completed** | YES | Atomic unit of work (1 commit per task) | +| **Plan completed** | YES | Metadata commit (SUMMARY + STATE + ROADMAP) | +| Handoff created | YES | WIP state preserved | @@ -56,30 +57,88 @@ git commit - -## Phase Completion + +## Task Completion (During Plan Execution) + +Each task gets its own commit immediately after completion. ``` -feat([domain]): [one-liner from SUMMARY.md] +{type}({phase}-{plan}): {task-name} -- [Key accomplishment 1] -- [Key accomplishment 2] -- [Key accomplishment 3] - -[If issues encountered:] -Note: [issue and resolution] +- [Key change 1] +- [Key change 2] +- [Key change 3] ``` -Use `fix([domain])` for bug fix phases. +**Commit types:** +- `feat` - New feature/functionality +- `fix` - Bug fix +- `test` - Test-only (TDD RED phase) +- `refactor` - Code cleanup (TDD REFACTOR phase) +- `perf` - Performance improvement +- `chore` - Dependencies, config, tooling + +**Examples:** + +```bash +# Standard task +git add src/api/auth.ts src/types/user.ts +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 add src/__tests__/jwt.test.ts +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 add src/utils/jwt.ts +git commit -m "feat(07-02): implement JWT generation + +- Uses jose library for signing +- Includes user ID and expiry claims +- Signs with HS256 algorithm +" +``` + + + + +## Plan Completion (After All Tasks Done) + +After all tasks committed, one final metadata commit captures plan completion. + +``` +docs({phase}-{plan}): complete [plan-name] plan + +Tasks completed: [N]/[N] +- [Task 1 name] +- [Task 2 name] +- [Task 3 name] + +SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md +``` What to commit: ```bash -git add .planning/phases/XX-name/ # PLAN.md + SUMMARY.md -git add src/ # Actual code created +git add .planning/phases/XX-name/{phase}-{plan}-PLAN.md +git add .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md +git add .planning/STATE.md +git add .planning/ROADMAP.md git commit ``` +**Note:** Code files NOT included - already committed per-task. + @@ -104,23 +163,92 @@ git commit +**Old approach (per-plan commits):** ``` -a]7f2d1 feat(checkout): Stripe payments with webhook verification -b]3e9c4 feat(products): catalog with search, filters, and pagination -c]8a1b2 feat(auth): JWT with refresh rotation using jose -d]5c3d7 feat(foundation): Next.js 15 + Prisma + Tailwind scaffold -e]2f4a8 docs: initialize ecommerce-app (5 phases) +a7f2d1 feat(checkout): Stripe payments with webhook verification +3e9c4b feat(products): catalog with search, filters, and pagination +8a1b2c feat(auth): JWT with refresh rotation using jose +5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold +2f4a8d docs: initialize ecommerce-app (5 phases) ``` +**New approach (per-task commits):** +``` +# Phase 04 - Checkout +1a2b3c docs(04-01): complete checkout flow plan +4d5e6f feat(04-01): add webhook signature verification +7g8h9i feat(04-01): implement payment session creation +0j1k2l feat(04-01): create checkout page component + +# Phase 03 - Products +3m4n5o docs(03-02): complete product listing plan +6p7q8r feat(03-02): add pagination controls +9s0t1u feat(03-02): implement search and filters +2v3w4x feat(03-01): create product catalog schema + +# Phase 02 - Auth +5y6z7a docs(02-02): complete token refresh plan +8b9c0d feat(02-02): implement refresh token rotation +1e2f3g test(02-02): add failing test for token refresh +4h5i6j docs(02-01): complete JWT setup plan +7k8l9m feat(02-01): add JWT generation and validation +0n1o2p chore(02-01): install jose library + +# Phase 01 - Foundation +3q4r5s docs(01-01): complete scaffold plan +6t7u8v feat(01-01): configure Tailwind and globals +9w0x1y feat(01-01): set up Prisma with database +2z3a4b feat(01-01): create Next.js 15 project + +# Initialization +5c6d7e docs: initialize ecommerce-app (5 phases) +``` + +Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable. + -- PLAN.md creation (wait for phase completion) +**Still don't commit (intermediate artifacts):** +- PLAN.md creation (commit with plan completion) - RESEARCH.md (intermediate) - DISCOVERY.md (intermediate) - Minor planning tweaks - "Fixed typo in roadmap" -These create noise. Commit outcomes, not process. +**Do commit (outcomes):** +- Each task completion (feat/fix/test/refactor) +- Plan completion metadata (docs) +- Project initialization (docs) + +**Key principle:** Commit working code and shipped outcomes, not planning process. + + + + +## Why Per-Task Commits? + +**Context engineering for AI:** +- Git history becomes primary context source for future Claude sessions +- `git log --grep="{phase}-{plan}"` shows all work for a plan +- `git diff ^..` shows exact changes per task +- Less reliance on parsing SUMMARY.md = more context for actual work + +**Failure recovery:** +- Task 1 committed ✅, Task 2 failed ❌ +- Claude in next session: sees task 1 complete, can retry task 2 +- Can `git reset --hard` to last successful task + +**Debugging:** +- `git bisect` finds exact failing task, not just failing plan +- `git blame` traces line to specific task context +- Each commit is independently revertable + +**Observability:** +- Solo developer + Claude workflow benefits from granular attribution +- Atomic commits are git best practice +- "Commit noise" irrelevant when consumer is Claude, not humans + + diff --git a/get-shit-done/references/principles.md b/get-shit-done/references/principles.md index 518317d1e..8c4b5f827 100644 --- a/get-shit-done/references/principles.md +++ b/get-shit-done/references/principles.md @@ -115,6 +115,29 @@ Plan → Execute → Ship → Learn → Repeat Milestones mark shipped versions (v1.0 → v1.1 → v2.0). + + +**Git commits = context engineering for Claude.** + +Each task gets its own commit immediately after completion: +- Format: `{type}({phase}-{plan}): {task-description}` +- Types: feat, fix, test, refactor, perf, chore, docs +- One final metadata commit per plan: `docs({phase}-{plan}): complete [plan-name]` + +**Why per-task commits:** +- Git history becomes primary context source for future Claude sessions +- `git bisect` finds exact failing task, not just failing plan +- Each task independently revertable +- Better failure recovery (task 1 committed ✅, retry task 2) +- Observability optimized for AI workflow, not human browsing + +**Plans produce 3-4 commits total:** +- 2-3 task commits (working code) +- 1 metadata commit (SUMMARY + STATE + ROADMAP) + +See `~/.claude/get-shit-done/references/git-integration.md` for complete strategy. + + NEVER include: diff --git a/get-shit-done/references/scope-estimation.md b/get-shit-done/references/scope-estimation.md index ed3ecb27a..11feb4cac 100644 --- a/get-shit-done/references/scope-estimation.md +++ b/get-shit-done/references/scope-estimation.md @@ -80,7 +80,7 @@ Plan 1: "Auth Database Models" (2 tasks) Plan 2: "Auth API Core" (3 tasks) Plan 3: "Auth API Protection" (2 tasks) Plan 4: "Auth UI Components" (2 tasks) -Each: 30-40% context, peak quality, focused commits +Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit) ``` @@ -137,7 +137,7 @@ Each plan: fresh context, peak quality. More plans = more thoroughness, same qua **2-3 tasks, 50% context target:** - All tasks: Peak quality -- Git: Atomic, surgical commits +- Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit) - Autonomous plans: Subagent execution (fresh context) **The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality. @@ -145,5 +145,7 @@ Each plan: fresh context, peak quality. More plans = more thoroughness, same qua **The rule:** If in doubt, split. Quality over consolidation. Always. **Depth rule:** Depth increases plan COUNT, never plan SIZE. + +**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude. diff --git a/get-shit-done/references/tdd.md b/get-shit-done/references/tdd.md index b913656a8..223bf2675 100644 --- a/get-shit-done/references/tdd.md +++ b/get-shit-done/references/tdd.md @@ -151,18 +151,37 @@ Follow project conventions for test location: ## Commit Pattern for TDD Tasks -Each TDD task produces atomic commits: +TDD tasks produce 2-3 atomic commits (one per TDD phase): ``` -test: add failing test for email validation +test({phase}-{plan}): add failing test for email validation -feat: implement email validation +- Tests valid email formats accepted +- Tests invalid formats rejected +- Tests empty input handling -refactor: extract regex to constant (optional) +feat({phase}-{plan}): implement email validation + +- Regex pattern matches RFC 5322 +- Returns boolean for validity +- Handles edge cases (empty, null) + +refactor({phase}-{plan}): extract regex to constant (optional) + +- Moved pattern to EMAIL_REGEX constant +- No behavior changes +- Tests still pass ``` -This pattern: -- Creates clean git history -- Each commit is independently revertable -- Shows TDD discipline in commit log +**This aligns with the standard task commit pattern:** +- Non-TDD tasks: 1 commit per task (feat/fix) +- TDD tasks: 2-3 commits per task (test/feat/refactor) + +Both follow same format: `{type}({phase}-{plan}): {description}` + +**Benefits:** +- Each commit independently revertable +- Git bisect works at commit level (not just task level) +- Clear history showing TDD discipline +- Consistent with overall commit strategy diff --git a/get-shit-done/templates/summary.md b/get-shit-done/templates/summary.md index 7e7677f27..e51832a14 100644 --- a/get-shit-done/templates/summary.md +++ b/get-shit-done/templates/summary.md @@ -62,6 +62,18 @@ completed: YYYY-MM-DD - [Second key accomplishment] - [Third if applicable] +## Task Commits + +Each task was committed atomically: + +1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor) +2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor) +3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor) + +**Plan metadata:** `lmn012o` (docs: complete plan) + +_Note: TDD tasks may have multiple commits (test → feat → refactor)_ + ## Files Created/Modified - `path/to/file.ts` - What it does - `path/to/another.ts` - What it does @@ -83,7 +95,7 @@ completed: YYYY-MM-DD - **Fix:** [What was done] - **Files modified:** [file paths] - **Verification:** [How it was verified] -- **Commit:** [hash] +- **Committed in:** [hash] (part of task commit) [... repeat for each auto-fix ...] @@ -189,7 +201,7 @@ The one-liner should tell someone what actually shipped. - **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10 - **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts - **Verification:** Password hash test passes, plaintext never stored -- **Commit:** abc123f +- **Committed in:** abc123f (Task 2 commit) **2. [Rule 3 - Blocking] Installed missing jose dependency** - **Found during:** Task 4 (JWT token generation) @@ -197,7 +209,7 @@ The one-liner should tell someone what actually shipped. - **Fix:** Ran `npm install jose` - **Files modified:** package.json, package-lock.json - **Verification:** Import succeeds, build passes -- **Commit:** def456g +- **Committed in:** def456g (Task 4 commit) ### Deferred Enhancements diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 2a70b30ed..39eb1e56c 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -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 ``) - RED → GREEN → REFACTOR cycle with multiple atomic commits - - If no: Standard implementation with single commit + - If yes: Follow TDD execution flow (see ``) - 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 `` 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. + +## 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 + + + When encountering `type="checkpoint:*"`: @@ -1181,16 +1292,11 @@ ROADMAP_FILE=".planning/ROADMAP.md" - Add completion date - -Commit plan completion (SUMMARY + PROJECT-STATE + ROADMAP + modified code files): + +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 **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:**