Specification: portfolio-portal-orchestrator

Status: SPEC ONLY — not implemented. This document specifies a future skill. No automation exists yet. Until it does, the portal is maintained by hand using the same templates and conventions this skill will target, so the eventual implementation is a drop-in.

1. Purpose

Automate maintenance of the Portfolio Architecture Portal by scanning multiple source repositories and keeping the portal’s system-of-systems layer accurate: repo digests, the unified registry, venture/system maps, architecture diagrams, dependency tracking, duplication detection, llms.txt, and staged content for the public showcase.

It operationalizes the three-layer principle: it reads repo-level docs, updates the portfolio portal, and prepares inputs for the public showcase — without blurring the layers.

2. Scope

In scope (eventual capabilities)

1. Scan multiple repos — take a list/globs of repo paths or URLs and enumerate them.
2. Read key sources per repo — CLAUDE.md, README, docs/**, ADRs, manifest/lock files, and a bounded selection of source files (entry points, config, interface definitions).
3. Produce repo digests — emit/update portal/repos/<slug>.md from the repo-digest template, writing only inside <!-- GENERATED --> regions.
4. Update the unified repo registry — reconcile portal/registry/repo-registry.md rows with the set of digests (add, update, flag-removed).
5. Update venture/system maps — refresh member-repo tables in venture digests and the venture map diagram.
6. Generate Mermaid architecture diagrams — system context, container/service, venture, and cross-repo dependency graphs, with stable node IDs = slugs.
7. Detect changed dependencies — diff each repo’s dependency set against the last recorded set; surface additions, removals, and version changes.
8. Identify duplicated capabilities — cluster the Capabilities lists across repos and flag overlaps for consolidation review.
9. Update llms.txt — regenerate the machine-readable index from the registry.
10. Prepare showcase content — stage curated facts (scale metrics, featured ventures, simplified diagram) into showcase/content/ for the Phase C build. It stages content; it does not build the website.

Out of scope

• Building or deploying the public website (that is Phase C tooling: landing-page-generator etc.).
• Editing source repositories (read-only against them).
• Overwriting <!-- HUMAN --> regions or any hand-authored prose.
• Inventing facts — unknowns are written as Unknown/TBD.

3. Inputs

4. Outputs

• Updated files under portal/ (repos/, ventures/, registry/, architecture/, current-state/), llms.txt, and staged showcase/content/.
• A run report: what changed, dependency deltas, duplication flags, and any Unknowns that need a human.
• Changelog entries appended to portal/current-state/changelog.md.

5. Contracts & invariants (must hold after every run)

• Registry ⇄ digests are 1:1 (no orphans, no duplicates).
• Every diagram node ID resolves to a real digest slug.
• Every venture lists only repos that have digests, and each such repo names its venture.
• <!-- GENERATED --> regions are the only regions written; <!-- HUMAN --> regions are preserved byte-for-byte.
• Slugs are stable across runs; a rename requires a superseding ADR, not a silent change.
• No fabricated facts; Unknown/TBD where data is missing.
• plan mode writes nothing; apply mode leaves the portal internally consistent or aborts.

6. High-level flow

graph TD
    IN[repos + portal_root] --> SCAN[Scan repos]
    SCAN --> READ[Read CLAUDE.md / README / docs / ADRs / manifests / selected source]
    READ --> DIG:::proc
    DIG[Build/refresh repo digests] --> REG[Reconcile registry]
    READ --> DEP[Diff dependencies]
    DIG --> DUP[Cluster capabilities → duplication flags]
    REG --> VEN[Update venture maps]
    VEN --> DIAG[Generate Mermaid diagrams]
    DEP --> REPORT
    DUP --> REPORT
    DIAG --> LLMS[Update llms.txt]
    LLMS --> SHOW[Stage showcase content]
    SHOW --> REPORT[Run report + changelog]
    classDef proc fill:#eee;

7. Capability duplication detection (approach sketch)

• Normalize each repo’s Capabilities entries (lowercase, canonical synonyms).
• Group identical/near-identical capabilities across repos.
• Emit a flag when ≥2 repos claim the same capability, with a suggested owner and a link to both digests. Surface in the run report and the status dashboard’s “duplicated capabilities” count.

8. Dependency-change detection (approach sketch)

• Parse manifests/locks (npm, Python, Go, Rust, etc. — reuse senior-architect / dependency-auditor capabilities where possible).
• Store the last-seen dependency set inside each digest’s <!-- GENERATED --> dependency table.
• On each run, diff and report added/removed/changed; never edit the source repo.

9. Reuse of existing skills

The orchestrator’s novelty is multi-repo aggregation + a unified registry + cross-repo diagrams + duplication detection — the gaps identified in the skills audit that no single existing skill covers.

10. Non-goals / risks

• Not a CI system — it is an on-demand skill; scheduling is external.
• Read budget matters — reading “selected source files” must stay bounded to avoid cost blowups; prefer manifests, entry points, and interface files over whole trees.
• Human-in-the-loop — duplication flags and Unknowns are surfaced for a human, not auto-resolved.

11. Acceptance criteria (for when it is built)

• Running in plan mode against a set of repos produces a correct change report and writes nothing.
• Running in apply mode leaves all invariants in §5 satisfied.
• Re-running with no repo changes is a no-op (idempotent).
• <!-- HUMAN --> content is never modified.

See README.md in this folder for status. Implementation is Phase D on the roadmap.