git-workflows

What this skill does

# Git Workflows

Modern agentic git workflow enforcement with multi-agent consensus review. Integrates deeply with contextd for cross-session learning, context folding, and remediation tracking.

---

## Parallel Development with Git Worktrees

### Why Worktrees for AI Agents

- Multiple agents can work simultaneously without file conflicts
- Each agent gets isolated working directory
- Shared .git folder = efficient storage
- Industry standard for parallel AI development (2024-2025)

### Directory Structure

```
~/projects/
├── my-project/              # Main worktree (main branch)
└── my-project-worktrees/    # All linked worktrees
    ├── feature-auth/        # Agent A
    ├── fix-database/        # Agent B
    └── refactor-api/        # Agent C
```

### Core Commands

| Task | Command |
|------|---------|
| Create worktree | `git worktree add -b <branch> <path>` |
| List all | `git worktree list` |
| Lock (portable storage) | `git worktree lock --reason "msg" <path>` |
| Unlock | `git worktree unlock <path>` |
| Remove properly | `git worktree remove <path>` |
| Cleanup stale | `git worktree prune -v` |
| Fix broken links | `git worktree repair [<path>...]` |

### Worktree Lifecycle for Agents

1. **Pre-work:** `git worktree add -b feature/task ../worktrees/task`
2. **During:** Agent works in isolated directory
3. **Completion:** `git worktree remove ../worktrees/task`
4. **Cleanup:** `git worktree prune -v`

### Worktree Quick Reference Card

```bash
# === SETUP ===
git worktree add -b <branch> ../worktrees/<name>  # Create
git worktree list                                   # List all
git worktree list --porcelain                       # Machine-readable

# === DURING WORK ===
cd ../worktrees/<name>                              # Enter worktree
git status                                          # Check state
git worktree lock --reason "active" <path>          # Prevent removal

# === COMPLETION ===
git worktree unlock <path>                          # Unlock first
git worktree remove <path>                          # Remove properly
git worktree prune -v                               # Clean stale refs

# === RECOVERY ===
git worktree repair                                 # Fix broken links
git worktree repair <path>...                       # Fix specific worktrees
```

### Dependency Management in Worktrees

| Scenario | Solution |
|----------|----------|
| Shared node_modules | Use workspace root: `npm install` from main |
| Go modules | `go work init` + `go work use <worktrees>` |
| Python venv | Create per-worktree: `python -m venv .venv` |
| Docker builds | Mount worktree as volume |

### Anti-Patterns

| Anti-Pattern | Why Bad | Correct Approach |
|--------------|---------|------------------|
| `rm -rf worktree` | Corrupts Git tracking | `git worktree remove` |
| Two agents, same files | Merge conflicts | Scope to non-overlapping files |
| Moving folder manually | Breaks gitdir link | `git worktree move` or `repair` |
| 20+ simultaneous worktrees | Unmanageable | Create, complete, remove |

### Official Git Warning

> "Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject."

### File Overlap Prevention

- Scope agent work to non-overlapping modules/directories
- Two agents touching same files = guaranteed conflicts
- Plan task decomposition before spawning agents

### Worktree + Background Agent Pattern

Combine worktrees with Task tool for true parallel development:

```bash
# 1. Create worktrees for each agent
git worktree add -b feature/auth ../worktrees/auth
git worktree add -b feature/api ../worktrees/api
git worktree add -b feature/ui ../worktrees/ui

# 2. Launch agents in parallel (each in own worktree)
Task(
  subagent_type: "general-purpose",
  prompt: "cd ../worktrees/auth && implement auth module",
  run_in_background: true
)
Task(
  subagent_type: "general-purpose",
  prompt: "cd ../worktrees/api && implement API layer",
  run_in_background: true
)
Task(
  subagent_type: "general-purpose",
  prompt: "cd ../worktrees/ui && implement UI components",
  run_in_background: true
)

# 3. Collect and merge
TaskOutput(task_id: "auth-id", block: true)
TaskOutput(task_id: "api-id", block: true)
TaskOutput(task_id: "ui-id", block: true)

# 4. Merge branches
git merge feature/auth feature/api feature/ui

# 5. Cleanup
git worktree remove ../worktrees/auth
git worktree remove ../worktrees/api
git worktree remove ../worktrees/ui
```

### Worktree-Aware Consensus Review

When reviewing changes across worktrees:

```
1. Each worktree gets its own review cycle
2. Cross-worktree dependencies detected via git diff
3. Integration review after individual passes
4. Merge conflicts flagged before human review
```

---

## Core Principles

1. **Flexible Trigger, Full Traceability** - Any work trigger acceptable, all changes traceable via commit/PR metadata
2. **Agent-Assisted, Human-Owned** - Agents propose, humans approve; AI code never ships without human sign-off
3. **Trunk-Based, Short-Lived** - Branches <24h encouraged, squash merge only, auto-delete after merge
4. **Consensus Before Human Review** - Multi-agent consensus gate before human reviewers engaged
5. **Learning-Enhanced** - contextd integration optional; file-based fallback when MCP unavailable

---

## Multi-Agent Consensus Review

### The Review Council

| Agent | Focus | Veto Power | Budget |
|-------|-------|------------|--------|
| **Security** | Auth, injection, secrets, OWASP | Yes | 8192 |
| **Vulnerability** | CVEs, deps, supply chain | Yes | 8192 |
| **Code Quality** | Logic, complexity, patterns, tests | Yes | 8192 |
| **Documentation** | README, comments, API docs, CHANGELOG | Yes | 4096 |
| **User Persona** | UX impact, breaking changes, API ergonomics | Yes | 4096 |

### Consensus Rules

- **All agents have veto power** on findings in their domain
- Use `--ignore-vetos` flag to override (requires justification)
- **100% consensus** required: all Critical/High/Medium resolved
- Low findings: auto-create issues if <3, author triage if ≥3

---

## contextd Integration (Optional)

### When contextd MCP is Available

| Feature | Tool | Benefit |
|---------|------|---------|
| Pre-flight search | `semantic_search`, `memory_search` | Learn from past reviews |
| Context isolation | `branch_create`, `branch_return` | Parallel agent execution |
| Learning capture | `memory_record`, `remediation_record` | Cross-session knowledge |
| Checkpoints | `checkpoint_save`, `checkpoint_resume` | Resumable sessions |

### When contextd is NOT Available

| Feature | Fallback | Location |
|---------|----------|----------|
| Review findings | JSON files | `.claude/consensus-reviews/PR-XXX.json` |
| Past patterns | Local search | Grep/Glob on previous reviews |
| Audit trail | Markdown logs | `.claude/consensus-reviews/audit.md` |

### Detection

```
# Check for contextd
ToolSearch("contextd")

# If available: use mcp__contextd__* tools
# If not: write to .claude/consensus-reviews/
```

---

## Workflow Phases

### Phase 1: Pre-Flight (ReasoningBank)

**Optional: If contextd available, gather additional context:**

```
1. mcp__contextd__semantic_search(
     query: "code patterns in [changed files]",
     project_path: "."
   )
   → Understand codebase context

2. mcp__contextd__memory_search(
     project_id: "<project>",
     query: "PR review patterns [area]"
   )
   → Retrieve past review strategies

3. mcp__contextd__remediation_search(
     query: "common issues in [file types]",
     tenant_id: "<tenant>",
     include_hierarchy: true
   )
   → Pre-load known problem patterns

4. mcp__contextd__checkpoint_save(
     session_id: "<session>",
     project_path: ".",
     name: "review-start-PR-XXX",
     description: "Starting consensus review",
     summary: "5-agent review of PR #XXX",
     context: "[PR description, files changed]",
     full_state: "[complete PR context]",