architecture-overview

Architecture Overview

Discovery-mode multi-repo landscape mapper. Walks each repo with an Explore subagent for narrative discovery and runs skills/architecture-overview/scripts/repo-stats.ts for deterministic metrics. Produces 4 markdown files using shared architectural vocabulary so downstream skills (notably /improve-codebase-architecture) consume without retranslation.

Announce at start: "I'm using the architecture-overview skill to produce a discovery-mode landscape across the supplied repos."

When To Use

• New eng leader needs day-3 whole-system mental model
• User explicitly invokes /architecture-overview
• User asks to "map the architecture", "produce a landscape doc", "list the services"

When NOT To Use

• Single-repo deepening grading → /improve-codebase-architecture
• Single architectural choice with named alternatives → /adr
• System-level design record → /sdr
• Tool/framework adoption evaluation → /tech-radar

Inputs

• --repos <yaml-or-csv> — path to a repos.yaml config OR comma-separated paths/URLs
• --output <path> — override default output dir
• --clone-cache <path> — override URL clone target (default ~/.cache/architecture-overview/)
• --no-fetch — skip git fetch on already-cached URL clones

Vocabulary

Canonical: architecture-language.md. Module / Interface / Seam / Adapter / Depth / Leverage / Locality. Avoid component / service / API / boundary as descriptive vocab — see output-format.md for the proper-noun carve-out.

Process

1. Parse Input

Resolve --repos into [{name, source: path | url}]. Reject unparseable entries with a clear error.

2. Resolve Repos (Parallel)

• Cache prompt (URL inputs only) — if --clone-cache not supplied, prompt: "Default cache: ~/.cache/architecture-overview/. Enter to accept or supply a path." Empty / "default" / "yes" = accept.
• Path → verify readable directory; bail-soft on error (record, don't abort).
• URL → git clone --depth=1 if not cached; git fetch --depth=1 unless --no-fetch. Auth failures → inferred-only entries.

3. Walk (Parallel per Repo)

• Explore subagent — intent first. Before walking source, read README.md and docs/*.md (and CONTEXT.md / ADRs when present) to extract three signals: (a) stated purpose — what the module does, in the project's own words; (b) lifecycle stage — research / prototype / production / archived, only when textually signalled; (c) audience — internal / external / shared lib. Emit *intent unstated* (italic-default) when no textual signal exists; never auto-classify lifecycle from generic signals (caller count, last-commit-age) alone.
• Walk source — produce four narrative threads: inventory (Module / Interface / Implementation / Signals), dependencies (Seam / Adapter / Observed-via), data-flow (numbered lifecycle steps), integrations (external SaaS).
• Italic-default; plain only when the agent cites file:line evidence. Inferences (manifest absence, env-var implies dep, conventional naming) → italic. Code-grounded claims (import at src/x.ts:42, env var read in config.ts) → plain. The agent applies the convention while writing the narrative — it is NOT a post-pass.
• bun run skills/architecture-overview/scripts/repo-stats.ts --repo <path> — capture stdout JSON for deterministic metrics.

4. Aggregate + Vocab Pass

Merge per-repo records. Cross-repo edge resolution: if repo A's manifest dep matches repo B's package name, emit edge A → B [observed]. Apply LANGUAGE.md vocab interleaved with the merge — per-repo CONTEXT.md domain terms layered on top. Single pass, not two; narrative is written once with the right vocab.

Intent-qualified brittleness. Brittleness signals (no test surface, high fan-in, stale last-commit, high TODO/FIXME density) MUST be qualified by the intent extracted in Step 3 before being labelled brittle. Render shape:

*<signal> — <interpretation given intent>*

A signal alone is data, not a brittleness verdict. The verdict is the interpretation; the interpretation is the contract. Worked examples:

• Research prototype + no test directory → *no test surface — expected for prototype-stage module; tests deferred until pattern stabilizes* (NOT brittle).
• Foundational shared lib + 47 callers → *high fan-in (47 callers) — gravity well by design; change-cost is high* (architectural, NOT brittle).
• Production service + 6mo idle + 23 unresolved TODOs → *production module idle 6mo with 23 unresolved TODOs — review backlog* (genuinely brittle).

If intent is unstated, italic-default the brittleness paragraph itself — extending §3's italic-default-for-inferences discipline — and emit *intent unstated; treat brittleness signals as observations, not verdicts* rather than auto-classifying. Two ramps of real-world data before codifying rigid lifecycle rules.

5. Render

• Output guardrails — refuse if output path is inside claude-config (git rev-parse --show-toplevel) — prevents polluting the source repo with generated landscapes that would re-trigger discovery on the next run. Default: exactly one ~/repos/onboard-*/ workspace → <workspace>/architecture/ — onboard workspaces are the canonical landing spot per /onboard convention; zero or multiple → require --output <path> so the user picks intentionally.
• Write 4 files at the resolved output path. Frontmatter format: references/output-format.md. language_ref is relative to each output file's parent directory — keeps the bundle portable when copied to a different repo; emit an absolute path or URL when the bundle lands outside the repo tree.
• Mermaid — render blocks per output-format.md — single canonical source post-#233 drift-collapse: graph TB in inventory.md (C4 Context), graph LR in dependencies.md, flowchart TD in data-flow.md. Each diagram has a sufficient-complexity floor — low-density diagrams add noise, not signal; below it, replace with > _diagram skipped: <reason>_.
• Done — print "Wrote 4 files at <path>. repos scanned."

Composition

• /improve-codebase-architecture — consumes this output (vocabulary is the contract). Run first; user holds bundle context while running the deepening-grader.
• /onboard — leader's broader ramp toolkit. Future versions may auto-invoke this skill; for now it is opt-in.

Repo Requirements

See references/repo-requirements.md for the hard / soft / auto-skipped / edge-case matrix.

Known Gaps

See references/known-gaps.md for the current v0.3.1 (Experimental) gap list.