# Feature Proposal: Multi-Agent Parallel Review System

> **Priority:** High
> **Complexity:** Medium
> **Estimated Effort:** 12-18 days
> **Status:** Proposal
> **Date:** 2026-02-09
> **Dependencies:** [Findings Tracking](feature-findings-tracking.md) (recommended)
> **Related:** [Overview Analysis](compound-engineering-analysis.md) · [Workflow Presets](feature-workflow-presets.md)

---

## Problem Statement

Makima's contract lifecycle includes a **Review** phase, but it currently has:

- **No automated review mechanism** — the review phase relies entirely on manual user inspection or a single supervisor task
- **Single-perspective review** — even when a review task is spawned, it examines code from one viewpoint
- **No structured review output** — findings are captured as unstructured text in task output
- **No review templates** — each review must be configured from scratch
- **No synthesis** — when multiple reviewers exist, there's no mechanism to deduplicate and prioritize findings

For complex contracts touching security, performance, and architecture, a single-pass review consistently misses category-specific issues that specialized reviewers would catch.

---

## How Compound Engineering Solves This

The compound engineering plugin spawns **12-15 specialized review agents in parallel**, each examining the code from a unique perspective:

| Agent | Focus Area | Example Findings |
|-------|-----------|-----------------|
| Security Sentinel | Auth, injection, secrets, CSRF | SQL injection in user input handler |
| Performance Oracle | N+1 queries, memory leaks, caching | Unbounded list growth in event handler |
| Architecture Strategist | Coupling, SOLID, layering | Service directly accessing repository internals |
| Code Philosopher | Readability, naming, complexity | Cyclomatic complexity > 15 in payment flow |
| Data Integrity Guardian | Validation, constraints, migrations | Missing NOT NULL constraint on required field |
| Error Resilience Analyzer | Error handling, retries, fallbacks | Unhandled timeout in external API call |
| API Contract Validator | Breaking changes, versioning | Removed required field from response |
| Dependency Health Checker | Vulnerabilities, licensing, freshness | CVE-2025-XXXX in transitive dependency |
| Test Coverage Analyzer | Coverage gaps, edge cases, mocking | No tests for error path in checkout flow |
| Documentation Completeness | Docs accuracy, examples, changelog | Public API endpoint undocumented |
| Concurrency Safety | Race conditions, deadlocks, atomicity | Non-atomic read-modify-write on shared counter |

After all agents complete, a **synthesis agent** deduplicates findings, resolves contradictions, and produces a prioritized report.

```
┌───────────────────────────────────────────────────────┐
│                  Review Orchestrator                   │
│                                                       │
│  spawn-group "review"                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │Security │ │ Perf    │ │  Arch   │ │  Code   │   │
│  │Sentinel │ │ Oracle  │ │Strategy │ │  Phil   │   │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘   │
│       │           │           │           │         │
│  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐   │
│  │  Data   │ │ Error   │ │  API    │ │  Deps   │   │
│  │Guardian │ │Resilien.│ │Contract │ │ Health  │   │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘   │
│       │           │           │           │         │
│  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐               │
│  │  Test   │ │  Docs   │ │Concurr. │               │
│  │Coverage │ │Complete │ │ Safety  │               │
│  └────┬────┘ └────┬────┘ └────┬────┘               │
│       │           │           │                     │
│  wait-group "review"                                 │
│       ▼           ▼           ▼                     │
│  ┌──────────────────────────────────────────┐       │
│  │         Synthesis Agent                   │       │
│  │  - Deduplicate findings                   │       │
│  │  - Resolve contradictions                 │       │
│  │  - Prioritize by severity                 │       │
│  │  - Generate summary report                │       │
│  └──────────────────────────────────────────┘       │
│                      │                               │
│                      ▼                               │
│             Structured Findings                      │
│             (P1 / P2 / P3)                           │
└───────────────────────────────────────────────────────┘
```

---

## Proposed Makima Implementation

### 1. New Supervisor Commands

#### `makima supervisor spawn-group`

Spawns multiple tasks as a named group and returns immediately:

```bash
# Spawn a review group with 5 agents
makima supervisor spawn-group "review" \
  --tasks '[
    {"name": "security-review", "plan": "Review for security vulnerabilities..."},
    {"name": "performance-review", "plan": "Review for performance issues..."},
    {"name": "architecture-review", "plan": "Review for architecture concerns..."}
  ]' \
  --share-worktree \
  --read-only
```

**Key parameters:**
- `--tasks` — JSON array of task definitions
- `--share-worktree` — All tasks in the group share the supervisor's worktree (read-only access)
- `--read-only` — Tasks cannot modify files, only produce output
- `--max-concurrent N` — Limit parallel execution (default: unlimited)

#### `makima supervisor wait-group`

Waits for all tasks in a named group to complete:

```bash
# Wait for all review tasks, timeout after 10 minutes
makima supervisor wait-group "review" --timeout 600

# Returns JSON with all task results
```

**Output format:**
```json
{
  "group": "review",
  "status": "completed",
  "tasks": [
    {"name": "security-review", "status": "done", "output": "..."},
    {"name": "performance-review", "status": "done", "output": "..."}
  ],
  "duration_seconds": 127
}
```

#### `makima supervisor review`

High-level command that orchestrates the full review pipeline:

```bash
# Run review with default agent config
makima supervisor review

# Run review with custom config
makima supervisor review --config .makima/review-agents.yaml

# Run only specific review categories
makima supervisor review --only security,performance,architecture
```

### 2. Review Agent Configuration

#### Repository-Level Configuration (`.makima/review-agents.yaml`)

```yaml
# .makima/review-agents.yaml
version: 1
review:
  # Maximum number of concurrent review agents
  max_concurrent: 8

  # Timeout per agent (seconds)
  agent_timeout: 300

  # Auto-trigger review when phase transitions to 'review'
  auto_trigger: true

  # Finding severity that blocks merge
  merge_blocking_severity: P1

  agents:
    - name: security-sentinel
      enabled: true
      plan: |
        You are a Security Sentinel reviewing code changes.

        Focus areas:
        - Authentication and authorization flaws
        - Injection vulnerabilities (SQL, XSS, command injection)
        - Secret/credential exposure
        - CSRF and session management
        - Input validation gaps

        Output format: One finding per section with severity (P1/P2/P3),
        affected file/line, description, and suggested fix.
      priority: critical  # Always runs

    - name: performance-oracle
      enabled: true
      plan: |
        You are a Performance Oracle reviewing code changes.

        Focus areas:
        - N+1 query patterns
        - Memory leaks and unbounded growth
        - Missing caching opportunities
        - Algorithmic complexity issues
        - Database index utilization

        Output format: One finding per section with severity (P1/P2/P3),
        affected file/line, description, and suggested fix.
      priority: standard

    - name: architecture-strategist
      enabled: true
      plan: |
        You are an Architecture Strategist reviewing code changes.

        Focus areas:
        - SOLID principle violations
        - Inappropriate coupling between modules
        - Layering violations (e.g., handler accessing DB directly)
        - Missing abstraction boundaries
        - Inconsistency with existing patterns

        Output format: One finding per section with severity (P1/P2/P3),
        affected file/line, description, and suggested fix.
      priority: standard

    - name: test-coverage-analyzer
      enabled: true
      plan: |
        You are a Test Coverage Analyzer reviewing code changes.

        Focus areas:
        - Missing test coverage for new code paths
        - Untested error/edge cases
        - Test quality (meaningful assertions vs superficial)
        - Integration test gaps
        - Mock appropriateness

        Output format: One finding per section with severity (P1/P2/P3),
        affected file/line, description, and suggested fix.
      priority: standard

    # Users can add custom agents here
    - name: custom-domain-reviewer
      enabled: false
      plan: "Review for domain-specific business logic concerns..."
      priority: optional
```

#### Contract-Level Override

```yaml
# In contract configuration or via CLI
review:
  agents:
    # Disable agents not relevant to this contract
    - name: concurrency-safety
      enabled: false
    # Add contract-specific reviewer
    - name: migration-safety
      enabled: true
      plan: "Review database migrations for data loss risks..."
```

### 3. Synthesis Step

After all review agents complete, a synthesis task:

1. **Collects** all findings from group task outputs
2. **Deduplicates** findings about the same issue from different perspectives
3. **Resolves contradictions** (e.g., one agent says "add caching" while another says "caching adds complexity")
4. **Prioritizes** by severity and cross-agent agreement
5. **Produces** a structured review report as a contract file

```bash
# Synthesis is automatically run after wait-group completes
makima supervisor synthesize-review "review" \
  --output-format findings \
  --create-contract-file
```

### 4. Auto-Review Trigger

When a contract's phase transitions to `review`:

```rust
// In phase transition handler
if new_phase == "review" && contract.review_config.auto_trigger {
    // Spawn review group automatically
    spawn_review_group(contract, review_config).await?;
}
```

---

## Integration with Existing Makima Features

### Supervisor/Worker Hierarchy

Review agents are spawned as **worker tasks** under the supervisor, using existing `spawn-task` infrastructure. The new `spawn-group`/`wait-group` commands are syntactic sugar over batch `spawn-task` + `wait` calls.

### Git Worktree Isolation

Review agents share the supervisor's worktree in **read-only mode** (a new capability). This avoids creating N separate worktrees for review-only tasks. Implementation:
- New `supervisor_worktree_task_id` parameter (already exists in SpawnTask)
- New `read_only: true` flag to prevent file modifications
- Workers see the same code state that triggered the review

### Contract Files

The synthesized review report is stored as a **contract file** attached to the review phase:
```rust
File {
    contract_id: contract.id,
    contract_phase: "review",
    name: "Review Report — 2026-02-09",
    body: vec![
        BodyElement::Heading { level: 1, text: "Review Summary" },
        BodyElement::Paragraph { text: "3 P1 findings, 7 P2 findings, 12 P3 findings" },
        // ... structured findings
    ],
}
```

### Phase Guards

If `phase_guard` is enabled and P1 findings exist, the phase transition from Review to Execute (or Compound) is blocked until P1s are resolved. This integrates with the existing `advance-phase` confirmation flow.

### Completion Gates

Each review agent uses the existing `<COMPLETION_GATE>` mechanism to signal when its review is complete:
```xml
<COMPLETION_GATE>
ready: true
reason: "Security review complete. Found 2 P1 and 3 P2 findings."
progress: "Reviewed 47 files across 12 modules."
</COMPLETION_GATE>
```

### Circuit Breaker

The existing CircuitBreaker protects against review agents getting stuck. If a review agent loops without progress for 3 iterations, it's terminated and its partial findings are included in synthesis.

---

## Implementation Plan

### Phase 1: Group Task Infrastructure (5-7 days)

| Task | Effort | Description |
|------|--------|-------------|
| `spawn-group` command | 2 days | Batch task spawning with named groups |
| `wait-group` command | 1 day | Wait for all tasks in group |
| Group tracking in DB | 1 day | Task group table, membership, status |
| Shared worktree (read-only) | 1-2 days | Workers share supervisor worktree |
| Tests | 1 day | Unit + integration tests |

### Phase 2: Review Agent System (4-6 days)

| Task | Effort | Description |
|------|--------|-------------|
| Review config YAML parser | 1 day | Parse `.makima/review-agents.yaml` |
| `supervisor review` command | 2 days | Orchestrate review pipeline |
| Synthesis agent logic | 1-2 days | Deduplicate, prioritize, format |
| Review report as contract file | 1 day | Store structured output |

### Phase 3: Automation & Polish (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| Auto-trigger on phase transition | 1 day | Hook into `advance-phase` |
| P1 merge blocking | 1 day | Phase guard integration |
| Default review agent templates | 1-2 days | Ship 8-10 built-in agents |
| Documentation | 1 day | User guide and config reference |

---

## Configuration Examples

### Minimal Setup (Zero Config)

```bash
# Uses built-in review agents with default settings
makima supervisor review
```

### Custom Review for a Specific Contract

```bash
# Override for this contract only
makima supervisor review \
  --only security,performance \
  --merge-blocking P1 \
  --timeout 300
```

### Full Custom Configuration

```yaml
# .makima/review-agents.yaml
version: 1
review:
  max_concurrent: 6
  agent_timeout: 300
  auto_trigger: true
  merge_blocking_severity: P1

  synthesis:
    dedup_threshold: 0.8        # Similarity score for deduplication
    min_agreement: 2             # Findings flagged by 2+ agents get priority boost
    output_format: "findings"    # "findings" | "report" | "both"
    create_contract_file: true

  agents:
    - name: security-sentinel
      enabled: true
      priority: critical
      plan: |
        ...
    - name: performance-oracle
      enabled: true
      priority: standard
      plan: |
        ...
    # ... more agents
```

---

## Open Questions

1. **Shared worktree read-only enforcement**: Should this be enforced at the filesystem level (mount read-only) or via convention (instructions to the agent)?
2. **Review scope**: Should review agents see all files or only changed files (git diff)?
3. **Incremental review**: When new commits are added during review, should agents re-review or only review the delta?
4. **Agent output parsing**: Should agents output structured YAML findings, or should the synthesis step parse natural language?
5. **Cost control**: With 10+ parallel agents, how do we manage API costs? Should there be a budget ceiling per review?
6. **Finding deduplication**: What similarity threshold should trigger deduplication? How to handle partial overlaps?

---

## Alternatives Considered

| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Single comprehensive review agent | Simple, no coordination overhead | Misses perspective-specific issues | Rejected — diminishes review quality |
| Sequential reviews (one after another) | Simpler orchestration | 5-10x slower; later reviews can't benefit from earlier ones | Rejected — latency unacceptable |
| External review tools integration | Leverage existing static analysis | Limited to tool capabilities; no semantic review | Complement — can integrate alongside agent review |
| User-configured number of agents | Maximum flexibility | Analysis paralysis for new users | Adopted — sensible defaults + customization |

---

## Priority & Complexity Assessment

- **Priority: HIGH** — Multi-agent review is the highest-impact feature from the compound engineering plugin. It directly improves code quality with no change to developer workflow.
- **Complexity: MEDIUM** — The core `spawn-group`/`wait-group` pattern is straightforward. The synthesis step requires careful design. Shared worktree read-only mode is a new capability.
- **Risk: LOW-MEDIUM** — Main risks are resource consumption (manageable with concurrency limits) and synthesis quality (improvable iteratively).
