Git Workflows

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

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

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

Anti-Patterns

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

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

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

When contextd is NOT Available

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

Background vs Foreground

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

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

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

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

Branch & Merge Strategy

Model: Trunk-Based with Short-Lived Branches

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

Branch Naming

Stale Branch Cleanup

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:

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.):

Audit Trail Levels

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

Without contextd (File Fallback)

Common Mistakes

Integration with git-repo-standards

This skill works alongside git-repo-standards:

Converted and distributed by TomeVault — claim your Tome and manage your conversions.