--- name: architecture-review-full description: '[Architecture] Use when auditing the ENTIRE project architecture and production readiness in one pass — bundles architecture-review + architecture-scalability-review + production-readiness-review at project or diff scope, then synthesizes one consolidated Architecture Health Report.' --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends. > **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason. > **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions. ## Quick Summary **Goal:** Audit the WHOLE project's architecture, scalability posture, and production readiness in ONE pass by orchestrating the three deliberately-non-overlapping sibling reviewers, then de-duplicating their intentional cross-references into ONE consolidated Architecture Health Report — this skill is a THIN orchestrator, it does NOT re-implement any of the three reviews. **Summary:** - **Purpose:** resolve scope once, fan three reviewers out as parallel read-only sub-agents behind an all-return barrier, PROGRESSIVELY synthesize + dedup each child's findings into ONE report file (status `IN PROGRESS` → `FINISHED`), run a `$why-review` fix gate that walks each review face, then finalize the combined verdict. Read-only until findings are validated — fixes route to a downstream `$plan` or feature flow. - **The three children — deliberately non-overlapping siblings that cross-reference each other, so their findings MUST be deduped:** - `architecture-scalability-review` (subagent `architect`) — project-grading scorecard `/20` + pass/fail gates. ALWAYS grades the project, even under diff scope (project-grader by design, "not the every-change diff reviewer"). - `architecture-review` (subagent `architect`) — diff/scope-scoped 13-category PASS/WARN/BLOCKED compliance. Its Category 11 delegates full scalability/coupling grading to `architecture-scalability-review`. - `production-readiness-review` (subagent `code-reviewer`) — service/API SRE `/24` + 8-item Extended SRE Readiness gate. `architecture-scalability-review` routes runtime readiness here. - **This skill runs INLINE** in the main session because it spawns sub-agents; the three children are each 25k–34k tokens and CANNOT run inline together — they MUST be sub-agents. - **Dedup is the core value.** Because the three siblings intentionally cross-reference each other, the same underlying issue surfaces from multiple angles; record it ONCE citing every source, preserve each child's route-to-sibling pointers. — why: undeduped, three intentionally-cross-referencing reviewers inflate severity counts and bury distinct issues. - **Coverage sweep + self-audit are orchestrator-only duties (Step 4).** After `Faces merged: 3/3`, sweep the merged report against the design-review script (`architecture-knowledge.md` §20.2) and record every unanswered question as an INFO `Coverage gap` line; frame remaining risk against the five judgments (§20.4); then run the 11 thinking red flags (§20.3) across the merged findings before Step 5. — why: three correctly-in-lane reviewers cannot see a question that belongs to no lane, and synthesis is where their confirmation biases compound. **Workflow:** 1. **Step 1: Resolve Scope** — `$ARGUMENTS` or ask the user directly; map the chosen scope to each child's args. 2. **Step 2: Load Project Reference Docs Once** — warm shared context before fan-out. 3. **Step 3: Parallel Fan-Out (all-return barrier)** — spawn all three read-only sub-agents in ONE message; advance only after ALL three return. 4. **Step 4: Progressive Synthesis (IN PROGRESS)** — open the ONE consolidated report at status `🚧 IN PROGRESS` when fan-out starts; merge + dedup each child's findings into it AS that child returns — never held in memory to the end; then run the §20.2 coverage sweep and the §20.3 self-audit over the merged set. 5. **Step 5: Fix-Report-Per-Review `$why-review` Gate** — ONE merged `$why-review` pass that walks each of the three review faces + the dedup and fixes the report in place (severities, false positives, dedup-dropped issues). 6. **Step 6: Finalize (FINISHED)** — lock the combined verdict (worst-case rollup) and flip the report status to `✅ FINISHED`. 7. **Next Steps** — ask the user directly: `$plan` (fix validated findings) / `$code-simplifier` / skip. **Key Rules (top 3 critical first):** - MUST ATTENTION this is a THIN orchestrator — NEVER re-implement any of the three reviews inline; fan them out as sub-agents and synthesize. - MUST ATTENTION dedup the intentional overlaps — one underlying issue = one finding citing every reporting child; NEVER let cross-referencing siblings triple-count it. - MUST ATTENTION read-only until validated — run the Step 5 `$why-review` gate before handoff; fixes route to a downstream `$plan`/feature flow, NEVER applied here. - Spawn all three sub-agents in ONE message and honor the all-return barrier — advance only after every child returns (`SYNC:parallel-phase-advancement` discipline). - Write the consolidated report to `plans/reports/architecture-full-review-{YYMMDD}-{HHmm}-{slug}.md`. ## Your Mission $ARGUMENTS ## Review Mindset (NON-NEGOTIABLE) Skeptical synthesizer. Judge the three children's reports; do not re-derive them. - Trust each child's `file:line` evidence, but NEVER inflate severity by counting the same underlying issue three times — dedup first, then rank. - A finding survives to the report only after the Step 5 `$why-review` gate; an unvalidated sub-agent claim is a hypothesis, not a finding. - Preserve every route-to-sibling pointer a child emits — the combined report is the union of owned findings, not a re-review. ## Step 1: Resolve Scope (ASK EACH RUN) Decide audit scope, then map to each child's arguments. - If `$ARGUMENTS` names files/dirs, or contains `full` / `whole` / `diff` / `changes`, use that directly. - Else ask the user directly: - **"Whole project (Recommended)"** — audit the entire repository. - **"Current changes (diff)"** — audit the uncommitted diff only. - **"Specific path"** — audit a named service/module/directory. **Scope → child args mapping:** | Chosen scope | `architecture-scalability-review` | `architecture-review` | `production-readiness-review` | | ---------------------- | ------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- | | Whole project | `mode=audit` over the whole repo | scope override `full codebase` | args = all backend service/API roots (per `project-structure-reference.md`) | | Current changes (diff) | `mode=audit` focused on the services/modules the diff touches | default uncommitted diff | default uncommitted service/API diff | | Specific path | `mode=audit` scoped to that path's services/modules | scope override = that path | that path's service/API files | > **MUST ATTENTION — `architecture-scalability-review` always grades the PROJECT, even under diff scope.** A project-grader by design ("do not use as the every-change diff reviewer"). Under diff scope it still emits the `/20` scorecard, focused on the services/modules the diff touches — it never degrades into a pure per-line diff reviewer. Document this nuance in the consolidated report so its scorecard is read as a project posture, not a diff verdict. ## Step 2: Load Project Reference Docs Once Warm shared context BEFORE fan-out so synthesis reasons from the same ground truth the children use. Read once here (each child re-reads what it needs via its own tool calls): - `docs/project-config.json` - `docs/project-reference/project-structure-reference.md` - `docs/project-reference/backend-patterns-reference.md` - `docs/project-reference/frontend-patterns-reference.md` - `docs/project-reference/code-review-rules.md` - Accepted ADRs under `docs/adr/**`, when present ## Step 3: Parallel Fan-Out (ALL-RETURN BARRIER) Spawn ALL THREE sub-agents in ONE message. Read-only and independent — no shared mutable state, no ordering dependency. Advance ONLY after EVERY member returns (`SYNC:parallel-phase-advancement`). Each sub-agent writes its FULL report to `plans/reports/` and returns ONLY the `SYNC:subagent-return-contract` summary (≤10 finding bullets + report path) — NEVER its full report inline. | # | Child skill | `agent_type` | Whole-project args | Diff-scope args | Emits | | --- | --------------------------------- | --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------- | | 1 | `architecture-scalability-review` | `architect` | `mode=audit` over whole repo | `mode=audit` focused on the diff's services/modules (still grades the project) | Scorecard `/20` + pass/fail gates | | 2 | `architecture-review` | `architect` | scope override `full codebase` | default uncommitted diff | 13-category PASS/WARN/BLOCKED | | 3 | `production-readiness-review` | `code-reviewer` | all backend service/API roots (per `project-structure-reference.md`) | default uncommitted service/API diff | SRE `/24` + 8-item gate | Each sub-agent prompt states: READ-ONLY findings/score mode (no fixes); re-read all target files from scratch via its own tool calls; write full report incrementally to `plans/reports/`; return only the return-contract summary. **Each of the three faces feeds TWO validation gates downstream — state this in each sub-agent's prompt so it knows its findings will be adversarially validated, not trusted as-is:** (1) the Step 5 fix-report-per-review `$why-review` gate that walks its face and fixes its findings in the consolidated report; (2) inside `workflow-architecture-audit`, the workflow-level FINAL `$why-review` gate that re-reviews the whole finalized report. A face's findings are hypotheses until they survive both — so every finding it emits MUST carry `file:line` proof + confidence that can withstand validation. ## Step 4: Progressive Synthesis → One Report (status `IN PROGRESS`) Exactly ONE report file for the whole audit — created ONCE, grown across Steps 4→6, never re-created per review. Open it when fan-out starts and evolve its status through its lifecycle: `🚧 IN PROGRESS` (Step 4) → `🔍 VALIDATING` (Step 5) → `✅ FINISHED` (Step 6). Write to `plans/reports/architecture-full-review-{YYMMDD}-{HHmm}-{slug}.md`. **On fan-out start — create the file with status `🚧 IN PROGRESS`** and a status line naming which of the three review faces have returned so far (e.g. `Faces merged: 0/3`). The single source of truth the whole audit synthesizes into — do NOT hold findings in memory until the end. **Header — all three sub-scores + ONE combined verdict** (each sub-score is `⏳ pending` until its face returns): - Scalability Scorecard: `X/20` + verdict (STRONG / NEEDS WORK / HIGH RISK) - Architecture Compliance: PASS / WARN / BLOCKED - SRE Readiness: `X/24` + verdict (PASS / NEEDS WORK / NOT READY) - **Combined Verdict:** `⏳ pending until FINISHED` — computed in Step 6 as the worst-case rollup across the three (any BLOCKED / NOT READY / HIGH RISK dominates). Do NOT assert a combined verdict while status is `IN PROGRESS`. **Merge each face AS it returns.** All three run behind the Step 3 all-return barrier, so all three summaries are in hand before synthesis — but merge them into the file one face at a time (updating `Faces merged: N/3` each time) so a mid-synthesis context loss leaves the partial report on disk, not in memory. When ≥2 children report the same underlying issue, record it ONCE, citing every source. Dedup on these KNOWN overlap axes (the siblings cross-reference each other here by design): | Overlap axis | `architecture-review` face | Sibling face(s) | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Module isolation / loose coupling / horizontal scaling / DRY regression | Category 11 (scalability & coupling regression) | `architecture-scalability-review` {module isolation, loose coupling, horizontal scaling, DRY} | | Quality tooling / CI / observability | Category 0 (quality-tooling baseline) | `architecture-scalability-review` {Build & CI, Observability} | | Recorded-decision / clean-architecture conformance | Category 9 (ADR conformance) | `architecture-scalability-review` {clean architecture} | | DB performance / capacity ceilings | `production-readiness-review` DB-perf + capacity gate | `architecture-scalability-review` {horizontal scaling} | | Technique applicability (advisory) — scale-tier technique matrix | Category 11 INFO advisory matrix | `architecture-scalability-review` + `production-readiness-review` advisory matrices | | Scenario stress (advisory) — big-traffic/big-data/failure/self-heal | Category 11 INFO scenario-stress matrix | `architecture-scalability-review` + `production-readiness-review` scenario-stress matrices | | Data / consistency / tenancy — dual write, idempotency, breaking migration, tenant isolation | Category 12 (data, consistency & tenancy boundaries) | `production-readiness-review` {migration safety, rollback}; `security-review` owns authz depth; `performance-review` owns query-plan depth | For each merged finding: assign ONE severity per `SYNC:severity-rubric` (do not sum severities across duplicate reports), cite each reporting child's `file:line`, and PRESERVE each child's route-to-sibling pointers. — why: undeduped, three intentionally-cross-referencing reviewers inflate severity counts and bury distinct issues. **Merged advisory Technique Applicability Matrix (does NOT change the combined verdict):** all three children emit a scale-tier Technique Applicability Matrix from `SYNC:scale-technique-gate`; dedup the three views of the same technique onto ONE advisory matrix in the consolidated report. **Pin ONE authoritative scale tier for the merged matrix — `architecture-scalability-review`'s derived tier is canonical (owns scalability grading); if another child's derived tier DIVERGES, record the divergence as a one-line note and key the merged matrix's `tier-warranted?` column to the pinned tier, rather than merging contradictory warranted-sets.** This only SELECTS which already-derived tier the matrix is keyed to — it does NOT re-derive any child's findings (respecting "you do not re-derive them" above). It is **advisory/INFO only** — a `MISSING-WARRANTED` technique is guidance, never a se