tomevault-io spec-kitty-git-workflow
Understand the boundary between what spec-kitty's Python code does with git and what LLM agents are expected to do. This boundary is critical — agents that try to create worktrees manually or skip implementation commits will break the workflow.
The Core Boundary
Python handles infrastructure git — worktrees, lane commits, merges, cleanup. Agents handle content git — implementation commits, rebases, conflict resolution.
| Git Operation | Who Does It | When |
|---|---|---|
git worktree add |
Python | spec-kitty implement WP## |
git commit (planning artifacts) |
Python | Before worktree creation |
git commit (lane transitions) |
Python | WP moves to doing/for_review |
git commit (implementation code) |
Agent | After writing code in worktree |
git rebase (stale lane sync) |
Agent | When the mission branch advanced and the lane must resync |
git merge (lane → mission → target) |
Python | spec-kitty merge |
git push |
Python (opt-in) | spec-kitty merge --push only |
git push |
Agent | Any other push scenario |
| Conflict resolution | Agent | During rebase or manual merge |
git worktree remove |
Python | After successful merge |
git branch -d (cleanup) |
Python | After successful merge |
What Python Does Automatically
1. Worktree Creation
When you run spec-kitty implement WP01, Python:
git worktree add -b kitty/mission-042-mission-lane-a .worktrees/042-mission-lane-a main
It also records the lane workspace context in
.kittify/workspaces/<feature>-<lane>.json so later commands resolve the same
lane worktree deterministically.
The agent never creates worktrees. Always use spec-kitty implement.
For dependent WPs in the same execution lane:
spec-kitty implement WP02
This reuses the lane worktree instead of creating a second workspace:
# WP02 reuses .worktrees/042-mission-lane-a
2. Planning Artifact Auto-Commits
Before creating a worktree, Python checks if kitty-specs/042-mission/ has
uncommitted changes on the primary branch. If so, it auto-commits:
git add -f kitty-specs/042-mission/
git commit -m "chore: Planning artifacts for 042-mission"
Controlled by: auto_commit: true in .kittify/config.yaml (default: true).
Can be disabled per-command with --no-auto-commit.
3. Lane Transition Auto-Commits
When a WP moves to doing or for_review, Python uses the safe-commit
pattern to commit only the WP frontmatter file:
- Moving to doing:
"chore: Start WP01 implementation [claude]" - Moving to for_review:
"chore: Start WP01 review [claude]"
The safe-commit pattern prevents accidentally committing agent work-in-progress:
- Stash current staging area
- Stage only the target files (WP frontmatter, status artifacts)
- Commit
- Pop stash to restore previous staging
4. Status Event Log (No Auto-Commit)
emit_status_transition() appends to status.events.jsonl, updates
status.json, and modifies WP frontmatter — but does NOT auto-commit
these files. They accumulate as uncommitted changes until the next lane
transition auto-commit or the agent commits them.
This is by design — status changes happen frequently and committing each one would create excessive git noise.
5. Merge Execution
spec-kitty merge --mission 042-mission runs the full merge sequence:
git checkout main
git pull --ff-only # sync with remote
git merge --no-ff kitty/mission-042-mission
git worktree remove .worktrees/042-mission-lane-a --force
git branch -d kitty/mission-042-mission-lane-a
Merge order follows the dependency graph (topological sort).
Supports 3 strategies: merge (--no-ff, default), squash, rebase.
--push is opt-in — without it, the merge is local only.
6. Pre-flight Validation (Read-Only)
Before merge, Python validates:
- All expected WPs have worktrees
- All worktrees are clean (
git status --porcelain) - Target branch is not behind origin (
git rev-list --left-right --count) - WPs in done lane with missing worktrees are skipped (already merged)
If any check fails, merge is blocked with specific error messages.
What Agents Must Do
1. Implementation Commits
All actual code work must be committed by the agent. Python creates the worktree but never commits code:
cd .worktrees/042-mission-lane-a
# ... write code, run tests ...
git add src/ tests/
git commit -m "feat(WP01): implement auth middleware"
Validation: When the agent tries to move WP to for_review, spec-kitty
checks that the worktree has commits ahead of the base branch
(git rev-list --count <base>..HEAD). If zero commits, the transition is
rejected.
2. Rebasing a Lane Workspace
If a lane branch has advanced while you were away:
cd .worktrees/042-mission-lane-a
git rebase kitty/mission-042-mission-lane-a
Python displays the lane workspace and branch, but the agent resolves conflicts and completes the rebase manually when needed.
3. Multi-Dependency Work
Task finalization computes a lane that already contains the required dependency shape. Agents do not choose one dependency as a manual base and do not manually merge sibling lane outputs to reconstruct the lane.
4. Pushing
spec-kitty merge only pushes with --push. All other pushing is the
agent's responsibility.
5. Conflict Resolution
If spec-kitty merge encounters conflicts, the agent must resolve them.
Python does not attempt automatic conflict resolution.
Auto-Commit Configuration
# .kittify/config.yaml
auto_commit: true # default
When true, spec-kitty auto-commits:
- Planning artifacts before worktree creation
- WP frontmatter on lane transitions (doing, for_review)
When false, agents must commit everything manually.
Per-command override: --no-auto-commit flag on spec-kitty implement.
Worktree Lifecycle
1. CREATED
spec-kitty implement WP01
→ git worktree add -b kitty/mission-042-mission-lane-a .worktrees/042-mission-lane-a main
→ .kittify/workspaces/042-mission-lane-a.json created
2. ACTIVE (agent works here)
cd .worktrees/042-mission-lane-a
→ agent writes code, commits, tests
→ WP status: in_progress
3. FOR REVIEW
spec-kitty agent tasks move-task WP01 --to for_review
→ auto-commit: "chore: Start WP01 review"
→ reviewer checks the diff
4. MERGED
spec-kitty merge --mission 042-mission
→ git merge --no-ff kitty/mission-042-mission-lane-a
→ git worktree remove .worktrees/042-mission-lane-a --force
→ git branch -d kitty/mission-042-mission-lane-a
→ .kittify/workspaces/042-mission-lane-a.json removed
5. CLEANED UP
Worktree directory gone, branch deleted, workspace context removed
No Git Hooks
Spec-kitty does NOT use git hooks. Feature 043 replaced the pre-commit hook
(which handled UTF-8 encoding validation) with a Python codec layer
(src/specify_cli/codec/). No .git/hooks/ files are installed or managed.
Key Anti-Patterns
Agent creates worktree manually — Don't
git worktree addyourself. Usespec-kitty implement. Manual worktrees won't have workspace context, canonical workspace context, or proper branch naming.Agent commits in main repo during implementation — Implementation commits belong in the worktree, not in the main repo. The main repo is for planning artifacts only.
Agent pushes without being asked — Never auto-push. Only push when the user explicitly requests it or when using
spec-kitty merge --push.Agent modifies other WPs from a worktree — Each worktree is isolated to one WP. Don't modify files belonging to other WPs.
Agent skips commits before for_review — Spec-kitty validates that worktree has commits ahead of base before accepting the transition.
References
references/git-operations-matrix.md-- Complete matrix of every git command spec-kitty runs
Converted and distributed by TomeVault — claim your Tome and manage your conversions.