Architecture Review — Recommendations

Observations from processing repositories, recorded as recommendations only — no architecture is changed here. Each entry is dated and sourced. Promote significant ones to ADRs when acted on.

From: shared-skills (2026-07-05)

Reusable capabilities identified

Capability	Where	Reuse opportunity
Architecture diagram + dependency generation	`senior-architect` scripts	Core engine for the future orchestrator’s diagram/dependency features
Multi-language dependency & license audit	`dependency-auditor`	Orchestrator “detect changed dependencies” feature
`llms.txt` generation	`create-llms` / `update-llms`	Keep the portal’s machine index in sync automatically
Doc/orphan/dead-link hygiene	`knowledge-ops`	Recurring portal consistency checks
Repo summarization	`codebase-onboarding`	First pass at each new repo digest
Design tokens / brand onboarding	`design-system`, `ui-design-system`	Phase C showcase consistency

Recommendation: the portfolio-portal-orchestrator should be assembled primarily by composing these existing skills rather than re-implementing their logic.

Missing documentation (in the source repo)

No repo-level README.md or CLAUDE.md for the skills library itself.
No internal skills index / taxonomy — discoverability depends entirely on per-skill descriptions.
No LICENSE aggregation despite skills carrying MIT/Apache-2.0 individually.
Recommendation: if the library is promoted to a first-class repo, add root docs + a generated taxonomy file. (Recorded, not actioned.)

Opportunities to simplify architecture

Consolidate near-duplicate skills to reduce trigger-routing ambiguity (see duplication below).
Introduce a cluster/taxonomy layer so the 169 skills are navigable as ~10 groups.
Recommendation: a lightweight INDEX.md/registry inside the skills repo (the orchestrator could generate it) would materially improve maintainability.

Dependencies that should be surfaced visually

portfolio-portal → shared-skills (realized) — now drawn in the System Dependency Map.
portfolio-portal-orchestrator → {shared-skills, portfolio-portal} (planned) — drawn dashed.
Recommendation: as layers 2–6 gain repos, each new upstream/downstream edge must be added to the dependency map in the same change (per update conventions).

Duplicated capabilities that may belong elsewhere

Overlap	Skills	Note
RevOps	`revops` ⟷ `revenue-operations`	Likely merge candidates
DB design	`database-designer` ⟷ `database-schema-designer`	Overlapping ERD/schema scope
Senior engineering	`senior-backend/frontend/fullstack` + `senior-architect`	Shared surface; clarify boundaries
Competitor analysis	`competitors`, `competitor-profiling`, `competitive-teardown`, `competitive-intel`	Four skills, adjacent intent
LLMs index	`create-llms` ⟷ `update-llms`	Complementary, but could be one skill with modes

Recommendation: treat consolidation as an internal-tooling roadmap item; do not merge blindly — some overlaps are intentional (different altitudes/audiences). Validate before acting.

From: Website Assessment capability (2026-07-05)

Recorded during Phase C (see the Capability Reuse Map for the full analysis):

Duplicate opportunity scoring. intelproducts pack scoring (website quality 0–100) and leadplatform’s own “Opportunity Intelligence” scoring use different dimensions. Recommend: have leadplatform consume the assessment/COP instead of maintaining a parallel score, to avoid two disagreeing “opportunity” numbers.
Recommendation logic spans three layers (engine rules → pack recommendation-library → COP action). Recommend: treat the pack as the single source of truth and pin versions across engine + COP.
Pack drift via vendoring. Consumers vendor intelproducts as pinned submodules; stale pins score against old intelligence. Recommend: track pinned pack versions in the registry.
Inference-derived scoring weights (not empirical). Recommend: prioritise the Hermes learning loop to replace review-gated defaults with outcome-derived weights.
Strong reuse win (keep doing): the engine is domain-agnostic + pack-driven — new verticals/ventures are new packs, not new code (cleaning, travel/Inbound Lanka proven). Use as the template for future capabilities.

How to use this page: add a dated ## From: <repo> section each time a repository is processed. When a recommendation is accepted and acted on, capture it as an ADR and link it here.