elb-pr/git-workflow

Git Workflow Methodology

When to use this skill

Use this skill when you need to:

• Run the claudikins-kernel:execute command
• Decompose plans into executable tasks
• Set up two-stage code review
• Decide batch sizes and checkpoints
• Handle stuck agents or failed tasks

Core Philosophy

"I'd use 5-7 agents per SESSION, not 30 per batch." - Boris

Execution is about isolation, verification, and human checkpoints. Not speed.

The Six Principles

1. One task = one branch - Isolation prevents pollution
2. Fresh context per task - context: fork gives a clean slate
3. Two-stage review - Spec compliance first, then code quality
4. Human checkpoints between batches - Not between individual tasks
5. Commands own git - Agents never checkout/merge/push
6. Features are the unit - Batch at feature level, not task level

Batch Size Guidance (GOSPEL)

Wrong: 30 agents for 10 tasks (3 per task micro-management) Right: 5-7 agents total (feature-level batches)

| Scenario | Wrong | Right | | -------------------- | -------------------------- | ------------------ | | 10 tasks, 5 features | 30 micro-task agents | 5-7 feature agents | | Simple refactor | 10 agents for tiny changes | 1-2 feature agents |

Default --batch 1 is correct. Features are the unit of work.

Task Decomposition

From a plan, extract tasks that are:

| Quality | Definition | Example | | --------------- | ---------------------------------------------- | --------------------------------------------- | | Atomic | Completable in one agent session | "Add auth middleware" not "Build auth system" | | Testable | Has measurable acceptance criteria | "Returns 401 for invalid token" | | Independent | Minimal dependencies on other tasks | Can be reviewed in isolation | | Right-sized | Not too small (noise) or large (context death) | 50-200 lines of changes |

See task-decomposition.md for patterns.

Review Stages

Two reviewers with different jobs. Never skip either.

Stage 1: Spec Compliance (spec-reviewer, opus)

Question: "Did it do what was asked?"

Checks:

• All acceptance criteria addressed?
• Any scope creep (features not in spec)?
• Any missing requirements?

Output: PASS or FAIL with line references.

Stage 2: Code Quality (code-reviewer, opus)

Question: "Is it well-written?"

Checks:

• Consistency with codebase style
• Error handling
• Edge cases
• Naming clarity
• Unnecessary complexity

Output: PASS or CONCERNS with confidence scores.

See review-criteria.md for detailed checklists.

Review Enforcement (MANDATORY)

This is non-negotiable. Violations here break the entire workflow.

The Iron Rule

After EVERY task completes, you MUST spawn BOTH reviewer agents:

1. spec-reviewer - Spawned via Task(spec-reviewer, {...})
2. code-reviewer - Spawned via Task(code-reviewer, {...}) (if spec passes)

What "MUST spawn" Means

| Allowed | NOT Allowed | |---------|-------------| | Task(spec-reviewer, { prompt: "...", context: "fork" }) | Inline spec check by orchestrator | | Task(code-reviewer, { prompt: "...", context: "fork" }) | "I'll just verify the code looks good" | | Waiting for agent output JSON | Making your own compliance table | | Reading from .claude/reviews/spec/ | Skipping because "it's a simple task" |

Inline Reviews Are VIOLATIONS

If you find yourself doing ANY of these, you are VIOLATING the methodology:

• Creating a "Spec Compliance Check" table yourself
• Writing "Verdict: PASS" without spawning an agent
• Saying "Let me verify the implementation meets criteria"
• Checking acceptance criteria in a loop instead of delegating

The orchestrator does NOT review. The orchestrator SPAWNS reviewers.

Pre-Merge Checklist (HARD GATE)

Before ANY merge decision can be offered to the user:

□ .claude/reviews/spec/{task_id}.json EXISTS for each task
□ .claude/reviews/code/{task_id}.json EXISTS for each task
□ Both files contain valid JSON with "verdict" field
□ spec-reviewer verdict is PASS (or user override documented)

If ANY file is missing: DO NOT proceed to merge. You skipped the review.

Why This Matters

1. Consistency - Every task gets the same rigor, not "looks simple, I'll check it"
2. Auditability - Review outputs are artifacts, not orchestrator judgments
3. Separation of concerns - Orchestrator orchestrates, reviewers review
4. No rationalization - You can't convince yourself your inline check is "good enough"

Verdict Matrix

What happens when reviewers return their verdicts:

| Spec Result | Code Result | Action | | ----------- | ----------- | ------------------------------------------------ | | PASS | PASS | Offer [Accept] [Revise anyway] | | PASS | CONCERNS | Offer [Accept with caveats] [Fix] [Klaus review] | | FAIL | * | Always [Revise] or [Retry] |

See review-conflict-matrix.md for edge cases.

Batch Checkpoint Flow

All tasks in batch complete?
├── No → Wait for remaining
└── Yes →
    All reviews pass?
    ├── No →
    │   Retry count < 3?
    │   ├── Yes → Retry failed tasks
    │   └── No → Escalate to Klaus or human
    └── Yes →
        Present results to human
        └── Human decides: [Accept] [Revise] [Retry]

See batch-patterns.md for decision trees.

Rationalizations to Resist

Agents under pressure find excuses. These are all violations:

| Excuse | Reality | | ------------------------------------------ | ------------------------------------------------------------------- | | "30 agents is fine, tasks are independent" | More agents = more chaos. 5-7 per session, features as units. | | "I'll just checkout main to compare" | Agents don't own git. Use git show main:file instead. | | "Skip spec review, code looks correct" | Spec review catches scope creep. Never skip. | | "I'll do the review myself, it's simple" | Spawn the reviewer agents. Inline reviews are VIOLATIONS. | | "Both passed, auto-merge is safe" | Human checkpoint required. Always. | | "Context is fine, I'll continue" | ACM at 60% = checkpoint offer. 75% = mandatory stop. | | "This tiny task doesn't need a branch" | One task = one branch. No exceptions. Isolation prevents pollution. | | "Retry limit is just a guideline" | 2 retries then escalate. Infinite retry = infinite waste. | | "I'll merge my changes when done" | Commands own merge. You own implementation. Stay in your lane. |

All of these mean: Follow the methodology. Speed is not the goal.

Red Flags — STOP and Reassess

If you're thinking any of these, you're about to violate the methodology:

• "Let me just run git checkout..."
• "30 tasks, 30 agents, maximum parallelism"
• "Review passed, no need for human checkpoint"
• "Context is getting tight but I can finish"
• "This is simple, don't need isolation"
• "I'll merge it myself"
• "Retry limit doesn't apply here"
• "Spec review is redundant if code review passes"
• "Let me verify the implementation meets criteria" (SPAWN THE AGENT)
• "I'll create a quick compliance table" (SPAWN THE AGENT)

All of these mean: STOP. Commands own git. Humans own checkpoints. Reviewers own reviews. You own orchestration.

Robustness Patterns

Things go wrong. Here's how to handle them.

SubagentStop Hook Failure (A-6)

If the capture hook fails, agent output is lost.

Pattern: Write to backup location first, then move to primary.

# Always backup first
echo "$OUTPUT" > "$BACKUP_DIR/agent-$(date +%s).json"
# Then move to primary
mv "$BACKUP_DIR/..." "$PRIMARY"

Malformed JSON Output (A-7)

Agents sometimes produce invalid JSON.

Pattern: Validate required fields before accepting.

REQUIRED='["task_id", "status"]'
jq -e "all($REQUIRED[]; has(.))" "$OUTPUT" || exit 2

Task Branch Directory Export (A-8)

Agents need to know where to work.

Pattern: Export directory as environment variable in SubagentStart hook.

export TASK_BRANCH_DIR="$PROJECT_DIR"
export TASK_BRANCH_NAME="execute/task-${TASK_ID}-${SLUG}"

Model Rate Limiting (A-10)

Opus gets rate limited more than Sonnet.

Pattern: Offer fallback options to human.

1. Notify: "Opus rate limited. Options:"
2. Offer: [Wait 60s] [Use Sonnet fallback] [Abort]
3. If fallback, add caveat to review output

Context Exhaustion Mid-Task (A-11)

Agent runs out of context before finishing.

Pattern: Output partial state and mark as resumable.

{
  "status": "partial",
  "files_changed": ["completed work..."],
  "next_steps": ["what remains..."],
  "checkpoint_hash": "sha256:..."
}

Dependency Failure Chains (S-7)

Task Y depends on Task X. Task X fails. What happens to Y?

See dependency-failure-chains.md.

Branch Collision (S-8)

Two tasks accidentally get the same branch name.

See branch-collision-detection.md.

Branch Guard Recovery (S-9)

The git-branch-guard hook blocks something it shouldn't.

See branch-guard-recovery.md.

Batch Size Verification (S-10)

Validating batch sizes before execution starts.

See batch-size-verification.md.

Task Branch Recovery (S-12)

Recovering orphaned branches from crashed sessions.

See task-branch-recovery.md.

Circuit Breakers (S-13)

Preventing cascading failures when operations fail repeatedly.

Pattern: Track failure rate. If threshold exceeded, "open" the circuit - fail fast without attempting.

Circuit: agent_spawn
State: OPEN (3 failures in 60s)
Reset in: 30 seconds

[Wait for reset] [Force close] [Skip operation]

See circuit-breakers.md.

Execution Tracing (S-14)

Debugging execution graphs and understanding what happened.

Pattern: Record spans for each operation. Visualise as waterfall or dependency graph.

Trace: exec-session-xyz
├── batch_1 (45s)
│   ├── task-1 (20s) ✓
│   └── task-2 (25s) ✓
└── batch_2 (60s)
    └── task-3 (60s) ✓

Critical path: batch_1 → batch_2

See execution-tracing.md.

Stuck Detection

| Signal | Threshold | Response | | --------------------- | ----------------------------- | ------------------- | | Tool call flooding | 20 calls without file changes | Warning, then Klaus | | Time without progress | 10 minutes | Warning, then Klaus | | Repeated failures | Same error 3x | Pause, offer Klaus | | Context burn rate | ACM at 60% | Checkpoint offer | | Review timeout | 5 minutes per reviewer | Offer [Wait] [Skip] |

Anti-Patterns

Don't do these:

• Running git checkout/merge/push from agents
• Batching 30+ tasks in parallel
• Skipping spec review because "code looks fine"
• Auto-merging without human checkpoint
• Ignoring stuck signals
• Continuing after context warnings

References

Full documentation in this skill's references/ folder:

• task-decomposition.md - How to break down plans
• review-criteria.md - What reviewers check (400 LOC threshold, attack surface tracing)
• batch-patterns.md - Checkpoint decision patterns (coordinated checkpoints, load shedding, deadline propagation)
• dependency-failure-chains.md - When dependent tasks fail
• branch-collision-detection.md - Preventing duplicate branches
• branch-guard-recovery.md - Recovering from guard failures
• batch-size-verification.md - Validating batch sizes
• review-conflict-matrix.md - Handling reviewer disagreements (RESOLVE framework)
• task-branch-recovery.md - Recovering orphaned branches
• circuit-breakers.md - Preventing cascading failures (circuit breaker pattern, timeout strategies)
• execution-tracing.md - Debugging execution graphs (spans, traces, critical path analysis)