Dev Context Multi Repo

Multi-Repo Context

Use this skill to inventory, normalize, and publish one coherent knowledge hub for many repositories. The strongest default is a two-layer system: raw source captures plus an LLM-maintained compiled markdown hub with profiles, concept pages, backlinks, and derived reports. It owns repo discovery, high-signal extraction, cross-repo inference, artifact-set generation, and knowledge-graph assembly. It does not replace single-repo context or code-graph work.

Quick Reference

When to Use

• Build a master context repo or docs hub for many services or repositories.
• Produce one normalized profile per repo instead of ad hoc summaries.
• Generate consistent repo descriptions from structured JSON profiles and graph edges instead of freehand summaries.
• Classify complex orchestration repos such as agent runtimes, remote bridges, terminal-first CLIs, plugin hosts, and worktree coordinators without collapsing them into unknown.
• Map stacks, interfaces, dependencies, owners, and integration edges across a portfolio.
• Generate hub artifacts for onboarding, migration planning, architecture review, or RAG.
• Retrofit a knowledge graph onto an existing coordination hub.
• Operate a raw/ evidence layer plus a compiled markdown wiki for a repo portfolio.
• Maintain or refresh a large repo portfolio, including 100+ repo hubs where incremental compilation matters more than one-shot summarization.

Recreate a Requirements-Hub

A ready-to-copy blank hub ships at assets/hub-scaffold/. It is the same shape this skill produces — hot layer (AGENTS.md, rules/), compiled layer (context/), and one example domain folder — with zero organization-specific content.

cp -r assets/hub-scaffold ~/repos/requirements-hub

Then follow assets/hub-scaffold/context/scripts/README.md for the end-to-end command sequence: discover_repos.py → scan_portfolio.py → build_knowledge_graph.py → query_graph.py --rank → validate_graph.py, then build/validate the hub's own context graph with the reused dev-context-engineering scripts. The scaffold's rules/ stubs point at the clearly-labelled generic templates in dev-context-engineering/assets/ — swap each regime reference for your own regulatory context.

Route Elsewhere

• Single-repo context layers and rollout across tools: use dev-context-engineering.
• Symbol or file graph inside one repo: use dev-context-code-graph.
• Spec writing or decision docs: use docs-ai-prd.
• Documentation freshness audits: use qa-docs-coverage.
• Parallel discovery across many repos with explicit delegation: use agents-swarm-orchestration.

Defaults

• Structured metadata first, narrative second.
• One canonical profile per repo.
• Raw ingest first, compiled wiki second.
• Treat repo knowledge as the system of record and keep root agent files as maps, not encyclopedias.
• Use just-in-time loading by default: store stable identifiers, paths, graph node IDs, and report links, then load the relevant artifact at task time.
• High-signal file reads before deep reads.
• Separate raw evidence, normalized metadata, and human summaries.
• Prefer markdown-native index pages, summaries, and backlinks before adding heavier retrieval layers.
• Let the LLM maintain the compiled hub; humans review, prune, and correct drift instead of hand-editing every page.
• File durable answers, diagrams, and reports back into the hub so portfolio queries compound over time.
• Treat hidden differentiators as first-class extraction targets: transport model, control plane, permission bridge, session lifecycle, worktree model, plugin lifecycle, and recovery policy are often more important than language or package metadata.
• Mark claims as verified, subset-verified, inferred, or unverified when coverage is incomplete.
• Keep generated artifacts under one artifact root instead of scattering them through docs.
• Do not create free-floating Markdown reports for every portfolio query; route reusable outputs into the hub catalog, reports lifecycle, or generated context artifact set.

May 2026 Stance

The current best default is not "index everything and stuff it into a prompt." Build a small, navigable context system that can select the right evidence at runtime.

• Keep AGENTS.md and sibling runtime files short; they should route agents to the hub, not duplicate the hub.
• Make structured artifacts the compiler inputs: profiles, code graphs, system edges, freshness reports, and evidence refs.
• Make markdown the operator surface: catalog pages, concept notes, architecture maps, and reusable query outputs.
• Use graph traversal when relationship structure changes the answer: dependency paths, ownership, blast radius, shared providers, cross-repo flows, migration seams, or "catch me up on this system" questions.
• Use lexical search, index pages, or direct file reads for simple lookup questions; graph-first retrieval for every query adds latency and noise.
• Use Personalized PageRank when the question is seeded by a repo/domain/process but needs budget-bounded context beyond a 1-2 hop neighborhood.
• Use community detection (--communities) at multiple resolutions when the question is global ("what does the platform look like?") and a single-seed walk would miss the structure. Drop in Leiden via igraph or graspologic when you need stronger connectedness guarantees on portfolios > 1k nodes.
• Calibrate weights when prose, Mermaid, manifests, and schemas all contribute edges; direct multi-source evidence should outrank single-source prose edges.
• Keep symbol-level graphs as per-repo artifacts from dev-context-code-graph; import summaries or links into the hub instead of merging every symbol into the portfolio graph.
• Apply context-hygiene gates before publishing: relevance, provenance, freshness, ACL/sensitivity scope, contradiction risk, and bounded token shape.
• Prefer dynamic pruning of irrelevant graph communities or subgraphs over static "include the whole graph" prompts.

Workflow

1. Inventory candidate repos and classify repo shape. 2. Index raw evidence first: repo roots, architecture docs, API contracts, datasets, screenshots, and other source captures should live in a raw layer instead of being flattened into summaries. 3. Read only high-signal manifests, docs, CI files, schema clues, and instruction artifacts. 4. Normalize evidence into one RepoProfile per repo. 5. If the repo appears to be an orchestration-heavy runtime, deepen the scan around transport, remote/session, approval, worktree, plugin, and recovery files before accepting a generic classification. 6. Infer repo kind, interfaces, dependencies, storage, ownership, and capability families without overclaiming. 7. Generate or refresh one repo description per repo from the normalized profile and relationship edges, with confidence labels derived from evidence coverage. 8. Compile the markdown hub incrementally: repo catalog pages, cross-repo concept notes, backlinks, and index files that help the agent navigate without scanning the whole corpus every time. 9. Rebuild only the changed pages, indexes, and graph edges when possible; do not re-summarize the whole portfolio by default. 10. Materialize the artifact set: profiles, catalog pages, graphs, and reports. 11. Validate graph consistency and freshness, then run hub health checks for stale claims, missing summaries, unindexed reports, and candidate pages worth adding before calling the hub current.

ASCII Flow

multi-repo context request
  -> discover repos and classify portfolio shape
  -> ingest raw evidence without flattening it into prose
  -> scan high-signal files into one RepoProfile per repo
  -> build compiled hub: catalog pages, indexes, backlinks, reports
  -> build graph artifacts: system edges and knowledge graph
  -> query with lexical search, direct reads, graph paths, PPR, or communities
  -> validate coverage, freshness, consistency, and unindexed outputs
  -> publish only durable hub artifacts, not free-floating reports

Core Decisions

Output Model

Default artifact set:

• profiles/<repo>.json
• catalog/<repo>.md
• graphs/system-edges.json
• graphs/knowledge-graph.json
• reports/coverage.md
• reports/drift.json

Do not invent alternate shapes unless there is a downstream consumer that requires a transform layer.

Treat catalog/ and reports/ as the compiled markdown layer by default. Add folders such as concepts/ or research/ only when there is a clear downstream consumer for concept articles or query outputs.

The repo description page should usually be generated from:

• verified fields in profiles/<repo>.json
• relationship edges from graphs/system-edges.json
• a bounded set of direct evidence references

Do not let the description page become an ungrounded prose summary.

For complex repos, the profile should capture capability families rather than only surface metadata. A strong profile often needs fields or derived sections for:

• runtime or deployment mode
• control-plane and transport model
• remote or bridge responsibilities
• session and resume semantics
• permission and approval path
• worktree or parallel-task isolation model
• plugin, hook, or hot-reload lifecycle
• recovery or retry policy

Extraction Strategy

Start from files that reveal repo reality quickly:

• manifests and lockfiles
• CI workflows
• container and infra files
• native/mobile project manifests such as Package.swift, project.yml, .xcodeproj, and .xcworkspace
• schema and migration files
• API contracts
• repo instruction files
• specs and plans

If the hub also stores non-repo evidence, keep those captures in the raw layer and summarize them into the compiled hub rather than treating screenshots, exports, or article clips as first-class catalog pages.

Use deep reads only when the high-signal layer is insufficient to classify the repo or prove an integration.

For orchestration-heavy repos, the high-signal layer must include runtime spine files, not just manifests:

• transport implementations
• remote bridge or client/server session managers
• permission and approval bridge code
• worktree and task orchestration setup
• plugin, hook, and hot-reload loaders
• reconnect, backpressure, batching, and recovery logic

Many of the most important differentiators are invisible in package metadata. If the extractor only sees language, lockfiles, and README text, it will under-classify repos that actually win on runtime design.

Complex Runtime Classification

When a repo contains files or modules for multiple of the following, prefer a complex-runtime classification over unknown:

• remote bridge or remote execution support
• explicit transport abstractions such as SSE, WebSocket, or hybrid read/write transport
• session manager or resume lifecycle
• permission or approval mediation
• task, coordinator, teammate, or worker orchestration
• worktree creation, branch isolation, or tmux/session bootstrapping
• plugin, hook, or lazy-loader infrastructure
• explicit recovery, retry suppression, buffering, or backpressure mechanisms

Typical classifications worth recognizing:

• agent runtime
• coding-agent CLI
• remote execution bridge
• terminal UI host
• plugin platform
• multi-repo coordinator

Verification Scope

Before synthesis:

• separate direct evidence from inferred structure
• avoid portfolio-wide universal claims unless every relevant repo was checked
• verify storage engines from manifests and drivers, not from README prose
• mark partial coverage explicitly in summaries and tables

For generated repo descriptions:

• distinguish what is proven from manifests or workflows vs what is inferred from naming or topology
• prefer concise, structured descriptions over narrative confidence theater
• include unknowns explicitly when a repo cannot be confidently classified

Knowledge Graph

Use the knowledge graph when the hub needs queryable relationships across repos, systems, and artifacts. Keep symbol-level graph work out of this layer; that belongs to single-repo code-graph workflows.

The graph complements the markdown hub; it does not replace it. The best default is graph-backed markdown pages with backlinks, index notes, and concise summaries that an agent can read directly at small and medium corpus sizes.

For complex runtimes, add capability and behavior edges, not just dependency edges. Useful examples:

• uses_transport
• splits_read_write_channels
• supports_resumable_streams
• bridges_permissions
• manages_remote_sessions
• supports_worktree_isolation
• supports_plugin_hot_reload
• serializes_writes
• buffers_stream_events
• has_recovery_policy

Q&A and Derived Outputs

Prefer answers as files, not terminal-only output:

• markdown reports for architecture questions or migration maps
• Mermaid or other diagrams for relationship views
• slide or image outputs when a viewer exists and the question is presentation-heavy

If an answer will likely be useful again, file it back into the hub and link it from the relevant repo or concept page.

Before adding the file, run the hub placement test:

• does this belong in an existing repo catalog, concept page, or report?
• will it be linked from the hub index or related repo page?
• is it generated from structured inputs, and if so is the rebuild command known?
• does it have a lifecycle state if it is a point-in-time analysis?

If not, keep it in the task thread or update an existing hub page.

Operating at 100+ Repos

At large portfolio scale, optimize for maintenance loops, not heroic one-off scans:

• keep a registry of repos and last-refresh state
• compile incrementally instead of rebuilding every page on every run
• maintain short index pages that help the LLM find the right repo or concept quickly
• prefer JSON + markdown + graph artifacts that can be diffed, linted, and repaired
• add lightweight CLIs for search, freshness checks, and targeted rebuilds before reaching for heavier retrieval systems

Hub Layout

Prefer a coordination repo with:

• root entry files
• domain folders at the root
• generated hub infrastructure under context/ or docs/context/
• optional raw/ capture areas for evidence the LLM compiles into the hub

Keep the root navigation-focused. Do not paste inventories into AGENTS.md.

For native/mobile repos, the default scanner should classify from high-signal project files before falling back to generic language heuristics. Swift/Xcode repos should resolve cleanly as app repos when project.yml, .xcodeproj, or .xcworkspace evidence is present, and scans should ignore generated build trees such as .build, DerivedData, Pods, and SourcePackages.

Output Modes

Default to one of these:

• Portfolio inventory:

repo registry, classifications, and scan coverage.

• Context hub:

profiles, catalog pages, relationship edges, and knowledge graph.

• Compiled wiki:

raw evidence registry, markdown indexes, concept notes, backlinks, and reusable query outputs.

• Repo description set:

one grounded page per repo compiled from profile JSON, graph edges, and verified evidence.

• Capability map:

per-repo runtime capabilities, differentiators, and operational behaviors derived from source evidence rather than README-level summaries.

• Migration map:

active vs legacy systems, integration edges, and transition hotspots.

• Freshness report:

drift, stale documents, and re-verification queue.

Known Traps

• Accepting a generic repo classification too early and missing the operational behavior that actually distinguishes orchestrators, bridges, or control planes.
• Reading README-heavy repos as if they were authoritative when manifests, workflows, and runtime scripts say something else.
• Rebuilding the full hub on every scan instead of compiling incrementally from the repos that actually changed.
• Letting inferred cross-repo edges harden into "facts" before they are traced back to manifests, schemas, or concrete integration evidence.
• Using portfolio summaries as the source of truth while raw evidence and normalized profiles quietly drift underneath them.
• Treating a longer model context window as permission to load the whole hub; large irrelevant context still causes distraction and context rot.
• Applying GraphRAG or graph traversal to every question even when a direct catalog lookup, lexical search, or bounded file read is more accurate.
• Letting generated markdown and generated JSON drift independently instead of regenerating prose from the structured profile and graph contracts.
• Re-ingesting LLM-generated summaries as fresh evidence without keeping the original source and timestamp.

Anti-Patterns

• Treating one repo summary as a portfolio model.
• Claiming complete coverage without a verified scan registry.
• Mixing raw evidence, normalized data, and commentary in the same file.
• Verifying storage or runtime claims from docs instead of manifests.
• Leaving useful portfolio answers in chat output instead of filing them back into the hub.
• Pasting portfolio inventories into root agent-memory files.
• Forcing symbol-level code graphs into the portfolio knowledge graph.
• Reaching for heavy RAG before maintaining index pages, concise summaries, and backlinks.
• Rebuilding 130 repo descriptions from scratch when only a subset changed.
• Writing repo descriptions directly from chat impressions instead of profile JSON and graph edges.
• Letting complex repos remain unknown because the scanner only looked at manifests and README text.
• Modeling only dependency edges and missing operational edges such as permission bridges, session control planes, resumable streams, or worktree isolation.
• Using a vector database, GraphRAG stack, or MCP server as a substitute for repo-owned profiles, evidence refs, and freshness checks.
• Publishing "complete codebase context" claims without parse coverage, scan date, excluded paths, and unsupported-language notes.
• Mixing public docs, private code evidence, secrets, and customer data in one context layer without sensitivity labels and access boundaries.

Navigation

• Core references: references/repo-discovery-patterns.md, references/repo-classification-rules.md, references/architecture-inference-rules.md, references/integration-signal-detection.md, references/confidence-scoring.md
• Hub and graph operations: references/output-model-and-gap-analysis.md, references/knowledge-graph-patterns.md, references/hub-design-patterns.md, references/hub-operations-playbook.md, references/hub-freshness-checking.md, references/large-portfolio-strategy.md
• references/network-science-applied.md — Centrality, PageRank, community detection, contagion applied to multi-repo knowledge graphs and portfolio topology.
• Assets: assets/hub-scaffold/ (copy-paste blank hub — see "Recreate a Requirements-Hub"), assets/coordination-repo-layout-template.md, assets/repo-catalog-page-template.md, assets/architecture-map-template.md, assets/integration-matrix-template.md, assets/freshness-report-template.md, assets/legacy-transition-map-template.md, assets/hub-agents-template.md
• Scripts and schemas: scripts/discover_repos.py, scripts/scan_repo.py, scripts/scan_portfolio.py, scripts/build_artifact_set.py, scripts/build_hub_views.py, scripts/build_knowledge_graph.py, scripts/query_graph.py, scripts/validate_profiles.py, scripts/validate_graph.py, scripts/check_graph_consistency.py, scripts/report_drift.py, scripts/check_hub_freshness.sh, schemas/repo-profile.schema.json, schemas/knowledge-graph.schema.json, schemas/system-edge.schema.json

Fact-Checking

• Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
• External source mapping lives in data/sources.json.
• Portfolio summaries must distinguish verified facts from inferred edges.
• If a claim cannot be traced to a manifest, schema, workflow, or other direct evidence, label it accordingly instead of hardening it into a fact.

Architecture Map Template

Domains

• Domain:

Repos: Responsibilities:

Core Flows

• Flow:

Source: Target: Notes:

Shared Platforms

• Datastores:
• Messaging:
• Identity:
• Observability:

Catalog Page Template — Compiled Truth + Timeline

Source: Adapted from garrytan/gbrain at commit adb02b7826a010700efc968b18df8aaf17d8ffa1. License: MIT. Extracted 2026-04-13.

Canonical shape for catalog/<repo>.md pages (and, by extension, any compiled-layer page that synthesizes durable facts about a single entity). Every page has exactly two zones separated by a horizontal rule (---):

• Above the line — Compiled Truth: current synthesis. Rewritten whenever new evidence changes the state of play. Read the top, know the state in 30 seconds.
• Below the line — Timeline: append-only evidence log. Every fact in the Compiled Truth section traces back to an entry here. Entries are never rewritten — only new entries are appended.

When to Use This Template

• Catalog pages in a portfolio hub (catalog/<repo>.md)
• Concept notes that synthesize across multiple repos (concepts/<topic>.md)
• Architecture decision records that need both a current-state summary and an audit trail
• Any page where the question "what is true now?" and the question "how did we get here?" have different answers

Template (Repo Catalog Page)

---
type: repo_catalog
repo_id: payments-ledger
title: payments-ledger — Payments Ledger Service
tags: [payments, postgres, kafka, dotnet]
last_compiled: 2026-04-13
last_verified: 2026-04-13
---

## Executive Summary

One paragraph. What this repo does, who owns it, why it exists. If a reader only reads this, they should know whether to keep reading.

## State

- **Runtime**: .NET 9, deployed as a Kubernetes service
- **Storage**: PostgreSQL 16 (primary), Redis (cache)
- **Messaging**: Kafka producer + consumer for `payments.*` topics
- **Owner**: Payments Platform team
- **Status**: Active

## Capabilities

- Double-entry ledger with immutable journal
- Idempotent settlement API
- Event streaming to downstream reconciliation

## Interfaces

- HTTP: `POST /v2/journal/entries`, `GET /v2/accounts/{id}/balance`
- Kafka topics published: `payments.journal.v1`, `payments.settlement.v1`
- Kafka topics consumed: `payments.command.v1`

## Open Threads

Items in flight. Removed from this section when resolved (and the resolution is appended to the Timeline below).

- [ ] Migration from legacy `payments-ledger.v1` endpoints — target Q2
- [ ] Decision pending on partitioning strategy for archive tables

## See Also

- [payments](payments.md) — upstream producer of settlement commands
- [sc.reconciliation](sc.reconciliation.md) — downstream consumer
- [concepts/double-entry-ledger](../concepts/double-entry-ledger.md)

## Evidence Coverage

- Profile: `verified` (scanned 2026-04-13)
- API contract: `verified` (openapi parsed)
- Messaging topology: `subset-verified` (producer confirmed, consumer inference-based)
- Storage: `verified` (from DbContext)

---

## Timeline

- **2026-04-13** — Catalog page regenerated from profile scan. No structural changes; cache layer added to State section. [Source: scripts/build_artifact_set.py, 2026-04-13 09:12 UTC]
- **2026-04-10** — Added Redis cache for account-balance lookups. Resolved open thread "cache layer decision". [Source: PR payments-ledger#412, 2026-04-10 14:30 UTC]
- **2026-03-28** — Upgraded to .NET 9. Runtime field updated above. [Source: Dockerfile diff, payments-ledger@9a3b2c1, 2026-03-28 11:00 UTC]
- **2026-03-15** — Initial profile scan. Repo classified as `service`, language `.NET`, confidence 0.92. [Source: scripts/scan_repo.py, 2026-03-15 08:00 UTC]

Rules of the Template

1. Above-line rewrites, below-line appends. When new evidence arrives, update the Compiled Truth section in place — but never edit or delete a Timeline entry. The Timeline is the audit trail; if an earlier entry turned out to be wrong, add a new entry correcting it rather than modifying the old one. 2. Every Compiled Truth claim has a Timeline citation. If a State field exists above the line but no Timeline entry below the line supports it, the claim is unverified — flag it during freshness checks. 3. Open Threads move, not disappear. When an open thread is resolved, remove it from the Open Threads list and append the resolution to the Timeline with the same day's date. The fact that it existed is preserved in the log. 4. Source format is strict: [Source: <who/what>, <date> <time> <tz>]. Who = script name, PR number, human name, tool output, etc. The format lets you grep for unattributed claims. 5. `last_compiled` vs `last_verified`: last_compiled is when the page was last regenerated from profile data. last_verified is when a human or trusted script last confirmed the Compiled Truth still matches reality. They can differ; use last_verified for freshness-check exit gates.

Why Two Zones

• "What's the current state?" is a one-screen read when the synthesis is pre-computed above the line. No one has to scroll through 200 timeline entries and assemble the answer in their head.
• "How did we get here?" is a full audit trail when the evidence log is below the line and never rewritten.
• "Why do I believe this?" traces from a Compiled Truth claim to its supporting Timeline entries via the source citation.

A single append-only log fails the first question. A single rewriteable summary fails the second and third. The two-zone split is how both questions can be cheap to answer at once.

Generation vs Hand-Editing

The Compiled Truth section can be human-edited, but the sustainable pattern is to generate it from the structured profile JSON plus the Timeline. That way:

• Profile scan updates (language, dependencies, manifests) flow automatically into the State fields above the line.
• Human commentary (Assessment, Why it matters, Strategic notes) is the part humans actually spend time on.
• Freshness checks can compare generated Compiled Truth against the last-known snapshot and flag anything that drifted without a Timeline entry explaining why.

Do not let Compiled Truth become an ungrounded prose summary written from memory. If a claim can't be traced to profile JSON, graph edges, or a Timeline entry, it doesn't belong above the line.

Related

• references/hub-design-patterns.md — Why compiled pages should be generated, not hand-written
• references/hub-operations-playbook.md — How to wire this template into the build pipeline
• references/hub-freshness-checking.md — Drift detection that respects the above-line / below-line split

{{ community_id }} — {{ community_name }}

Generated from query_graph.py --communities --resolution {{ resolution }} on {{ generated_at }}.

Snapshot

• Size: {{ size }} nodes
• Modularity contribution: {{ modularity_contribution }}
• Resolution: γ = {{ resolution }}
• Detection seed: {{ seed }}

Composition

{{ /type_breakdown }}

{{ /domain_breakdown }}

Anchor nodes

The 5–10 most central nodes by weighted PPR within this community.

{{ #anchor_nodes }}- {{ id }} — {{ label }} ({{ type }}); ppr_score = {{ ppr_score }} {{ /anchor_nodes }}

What this community does

One paragraph describing the shared responsibility, integration boundary, or business capability that ties these nodes together. Generate from anchor-node summaries plus the dominant edge relations between members.

Avoid prose that re-lists every member. Reference the member-ids list at the bottom for full enumeration.

Cross-community ties

Edges that leave this community and where they go.

{{ /external_edges }}

Verification status

• Verified: claims grounded in manifests, schemas, or workflow files
• Inferred: claims derived from naming, topology, or graph-edge patterns
• Unverified: claims that need re-checking against source

Members

<details> <summary>Full member list ({{ size }})</summary>

{{ #member_ids }}- {{ id }} {{ /member_ids }}

</details>

Lifecycle

• Generated from: graphs/knowledge-graph.json at version {{ graph_contract_version }}
• Source detection run: reports/community-runs/{{ run_id }}.json
• Refresh trigger: regenerate when graph membership churn exceeds 10% or modularity changes by more than 0.05

Coordination Repo Layout

portfolio-hub/
├── AGENTS.md
├── CLAUDE.md
├── catalog/
├── profiles/
├── graphs/
├── reports/
├── docs/
│   ├── architecture/
│   ├── domains/
│   └── migrations/
├── schemas/
├── scripts/
└── sources/

Design rule:

• generated artifacts live outside the root instruction files
• schemas and scripts are versioned
• architecture docs link to profiles instead of duplicating them

Embedded repo-local variant:

repo/
├── AGENTS.md
├── docs/
│   ├── product/
│   ├── tech/
│   ├── reports/
│   └── context/
│       ├── profiles/
│       ├── catalog/
│       ├── graphs/
│       └── reports/
└── scripts/

Use the embedded layout when the repo already has canonical narrative docs and you need generated context artifacts to stay isolated from those hand-authored files.

Freshness Report Template

Stale Profiles

Low-Confidence Profiles

Hub AGENTS.md Template

Use this template for the master coordination repo, not for source repos.

Purpose

This repo is the canonical context hub for a portfolio of repositories. It stores generated repo profiles, cross-repo architecture views, and refresh workflows.

Canonical Sources

• profiles/ = machine-readable repo truth
• catalog/ = human-readable repo summaries generated from profiles
• graphs/ = system relationships
• reports/ = freshness and coverage

Rules

• Do not hand-edit generated files unless the workflow says they are curated.
• Update schemas and generation scripts before changing output formats.
• Keep root instructions navigation-focused; do not paste large inventories here.
• Prefer evidence-backed summaries over inferred prose.

AGENTS.md — &lt;company&gt; Requirements Hub

This file is the portable, always-on instruction layer for any AI agent operating against this hub. Keep it short. It is a map, not an encyclopedia — it routes to the compiled layer, it does not duplicate it.

What this repo is

A cross-repo knowledge hub. It contains compiled markdown, profiles, and graphs about many source repos. It does not contain their source code. Treat the compiled layer as the system of record for cross-repo facts.

Operating rules

1. Read before answering. For any cross-repo question, start from context/docs/repo-index.md and the relevant <domain>/README.md. Do not infer architecture from repo names. 2. Ground every claim. A statement about a repo must trace to a profile (context/graphs/ / <domain>/as-is/) or a cited source. Mark unverified claims as inferred or unverified. 3. Right tool for the question. Direct file read or lexical search for simple lookups; the knowledge graph (context/scripts/README.md) only when relationship structure changes the answer. 4. File durable answers back. A reusable analysis becomes a catalog page, concept note, or context/reports/ entry — not a chat-only reply. Run the placement test in context/docs/documentation-governance.md first. 5. Do not paste inventories here. Repo lists, dependency dumps, and long tables belong in the compiled layer, never in this file. 6. Respect the rule layer. rules/ constraints (compliance, data handling, AI governance, secrets, resilience) are binding. If a task conflicts with a rule, stop and surface the conflict.

Layout

AGENTS.md            this file (hot layer)
rules/               binding policy stubs
context/docs/        canonical platform docs
context/templates/   page templates the compiler uses
context/scripts/     thin runners + pointers to the pipeline skills
context/graphs/      repos.json, knowledge-graph.json, context-graph.json
context/overview/    generated cross-cutting maps and catalogs
context/reports/     dated, lifecycle-tagged analyses
<domain>/            one folder per domain (as-is / assessment / initiatives)

Runtime layers

AGENTS.md is the portable baseline read by Claude Code, Codex, and Copilot. Add .claude/, .codex/, or .github/ layers only when a tool needs behavior it cannot get from this file.

Replace <company> / <domain> placeholders before use.

Architecture Overview

Template stub. One page that lets a new agent or engineer understand the

whole platform before drilling into a domain. Generated/maintained from

profiles and the knowledge graph — do not hand-write what the compiler

can produce.

Platform in one paragraph

&lt;What the platform does, who it serves, the 3–5 load-bearing systems.&gt;

Domains

&lt;Table of domains → one-line purpose. Keep in sync with domain-map.md.&gt;

Cross-cutting flows

&lt;The 2–4 flows that cross domains (e.g. onboarding, settlement). Link the generated diagrams in context/overview/.&gt;

Tech baseline

&lt;Languages, runtimes, datastores, messaging — derived from repo profiles, not prose.&gt;

How this page is built

Regenerate from context/graphs/knowledge-graph.json + repo profiles. See context/scripts/README.md.

Documentation Governance

Template stub. The placement gate every new markdown file must pass

before it is created. This is what keeps the compiled layer from

rotting into one-off files.

Placement test

Before creating a new markdown file, answer:

1. Does this belong in an existing catalog page, domain doc, or report? 2. Will it be linked from an index or domain README? 3. Is it generated from structured inputs? If so, is the rebuild command recorded in the file? 4. If it is a point-in-time analysis, does it carry a lifecycle state?

If you cannot answer all four, do not create the file — update the closest canonical doc or keep the result in the task thread.

Layer ownership

Lifecycle states for reports

draft → current → superseded. A superseded report links its successor; it is not deleted (the timeline matters).

Domain Map

Template stub. The authoritative mapping of repo → domain. Every

repo in repo-index.md must appear in exactly one domain here.

Domains

&lt;domain&gt;

• Purpose: &lt;one line&gt;
• Repos: &lt;repo-a&gt;, &lt;repo-b&gt;
• Owns: &lt;the data/flows this domain is the system of record for&gt;
• Upstream: &lt;domains/repos it depends on&gt;
• Downstream: &lt;domains/repos that depend on it&gt;
• Folder: <domain>/

&lt;Repeat per domain. A repo that genuinely spans domains belongs to the one that owns its primary data; note the secondary in Upstream/ Downstream.&gt;

Unassigned

&lt;Repos discovered but not yet classified. Empty is the goal.&gt;

Engineering Standards

Template stub. Non-inferable conventions an agent must follow when it

writes code in the portfolio. Keep only what an agent cannot infer from

reading the repo itself.

Conventions (replace)

• &lt;Language/style baseline per stack — or "match the repo's enforced

style". Phrase as outcomes, not tools that may be absent.&gt;

• &lt;Branching / commit / PR conventions.&gt;
• &lt;Test expectation before a change is considered done.&gt;
• &lt;Architecture boundaries that must not be crossed without approval.&gt;

Anti-patterns

• &lt;Known failure modes specific to this portfolio.&gt;

This is hot-layer policy. The detailed rationale belongs in canonical docs or the relevant domain's as-is/, not here.

Onboarding

Template stub. The path a new engineer or agent takes to become

productive against this portfolio. Link, don't duplicate.

Day-one reading order

1. ../../README.md — what the hub is. 2. ../../AGENTS.md — how to operate. 3. architecture-overview.md — the platform in one page. 4. domain-map.md + repo-index.md — who owns what. 5. The <domain>/README.md for your first task's area.

First task checklist (replace)

• [ ] Cloned the relevant source repos next to this hub.
• [ ] Read the domain's as-is/ for the system you will change.
• [ ] Checked blast radius via the knowledge graph.
• [ ] Read rules/ constraints that apply.
• [ ] Know who the named approver is for this change.

Where to ask

&lt;Channel / owner per domain.&gt;

Regulatory Context

Template stub. The regulatory frame the portfolio operates under, so an

agent knows why the rules/ constraints exist. Swap every regime

reference for your own. Illustrative scaffolding, not legal advice.

Applicable regimes (replace)

Important business services

&lt;The flows/repos that, if degraded, cause regulatory or customer harm. Maintained in the relevant <domain>/as-is/. The knowledge graph's blast-radius queries must respect this mapping.&gt;

Source templates

The example regime templates live in dev-context-engineering/assets/ (compliance, data-handling, AI governance). They are labelled examples — replace, do not ship as-is.

Repo Index

Template stub. One line per repo, generated from

context/graphs/repos.json + profiles. This is the agent's fast lookup

— keep it short; the detail lives in the per-repo catalog page.

Coverage

• Repos discovered: &lt;n&gt;
• Profiled: &lt;n&gt;
• Last scan: &lt;date&gt;

Regenerate with the multi-repo scan pipeline — see context/scripts/README.md. Do not hand-edit rows the scanner owns.

context/overview — generated cross-cutting maps

Index of portfolio-wide artifacts the pipeline generates. These are derived: regenerate them, do not hand-edit. Keep this index current as maps are added.

Add a row whenever a new generated map lands. Each artifact must name

its rebuild command in its own header (see

../docs/documentation-governance.md).

.gitkeep keeps this folder under version control while empty.

context/scripts — pipeline runners

This folder holds thin runners. The heavy lifting lives in the three dev-context-* skills. Do not copy the skill scripts here; point at them.

Wiring

Install the three skills (e.g. into .claude/skills/ of this hub, or any path), then set:

export SKILLS=/path/to/skills            # contains dev-context-* folders
export CG="$SKILLS/dev-context-code-graph/scripts"
export MR="$SKILLS/dev-context-multi-repo/scripts"
export CE="$SKILLS/dev-context-engineering/scripts"

Clone the source repos next to this hub, e.g. ~/repos/<repo>, and this hub at ~/repos/requirements-hub.

Recreate the hub — end to end

# 0. from the hub root
cd ~/repos/requirements-hub

# 1. discover repos → context/graphs/repos.json
python3 "$MR/discover_repos.py" ~/repos --out context/graphs/repos.json

# 2. scan each repo into a normalized profile
python3 "$MR/scan_portfolio.py" --repos context/graphs/repos.json \
        --out context/graphs/

# 3. (optional, per repo) single-repo symbol graph for blast radius
python3 "$CG/scan_code_repo.py"  ~/repos/<repo> --out /tmp/<repo>.profile.json
python3 "$CG/build_code_graph.py" /tmp/<repo>.profile.json \
        --out ~/repos/<repo>/graphs/code-graph.json

# 4. build the cross-repo knowledge graph from profiles
python3 "$MR/build_knowledge_graph.py" --profiles context/graphs/ \
        --out context/graphs/knowledge-graph.json

# 5. sanity-query it (ranked central repos)
python3 "$MR/query_graph.py" context/graphs/knowledge-graph.json --rank

# 6. validate the knowledge graph (auto-repair with --fix)
python3 "$MR/validate_graph.py" context/graphs/knowledge-graph.json

# 7. build/validate THIS hub's own context graph (the dev-context-engineering
#    scripts are reused as-is — do not reimplement them here)
python3 "$CE/scan_context_artifacts.py" . \
        --output context/graphs/context-graph.json
python3 "$CE/validate_context_graph.py" context/graphs/context-graph.json --repo .

Expected on a blank hub: validate_context_graph.py flags the root

AGENTS.md as an orphan (one node, no edges) and exits non-zero. That

is correct for an empty skeleton — the scanner is repo-native and only

the hot-layer file exists yet. The orphan clears once you populate the

hub: as catalog pages, profiles, and .claude/rules/ (if you add a

runtime layer) come in and cross-link, edges form. Do not restructure

the hub to silence this on day one.

Then compile catalog pages from the profiles using the templates in ../templates/ and the dev-context-multi-repo workflow. File generated cross-cutting maps into ../overview/ and dated analyses into ../reports/.

Local thin runners

• sync-rules.sh — copy the hub's rules/ into each source repo (or a

per-repo AGENTS.md pointer) so tools pick them up locally.

• audit-agents.sh — find AGENTS.md/CLAUDE.md across the portfolio and

flag missing or stale ones.

• generate-api-catalog.sh — collect API contracts (OpenAPI/proto/etc.)

across repos into a single catalog stub under ../overview/.

All three are generic and safe to edit for your layout.

AGENTS.md (per source-repo template)

Drop a short AGENTS.md like this into each source repo so any tool

(Claude Code, Codex, Copilot) routes back to this hub instead of

re-deriving cross-repo context. Keep it tiny — it is a pointer.

# AGENTS.md — <repo>

This repo belongs to the **<domain>** domain.
Cross-repo context lives in the requirements hub, not here.

- Hub: <relative-or-URL path to requirements-hub>
- This repo's catalog page: <hub>/<domain>/as-is/<repo>.md
- Domain overview: <hub>/<domain>/README.md
- Binding rules: <hub>/rules/

## Local conventions (non-inferable only)
- <commands / boundaries an agent cannot infer from the code>

Do not paste cross-repo inventories here. Update the hub catalog page.

Replace placeholders. The hub is the system of record for anything that spans repos; the per-repo AGENTS.md only carries what is local and non-inferable.

&lt;domain&gt;

Template for a domain folder's README.md. Copy example-domain/ per

real domain, rename, and fill this in.

Purpose

&lt;What this domain is responsible for, in two sentences.&gt;

Repos in this domain

Key flows

&lt;The 1–3 flows this domain owns end-to-end. Link diagrams in as-is/diagrams.md.&gt;

Boundaries

• Owns (system of record): &lt;data/flows&gt;
• Depends on: &lt;upstream domains&gt;
• Consumed by: &lt;downstream domains&gt;

Folder map

• as-is/ — current state: per-repo catalog pages, diagrams,

cross-repo dependencies.

• assessment/ — gap analysis, migration roadmap, proposals.
• initiatives/ — change RFCs (see ../example-domain/README.md for the

lifecycle).

&lt;frontend-repo&gt;

Catalog-page template for a frontend / app repo.

• Domain: &lt;domain&gt;
• Kind: web app | mobile app | desktop app
• Stack: &lt;framework / language / build&gt;
• Status: active | legacy
• Confidence: verified | inferred

What it is

&lt;User-facing surface and primary flows.&gt;

Backends consumed

Build & runtime

&lt;From project manifests (package.json, project.yml, .xcodeproj, Package.swift) — not README prose. Note excluded generated trees.&gt;

Provenance

• Profile: context/graphs/<repo>.json · Last scan: &lt;date&gt;

Integration: &lt;system-a&gt; ↔ &lt;system-b&gt;

Catalog-page template for a cross-repo integration. One edge of the

knowledge graph, written up. Generated from system-edge evidence.

• Type: sync API | async event | shared datastore | batch/ETL
• Direction: &lt;a → b&gt;
• Contract: &lt;OpenAPI / schema / topic name + version&gt;
• Confidence: verified | inferred

What flows

&lt;The data/commands crossing this boundary.&gt;

Evidence

Failure & coupling

&lt;What breaks downstream if the producer changes. Tie to blast-radius query output.&gt;

Provenance

• Edge: context/graphs/system-edges.json
• Rebuild: see context/scripts/README.md

&lt;library-repo&gt;

Catalog-page template for a shared library / package repo.

• Domain: &lt;domain&gt; (often core/infra)
• Kind: library
• Stack: &lt;language / package ecosystem&gt;
• Status: active | legacy
• Confidence: verified | inferred

What it provides

&lt;The capability it factors out. One paragraph.&gt;

Consumers

&lt;Repos that depend on it — from dependency edges, not guesswork. This list drives blast-radius scoring; keep it evidence-backed.&gt;

Change risk

&lt;Why a breaking change here is high blast radius. Tie to graph articulation-point / impact output.&gt;

Provenance

• Profile: context/graphs/<repo>.json · Rebuild: context/scripts/README.md

Merge / Pull Request Description Template

Use for changes made against the source portfolio while working from

this hub. Pairs with the AI-disclosure template in

dev-context-engineering/assets/pr-template-ai-disclosure.md.

Summary

&lt;What changed and why, in two sentences.&gt;

Scope

• Repo(s): &lt;repo&gt;
• Domain: &lt;domain&gt;
• Blast radius checked: yes/no — &lt;graph query + result&gt;

Rule compliance

• [ ] rules/01-compliance.md — &lt;n/a or how satisfied&gt;
• [ ] rules/02-data-handling.md
• [ ] rules/04-security-secrets.md — no secrets committed
• [ ] Named approver (if required): &lt;name&gt;

AI disclosure

&lt;Which parts were agent-generated; reviewer of record. See the disclosure template.&gt;

Hub updates

• [ ] Catalog page updated: <domain>/as-is/<repo>.md
• [ ] Graph/profile regenerated if structure changed

&lt;service-repo&gt;

Catalog-page template for a service repo. Generated from the repo

profile + graph edges. Keep prose minimal; cite evidence.

• Domain: &lt;domain&gt;
• Kind: service
• Stack: &lt;lang / runtime / framework&gt;
• Status: active | legacy | deprecated
• Owner: &lt;team / named owner&gt;
• Confidence: verified | subset-verified | inferred

Responsibility

&lt;What this service owns. One paragraph.&gt;

Interfaces

Dependencies

• Upstream: &lt;repos/services&gt;
• Downstream: &lt;repos/services&gt;
• Datastores: &lt;engines, from manifests not prose&gt;

Operational notes

&lt;Resilience role, known failure modes — only if evidenced.&gt;

Provenance

• Profile: context/graphs/<repo>.json
• Last scan: &lt;date&gt; · Rebuild: see context/scripts/README.md

example-domain

This is the per-domain template. Copy this whole folder once per real

domain (cp -r example-domain payments), rename it, and fill in

README.md from ../context/templates/domain-readme.md.

Purpose

&lt;What this domain owns, in two sentences.&gt; — replace.

Repos in this domain

Folder map

example-domain/
├── README.md       this file
├── as-is/          current state: catalog pages, diagrams, deps
├── assessment/     gap analysis, migration roadmap, proposals
└── initiatives/    change RFCs (lifecycle below)

• `as-is/` — compiled current-state truth. Per-repo catalog pages

(from ../context/templates/), diagrams.md, cross-repo-dependencies.md. Generated from profiles; human-reviewed.

• `assessment/` — gap-analysis.md, migration-roadmap.md,

architecture-proposal.md. Point-in-time; carry a lifecycle state.

• `initiatives/` — one folder per change RFC, numbered:

001-<slug>/, 002-<slug>/.

Initiative lifecycle

Each initiative folder carries a status: in its own README and moves through:

draft → proposed → accepted → in-progress → done → graduated

• draft — being written, not yet circulated.
• proposed — circulated for review/approval.
• accepted — approved, not yet started.
• in-progress — being implemented in the source repos.
• done — shipped; as-is/ updated to reflect new reality.
• graduated — fully absorbed into as-is/; the initiative folder

moves to initiatives/_graduated/ for history.

Create initiatives/_graduated/ when the first initiative graduates. .gitkeep files keep as-is/, assessment/, and initiatives/ under version control while empty.

&lt;company&gt; Requirements Hub

A single, navigable knowledge hub for a portfolio of repositories. This is a blank scaffold: copy it next to your repos, then let the dev-context-* skills populate it from your actual code.

cp -r hub-scaffold ~/repos/requirements-hub

What this is

A coordination repo that holds compiled, agent-maintained knowledge about many source repos — without containing their source. It separates:

• hot layer — AGENTS.md + rules/: short, always-on execution policy.
• compiled layer — context/ and the domain folders: profiles, catalog

pages, graphs, and reviewed markdown the LLM maintains.

• raw layer — optional raw/ capture areas (add when you ingest

non-repo evidence such as exported docs or screenshots).

The hub is the system of record for cross-repo knowledge. Each source repo keeps its own single-repo context.

Reading order

1. AGENTS.md — how agents should operate against this hub. 2. context/docs/architecture-overview.md — the platform in one page. 3. context/docs/domain-map.md — domains and which repos belong to each. 4. context/docs/repo-index.md — every repo, one line, with a catalog link. 5. The relevant <domain>/README.md for the area you are working in.

Quick links

How it gets populated

This scaffold ships empty on purpose. Use the three pipeline skills:

• `dev-context-code-graph` — per-repo symbol/import graph

(graphs/code-graph.json) for one repo at a time.

• `dev-context-multi-repo` — discover repos, scan them into profiles,

build the cross-repo knowledge graph, and compile catalog pages here.

• `dev-context-engineering` — single-repo context layers + the

context-graph.json build/validate for this hub itself.

See context/scripts/README.md for the exact command sequence.

Domain folders

Each domain (e.g. payments/, identity/) follows the same shape:

<domain>/
├── README.md           # what this domain is, repos in it, key flows
├── as-is/              # current-state docs, diagrams, dependencies
├── assessment/         # gap analysis, migration roadmap, proposals
└── initiatives/        # RFC lifecycle: see example-domain/README.md

example-domain/ is a working template — copy it per real domain and rename.

Replace every <company> / <domain> placeholder. Nothing here is

specific to any organization.

Rule 01 — Compliance

Stub. Replace with your own regulatory regime. This points at an

example template; it is illustrative scaffolding, not compliance advice.

Binding compliance constraints for any agent changing code or docs in the portfolio. Keep this short and non-inferable — the why and the full checklist live in the referenced template.

Source template

Start from the generic, clearly-labelled example: dev-context-engineering/assets/compliance-fca-emi.md (swap the FCA/EMI regime references for yours: e.g. PSD2, MiCA, SOC 2, HIPAA, PCI DSS, or your sector regulator).

What goes here (replace)

• The 3–6 hard rules an agent must never violate (e.g. "no change to

&lt;regulated-flow&gt; without a named human approver").

• The gate that blocks merge — see dev-context-engineering/assets/fca-compliance-gate.yml.
• Where the evidence/audit trail is recorded.

If a task conflicts with a rule here, stop and surface the conflict.

Rule 02 — Data Handling

Stub. Replace with your own data-protection regime. Illustrative

scaffolding, not legal advice.

Constraints on how agents handle personal, payment, or otherwise sensitive data when reading repos or writing into this hub.

Source template

dev-context-engineering/assets/data-handling-gdpr-pci.md (swap GDPR/PCI DSS for your applicable regime: CCPA, LGPD, HIPAA, etc.).

What goes here (replace)

• Never paste secrets, tokens, PII, or cardholder data into hub markdown,

profiles, graphs, or reports.

• Classification labels the compiled layer must carry

(public / internal / restricted).

• Redaction expectation for raw evidence captured into raw/.
• Data-residency or retention constraints that affect what can be stored.

Rule 03 — AI Governance

Stub. Replace with your own AI-use policy. Illustrative scaffolding.

How AI agents are allowed to operate against this hub and the source portfolio: autonomy boundaries, disclosure, and human accountability.

Source template

dev-context-engineering/assets/ai-agent-governance.md and the disclosure template dev-context-engineering/assets/pr-template-ai-disclosure.md.

What goes here (replace)

• Which actions an agent may take unattended vs. which require a named

human approver.

• AI-contribution disclosure expectation on every change (link the PR

template).

• Model/provider portability constraint (no lock-in to one vendor format).
• Who owns the outcome of agent-generated changes (named accountability).

Rule 04 — Security & Secrets

Stub. Replace with your own security policy. Illustrative scaffolding.

Non-negotiable security constraints for agents touching the portfolio or this hub.

What goes here (replace)

• Never commit secrets, credentials, tokens, private keys, or connection

strings — into source repos or into hub markdown/profiles/graphs.

• Never reproduce a discovered secret into a report or chat answer; record

only its location and that it must be rotated.

• Treat scan output that includes secrets as restricted; redact before it

enters the compiled layer.

• Where to report a discovered exposure (named owner / channel).

Pair with rules/02-data-handling.md for the data-classification labels the compiled layer must carry.

Rule 05 — Operational Resilience

Stub. Replace with your own resilience/continuity regime (e.g.

DORA, SS1/23, or your internal standard). Illustrative scaffolding.

Constraints that keep agent activity from degrading the operational resilience picture this hub is supposed to describe accurately.

Source template

See the resilience portions of dev-context-engineering/assets/compliance-fca-emi.md and your own important-business-services (IBS) register.

What goes here (replace)

• Which repos/flows map to important business services — and that the

mapping in <domain>/as-is/ must stay current.

• Change-impact expectation: cross-repo blast radius must be checked

(via the knowledge graph) before claiming a change is low-risk.

• Freshness obligation: stale resilience claims must be flagged, not

silently trusted (context/scripts/README.md → freshness checks).

NNN — Initiative Title

One-line description of what this initiative improves and why.

>

Date: YYYY-MM-DD · Status: Draft · Target: YYYY-QN

<!-- last_verified: YYYY-MM-DD -->

---

Problem

<!-- 1-3 sentences: what's broken, risky, or inefficient -->

Proposal

<!-- What we plan to do — keep it concise -->

Scope

<!-- Checklist of concrete deliverables -->

• [ ] Deliverable 1
• [ ] Deliverable 2
• [ ] Deliverable 3

Documents

<!-- Add rows as needed — not all are required for every initiative -->

Decision Log

Graduation Criteria

<!-- When is this initiative done? What must be true before graduating to as-is? -->

1. All scope checkboxes complete 2. New architecture documented in as-is/ 3. Old components decommissioned or migration path documented 4. Initiative folder moved to _graduated/

Integration Matrix Template

Legacy Transition Map

Use this template to map legacy components to target services and sequence the cutover work. Adjust ordering based on dependency constraints, blast radius, validation cost, customer impact, and deadlines rather than forcing one universal rollout rule.

Service Migration Matrix

Sequencing Factors

• Dependency constraints: which upstream or downstream systems must move first?
• Validation window: how long must old and new paths run in parallel?
• Data migration: which services need storage backfill or dual-write support?
• Contract migration: which packages, schemas, or message topics change?
• External deadlines: which customer, compliance, or provider dates affect cutover order?

Rollout Stages

1. Adapt - refactor or extend the target service to handle the legacy use case. 2. Parallel run - dual-publish, dual-read, or route mirrored traffic where needed. 3. Validate - compare behavior, reconcile mismatches, and confirm success metrics. 4. Cut over - switch consumers and operators to the target path only. 5. Clean up - remove the old path, temporary bridges, and transitional toggles.

Per-Service Notes

Cross-Cutting Concerns

Repo Catalog Page Template

Snapshot

• Repo:
• Status:
• Kind:
• Languages:
• Frameworks:
• Architecture:
• Confidence:

Purpose

Short explanation of the repo's role in the portfolio.

Interfaces

• Public interfaces:
• Internal interfaces:

Integrations

• Upstream systems:
• Downstream systems:

Risks

• Known gaps:
• Low-confidence areas:

Evidence

• Path:
• Path:

Scan Backlog Template

Example: Mixed Active + Legacy Portfolio

Use this mode when a portfolio contains current systems plus superseded repos.

Expected outputs:

• active vs legacy tagging
• replacement edges
• legacy transition map
• risk report for legacy repos still referenced by active systems

Example: Monorepo Platform

Use this skill when a single repo contains apps/, packages/, and infra/.

Expected outputs:

• one profile for the monorepo root
• optional child-package inventory if the task requires package-level mapping
• architecture summary describing workspace tooling and deployable units

Example: Polyrepo Portfolio

Use this skill when services live in separate repos under one organization.

Expected outputs:

• one RepoProfile per repo
• one edge list for service-to-service and service-to-platform relationships
• one catalog page per repo
• one combined architecture summary

Example: Regulated Enterprise Portfolio

Example shape:

• active product repos
• legacy and superseded repos
• vendor and platform integration repos
• shared libraries and infra repos
• one master coordination repo for generated context

Use this example to validate the universal workflow without encoding client-specific assumptions.

Architecture Inference Rules

Prefer explicit evidence over naming heuristics.

Strong signals:

• API specs imply external or internal service contracts.
• workspace manifests imply multi-package architecture.
• services/, apps/, packages/, libs/ plus workspace config imply monorepo or package workspace.
• queue, topic, or consumer config implies event-driven components.
• migration folders plus HTTP framework usually imply a stateful service.

Weak signals:

• folder names alone
• generic src/ structure
• one-off integration mentions in comments

If only weak signals exist, keep architecture_style as unknown or mixed.

Confidence Scoring

Use additive confidence, capped at 1.0.

Suggested weights:

• README with clear purpose: +0.20
• manifest confirms language/runtime: +0.20
• CI or deploy config confirms packaging/runtime: +0.10
• API spec or interface artifact confirms exposure: +0.15
• explicit dependency/integration config: +0.15
• ownership signal: +0.10
• multiple corroborating files for architecture: +0.10

Penalties:

• no README: -0.10
• contradictory manifests or docs: -0.15
• only naming heuristics: -0.20

Never hide low confidence in prose. Surface it.

Confidence does not transfer sideways across sibling repos, providers, or services. A high-confidence finding for one adapter or repo does not justify a universal statement about the rest of the portfolio. When only a subset was checked, keep the summary labeled subset-verified until full coverage is complete.

Hub Design Patterns

Recommended shape:

• one coordination repo
• one portable root AGENTS.md
• one thin CLAUDE.md compatibility layer when Claude-specific behavior matters
• one schema set
• generated profiles
• generated catalog pages
• graph outputs
• freshness and coverage reports

Best-practice organization:

• keep the root instruction file concise and task-routing focused
• put deep operating rules in linked docs or scoped rules
• add nested instruction files only when the nearest-directory override is genuinely needed
• keep platform-specific instruction files additive, not divergent
• derive human-readable catalog pages from structured profile data
• treat raw scans as transient inputs and normalized profiles as canonical generated outputs

Avoid:

• giant root instruction files
• manually curated duplicate summaries
• one-off profile formats per portfolio
• coupling the hub to one AI vendor

Canonical Page Shape

<!-- Source: github.com/garrytan/gbrain@adb02b7826a010700efc968b18df8aaf17d8ffa1 (MIT), extracted 2026-04-13 -->

Catalog and concept pages should default to the compiled-truth + timeline two-zone layout. The top of the page is a regenerable synthesis of current state; the bottom is an append-only evidence log where every claim above the line can be traced to a dated source.

Reference: assets/catalog-compiled-truth-template.md has a full example for a repo catalog page plus the discipline rules (above-line rewrites, below-line appends, strict [Source: …] citation format, resolved Open Threads moving into the Timeline rather than disappearing).

Use this shape because it answers two different questions cheaply at the same time: "what is true now?" reads the top, "how did we get here?" reads the bottom. A single append-only log fails the first question; a single rewriteable summary fails the second.

Hub Freshness Checking

How to detect when a documentation hub is stale relative to its source repositories, and what to do about it.

Table of Contents

• When to Run Freshness Checks
• Quick Start
• How Auto-Mapping Works
• Explicit Mapping Configuration
• Change Detection Categories

When to Run Freshness Checks

Quick Start

# Basic: auto-detect baseline from hub's last_verified dates
check_hub_freshness.sh ~/repos/platform ~/repos/platform/requirements-hub

# Explicit date range
check_hub_freshness.sh ~/repos ~/docs-hub --since 2026-03-01

# JSON output for CI pipelines
check_hub_freshness.sh ~/repos ~/docs-hub --json --out freshness.json

# With explicit mapping file
check_hub_freshness.sh ~/repos ~/docs-hub --mapping hub-mapping.json --verbose

How Auto-Mapping Works

Without --mapping, the script greps hub markdown files for repo names. It tries:

1. Exact name — the directory name of the repo (e.g., payments-ledger) 2. Lowercase — case-insensitive match 3. Dot-to-hyphen — payments.ledger also matches payments-ledger

This works well when hub docs naturally reference source repos by name. For hubs that use different terminology, use explicit mapping.

Explicit Mapping Configuration

Create a JSON file following assets/hub-mapping-template.json:

{
  "hub_root": ".",
  "last_verified_pattern": "last_verified:\\s*(\\d{4}-\\d{2}-\\d{2})",
  "mappings": [
    {
      "repo_pattern": "payments-ledger*",
      "hub_docs": ["payments-ledger/README.md", "overview/data-catalog.md"],
      "change_weight": "critical"
    },
    {
      "repo_pattern": "payments*",
      "hub_docs": ["incomings/**/*.md", "overview/process-catalog.md"],
      "change_weight": "critical"
    },
    {
      "repo_pattern": "web*",
      "hub_docs": ["channels/web-app.md"],
      "change_weight": "standard"
    }
  ]
}

repo_pattern supports shell glob matching (fnmatch). change_weight is informational — the script uses commit-level change categories for priority.

Change Detection Categories

The script classifies changed files by pattern:

Multiple categories can apply to the same repo if different types of files changed.

Interpreting the Report

Markdown Report

The markdown table is sorted by priority. Focus on:

1. P1 repos first — their hub docs likely contain outdated data models, API contracts, or interface descriptions 2. P2 repos — messaging and event flow docs may be inaccurate 3. Affected Hub Docs column — tells you exactly which hub files to re-verify 4. Commit count — high commit counts suggest significant rework, not just patches

JSON Report

The JSON output is designed for CI/CD integration:

# Check if updates needed (exit code 1)
if ! check_hub_freshness.sh ~/repos ~/hub --json --out /tmp/freshness.json; then
  # Parse P1 count
  p1_count=$(python3 -c "import json; d=json.load(open('/tmp/freshness.json')); print(sum(1 for c in d['changes'] if c['priority']=='P1'))")
  if [ "$p1_count" -gt 0 ]; then
    echo "ALERT: $p1_count repos have P1 (schema/API) changes affecting the hub"
    # Create ticket, send notification, etc.
  fi
fi

CI/CD Integration

Nightly Check (GitLab CI)

hub-freshness:
  stage: verify
  schedule:
    cron: '0 6 * * *'  # 6 AM daily
  script:
    - ./scripts/check_hub_freshness.sh $REPOS_ROOT $HUB_ROOT --json --out freshness.json
  artifacts:
    paths: [freshness.json]
    when: always
  allow_failure: true  # Don't block pipelines

GitHub Action

- name: Check hub freshness
  run: |
    chmod +x scripts/check_hub_freshness.sh
    scripts/check_hub_freshness.sh repos/ docs-hub/ --json --out freshness.json || true
    if jq -e '.updates_needed' freshness.json; then
      echo "::warning::Hub docs need updating — see freshness.json"
    fi

Extending Change Categories

To add domain-specific patterns, modify the pattern variables at the top of check_hub_freshness.sh:

# Example: add GraphQL schema detection
API_PATTERNS='Controller.*\.cs|/routes/|openapi|swagger|\.proto$|\.graphql$|schema\.gql$'

# Example: add Prisma schema detection
SCHEMA_PATTERNS='Migrations/|DbContext\.cs|MongoRegistry\.cs|\.sql$|InitSchema|schema\.prisma'

Relationship to Other Tools

check_hub_freshness.sh complements report_drift.py — the former checks source repos against hub docs, the latter checks profiles against source repos. Together they cover the full chain: source → profile → hub doc.

Nightly Compounding Loop (The Dream Cycle)

<!-- Source: github.com/garrytan/gbrain@adb02b7826a010700efc968b18df8aaf17d8ffa1 (MIT), extracted 2026-04-13 -->

Drift detection reports what's stale; the compounding loop repairs it. Running the loop nightly is what turns a hub from a snapshot into an asset that gets more useful over time.

The Four Passes

A nightly job walks the hub and runs four passes, each writing a structured report:

1. Entity sweep — scan all catalog and concept pages for unlinked mentions of other entities in the hub. When a page mentions payments-ledger but has no backlink edge to catalog/payments-ledger.md, add the missing link. Output: reports/entity-sweep-YYYY-MM-DD.json listing added backlinks. 2. Citation audit — flag facts in Compiled Truth sections that lack a Timeline entry with [Source: …] attribution. Do not auto-fix — queue for human review. Output: reports/citation-audit-YYYY-MM-DD.md with flagged claims per page. 3. Memory consolidation — find near-duplicate entries (two Timeline entries within a day describing the same event from slightly different angles; two Open Threads that describe the same in-flight work). Merge duplicates, preserve both source citations. Output: reports/consolidation-YYYY-MM-DD.md. 4. Resolved-thread migration — any Open Thread item closed in the last 24 hours gets moved into the Timeline with its resolution appended as a new entry. This keeps the Open Threads list short and preserves the resolution history.

Recommended Cadence

Run during a quiet window so the compute cost is invisible. Output JSON reports go into reports/ so the next planning session can read them as Level 1 context input.

Why Nightly and Not On-Demand

On-demand feels faster but produces two failure modes: either the loop runs so rarely that drift accumulates, or developers trigger it manually and forget. A cron job running while everyone is asleep compounds quietly — the key insight from the source material is that "the brain compounds overnight," and the compounding only happens if the loop runs without human intervention.

When Not to Run It

• First week of a new hub: the loop is most valuable once there are enough entities and pages for backlinks to matter. For a 5-repo hub with 30 pages, skip the nightly loop and run it weekly instead.
• Hubs under active refactoring: if the directory schema is changing, the entity sweep will thrash. Pause the loop for the duration of the refactor, then run it once to resynchronize.

Contradiction Categories

<!-- Source: github.com/MemPalace/mempalace@6614b9b4e71e67da2236493b036b7bf42ba2d55f (MIT), extracted 2026-04-13 -->

Drift reports are more useful when they classify what kind of drift. Three categories cover most real-world contradictions in a multi-repo knowledge hub:

Detection Hints

• Attribution conflicts surface from the graph: when an edge in graphs/knowledge-graph.json contradicts a claim in a catalog page's Compiled Truth section, flag it. This is the highest-confidence category because the graph is built from structured profile data.
• Temporal errors surface from manifest diffs: when profiles/<repo>.json has a newer language/framework version than what the catalog page's State section says, flag the State field and link to the profile entry.
• Stale information is the hardest to detect automatically because it requires noticing that a newer claim exists without the older claim being retracted. Default detector: scan Timeline entries for contradictory pairs within the same page, preferring the later entry's claim over the earlier one's.

Reporting Format

Contradictions should feed into reports/drift.json alongside the existing change-category output from check_hub_freshness.sh:

{
  "contradictions": [
    {
      "category": "attribution_conflict",
      "page": "catalog/payments.md",
      "claim": "owns the settlement topic",
      "evidence_against": "graphs/knowledge-graph.json:payments-ledger publishes_to payments.settlement.v1",
      "severity": "high",
      "suggested_fix": "Update State section to reflect payments-ledger as producer; move old claim to Timeline with correction"
    }
  ]
}

Do not auto-fix contradictions. The fix requires judgment about which claim is correct (sometimes the source scan is wrong, not the hub page). Queue them for human review during the next freshness pass.

Hub Operations Playbook

Table of Contents

• Graph Assembly
• Incremental Updates
• Queries And Reports
• Freshness Monitoring
• Resolver-Driven Filing Discipline
• Recommended Hub Layout
• Stable Types
• Validation Checklist
• Workspace Alignment

Graph Assembly

After verification, materialize the portfolio graph.

Mode A, from profiles:

python3 scripts/build_knowledge_graph.py --profiles profiles/

Mode B, from an existing hub:

python3 scripts/build_knowledge_graph.py --hub /path/to/hub

Validate every build:

python3 scripts/validate_graph.py graphs/knowledge-graph.json \
  --output reports/graph-validation.json

Run consistency checks after validation:

python3 scripts/check_graph_consistency.py \
  --hub /path/to/hub \
  --graph graphs/knowledge-graph.json \
  --output reports/consistency-report.json

For ontology, normalization, and parser behavior, use knowledge-graph-patterns.md.

Incremental Updates

Bootstrap or refresh graph state after the first build:

python3 scripts/incremental_update.py graphs/knowledge-graph.json \
  --repo-map graphs/repos.json \
  --output graphs/knowledge-graph.json \
  --report reports/incremental-update.json

graphs/repos.json can stay portable by using named roots plus repo-relative paths:

{
  "roots": {
    "main": ["../.."],
    "qa": ["../../../platform-qa"],
    "legacy": ["../../../platform-legacy"]
  },
  "repos": {
    "payments-ledger": {"root": "main", "path": "payments-ledger"}
  }
}

Override roots at runtime when local checkout layout differs:

python3 scripts/incremental_update.py graphs/knowledge-graph.json \
  --repo-map graphs/repos.json \
  --repo-root main=/work/platform

Queries And Reports

Generate static graph reports for humans:

python3 scripts/export_graph_report.py graphs/knowledge-graph.json \
  --output-dir reports/

Common query patterns:

python3 scripts/query_graph.py graphs/knowledge-graph.json --node <id> --hops 1
python3 scripts/query_graph.py graphs/knowledge-graph.json --impact <id> --hops 2
python3 scripts/query_graph.py graphs/knowledge-graph.json --from <id> --to <id>
python3 scripts/query_graph.py graphs/knowledge-graph.json --type repo
python3 scripts/query_graph.py graphs/knowledge-graph.json --search "sumsub kyc" --types provider,process,repo --limit 10
python3 scripts/query_graph.py graphs/knowledge-graph.json --node <id> --hops 1 --format mermaid

Prefer static HTML or Markdown reports as the default human-facing output. Treat richer visualization layers as downstream consumers of knowledge-graph.json, not as required outputs of this skill.

Resolver-Driven Filing Discipline

<!-- Source: github.com/garrytan/gbrain@adb02b7826a010700efc968b18df8aaf17d8ffa1 (MIT), extracted 2026-04-13 -->

Hubs rot when filing is ambiguous. The same fact ends up on three pages with three slightly different versions, nobody knows which is current, and agents stop trusting the system. The fix is MECE directories + per-directory resolvers, enforced with a hard rule that no page gets created without walking the resolver first.

Three Founding Rules

1. Every piece of knowledge has exactly one primary home. Directories are mutually exclusive and collectively exhaustive. A repo catalog entry lives in catalog/. A cross-repo concept lives in concepts/. A system map lives in graphs/ (generated) or diagrams/ (hand-authored). MECE applies to directories, not to reality — a complex repo can be referenced from multiple concept pages, but its primary catalog page exists in exactly one place.

2. Every directory has a `README.md` resolver. The resolver answers two questions:

• What goes here — a positive definition with a concrete test. Example: "catalog/ holds one page per repo scanned into profiles/. If a topic does not correspond to a single repo, it does not go here."
• What does NOT go here — the key distinctions from neighbouring directories. Example: "Architecture patterns that span many repos do not go here; they go in concepts/. Generated dependency maps do not go here; they go in graphs/."

3. Top-level `RESOLVER.md` is the decision tree. A numbered walk that answers "where does this new item go?" When two directories seem to fit, explicit disambiguation rules break the tie. When nothing fits, the item goes in inbox/ — which is itself a signal the schema needs to evolve.

The Agent Must Read the Resolver Before Filing

This is not optional. If an agent creates a page without walking RESOLVER.md, the discipline collapses within a month. Wire this into the hub's AGENTS.md as a hard rule, not buried guidance:

# Hub AGENTS.md (excerpt)

## Filing rule (hard)

Before creating ANY new page in this hub:
1. Read `RESOLVER.md` from the hub root.
2. Walk the decision tree for the item type.
3. Read the target directory's `README.md` resolver.
4. If the item does not fit cleanly, place it in `inbox/` and flag for schema review — do NOT force-fit into an existing directory.

Resolver Template (Per Directory)

# <directory>/ README (resolver)

## What goes here
<positive test — one sentence, concrete>

Example: A repo catalog page (`catalog/<repo>.md`) belongs here if and only if `profiles/<repo>.json` exists. No profile, no catalog entry.

## What does NOT go here
- <distinction from neighbouring directory 1> → goes in `<neighbour1>/`
- <distinction from neighbouring directory 2> → goes in `<neighbour2>/`
- <distinction from inbox> → goes in `inbox/` if the schema does not cover this case

## Naming convention
<slug rule>

## Required fields
<what every page in this directory must include>

## Related directories
- `<neighbour1>/` — <one-line relationship>
- `<neighbour2>/` — <one-line relationship>

Why the Inbox Matters

The inbox/ directory is not a dumping ground — it's a signal channel. When items keep landing there, the schema needs a new directory or a new resolver rule. Treat inbox/ contents as the agenda for the next schema-evolution review (weekly or monthly depending on hub velocity). A well-governed hub aims for a near-empty inbox; a consistently full inbox means the resolver has an unaddressed gap.

Why This Beats "Just Be Consistent"

Agents (and humans under time pressure) cannot "be consistent" across 50-100 directories by willpower. The resolver turns filing into a deterministic walk: read rule, check test, place file. Same input → same destination, every time. That's what makes the hub an artifact that can be rebuilt and audited rather than a pile of human judgment calls that drift with whoever filed things most recently.

Freshness Monitoring

Use check_hub_freshness.sh after source repo pulls, before planning sessions, and on scheduled CI runs:

check_hub_freshness.sh ~/repos ~/docs-hub
check_hub_freshness.sh ~/repos ~/docs-hub --json --out freshness.json

Default change categories:

• SCHEMA
• API
• MESSAGING
• CONFIG
• INFRA
• OTHER

The script ships with .NET/C#-biased patterns. Adapt the regexes for Node, Python, Go, Java, or mixed stacks.

Detailed guidance lives in hub-freshness-checking.md.

Recommended Hub Layout

Preferred shape:

portfolio-hub/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── context/
│   ├── docs/
│   ├── overview/
│   ├── scripts/
│   ├── templates/
│   ├── graphs/
│   ├── reports/
│   ├── schemas/
│   └── profiles/
├── {domain}/
│   ├── README.md
│   ├── as-is/
│   ├── assessment/
│   └── initiatives/
└── sources/

Rules:

• keep the root clean and domain-focused
• keep hub infrastructure under context/
• keep root AGENTS.md short and navigation-first
• keep generated inventories in profiles/, catalog/, graphs/, and reports/
• use assets/coordination-repo-layout-template.md as the starting layout

Stable Types

Do not invent alternate contracts unless a downstream system requires a transform layer. The canonical schema set is:

• schemas/repo-profile.schema.json
• schemas/evidence-ref.schema.json
• schemas/system-edge.schema.json
• schemas/scan-registry-entry.schema.json
• schemas/hub-summary.schema.json
• schemas/knowledge-graph.schema.json

Validation Checklist

• every repo has one RepoProfile
• every nontrivial claim has at least one evidence reference
• portfolio-wide claims are only marked universal when the full scope was verified
• active and legacy repos are not conflated
• storage engine claims are verified from manifests, not docs
• graphs/knowledge-graph.json has been built and validated
• reports/consistency-report.json has been generated and reviewed
• root AGENTS.md remains navigation-focused
• domain folders include as-is/, assessment/, and initiatives/ where the assessment model is in use

Workspace Alignment

Domain folder names should match team mental models, usually the IDE workspace prefixes used by the organization.

This is naming alignment only. Do not physically move git repos into domain folders. Use workspace files for IDE grouping and the hub for documentation grouping.

Integration Signal Detection

Look for these signal classes:

• dependency manifests
• environment variable names
• API specs
• webhook handlers
• queue/topic names
• infrastructure config
• vendor SDK package names
• CI/CD deploy steps
• database schema artifacts (see below)
• ORM/data-access registrations (see below)

Database & Storage Signal Detection

Storage engine detection is a common source of errors — the documented storage type often drifts from the actual driver in code. Always verify the actual driver package in dependency manifests rather than trusting documentation headers.

Cross-Service Data Flow Signals

Beyond storage, detect how data flows between services:

Emit a SystemEdge only when there is at least one concrete artifact or two weaker corroborating signals.

Do not upgrade edge-level evidence into portfolio-wide topology claims unless every sibling edge in scope was checked. Central diagrams, dependency matrices, and messaging summaries must preserve verification scope from the underlying edges and label gaps as subset-verified, inferred, or unverified.

Large Portfolio Strategy

For 100+ repos:

1. Inventory all repos first. 2. Deep-scan only high-priority or low-confidence repos. 3. Use incremental rescans after bootstrap. 4. Separate active, legacy, archived, and vendor repos early. 5. Generate graph outputs from structured data, not markdown parsing. 6. Keep one canonical profile per repo and derive all other views from it. 7. Keep the root hub instructions small and use nearest-scope overrides only where local behavior changes. 8. Split portable instructions from platform-specific layers instead of maintaining multiple drifting root files.

When time is limited:

• full scan metadata for all repos
• manual review for the top 10 highest-risk or most-central repos

Manifest Detection Matrix

Read the smallest set that reveals runtime, dependencies, and build model.

Output Model And Gap Analysis

Table of Contents

• Artifact Root Model
• Core Outputs
• Extended Domain Assessment Model
• Assessment vs Initiatives
• Initiative Lifecycle
• Gap Analysis Categories

Artifact Root Model

Every run should target one artifact root and keep generated outputs grouped consistently.

Recommended shapes:

• coordination repo style: <artifact-root>/profiles, <artifact-root>/catalog, <artifact-root>/graphs, <artifact-root>/reports
• embedded repo-local style: docs/context/profiles, docs/context/catalog, docs/context/graphs, docs/context/reports

Use scripts/build_artifact_set.py --artifact-root <dir> ... when you want one command to materialize the whole set into a location such as docs/context/.

Core Outputs

Minimum standard outputs:

• profiles/<repo>.json

Machine-readable repo profile conforming to schemas/repo-profile.schema.json

• catalog/<repo>.md

Canonical human-readable repo profile generated from the JSON profile plus evidence

• graphs/system-edges.json

Cross-repo and repo-to-external-system relationships

• graphs/knowledge-graph.json

Primary machine-readable graph output for query, blast radius, and report generation

• reports/coverage.md

Coverage, completeness, and low-confidence gaps

• reports/drift.json

Profiles whose evidence is stale relative to source repos

Common optional outputs:

• reports/graph-validation.json
• reports/consistency-report.json
• reports/graph-report.html
• reports/graph-report.md
• catalog/database-schemas.md
• catalog/data-catalog.md

If you need per-repo symbol graphs, keep them as a sibling artifact set via ../../dev-context-code-graph/SKILL.md instead of forcing symbol-level nodes into the portfolio graph.

Extended Domain Assessment Model

For regulated or complex platforms, extend the standard outputs with a per-domain assessment shape:

{domain}/
├── README.md
├── as-is/
│   ├── README.md
│   ├── services/
│   ├── providers/
│   ├── cross-repo-dependencies.md
│   └── diagrams.md
├── assessment/
│   ├── README.md
│   ├── gap-analysis.md
│   ├── architecture-proposal.md
│   ├── migration-roadmap.md
│   └── business-gaps.md
└── initiatives/
    ├── README.md
    ├── NNN-short-name/
    │   ├── README.md
    │   ├── gap-analysis.md
    │   ├── adr-*.md
    │   └── ...
    └── _graduated/

Three layers:

Assessment vs Initiatives

Use assessment/ for domain-wide strategic review that spans all repos and all gap categories.

Use initiatives/ for scoped tactical work on one sub-area, for example:

• incoming payments refactoring
• contract-governance rollout
• provider adapter normalization
• observability hardening

Multiple initiatives can run in parallel inside the same domain.

Use assets/initiative-doc-template.md for new initiatives.

Initiative Lifecycle

Standard lifecycle:

draft → proposed → accepted → in-progress → done → graduated

Graduation rule:

• findings from a completed initiative must be merged into as-is/ before moving the folder to _graduated/
• _graduated/ is historical archive only; agents and humans should skip it by default

Gap Analysis Categories

Use the A-O framework when producing regulated or platform-wide gap reviews:

Use severity levels appropriate to the context: BLOCKER, HIGH, MEDIUM, LOW.

Repo Classification Rules

repo_kind defaults:

• service for deployable backend systems with runtime plus service interfaces
• app for user-facing web, mobile, or desktop applications
• library for shared packages or SDKs
• infra for Terraform, Helm, CI/platform repos
• data for analytics, ETL, warehouse, or ML pipelines
• docs for documentation-only repos
• mono-root for workspace roots coordinating many packages
• unknown when signals conflict or are insufficient

Native/mobile-specific guidance:

• classify as app when Swift is present and high-signal Apple project files such as project.yml, .xcodeproj, or .xcworkspace are present
• prefer project-file evidence over generic dependency heuristics for native repos
• ignore generated build trees such as .build, DerivedData, Pods, Carthage, and SourcePackages before making repo-shape claims

status defaults:

• legacy when repo naming, archived markers, or docs say it is superseded
• archived when git hosting or docs explicitly mark it archived
• experimental for POCs or labs
• active only when no legacy/archive signal is present

Repo Discovery Patterns

Use shallow discovery first.

Priority signals:

• .git/
• root manifests
• CI configuration
• workspace files such as pnpm-workspace.yaml, nx.json, turbo.json
• spec artifacts such as SPEC.md, specs/, plans/, docs/specs/

Exclude by default:

• .archive
• build artifacts
• vendored dependencies
• generated clients

Classify before scanning deeply:

• standalone repo
• monorepo root
• package inside workspace
• legacy or archived repo