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)

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

Task Decomposition

From a plan, extract tasks that are:

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

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:

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:

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 wr