Portfolio Portal

CLAUDE.md — How to maintain the Portfolio Architecture Portal

This file tells Claude (and any AI agent or human) how to work inside this repository. Read it fully before creating or editing anything.

1. What this repo is

A markdown-first portal that documents Azwaan’s AI venture ecosystem as a system of systems. It is documentation and structure — not application code. There is no build step in Phase A. Everything is human-readable markdown plus Mermaid diagrams that render on GitHub.

Keep these three layers distinct at all times:

  • Repo-level docs live in the individual repos, not here. This portal only holds digests of them.
  • Portfolio portal (portal/) explains how repos and ventures combine.
  • Public showcase (showcase/) is a later target; do not build the website yet.

2. Golden rules

  1. Markdown-first. Prefer .md with embedded fenced ```mermaid diagrams over binary or HTML artifacts. GitHub must be able to render every page.
  2. Templates are canonical. Never invent a new page shape. Copy the matching file from templates/ and fill it in. If a template is missing, add the template first.
  3. One digest per repo, one digest per venture. Digests are summaries — link back to the source repo for detail; do not duplicate full repo docs here.
  4. The registry is the index of record. Every repo digest MUST have a matching row in portal/registry/repo-registry.md. No orphan digests.
  5. Decisions get ADRs. Any structural or cross-repo decision is recorded in portal/decisions/ using the ADR template. ADRs are append-only and immutable once Accepted — supersede, never rewrite.
  6. Keep current-state current. When something changes, update portal/current-state/ (status dashboard + changelog) in the same change.
  7. Placeholders are explicit. Mark unfinished content with > **TODO:** or <!-- PLACEHOLDER --> so gaps are visible and greppable. Never leave silent blanks.
  8. Do not fabricate. If a repo’s stack, status, or dependency is unknown, write Unknown / TBD, not a guess. This portal is a factual map.

3. Where things go

You want to… Do this
Add a repo Copy templates/repo-digest.template.md → portal/repos/<slug>.md; add registry row
Add a venture/system Copy templates/venture-digest.template.md → portal/ventures/<slug>.md
Add/replace a diagram Edit the relevant page in portal/architecture/ (embedded Mermaid)
Record a decision Copy templates/adr.template.md → portal/decisions/NNNN-title.md
Log a change Add an entry to portal/current-state/changelog.md
Add a generic page Copy templates/page.template.md
Update the AI index Edit llms.txt (keep it in sync with the registry)

4. File & naming conventions

  • Slugs: lowercase, hyphenated, stable. A repo’s digest filename = its slug (e.g. repos/auth-service.md).
  • ADRs: NNNN-kebab-title.md, zero-padded 4-digit sequence, never reused.
  • Frontmatter: every portal content page starts with the YAML block defined in its template (title, type, status, last_reviewed, owner). Keep last_reviewed accurate (YYYY-MM-DD).
  • Diagrams: Mermaid, embedded in fenced blocks. Keep node IDs stable so diffs stay small.

5. Update conventions (summary)

Full detail in docs/update-conventions.md. In short:

  • Editing a repo digest → bump last_reviewed, sync the registry row, add a changelog line.
  • New cross-repo relationship → update the architecture diagrams + note in the changelog.
  • New decision → ADR + changelog line.
  • Every change should leave the portal internally consistent (no dangling links, no orphan pages).

6. Working with the future orchestrator

A skill named portfolio-portal-orchestrator is specified (not yet built) in skills/portfolio-portal-orchestrator/SPEC.md. When it exists it will generate many of these pages automatically from source repos. Until then, maintain pages by hand using the same templates the skill will target — so the eventual automation is a drop-in, not a rewrite. Do not hand-author anything the spec marks as machine-generated in a way that would conflict with regeneration; keep generated and hand-written sections clearly separated (see the <!-- GENERATED --> / <!-- HUMAN --> markers in templates).

7. Diátaxis, IA & Principles

Portal content follows the Diátaxis model (see docs/documentation-model.md) and the information architecture in docs/information-architecture.md. Respect the page-type of whatever you edit — don’t turn a reference page into a tutorial.

Systems and documentation are governed by the ecosystem-wide Architecture Principles (10 principles, e.g. reproducibility & provenance, knowledge referenced never owned, honest realization labelling). Cite them in digests/ADRs; a change that violates one needs an ADR justifying the exception.

8. Definition of done for any change

  • [ ] Used the correct template / respected page frontmatter
  • [ ] Registry and digests are consistent (no orphans, no dangling links)
  • [ ] Diagrams still render and reflect reality
  • [ ] current-state + changelog updated
  • [ ] Any decision captured as an ADR
  • [ ] last_reviewed dates bumped where touched