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](references/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](references/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](references/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](references/batch-patterns.md) for decision trees.

## Rationalizations to Resist

Agents under pressure find excuses. These are all violations:

| Excuse                                     | Reality