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:

   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:

   pnpm review:architecture:package

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

   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:

   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