AGENTS/.pi/gsd/references/git-integration.md

Git integration for GSD framework.

<core_principle>

Commit outcomes, not process.

The git log should read like a changelog of what shipped, not a diary of planning activity. </core_principle>

<commit_points>

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

</commit_points>

<git_check>

[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"

If NO_GIT: Run git init silently. GSD projects always get their own repo. </git_check>

<commit_formats>

## Project Initialization (brief + roadmap together)

docs: initialize [project-name] ([N] phases)

[One-liner from PROJECT.md]

Phases:
1. [phase-name]: [goal]
2. [phase-name]: [goal]
3. [phase-name]: [goal]

What to commit:

node ".pi/gsd/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/

## Task Completion (During Plan Execution)

Each task gets its own commit immediately after completion.

Parallel agents: When running as a parallel executor (spawned by execute-phase), use --no-verify on all commits to avoid pre-commit hook lock contention. The orchestrator validates hooks once after all agents complete.

{type}({phase}-{plan}): {task-name}

- [Key change 1]
- [Key change 2]
- [Key change 3]

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:

# 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:

node ".pi/gsd/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md

Note: Code files NOT included - already committed per-task.

## Handoff (WIP)

wip: [phase-name] paused at task [X]/[Y]

Current: [task name]
[If blocked:] Blocked: [reason]

What to commit:

node ".pi/gsd/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/

<example_log>

Old approach (per-plan commits):

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.

</example_log>

<anti_patterns>

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"

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.

</anti_patterns>

<commit_strategy_rationale>

Why Per-Task Commits?

Context engineering for AI:

• Git history becomes primary context source for future the agent sessions
• git log --grep="{phase}-{plan}" shows all work for a plan
• git diff <hash>^..<hash> shows exact changes per task
• Less reliance on parsing SUMMARY.md = more context for actual work

Failure recovery:

• Task 1 committed ✅, Task 2 failed ❌
• the agent 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 + the agent workflow benefits from granular attribution
• Atomic commits are git best practice
• "Commit noise" irrelevant when consumer is the agent, not humans

</commit_strategy_rationale>

<sub_repos_support>

Multi-Repo Workspace Support (sub_repos)

For workspaces with separate git repos (e.g., backend/, frontend/, shared/), GSD routes commits to each repo independently.

Configuration

In .planning/config.json, list sub-repo directories under planning.sub_repos:

{
  "planning": {
    "commit_docs": false,
    "sub_repos": ["backend", "frontend", "shared"]
  }
}

Set commit_docs: false so planning docs stay local and are not committed to any sub-repo.

How It Works

1. Auto-detection: During /gsd-new-project, directories with their own .git folder are detected and offered for selection as sub-repos. On subsequent runs, loadConfig auto-syncs the sub_repos list with the filesystem - adding newly created repos and removing deleted ones. This means config.json may be rewritten automatically when repos change on disk.
2. File grouping: Code files are grouped by their sub-repo prefix (e.g., backend/src/api/users.ts belongs to the backend/ repo).
3. Independent commits: Each sub-repo receives its own atomic commit via gsd-tools.cjs commit-to-subrepo. File paths are made relative to the sub-repo root before staging.
4. Planning stays local: The .planning/ directory is not committed; it acts as cross-repo coordination.

Commit Routing

Instead of the standard commit command, use commit-to-subrepo when sub_repos is configured:

node .pi/gsd/bin/gsd-tools.cjs commit-to-subrepo "feat(02-01): add user API" \
  --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx

This stages src/api/users.ts and src/types/user.ts in the backend/ repo, and src/components/UserForm.tsx in the frontend/ repo, then commits each independently with the same message.

Files that don't match any configured sub-repo are reported as unmatched.

</sub_repos_support>