dev-context-multi-repo

What this skill does

# 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

| Task | Use |
|------|-----|
| Discover repos and classify portfolio shape | `scripts/discover_repos.py`, [references/repo-discovery-patterns.md](references/repo-discovery-patterns.md) |
| Scan repos into normalized profiles | `scripts/scan_repo.py`, `scripts/scan_portfolio.py`, [references/repo-classification-rules.md](references/repo-classification-rules.md) |
| Build standard artifact set | `scripts/build_artifact_set.py`, [references/output-model-and-gap-analysis.md](references/output-model-and-gap-analysis.md) |
| Build and validate graph outputs | `scripts/build_knowledge_graph.py`, `scripts/validate_graph.py`, `scripts/check_graph_consistency.py`, [references/knowledge-graph-patterns.md](references/knowledge-graph-patterns.md) |
| Calibrate graph edge weights from evidence | `scripts/calibrate_weights.py`, [references/knowledge-graph-patterns.md](references/knowledge-graph-patterns.md) |
| Query graph neighborhoods, paths, impact, rank, PPR, and communities | `scripts/query_graph.py --node\|--from\|--impact\|--rank\|--ppr\|--communities`, [references/knowledge-graph-patterns.md](references/knowledge-graph-patterns.md) |
| Detect communities (Louvain) and generate per-community summaries | `scripts/query_graph.py --communities --resolution`, [assets/community-summary-template.md](assets/community-summary-template.md) |
| Bitemporal time-slice queries | `scripts/query_graph.py --as-of <date> --known-at <date>`, [references/knowledge-graph-patterns.md](references/knowledge-graph-patterns.md) §12 |
| Create or operate a coordination hub | [assets/coordination-repo-layout-template.md](assets/coordination-repo-layout-template.md), [references/hub-operations-playbook.md](references/hub-operations-playbook.md) |
| Run a raw-ingest to compiled-wiki loop | the `docs-notes-retrieval` skill, [references/hub-design-patterns.md](references/hub-design-patterns.md), [references/hub-operations-playbook.md](references/hub-operations-playbook.md) |
| Freshness and drift checks | `scripts/report_drift.py`, `scripts/check_hub_freshness.sh`, [references/hub-freshness-checking.md](references/hub-freshness-checking.md) |

## 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/](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.

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

Then follow [assets/hub-scaffold/context/scripts/README.md](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](../dev-context-engineering/SKILL.md).
- Symbol or file graph inside one repo: use [dev-context-code-graph](../dev-context-code-graph/SKILL.md).
- Spec writing or decision docs: use [docs-ai-prd](../docs-ai-prd/SKILL.md).
- Documentation freshness audits: use [qa-docs-coverage](../qa-docs-coverage/SKILL.md).
- Parallel discovery across many repos with explicit delegation: use [agents-swarm-orchestration](../agents-swarm-orchestration/SKILL.md).

## 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 g