Portfolio Portal
About living owner: Azwaan reviewed: 2026-07-05

Update Conventions

Recipes for keeping the portal accurate and internally consistent. These conventions are the contract that both human maintainers and the future portfolio-portal-orchestrator skill follow.

Cadence

Trigger Update
A repo is created / renamed / archived Repo digest + registry row + affected venture(s) + changelog
A repo’s stack or purpose changes materially Its digest (last_reviewed) + registry row + changelog
A new cross-repo relationship or dependency Architecture diagrams + both digests + changelog
A structural/portal decision New ADR + changelog + any affected page backlinks
A duplicated capability is noticed across repos Note on both digests + a duplication flag + possible ADR
Roadmap shifts current-state/roadmap.md + changelog
Monthly review Re-verify last_reviewed dates; sweep for orphans & dead links

Recipe: add a repo

  1. Copy templates/repo-digest.template.md → portal/repos/<slug>.md.
  2. Fill in every field; use Unknown/TBD where you don’t yet know — do not guess.
  3. Add a row to portal/registry/repo-registry.md.
  4. Link the repo from its venture digest (create the venture first if needed).
  5. If it introduces a new cross-repo edge, update the diagrams in portal/architecture/system-of-systems.md.
  6. Add a changelog line and update the status dashboard counts.

Recipe: add a venture / system

  1. Copy templates/venture-digest.template.md → portal/ventures/<slug>.md.
  2. List member repos (each must have a digest + registry row).
  3. Add or update the Venture map diagram in the architecture page.
  4. Changelog line.

Recipe: record a decision

  1. Copy templates/adr.template.md → portal/decisions/NNNN-kebab-title.md (next free zero-padded number).
  2. Set status: proposed → move to accepted when decided. Never edit an accepted ADR’s decision; supersede it with a new ADR and set the old one to superseded.
  3. Backlink from every page the decision affects; forward-link from those pages to the ADR.
  4. Changelog line.

Recipe: update a diagram

  1. Edit the embedded Mermaid block in the relevant portal/architecture/ page.
  2. Keep node IDs stable (rename labels, not IDs) so diffs stay readable.
  3. Ensure every node maps to a real digest and every digest that participates is drawn.
  4. Changelog line if the topology changed.

Consistency invariants (must always hold)

  • Every repo digest ⇄ exactly one registry row (no orphans, no duplicates).
  • Every venture ⇄ its member repos are mutually linked.
  • Every architecture node ⇄ a real digest.
  • No dead internal links; no silent blanks (use explicit placeholders).
  • last_reviewed on any page you touched is today’s date.

Generated vs human-authored regions

The orchestrator will eventually own regions wrapped in <!-- GENERATED --> markers and must preserve <!-- HUMAN --> regions verbatim. Until the skill exists, humans may edit both, but should keep hand-written prose inside <!-- HUMAN --> so it survives the first automated run.

Definition of done

See the checklist at the end of CLAUDE.md.