Codex compatibility note:
- Invoke
$skill-name: load the registered.agents/skills/<name>/SKILL.mdand execute it with Codex tools; no separateSkilltool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author.claude/**; mirrors are generated.- Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
- Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
- 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_agentsubagent(s) for that task.- Preserve protocol order unless the user approves a deviation. Workflows use
$start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.
Workflow Calls and Todo Bootstrap
Read the registry → workflows.workflow-architecture-audit together with this skill. Call $start-workflow workflow-architecture-audit to resolve the selected mode, pre-actions and fingerprint.
Todo FIRST: before triage, analysis or step execution, create one todo per phase of the selected mode, in order, listing every occurrence of that phase as a line, including conditional/optional ones (a mode that declares no phases gets one todo per occurrence); preserve occurrence IDs, roles and barrier groups. Use native todo tools or an equivalent persistent ledger. Then mark the first todo in_progress; close each step line with its run or skip evidence, and complete a phase todo only when every line is closed and its applicable exit gates hold.
Mode selection and registry loading prepare tracking; any 'first action' below means the first substantive action after this bootstrap.
Call each step skill: start its linked SKILL.md through the active host's skill call with the registry args. When the host refuses that call (a user-only skill) or has no skill call, read the SKILL.md in full yourself (every line, with no line limit; in parts only when output is cut off) and follow it with the same args; that is the same execution, not a bypass. Naming a skill alone is not execution. After a context compaction, re-read the SKILL.md of the step in progress before continuing: compaction can drop or truncate a loaded skill. Required gates and core/optional flex follow the linked start-workflow Step Execution Protocol; keep this skill's quality gates, loops and evidence requirements.
Conditions: load each occurrence's registry applicability.when and skipReason verbatim, and record its run/skip evidence through the linked start-workflow protocol. Do not silently omit a todo or turn a conditional skill into an unconditional call; close, in one batch at triage, the todos whose condition is already false there. Declared parallel groups retain their all-return barrier.
Explicit step-skill calls by mode (registry order; roles and conditions remain owned by the registry):
- Mode
default:$investigate(optional; conditional) →$architecture --mode=full --defer=validate(gate) →$why-review(gate) →$docs-manager --mode=update(optional; conditional) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (1) → Review (3; exit review-converged) → Close (2; exit run-closed)
Regenerate this block with node .claude/scripts/lib/workflow-skill-contract.cjs --write after registry edits; $sync-codex refreshes it before mirroring.
Quick Summary
Goal: Audit architecture, scalability and production readiness without changing code; deliver ONE validated Architecture Health Report with follow-up owners.
Summary: Triage scope/size/risk → map scope when needed → run the three-face architecture --mode=full --defer=validate engine inline → validate its FINISHED report once with $why-review, face by face → update contradictory docs when applicable → close with the handoff. Retain three sub-scores, the worst-case combined verdict and merged advisory Technique Applicability and Scenario Stress matrices.
Use when: project/path architecture health, production readiness or scalability/coupling audit. Adjacent requests: single-change compliance → $architecture --mode=review; standalone consolidated report without run closure → $architecture --mode=full; change-set review → workflow-review-changes.
IMPORTANT MANDATORY Steps: $investigate -> $architecture --mode=full --defer=validate -> $why-review -> $docs-manager --mode=update -> $workflow-end -> $watzup
Workflow: The parsed chain above follows $start-workflow → Step Execution Protocol — gate steps always run, a step that runs is started through the host's skill call, or read in full and followed when the host refuses that call, and every other deviation is logged. NEVER batch-complete validation gates.
Key Rules: Keep source/config read-only, validate findings with evidence, and route fixes to follow-up owners. Advisory matrices never change scores, verdicts or gates.
Activate with $start-workflow workflow-architecture-audit, passing the user's prompt as context.
Contents
- Workflow Calls and Todo Bootstrap
- Quick Summary
- Scope & Size Triage (first action)
- Required Quality Gates
- Recommended Skills
- Orchestration
- Memory & Reporting
- Findings & Fix Path
- Closing Reminders
Scope & Size Triage (first action)
Record target scope, size and risk at the top of the workflow report before choosing depth. Escalate on risk and ambiguity; size bands guide depth.
| Axis | Values | Effect |
|---|---|---|
| Scope | whole project · current diff · specific path · greenfield foundation (mode=init) |
Passed to architecture --mode=full scope resolution; ask only when the prompt names none. |
| Size (files in scope) | XS 1–3 · S ≤15 · M ≤60 · L ≤300 · XL >300 | XS/S with a pinned scope: $investigate has no work to do, keep child briefs narrow. M: defaults. L/XL: $investigate maps modules and hotspots first; the reviewers batch per module (systematic-review-batching), one report per batch. |
| Risk | production-critical path · data integrity · security/PII · multi-service seams | Raise depth: full-scope reviewers, explicit cross-service seam checks, and name specialist follow-ups ($security-audit, $performance-review) in the handoff. |
Required Quality Gates
Before $workflow-end, verify every gate with evidence:
- Consolidated report finished (
review-converged) — Thearchitecture --mode=full --defer=validatereport at statusFINISHED:Faces merged: 3/3, three sub-scores, the worst-case combined verdict, the merged advisory matrices, andValidation: deferred to <occurrence-id>naming the workflow's$why-reviewgate. - Report validated once — The workflow-level
$why-reviewrecord over the FINISHED report: it walks each face's findings (file:lineproof, severity), then scope (nothing in-scope missed, nothing out-of-scope pulled in), verdict rollup, dedup completeness and cross-face severity consistency, and appends its Why-Review Fix Notes or Validation section. When it demotes or restores a finding, the report is fixed in place. - Evidence bar — Every finding carries
file:lineproof and a confidence; findings below 60% are flagged and never recommended. - Read-only — This workflow edits no source or config. Every validated finding names its follow-up owner:
$planfor large or cross-module fixes, a feature or refactor workflow otherwise. - Advisory stays advisory — The technique and scenario matrices and any coverage gaps never change a sub-score, the combined verdict, or a gate.
- Docs truthful (when applicable) — When the audit finds project docs contradicting the code,
$docs-manager --mode=updateran and its non-trivial doc diff received its own$why-review. - Run closed (
run-closed) —$workflow-endran last.
Recommended Skills
$investigate(optional) — The prompt does not pin the audit scope to an explicit path or the current diff, or the scope is medium or larger (more than about 15 files) so modules, boundaries and hotspots must be mapped before the reviewers fan out. Skip reason: The prompt pins a small audit scope to an explicit path or the current diff, soarchitecture --mode=fullresolves the scope itself without a separate map. · Evidence: Scope map for the engine and for the final scope check.$architecture --mode=full --defer=validate(gate) — Always. · Evidence: Three non-overlapping faces (architecture --mode=scalability,architecture --mode=review,production-readiness-review), progressive dedup synthesis, finalized verdict →review-converged.--defer=validateskips the engine's own Step 5 findings validation and hands it to the next gate (.claude/skills/architecture/references/mode-full.md→--defer=validate).$why-review(gate) — Always, after the report isFINISHED. · Evidence: The run's one findings validation: it walks each face exactly as the engine's Step 5 describes, then validates the report level, so the merged findings are validated once, never twice.$docs-manager --mode=update(optional) — The validated audit found project documentation (reference docs, project config, README, ADR status) that contradicts the audited code. Skip reason: The validated audit found no project documentation contradicting the audited code, and a read-only audit leaves no diff for docs-manager --mode=update to sync. · Evidence: Docs truthful.$workflow-end(gate) — Always, last. · Evidence:run-closed.$watzup(optional) — The user asked for a session report or an HTML wrap-up, or the session spanned several workflows or prompts that need one consolidated handoff. Skip reason: workflow-end printed the recap, or the short handoff when nothing was built, and every applicable outcome gate passed. · Evidence: Session report. Without it, the verdict, sub-scores and follow-up owner per finding live in theFINISHEDreport, and$workflow-endprints the short handoff.
Orchestration
Choose inline vs sub-agent, batching and ordering for equal quality at lower time/token cost. Registry stepMeta defaults: $investigate and $docs-manager --mode=update delegated; engine and $why-review inline.
Fixed constraints:
- Run
architecture --mode=fullINLINE: it owns the three-reviewer fan-out and all-return barrier; a sub-agent cannot fan out further. No workflow-level parallel groups. $why-reviewruns only on theFINISHEDreport.$docs-manager --mode=updateruns after$why-review.$workflow-endruns last.
Recommended: XS/S → inline $investigate or engine scope resolution; L/XL → provide a module partition for bounded reviewer batches.
Memory & Reporting
- Create one phase task per phase, one row per selected step. The engine pre-expands its own phases under the parent row.
- Create the workflow report FIRST at
tmp/reports/workflow-architecture-audit-{YYMMDD}-{HHmm}-{slug}.md: triage, per-step evidence, deviations, and the path of the engine's consolidated report (tmp/reports/architecture-full-review-{date}-{slug}.md). Append after each step. - Sub-agent briefs make report writing their first deliverable and return only the
subagent-return-contractenvelope. - After compaction, re-read the current task list, the workflow report, and the consolidated report's status line before continuing.
Findings & Fix Path
- Repair the report only, through the workflow-level
$why-reviewthat validates it (the engine defers its own validation to that gate). Source fixes belong to follow-up workflows. - Validate findings through
$why-reviewwith evidence. Hand off each with owner, severity and confidence:$planfor large, cross-module or ambiguous fixes; feature/refactor workflow for bounded fixes. - Loop bounds for the report-level
$why-review: round 1 exits on zero open findings; from round 2 the bar is zero CRITICAL/HIGH/MEDIUM, with LOWs deferred and listed; cap 3 review rounds; escalate viaask user question toolwhen a round makes no progress.
Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.
incremental-persistence— Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.mdreview-decision-autonomy— Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.mdsession-goal-ledger— Keep the original goal and every user prompt of the session; running a long or multi-prompt session → .claude/skills/shared/protocols/session-goal-ledger.mdsubagent-return-contract— Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.mdworkflow-registry-binding— Read the workflow registry entry and the workflow skill together, since they must agree; executing or editing a workflow → .claude/skills/shared/protocols/workflow-registry-binding.md
- MANDATORY Session goal ledger per the
Task Planning Rules: pinOriginal goal:, keepUser prompts this session: P1…Pn, and map the result to every prompt before claiming done; full text:.claude/skills/shared/protocols/session-goal-ledger.md.
MUST ATTENTION Decide supported review choices and recommendations, record the rationale, and finish without routine user questions. Keep round-limit extension, indispensable facts and actual action authority; preserve source coverage, validation, tests, read-only boundaries and budgets. Review decisions do not accept open risks or make a failed gate pass.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Audit architecture, scalability and production readiness without changing code; deliver ONE validated Architecture Health Report with follow-up owners.
MUST ATTENTION Main steps: triage → map scope when needed → inline architecture --mode=full --defer=validate → one $why-review validation of the FINISHED report → $docs-manager --mode=update for contradictory docs → $workflow-end with its handoff → $watzup only when a session report is wanted. Verify all gates before closure.
- MUST ATTENTION triage scope, size and risk FIRST and record them. Depth follows the triage: a small pinned scope does not need a separate
$investigatemap, and L/XL targets batch per module. - MUST ATTENTION run
architecture --mode=fullINLINE (it owns the fan-out and the all-return barrier), then the$why-reviewgate over theFINISHEDreport. Every finding carriesfile:lineproof and a confidence. - NEVER apply source fixes in this workflow. Route each validated finding to
$planor a feature/refactor workflow; the advisory matrices never move a score or the verdict. - MUST ATTENTION write the workflow report first, append per step, and re-read it with the current task list after compaction.
$workflow-endruns last.
| Evasion | Required action |
|---|---|
| "Engine PASS is enough" | Validate the FINISHED report at workflow level, including zero-open-finding PASS. |
| "Fix it during the audit" | Repair reports only; route source fixes to follow-up owners. |
Protocols in force (digest; the guide entries above point to the full text): Nested Task Creation · Incremental Persistence · Sub-Agent Return Contract · Session Goal Ledger · Workflow Registry Binding.