Make review fan-out topology mode-aware to reduce cost in lite/vibe modes

[williamthorsen]

Problem

The review cycle dispatches up to 4 parallel reviewers (core + 3 aspect) regardless of mode. In vibe mode this is disproportionately expensive — the core reviewer finds most unique issues, and aspect reviewers largely duplicate its findings. Token analysis from run 20260305-184232Z (#181) showed 4-way parallel reviewer fan-out consumed ~326K tokens across 2 rounds.

The review-cycle module already handles variable fan-out correctly. The gap: mode presets in orchestrate-dev can't feed into aspect reviewer activation — activation is resolved from preferences.yaml only, not from the mode cascade.

Scope

Two changes in this ticket:

1. Thread aspect_reviewers through the mode cascade so modes control which aspect reviewers run.
2. Remove --lite mode entirely. Replace orchestration mode with effort system #199's auto-sizing within accountability levels makes lite redundant — a small task at default accountability gets lite-like settings automatically.

Design decisions

• Vibe mode: explicitly deactivates all aspect reviewers (false). Vibe intentionally trades thoroughness for speed.
• Default/strict: no override (absent). The orchestrator retains discretion via the review-cycle module's file-pattern activation logic, which skips aspect reviewers when the changed files don't warrant them.
• preferences.yaml override removed: The orchestration.aspect_reviewers boolean override mechanism in review-cycle.md is removed. It was never used in practice and would complicate Replace orchestration mode with effort system #199's cascade. Can be re-added when a concrete use case emerges.
• review-cycle becomes a pure function of its inputs: it no longer reads preferences directly — the engine threads {aspect_reviewers} as a context variable.

Changes

File	Change
orchestrate-dev/SKILL.md	Remove lite (argument, preset column, pipeline spec). Add aspect_reviewers row to mode presets.
orchestrate/SKILL.md	Remove lite from wrapper reference. Add {aspect_reviewers} to review-cycle context preparation.
review-cycle.md	Add {aspect_reviewers} input. Replace preferences.yaml lookup with input-driven activation.

Acceptance criteria

• --mode=vibe deactivates all three aspect reviewers (only core reviewer runs)
• Default mode (no --mode) leaves aspect reviewer activation to the file-pattern logic in review-cycle
• --mode=strict leaves aspect reviewer activation to the file-pattern logic in review-cycle
• --lite is no longer accepted as a mode value
• review-cycle.md no longer references preferences.yaml or orchestration.aspect_reviewers
• {aspect_reviewers} appears in the review-cycle inputs table and the orchestrate engine's context preparation section
• No other files reference lite in the orchestration context

Expected impact

For vibe mode (1 round): ~120K tokens (1 reviewer × 1 round) vs ~163K (4 reviewers × 1 round). ~63% savings on the review phase.

Related

• Replace orchestration mode with effort system #199 — Adds auto mode that right-sizes orchestration settings within accountability levels (depends on this ticket)
• Build run-log analysis tooling to compute cost-vs-value metrics per phase and reviewer #198 — Run-log analysis for tuning thresholds (independent)
• Subagents complete analysis but fail to write artifact files #105 — Subagents fail to write artifact files (fan-out multiplies impact)

[williamthorsen]

This ticket is a prerequisite for #199 (auto mode). The aspect_reviewers context variable this ticket threads into the review-cycle module is the mechanism auto mode uses to control fan-out dynamically.

[williamthorsen]

Implementation plan

Mode-aware review fan-out implementation plan

Goal: Thread aspect_reviewers through the mode cascade so modes control review fan-out, and remove --lite mode.

Architecture: Three markdown skill files are edited. orchestrate-dev (wrapper) defines mode presets including the new aspect_reviewers setting. orchestrate (engine) threads the resolved value to the review-cycle module. review-cycle (module) accepts {aspect_reviewers} as input and drops its preferences.yaml lookup.

Tech Stack: Markdown skill definitions (no TypeScript, no tests)

---

Task 1: Remove lite mode and add aspect_reviewers to orchestrate-dev/SKILL.md

Files:

• Modify: packages/agents/content/skills/orchestrate-dev/SKILL.md

Step 1: Update the --mode argument

On line 18, change:

- `--mode=<vibe|lite|strict>`: select a mode preset (default: no mode, preserving current behavior)

To:

- `--mode=<vibe|strict>`: select a mode preset (default: no mode, preserving current behavior)

Step 2: Replace the mode preset table

Replace lines 29-36 (the table including header, separator, and all rows) with:

| Setting             | `vibe`      | (default) | `strict` |
| ------------------- | ----------- | --------- | -------- |
| architecture        | absent      | optional  | required |
| planning            | absent      | optional  | required |
| aspect_reviewers    | all `false` | (absent)  | (absent) |
| approval-threshold  | high        | low       | low      |
| budget-threshold    | high        | low       | low      |
| holistic_reviewer\* | sonnet      | opus      | opus     |
| max-review-rounds   | 1           | 3         | 4        |

The aspect_reviewers row is placed between the phase settings (architecture, planning) and the threshold settings (approval, budget), grouping "what runs" together.

Step 3: Replace the "vibe and lite" pipeline section

Replace lines 65-76 (the combined "vibe and lite" pipeline section) with a vibe-only section:

**`--mode=vibe`**:

```
implementation (required) -> review-cycle (required)
```

| Phase            | Requirement | Description                                       |
| ---------------- | ----------- | ------------------------------------------------- |
| `implementation` | `required`  | Write code                                        |
| `review-cycle`   | `required`  | Parallel review, code-simplifier, holistic review |

Vibe mode skips architecture and planning and deactivates all aspect reviewers — only the core reviewer runs. See the mode preset table above.

Step 4: Verify the file reads correctly

Read the full file and confirm:

• No remaining references to lite
• The mode preset table has 3 columns (vibe, default, strict)
• The aspect_reviewers row is present
• The pipeline section references only vibe (not "vibe and lite")

Step 5: Commit

git add packages/agents/content/skills/orchestrate-dev/SKILL.md
git commit -m "#197 orchestrate-dev: Remove lite mode and add aspect_reviewers to mode presets"

---

Task 2: Thread {aspect_reviewers} through orchestrate/SKILL.md

Files:

• Modify: packages/agents/content/skills/orchestrate/SKILL.md

Step 1: Update wrapper skill reference

On line 11, change:

Wrapper skills (`orchestrate-dev` with optional `--mode=vibe|lite|strict`, `orchestrate-review`) configure which phases to run and invoke this engine with a pipeline specification.

To:

Wrapper skills (`orchestrate-dev` with optional `--mode=vibe|strict`, `orchestrate-review`) configure which phases to run and invoke this engine with a pipeline specification.

Step 2: Add {aspect_reviewers} to the context preparation section

After line 378 (the {plan-md-path} bullet in "review-cycle: variables from the engine"), add a new bullet:

- `{aspect_reviewers}` — resolved aspect reviewer overrides from mode preset. Map of `{ code: bool, silent_failure: bool, test: bool }` where `false` means deactivate, absent means use the module's file-pattern default. For vibe mode: `{ code: false, silent_failure: false, test: false }`. For default and strict: empty map (all keys absent).

Step 3: Verify the file reads correctly

Read the context preparation section and confirm:

• No remaining references to lite
• {aspect_reviewers} is listed as a variable passed to the review-cycle module
• The description explains both the vibe case and the default/strict case

Step 4: Commit

git add packages/agents/content/skills/orchestrate/SKILL.md
git commit -m "#197 orchestrate: Thread aspect_reviewers to review-cycle module"

---

Task 3: Accept {aspect_reviewers} input and remove preferences.yaml lookup in review-cycle.md

Files:

• Modify: packages/agents/content/skills/orchestrate/modules/review-cycle.md

Step 1: Add {aspect_reviewers} to the inputs table

After line 22 (the {mcp-available} row), add a new row:

| `{aspect_reviewers}`         | Aspect reviewer overrides from mode preset. Per-aspect: `false` = never activate, absent = use file-pattern default |

Step 2: Replace the activation logic

Replace lines 43-69 (from "### Aspect reviewer activation" through the end of the example YAML block) with:

### Aspect reviewer activation

Before dispatching aspect reviewers, determine which ones are relevant to the change. The core reviewer (`orchestrated-reviewer`) always runs. Each aspect reviewer's activation is resolved in two steps:

1. **Check `{aspect_reviewers}` override**: if the reviewer has an explicit `false` in the `{aspect_reviewers}` map, skip it.
2. **Apply file-pattern default**: if no override exists (key absent from `{aspect_reviewers}`), activate based on the changed-file list:

| Aspect reviewer                  | File-pattern default                                                                                            | Skip reason                     |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `aspect-code-reviewer`           | Always                                                                                                          | -                               |
| `aspect-silent-failure-reviewer` | Changed files include source code (`.ts`, `.js`, `.tsx`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.sh`, `.zsh`)   | No source files changed         |
| `aspect-test-reviewer`           | Changed files include source code (same extensions as above) or test files (`*.test.*`, `*.spec.*`, `*_test.*`) | No source or test files changed |

This removes:

• The orchestration.aspect_reviewers preferences.yaml lookup (lines 53-59)
• The example YAML configuration block (lines 61-69)

Step 3: Verify the file reads correctly

Read the full activation section and confirm:

• No references to preferences.yaml or orchestration.aspect_reviewers
• The two-step resolution is clear: override → file-pattern
• The file-pattern table is preserved unchanged
• The dispatch section (starting at "### Dispatch") is untouched

Step 4: Commit

git add packages/agents/content/skills/orchestrate/modules/review-cycle.md
git commit -m "#197 review-cycle: Accept aspect_reviewers input, remove preferences.yaml override"

---

Task 4: Final verification

Step 1: Search for remaining "lite" references

Search all files under packages/agents/content/ for the word "lite" (case-insensitive). The only expected match is read-vibelassian-conversation/SKILL.md which references "vibelassian" (unrelated).

Step 2: Search for remaining preferences.yaml references to aspect_reviewers

Search all files under packages/agents/content/ for aspect_reviewers and confirm it appears only in:

• orchestrate-dev/SKILL.md (mode preset table)
• orchestrate/SKILL.md (context preparation)
• review-cycle.md (inputs table and activation logic)

Step 3: Post insight as ticket comment

Post a comment on #197 summarizing the implementation and the relationship to #199.

[williamthorsen]

Implementation summary

Threaded aspect_reviewers through the orchestration mode cascade across three skill files:

1. orchestrate-dev/SKILL.md — removed --lite mode entirely (argument, preset column, pipeline section). Added aspect_reviewers row to the mode preset table: vibe sets all three to false (deactivated), default/strict leave the value absent (file-pattern defaults apply).

2. orchestrate/SKILL.md — removed lite from wrapper skill reference. Added {aspect_reviewers} to review-cycle context preparation, derived via shared conversation context (same mechanism as the pipeline table).

3. review-cycle.md — added {aspect_reviewers} to inputs table. Replaced preferences.yaml-based activation with a two-step resolution: (1) check override — false means skip, (2) fall through to file-pattern defaults. Made aspect-code-reviewer dispatch conditional.

4. .agents/PROJECT.md — removed --mode=lite reference.

Relationship to #199: Removing --lite clears the way for #199's auto-sizing within accountability levels. A small task at default accountability will get lite-like settings automatically, making a separate lite mode redundant. The aspect_reviewers threading established here gives #199 a clean mechanism for controlling review fan-out per accountability level.

Insight from the run

The holistic reviewer caught a consistency gap where aspect-code-reviewer's dispatch call and sequencing label still said "always" after activation was changed to conditional — a gap the parallel reviewers missed. This validates the holistic review's cross-cutting value for documentation-heavy changes where inconsistencies span multiple sections.