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

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

Worktree Quick Reference Card

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

# 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

Flexible Trigger, Full Traceability - Any work trigger acceptable, all changes traceable via commit/PR metadata
Agent-Assisted, Human-Owned - Agents propose, humans approve; AI code never ships without human sign-off
Trunk-Based, Short-Lived - Branches <24h encouraged, squash merge only, auto-delete after merge
Consensus Before Human Review - Multi-agent consensus gate before human reviewers engaged
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]",
     token_count: <current>,
     threshold: 0.0,
     auto_created: false
   )
   → Preserve review start state

Phase 2: Parallel Agent Review (Context Folding)

Launch all 5 agents in isolated branches:

# For each agent:
mcp__contextd__branch_create(
  session_id: "<session>",
  description: "[Agent] review of PR #XXX",
  prompt: "[Agent-specific review instructions - see below]",
  budget: [agent budget],
  timeout_seconds: 300
)
→ Returns: branch_id

# Each agent internally:
# 1. semantic_search for relevant code
# 2. remediation_search for known patterns
# 3. Analyze and produce findings
# 4. Return structured results

Agent Prompts:

Security Agent

You are a SECURITY REVIEWER analyzing PR #XXX.

Context from pre-flight:
[Include semantic_search results]
[Include relevant remediation patterns]

Review focus:
1. Injection vulnerabilities (SQL, command, XSS)
2. Authentication/authorization flaws
3. Secrets exposure (hardcoded keys, tokens)
4. Supply chain risks (new dependencies)
5. OWASP Top 10 violations

For each finding:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- Location: file:line
- Issue: What's wrong
- Recommendation: How to fix
- Related remediation: [ID if from remediation_search]

You have VETO POWER on security issues.

Vulnerability Agent

You are a VULNERABILITY REVIEWER analyzing PR #XXX.

Review focus:
1. Known CVEs in dependencies
2. Outdated packages with security patches
3. Dependency confusion risks
4. License compliance issues
5. Transitive dependency risks

For each finding:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- Location: file or dependency
- CVE: [if applicable]
- Issue: What's vulnerable
- Recommendation: Version upgrade or mitigation

You have VETO POWER on security issues.

Code Quality Agent

You are a CODE QUALITY REVIEWER analyzing PR #XXX.

Review focus:
1. Logic errors and edge cases
2. Test coverage gaps
3. Cyclomatic complexity spikes
4. Code duplication
5. Pattern violations
6. Error handling gaps

For each finding:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- Location: file:line
- Issue: What's wrong
- Recommendation: How to fix

Documentation Agent

You are a DOCUMENTATION REVIEWER analyzing PR #XXX.

Review focus:
1. README updates needed
2. Missing/outdated code comments
3. API documentation gaps
4. CHANGELOG entry required
5. Breaking change documentation

For each finding:
- Severity: MEDIUM / LOW
- Location: file or section
- Issue: What's missing
- Recommendation: What to add

User Persona Agent

You are a USER EXPERIENCE REVIEWER analyzing PR #XXX.

Review focus:
1. Breaking API changes
2. Migration path clarity
3. Error message quality
4. Configuration complexity
5. Developer ergonomics

For each finding:
- Severity: MEDIUM / LOW
- Location: file:line or feature
- Issue: UX impact
- Recommendation: Improvement

Phase 3: Collect & Aggregate

# For each agent:
mcp__contextd__branch_return(
  branch_id: "<branch>",
  message: "[Structured findings JSON]"
)
→ Auto-scrubs secrets before return

# Aggregate findings:
1. Parse all agent responses
2. Tally by severity across agents
3. Identify consensus (2+ agents = higher priority)
4. De-duplicate similar findings
5. Apply veto rules:
   - Any agent CRITICAL/HIGH → BLOCK regardless
   - Use `--ignore-vetos` for advisory mode only

Findings Structure:

{
  "agent": "security",
  "verdict": "REQUEST_CHANGES",
  "findings": [
    {
      "severity": "HIGH",
      "location": "auth/handler.go:45",
      "issue": "SQL injection via unsanitized user input",
      "recommendation": "Use parameterized queries",
      "related_remediation": "rem_abc123"
    }
  ],
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0
  }
}

Phase 4: Consensus Decision

IF any agent has Critical/High/Medium findings:
  → BLOCK PR
  → Return to author with:
    - All findings prioritized
    - remediation_search suggestions for each
    - Links to past solutions

IF only Low findings:
  IF count < 3:
    → Auto-create GitHub issues for each
    → Link issues to PR
    → Mark as "deferred to backlog"
  ELSE (≥3):
    → Require author to triage
    → Author acknowledges or disputes each
    → Issues created for acknowledged items

IF all agents APPROVE (no Critical/High/Medium, Low handled):
  → CONSENSUS PASSED
  → Proceed to human review tier

Phase 5: Post-Flight (Learning Capture)

With contextd (recommended for cross-session learning):

# 1. Record review outcome
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "PR #XXX review - [PASSED|BLOCKED]",
  content: "Agents: 5, Findings: [summary], Novel: [patterns],
            Blocked on: [if blocked], Time: [duration]",
  outcome: "success" | "failure",
  tags: ["pr-review", "consensus", "<project>", "<severity>"]
)

# 2. Record novel findings as remediations
# For each finding NOT from existing remediation:
mcp__contextd__remediation_record(
  title: "[Issue pattern title]",
  problem: "[Exact issue found]",
  symptoms: ["[observable symptoms]"],
  root_cause: "[Why it's a problem]",
  solution: "[How to fix]",
  affected_files: ["[files]"],
  category: "security" | "syntax" | "logic" | "config" | etc,
  confidence: 0.8,
  tags: ["pr-review", "[category]", "<project>"],
  tenant_id: "<tenant>",
  scope: "org"  # Share across projects
)

# 3. Feedback on memories that helped
mcp__contextd__memory_feedback(
  memory_id: "<id>",
  helpful: true | false
)

# 4. Report outcome for memories used
mcp__contextd__memory_outcome(
  memory_id: "<id>",
  succeeded: true | false,
  session_id: "<session>"
)

# 5. Final checkpoint
mcp__contextd__checkpoint_save(
  session_id: "<session>",
  project_path: ".",
  name: "review-complete-PR-XXX",
  description: "Consensus review completed",
  summary: "[verdict]: [finding counts]",
  context: "[final state]",
  full_state: "[complete audit trail if Full Trace mode]",
  token_count: <current>,
  threshold: 0.0,
  auto_created: false
)

Task Tool Orchestration (Claude Code 2.1+)

Parallel Agent Execution

Launch all reviewers simultaneously using the Task tool:

# Launch 5+ agents in parallel (non-blocking)
Task(subagent_type: "fs-dev:security-reviewer", run_in_background: true)
Task(subagent_type: "fs-dev:vulnerability-reviewer", run_in_background: true)
Task(subagent_type: "fs-dev:code-quality-reviewer", run_in_background: true)
Task(subagent_type: "fs-dev:documentation-reviewer", run_in_background: true)
Task(subagent_type: "fs-dev:user-persona-reviewer", run_in_background: true)
Task(subagent_type: "fs-dev:go-reviewer", run_in_background: true)  # if Go files

Task Tool Parameters

Parameter	Required	Purpose
`subagent_type`	Yes	Agent to spawn (e.g., "fs-dev:security-reviewer")
`description`	Yes	3-5 word task summary
`prompt`	Yes	Detailed instructions
`run_in_background`	No	`true` for async execution
`model`	No	sonnet (default), opus, haiku
`resume`	No	Resume previous agent by ID

Background vs Foreground

Mode	When to Use
Foreground (default)	Tasks <30 seconds needing immediate results
Background (`run_in_background: true`)	Tasks >1 minute, parallel work

Collecting Results

# Check status
/tasks

# Read output
TaskOutput(task_id: "<id>", block: true)

# Monitor live
tail -f /path/to/task.output

Task Dependencies

Use addBlockedBy for staged reviews:

# Create dependent tasks
TaskCreate(subject: "Security review", ...)  # Returns #1
TaskCreate(subject: "Quality review", ...)   # Returns #2
TaskCreate(subject: "Final synthesis", ...)  # Returns #3

# Set dependencies
TaskUpdate(taskId: "3", addBlockedBy: ["1", "2"])

# Task #3 auto-unblocks when #1 and #2 complete

Swarm Orchestration Patterns

Multi-Agent Review Swarm

Coordinate multiple agents for comprehensive review:

# Pattern 1: Parallel Independent Review
Launch all agents simultaneously, aggregate results

# Pattern 2: Staged Review
Security → Quality → Documentation (each gates the next)

# Pattern 3: Specialist + Generalist
Domain expert first, generalist validates

Swarm Coordination

Pattern	When to Use	Example
Fan-out	Independent tasks	5 reviewers in parallel
Pipeline	Sequential dependencies	Security → then Quality
Map-reduce	Aggregate findings	All agents → synthesizer
Supervisor	Complex orchestration	Orchestrator manages workers

Agent Handoff Protocol

1. Agent A completes work
2. Writes summary to shared location
3. Notifies orchestrator via TaskOutput
4. Orchestrator assigns to Agent B
5. Agent B reads context, continues

Agent Lifecycle Hooks (Claude Code 2.1+)

Available Hook Events

Event	Fires When	Use Case
`PreToolUse`	Before any tool executes	Validate, block, inject context
`PostToolUse`	After tool completes	Log, transform output, chain actions
`Stop`	Session ends	Cleanup, final reports

Hook Configuration

// hooks/hooks.json
{
  "hooks": [
    {
      "event": "PreToolUse",
      "command": "python3 hooks/validate-commit.py",
      "matcher": { "tool_name": "Bash", "command_pattern": "git commit" }
    },
    {
      "event": "PostToolUse",
      "command": "python3 hooks/log-findings.py",
      "matcher": { "tool_name": "Task", "subagent_pattern": "*-reviewer" }
    },
    {
      "event": "Stop",
      "command": "python3 hooks/generate-report.py"
    }
  ]
}

Review Workflow Hooks

Hook	Purpose
`pre-review`	Load past patterns, check prerequisites
`post-agent`	Aggregate findings as each agent completes
`pre-commit`	Block commits without consensus
`post-review`	Record learnings, update remediations

Human Review Tiers (Label-Based)

After agent consensus passes, human review is required:

# Configurable in .github/fyrsmith-workflow.yml
review:
  tiers:
    - labels: [critical-path, security-sensitive, breaking-change]
      approvals: 2  # Configurable
      required_reviewers: ["@security-team"]
    - labels: [api-change, infrastructure]
      approvals: 2
    - labels: []  # default
      approvals: 1

Label	Approvals	Rationale
`critical-path`	2	Core system changes
`security-sensitive`	2	Security-related code
`breaking-change`	2	API/behavior breaking
`api-change`	2	Public API modifications
`infrastructure`	2	Infra/deployment changes
(default)	1	Standard changes

Branch & Merge Strategy

Model: Trunk-Based with Short-Lived Branches

main (protected)
  └── feature/short-description
  └── fix/issue-number-description
  └── chore/cleanup-description

Branch Naming

Type	Purpose	Example
`feature/`	New functionality	`feature/plugin-search`
`fix/`	Bug fixes	`fix/123-auth-timeout`
`chore/`	Maintenance, deps	`chore/update-deps`
`docs/`	Documentation only	`docs/api-reference`
`refactor/`	Code restructuring	`refactor/auth-module`
`release/`	Release prep	`release/1.2.0`

Stale Branch Cleanup

Timeline	Action
7 days	Warning notification
14 days	Auto-close PR
21 days	Delete branch

Exceptions:

long-running label exempts from auto-close
Active worktrees auto-extend deadline
Agent-assigned branches get 48h extension per activity

Merge Requirements

Squash merge only (linear history)
Branch must be up-to-date with main
Auto-delete branch after merge
All CI checks passing
Agent consensus passed
Human approvals met

Force Push Policy

Force push is prohibited except for one specific case:

Scenario	Allowed	Required Actions
Secret accidentally committed	Yes	1. Rotate credential immediately, 2. Force push to remove from history, 3. Verify removal, 4. Document in PR
Clean up commit history	No	Use interactive rebase before push
Fix merge conflicts	No	Pull and merge properly
Override CI failures	No	Fix the actual issue
"Clean up" force push to main	Never	Not allowed under any circumstances

Secret Removal Procedure:

Recommended: Use git-filter-repo (safer, faster):

# 1. IMMEDIATELY rotate the exposed credential
# 2. Install git-filter-repo: pip install git-filter-repo
# 3. Remove file from history (use single quotes to prevent injection):
git filter-repo --invert-paths --path 'config/secrets.json'

# 4. Force push (branch only, NEVER main)
git push origin --force --all

Alternative: BFG Repo-Cleaner:

# For removing specific secrets from all files:
bfg --replace-text passwords.txt repo.git

Legacy: git filter-branch (deprecated, use with caution):

# WARNING: Ensure filename is properly escaped
# NEVER use user input directly in this command
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch -- "config/secrets.json"' \
  --prune-empty --tag-name-filter cat -- --all

# Clean up refs
git for-each-ref --format='delete %(refname)' refs/original | git update-ref --stdin
git reflog expire --expire=now --all
git gc --prune=now

Security Warning: Never interpolate untrusted input into shell commands. Always validate and escape file paths before use.

Key Rule: Force push for secret removal is acceptable ONLY with immediate credential rotation. The credential must be rotated BEFORE the force push completes.

PR Structure (Agent-Assisted)

Agent auto-generates PR description from commits; author reviews and approves:

## Description
<!-- Agent-generated from commits, author-verified -->
[Auto-generated summary of changes]

## Change Type
- [ ] feat | fix | refactor | docs | chore | test

## Test Plan
- [ ] Unit tests added/updated
- [ ] Integration tests (if applicable)
- [ ] Manual testing performed

## Breaking Changes
- [ ] None
- [ ] Yes: <!-- describe migration path -->

## Linked Issues
Closes #XXX

---
## Agent Review Summary
| Agent | Verdict | Critical | High | Medium | Low |
|-------|---------|----------|------|--------|-----|
| Security | ✅ | 0 | 0 | 0 | 0 |
| Vulnerability | ✅ | 0 | 0 | 0 | 0 |
| Code Quality | ✅ | 0 | 0 | 1 | 2 |
| Documentation | ⚠️ | 0 | 0 | 1 | 0 |
| User Persona | ✅ | 0 | 0 | 0 | 1 |

**Consensus:** PASSED
**Low Issues Created:** #124, #125, #126

Agent-Generated Commits

When agents commit directly (GitHub Copilot agent mode, etc.):

Rule	Implementation
Auto-label	`agent-generated` label applied
Same rules	Identical consensus loop, no exceptions
Track separately	Metrics collected for process improvement
Audit trail	Full trace mode recommended

Audit Trail Levels

Level	Captured	Storage
Standard	Agent verdicts, findings summary, consensus result, issues created	`memory_record`
Full Trace	+ Agent reasoning, branch timelines, debate transcripts, confidence scores	`checkpoint_save` with `full_state`

Configuration:

consensus:
  tracing:
    level: standard  # standard | full
    contextd_enabled: true

Configuration Schema

# .github/fyrsmith-workflow.yml

consensus:
  agents:
    security:
      enabled: true
      veto_power: true
      budget: 8192
    vulnerability:
      enabled: true
      veto_power: true
      budget: 8192
    code_quality:
      enabled: true
      veto_power: true
      budget: 8192
    documentation:
      enabled: true
      veto_power: true
      budget: 4096
    user_persona:
      enabled: true
      veto_power: true
      budget: 4096

  ignore_vetos: false  # Set true or use --ignore-vetos flag

  thresholds:
    block_on: [critical, high, medium]
    auto_issue_below: 3  # Low findings count

  tracing:
    level: standard
    contextd_enabled: true

review:
  tiers:
    - labels: [critical-path, security-sensitive, breaking-change]
      approvals: 2
    - labels: [api-change, infrastructure]
      approvals: 2
    - labels: []
      approvals: 1

branches:
  strategy: trunk-based
  merge_method: squash
  auto_delete: true
  stale:
    warn_days: 1
    close_days: 2
    delete_days: 3
    exempt_labels: [long-running]

pr_template:
  agent_assisted: true
  required_sections:
    - description
    - change_type
    - test_plan
    - breaking_changes
    - linked_issues

agent_commits:
  label: agent-generated
  same_rules: true
  track_metrics: true

Quick Reference

With contextd MCP

Phase	Tools	Purpose
Pre-flight	`semantic_search`, `memory_search`, `remediation_search`	Context loading
Review	`Task(run_in_background: true)` x5	Parallel agents
Collect	`TaskOutput(task_id, block: true)`	Gather findings
Post-flight	`memory_record`, `remediation_record`	Learning capture

Without contextd (File Fallback)

Phase	Action	Location
Pre-flight	Grep previous reviews	`.claude/consensus-reviews/`
Review	`Task(run_in_background: true)` x5	Same parallel agents
Collect	`TaskOutput(task_id, block: true)`	Same collection
Post-flight	Write JSON	`.claude/consensus-reviews/PR-XXX.json`

Common Mistakes

Mistake	Prevention
Skipping pre-flight search (when contextd available)	Search first for past patterns
Not using context folding for agents	Agents MUST run in isolated branches
Forgetting post-flight learning capture	Record outcomes for every review
Ignoring veto power	All agent vetoes are non-negotiable (unless `--ignore-vetos`)
Not creating issues for Low findings	All findings must be tracked
Skipping remediation_record for novel issues	Novel patterns must be captured

Integration with git-repo-standards

This skill works alongside git-repo-standards:

git-repo-standards	git-workflows
Repo structure	PR/review process
Naming conventions	Branch naming
README/CHANGELOG	PR template
Gitleaks config	Security agent
License compliance	Vulnerability agent

git-workflows