tutti-architecture-review

# Tutti Architecture Review

Use this skill when reviewing a `tutti` change or a named module for repository structure, module ownership, or layering compliance. This is a focused architecture review, not a general bug hunt.

## Vocabulary

Use the architecture vocabulary consistently:

- **Module**: anything with an interface and an implementation.
- **Interface**: everything a caller must know to use the module correctly.
- **Implementation**: the code inside a module.
- **Depth**: leverage at the interface; deep modules hide useful behavior behind a small interface.
- **Seam**: where an interface lives.
- **Adapter**: a concrete thing satisfying an interface at a seam.
- **Leverage**: what callers get from depth.
- **Locality**: what maintainers get from depth.

Prefer these words in findings. Avoid vague substitutes such as "component", "service", "utility", or "boundary" when a vocabulary term fits.

## Workflow

1. Resolve the user's review intent:
   - plain `git diff` review for the current change
   - module-focused diff review when the user names a module inside the current change
   - static module review when the user wants a named module inspected even without current diff overlap

   Use light natural-language guidance when the request is ambiguous. Do not force the user through a fixed mode menu.

2. When the user names a module, let the main agent infer a few candidate path keywords and gather candidate paths. Then normalize those paths into a scope file:

   ```bash
   node ./.codex/skills/tutti-architecture-review/scripts/build-review-scope.mjs \
     --input /tmp/tutti-review-candidates.json \
     --output /tmp/tutti-review-scope.json
   ```

   Candidate input is agent-produced. The script does not invent module keywords or search the repository itself; it only normalizes candidate paths into a stable scope contract for the planner.

   Read `references/scope-contract.md` when changing or consuming the candidate input, normalized scope output, or planner scope metadata.

3. Run the review planner from the repository root:

   ```bash
   pnpm review:architecture:package
   ```

   For module-focused review, pass the generated scope file:

   ```bash
   node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs \
     --scope-file /tmp/tutti-review-scope.json \
     --format json \
     --output-temp
   ```

   The planner remains `git diff` first. With `--scope-file`, it reviews `scope ∩ diff` when there is overlap, and falls back to scoped-file review only when there is no diff overlap.

   For explicit static module review, force scope-only planning:

   ```bash
   node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs \
     --scope-file /tmp/tutti-review-scope.json \
     --scope-mode static-only \
     --format json \
     --output-temp
   ```

4. Read the generated JSON task package from `workflowEntry.packagePath`. Each task includes `riskLevel`, `spawnRecommendation`, `summaryForMainAgent`, `matchedFiles`, `preflightSignals`, and a ready-to-use `prompt`.

5. Spawn `explorer` sub-agents according to `spawnRecommendation`:
   - `required`: spawn unless the user explicitly asked for a narrower review
   - `recommended`: spawn when the review is not trivially small
   - `optional`: the main agent may review locally

   Do not ask sub-agents to edit files. Their job is to inspect the relevant diff and report architecture findings.

6. Continue local work while sub-agents run only if there is non-overlapping review or summarization work. Do not duplicate a sub-agent's assigned scope.

7. Merge sub-agent reports into a code-review style answer:
   - findings first, ordered by severity
   - cite file paths and line numbers when possible
   - explain the violated rule and why it matters for locality, leverage, or dependency direction
   - include "No architecture findings" when a reviewer found no issues

## Reviewer Expectations

Every sub-agent should:

- read `AGENTS.md` and the closest area `AGENTS.md` for its changed files
- read only the reference files listed in the task package, plus files needed to understand the diff
- inspect the relevant git diff directly instead of relying only on file names
- report only actionable architecture issues, not taste preferences
- distinguish hard rule violations from speculative deepening opportunities
- avoid proposing new interfaces unless the changed code already creates pressure for a real seam
- when eventing, pub-sub, or bidirectional coordination appears, check whether the shared business event stream's `global`, `desktop`, or `workspace` scope modules already own the seam before accepting new event-center infrastructure

## Task Planner

The planner is deterministic and repository-local:

- `scripts/plan-review.mjs` reads `git diff`, optional untracked files, and an optional normalized scope file
- `scripts/build-review-scope.mjs` normalizes agent-produced candidate paths into a stable scope contract
- `references/review-rules.json` declares reviewer tasks, path rules, and regex-style preflight signals
- the script maps changed paths to architecture reviewer tasks
- it adds lightweight preflight signals for suspicious imports, generated-contract drift, possible hardcoded copy, and cross-area seams
- it assigns task risk and spawn recommendations for the main agent
- it emits JSON or Markdown for the main agent to orchestrate
- it never starts sub-agents itself

Useful options:

```bash
pnpm review:architecture
pnpm review:architecture:package
pnpm review:architecture:test
node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs --format markdown
node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs --format summary
node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs --base origin/main
node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs --staged
node ./.codex/skills/tutti-architecture-review/scripts/plan-review.mjs --no-un