Project Architecture Audit

Audit one project

Diagnose the current architecture against the project's own profile and constraints. Identify strengths as well as risks. Do not confirm your own candidates, change production code, or recommend fixes. Use architecture-finding-verifier for confirmation and architecture-remediation-planner only after findings are confirmed.

Choose the persistence level

Treat an explicit request to run this Skill as a persistent audit. If .architecture/ is absent, initialize it before auditing; absence is a bootstrap condition, never a reason to downgrade the audit. Reuse and validate an existing control plane without overwriting it.

Operate in Advisory mode only when the user explicitly requests read-only work, forbids repository changes, or the checkout cannot be written. In Advisory mode, write no repository artifacts, do not run a Gate, and label conclusions as observations or candidates in the response. State the write constraint; do not cite a missing .architecture/ directory as the reason.

Context execution and progressive disclosure

Use model context in this order, and do not advance a later stage merely because its files are available:

1. Stable operational kernel — this Skill's workflow, the validated artifact invariants below, and the smallest relevant contract sections.
2. Project-stable context — the prepared Profile, constraints, critical flows, and repository-local policy.
3. Run-specific context — the current repository facts, Profile snapshot, selected lock metadata, and its validated compact context sidecar. Retain the full Knowledge Selection lock as an artifact; expose only its hash and the selected bindings unless a validation or ambiguity requires more.
4. On-demand source evidence — source, configuration, tests, history, and full Knowledge Markdown only when a candidate-driving claim, ambiguity, volatile fact, or explicit trade-off requires it.

The compact context sidecar is a validated projection, not a new source of truth. Keep the full Selection, facts, Profile, and source hashes in the run artifacts even when they are not loaded into model context. If execution telemetry is recorded, bind it to the stage and artifact hashes, but never use telemetry as Review or Gate evidence.

Load the contract

Use these files as the contract source of truth:

• ../../resources/references/review-contract.md
• ../../resources/references/knowledge-contract.md
• ../../resources/references/project-rules.md
• ../../resources/rules/project-core.yaml

Load .architecture/profile.yaml, .architecture/constraints.md, and .architecture/critical-flows.md after preparation. Treat them as declared intent, not proof. In explicit Advisory mode, infer a provisional profile in memory and do not initialize.

Initialize a project profile

For every persistent audit, read ../../resources/references/profile-guide.md, then run:

python3 ../../resources/scripts/architecture_tool.py prepare-project-audit \
  --repo <repo>

The command atomically creates a facts-derived .architecture/ control plane when missing. When it already exists, the command validates and reuses it. It never overwrites an existing or partial directory. After first initialization, replace provisional owner, constraint, and critical-flow values when repository evidence supports them; preserve unknowns explicitly and validate:

python3 ../../resources/scripts/architecture_tool.py validate-project <repo>

Use init-project directly only when the user supplies explicit initialization values:

python3 ../../resources/scripts/architecture_tool.py init-project \
  --repo <repo> \
  --name "<project name>" \
  --type <project-type> \
  --quality <critical-quality> \
  --review project-architecture

Add repeated flags for additional types, qualities, rule packs, owners, and required reviews. The command refuses to overwrite an existing .architecture directory.

Workflow

1. Inspect facts and select knowledge

Set one stable <run-id> for the audit. Run the deterministic fact collector before interpreting architecture and preserve a per-run input instead of rewriting a prior evidence chain:

python3 ../../resources/scripts/architecture_tool.py inspect-repository \
  --repo <repo> \
  --output <repo>/.architecture/reviews/inputs/<run-id>-repository-facts.yaml

Build a current Profile from those facts while retaining the initialized Profile as declared intent. Keep detected, declared, and inferred inputs separate:

python3 ../../resources/scripts/architecture_tool.py build-profile \
  --facts <repo>/.architecture/reviews/inputs/<run-id>-repository-facts.yaml \
  --declared <repo>/.architecture/profile.yaml \
  --output <repo>/.architecture/reviews/inputs/<run-id>-profile.yaml

Select only task-relevant Markdown knowledge and persist the reasons and exclusions:

python3 ../../resources/scripts/architecture_tool.py select-knowledge \
  --facts <repo>/.architecture/reviews/inputs/<run-id>-repository-facts.yaml \
  --profile <repo>/.architecture/reviews/inputs/<run-id>-profile.yaml \
  --task "<current audit request>" \
  --skill project-architecture-audit \
  --output <repo>/.architecture/reviews/inputs/<run-id>-knowledge-selection.yaml \
  --context-output <repo>/.architecture/reviews/inputs/<run-id>-knowledge-context.yaml

Before reading model context, validate the sidecar against the exact lock:

python3 ../../resources/scripts/architecture_tool.py validate-knowledge-context \
  <repo>/.architecture/reviews/inputs/<run-id>-knowledge-context.yaml \
  --selection <repo>/.architecture/reviews/inputs/<run-id>-knowledge-selection.yaml \
  --facts <repo>/.architecture/reviews/inputs/<run-id>-repository-facts.yaml \
  --profile <repo>/.architecture/reviews/inputs/<run-id>-profile.yaml

Read knowledge-context.yaml only after validation succeeds. Treat its selected array as the compact Knowledge projection and do not load selected Markdown entries by default. Do not load the full knowledge-selection.yaml exclusion ledger into model context; that lock is for scripts, Reviews, and Gates. Open a selected Markdown path only after checking its recorded SHA-256, and only when the source is needed for a candidate-driving claim, an ambiguity, a volatile fact, or a detailed trade-off. Read that full source entry when the claim depends on it. Do not load the full knowledge tree. Treat repository facts as observations, never as risk conclusions.

2. Establish scope and provenance

• Resolve the repository root, requested paths, current commit, dirty-tree state, and active guidance.
• Inventory only source-of-truth inputs relevant to architecture: product and architecture documents, source, migrations, schemas, API or event definitions, deployment configuration, tests, and CI.
• Record missing or inaccessible evidence as not_assessed; never turn absence of inspection into a pass.
• Redact secrets and personal data from excerpts.

For a repeat audit on a clean, committed tree, use a prior verified Review only to plan investigation. Generate a deterministic plan from the Git diff and the project's Gate policy:

python3 ../../resources/scripts/architecture_tool.py plan-review-execution \
  --project <repo> \
  --review <repo>/.architecture/reviews/<prior-verified-review>.yaml \
  --base-commit <prior-reviewed-commit> \
  --scope .

The command derives changed paths and critical, security, public-contract, and migration impact; callers do not declare those results. Treat prior coverage as context only and explicitly reassess every listed rule and critical flow. If the tree is dirty, ancestry or hashes do not close, or scope exclusions remain, fall back to the full audit path. The diff-aware Gate independently rejects any changed path outside the selected Review's scope_manifest; the informational plan cannot be bypassed to turn an excluded path into a pass.

3. Build an architecture evidence map

Map:

• modules and domain boundaries;
• inbound and outbound dependencies;
• data stores, owners, writers, and migration paths;
• synchronous APIs, asynchronous events, background jobs, and critical flows;
• authentication, authorization, trust boundaries, and sensitive data;
• deployment units, configuration sources, telemetry, and test seams.

Trace every declared critical flow end to end. Prefer ownership and runtime paths over directory names.

4. Assess the rule set

Assess every machine rule in each Profile rule_packs entry and use project-rules.md as investigation guidance. Load additional specialist audits named by required_reviews; do not silently substitute a generic rule for an AI, mobile, privacy, threat-model, or data-specific review. Load repository-local Rule Packs from .architecture/rules/ when selected by the Profile. Treat them as project policy, validate their schema and review kind, and never allow them to shadow bundled IDs.

For a large or cross-boundary repository, use up to four read-only specialists when subagent tools are available: boundaries, integration/data, runtime/reliability, and security/quality. Keep scopes non-overlapping and retain synthesis and verification in the main agent. If delegation is unavailable, run the same passes sequentially.

5. Form candidate findings

For each candidate:

• name the violated or protected invariant;
• cite the current path, line or symbol, and a concrete observation;
• trace the affected flow and owning boundary;
• state impact, blast radius, confidence, and counter-evidence;
• distinguish repository fact, inference, and unknown;
• record the E1–E5 evidence level, evidence fingerprint, Rule Pack version, profile applicability, selected knowledge, and staleness state;
• use a stable finding ID.

Do not infer an architecture flaw from file size, import count, a singleton, SQLite, a framework choice, or a directory name. Metrics are investigation leads only.

6. Prepare the verification handoff

Before handing candidates to the verifier:

• ensure every candidate records repository identity, direct evidence path, Git commit, blob SHA when available, and the inspected commit;
• state the strongest known benign explanation as counter-evidence;
• remove claims that do not meet the candidate evidence threshold;
• keep category, provisional severity, confidence, scope, and possible duplicates explicit;
• leave verification.status as candidate.

Do not promote a candidate to a final risk. When the user requested a complete or verified review, continue with $architecture-finding-verifier after persisting the candidate artifact.

7. Persist and validate

For every non-Advisory audit, write:

• candidate review: .architecture/reviews/<timestamp>-project-candidates.yaml;

Start machine-readable output from ../../resources/templates/review.yaml; replace every example value and remove unused example entries.

Validate each YAML review:

python3 ../../resources/scripts/architecture_tool.py validate-review \
  <review.yaml> --project <repo>

python3 ../../resources/scripts/architecture_tool.py validate-coverage \
  --project <repo> --review <review.yaml> --allow-candidates

Resolve the script path from this Skill's directory when invoking it from another repository. Use Review schema 1.2 for new audits. Bind the exact repository-facts and knowledge-selection files and hashes; enumerate every critical flow and Rule Pack rule. A candidate may say not_assessed with a reason, but must never silently omit coverage.

Handoff requirements

Lead with the architecture shape and clearly label all findings as candidates. Include:

• current architecture and key boundaries;
• candidate strengths worth checking;
• candidate risks ordered by provisional severity;
• affected critical flows and ownership;
• coverage by rule, including not_applicable and not_assessed;
• hotspots and unanswered evidence questions;
• commit, scope, inspected artifacts, raw candidate count, and limitations.

Do not include remediation options in this audit.