/arch-map

name: arch-map
description: >
  USE WHEN setting up a repo for AI-first work, after a major directory
  restructure, or when an agent needs structured answers like "which
  modules are stable?" / "what's the public surface of X?" that the
  prose AGENTS.md doesn't give cheaply. Bootstraps or refreshes
  `architecture.yml` at repo root — machine-readable module metadata
  (path / role / stability / public_surface / depends_on / paired_with /
  owners). Hand-curated; the skill drafts, the user confirms. See ADR
  0005 for why this file lives at root and why YAML over JSON.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(git rev-parse:*)
  - Bash(git ls-files:*)
  - Bash(test:*)
  - Bash(ls:*)
  - Bash(find:*)
  - Bash(python:*)
  - Bash(python3:*)
argument-hint: "[--depth N] [--validate] [--target path] [--noninteractive]"

/arch-map

What it does

Maintains `architecture.yml` at the repo root — a hand-curated, machine-readable map of top-level modules. Complements [`/repo-map`](../repo-map/SKILL.md), which generates a *human-readable* mermaid diagram; this skill produces the *structured-metadata* layer an agent can load and query in one parse.

The point: agents proposing refactors regularly ask "is this module stable or experimental?" / "what's the public surface I shouldn't silently rename?" / "what module does this pair with?". Re-deriving the answer from prose AGENTS.md + directory tree walks is wasted tokens every session. `architecture.yml` answers in one YAML load.

This skill **drafts the file** (from directory walk + AGENTS.md hints). The user **confirms `role` and `stability`** per module. Auto-generated guesses get a `<TODO>` placeholder until the user fills them.

See ADR 0005 for the rationale (why YAML over JSON, why root over `docs/`, why not per-folder).

When to invoke

• First setup of an AI-first repo (after `/init-repo` and ideally

after `/repo-map`).

• After major directory restructuring (modules added, renamed,

removed).

• When an agent is about to propose a refactor and you'd rather it

read `architecture.yml` first than guess at module roles.

Do NOT invoke for:

• Per-file documentation (use AGENTS.md per directory, or docstrings

in the code).

• Auto-generated dep graphs from imports (that's `/repo-map`'s

`madge`/`pydeps` block).

• Tracking current commit / branch / version (this file is

*architectural*, not point-in-time).

File format

# claude-leverage:architecture-map v1
# Hand-curated structured architecture metadata. Update via /arch-map
# or by hand-editing this file. Schema: claude-leverage v1.
# See: https://github.com/Filip-Podstavec/claude-leverage/blob/main/skills/arch-map/SKILL.md

repo:
  name: "<repo-name>"
  primary_lang: "<lang or lang+lang+lang>"
  one_line: "<one-sentence concrete description: what + for whom>"

modules:
  - path: "<dir-or-file>/"
    role: "<one-line purpose>"
    stability: stable | evolving | experimental | deprecated
    public_surface:
      - "<name agents must not silently rename>"
      - "<another>"
    depends_on:
      - "<other module path>"
    paired_with: "<module that mirrors this one>"
    owners:
      - "<name or @handle>"

Required fields

• `repo.name`, `repo.primary_lang`, `repo.one_line`
• Each module: `path`, `role`, `stability`

Optional fields

• `modules[].public_surface` — names/files agents must not casually

rename (the rename will break callers outside the module). Strings.

• `modules[].depends_on` — array of other module `path` values this

module depends on at the architectural level (not import-level).

• `modules[].paired_with` — single module path that mirrors this one,

e.g. `agents/` paired with `.codex/agents/`.

• `modules[].owners` — array of names or @handles.

Stability levels

| Value | Meaning | |-------|---------| | `stable` | Public surface is load-bearing; renames need an ADR + caller migration. | | `evolving` | Public surface may change; callers should pin imports. | | `experimental` | May be deleted entirely. Don't depend on this module from outside. | | `deprecated` | Scheduled for removal. New code should not reference it. |

Workflow

1. **Resolve repo root.** `git rev-parse --show-toplevel`. If not in a git repo, STOP and report.

2. **Detect mode.**

• `--validate` → parse existing `architecture.yml`, check required

fields, check `path` values exist, report findings, write nothing.

• No existing file → **bootstrap mode**.
• Existing file + no `--validate` → **extend / refresh mode**:

re-walk directories, suggest entries for new modules; preserve existing module entries unchanged.

3. **Walk top-level directories** (depth 1 by default; pass `--depth N` for 1–3). Skip:

• Dotfiles except `.codex` / `.claude*` (those are tooling).
• Standard noise: `node_modules`, `__pycache__`, `dist`, `build`,

`.next`, `.pytest_cache`, `target`, `vendor`, `bench/archive-*`.

• Empty directories.

4. **For each non-trivial directory, infer:**

• `path` — the directory path relative to repo root, with trailing

slash.

• `role` (draft) — read the directory's `AGENTS.md` if present;

extract the first H1 heading + first paragraph. If no AGENTS.md, emit `"<TODO: one-line purpose>"`.

• `stability` (draft) — emit `<TODO: stable|evolving|experimental|deprecated>`.

The skill won't guess this; the user knows.

• `public_surface` (draft) — best-effort: list top-level filenames

without leading `_`, plus any obvious exports (Python `__all__`, TS named exports, Go exported identifiers). Cap at 10 entries. If unclear, omit the field.

• `depends_on` (draft) — omit; the user fills if architecturally

meaningful.

• `paired_with` (draft) — heuristic: if there's a `.codex/<name>/`

mirror of `<name>/`, propose that pairing.

• `owners` (draft) — omit by default. The user can fill or skip.

5. **Read existing `architecture.yml`** i