Portfolio Architecture Audit

Audit a project portfolio

Evaluate the portfolio as a system of systems. A locally reasonable design may still create global duplication, coupling, ownership ambiguity, or operational cost.

Load the contract

Read these files completely:

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

Load .architecture-portfolio/portfolio.yaml, shared-capabilities.yaml, technology-catalog.yaml, and dependency-map.yaml. The registry defines scope. Do not silently discover unrelated repositories. If the registry is missing, stop and ask the user to initialize or identify the intended projects.

Initialize a portfolio

When the user requests setup, run:

python3 ../../resources/scripts/architecture_tool.py init-portfolio \
  --root <portfolio-root> \
  --name "<portfolio name>" \
  --owner "<owner>"

Populate the explicit project registry and catalogs, then run validate-portfolio. Initialization creates an empty registry; never add repositories that the user did not place in scope.

Workflow

1. Resolve every registered repository, profile, commit, owner, lifecycle state, and declared dependency. Record inaccessible projects.
2. For each accessible registered repository, run inspect-repository and select-knowledge --skill portfolio-architecture-audit against that repository's Profile with a compact --context-output. Persist facts, selection locks, and context indexes inside the registered project only when the user authorized project writes; otherwise use a temporary directory and record hashes in the portfolio evidence. Do not derive one project's stack from another project's files.
3. Run validate-knowledge-context for each context index with its exact --selection, --facts, and --profile paths. Read each compact context index only after validation succeeds and read its selected Markdown entries, union them by canonical ID, and retain every per-project inclusion reason. Keep exclusions in the machine lock rather than model context. Do not load the whole knowledge tree.
4. Normalize a portfolio inventory:
   • business and platform capabilities;
   • identity, permissions, notifications, scheduling, AI gateways, MCP/Skill/Agent runtimes, design systems, configuration, telemetry, and deployment;
   • databases, caches, queues, object stores, external providers, domains, and environments;
   • APIs, events, shared schemas, data owners, and cross-project flows.
5. Produce a technology matrix and dependency/data-flow maps.
6. Compare implementations by semantics, lifecycle, reliability, privacy, and ownership—not name or technology alone.
7. Identify:
   • repeated capability with a credible consolidation case;
   • intentional duplication that preserves autonomy;
   • shared infrastructure with unclear ownership or blast radius;
   • stack diversity without a justified quality requirement;
   • a project that is becoming a module of another;
   • changes in one project that can silently break another.
8. Require candidate evidence from every affected project. One repository's assumption is not evidence about another.
9. Classify recommendations only as questions or governance opportunities in the audit; use the remediation planner for actual consolidation plans.

For a large portfolio, use up to four read-only specialists when available, partitioned by capabilities, data/integration, runtime/infrastructure, and governance. Keep synthesis and verification in the main agent.

Output

Write under .architecture-portfolio/reviews/:

• <timestamp>-portfolio-candidates.yaml;

Start machine-readable output from ../../resources/templates/portfolio-review.yaml; replace every example value.

The verification handoff must include:

• portfolio architecture diagram;
• project and technology matrix;
• shared-capability and duplication inventory;
• infrastructure dependency and cross-project data-flow maps;
• candidate coupling and ownership risks;
• boundaries that should remain independent;
• open governance questions and a horizon-based roadmap outline.

Keep the roadmap descriptive; do not turn unverified consolidation ideas into committed plans.

Leave every finding at verification.status: candidate, validate YAML with architecture_tool.py validate-review, and use $architecture-finding-verifier for confirmed conclusions and the final report. Do not modify project repositories.

Portfolio Review 1.1 remains the compatibility contract for the aggregate artifact; each registered repository's facts and knowledge selections are individually hash-bound as evidence. Never claim the aggregate artifact has Review 1.2 project-profile bindings.