filip-podstavec/claude-leverage/arch-map

/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`, 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

Workflow

1. Resolve repo root. git rev-parse --show-toplevel. If not in a

git repo, STOP and report.

1. 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.

1. 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.

1. 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.

1. Read existing `architecture.yml` if present. Parse YAML

(stdlib-only via python -c 'import yaml' if available, else a conservative line-based parser — see "Parser fallback" below). Compute set of modules[].path values already documented. New module entries proposed only for paths not in that set.

1. Show the user the draft (interactive mode):

``` I'll write architecture.yml at <repo-root>/. Confirm or edit:

repo: name: "claude-leverage" primary_lang: "shell+python+markdown" one_line: "<TODO: one-sentence concrete description: what + for whom>"

modules (proposed):

• path: "scripts/hooks/"

role: "<TODO: one-line purpose>" <-- AGENTS.md present at this path? no stability: <TODO>

• path: "skills/"

role: "Cross-tool on-demand skills (agentskills.io spec)" <-- from skills/README.md stability: <TODO>

• path: "agents/"

role: "Claude Code subagents" <-- from agents/README.md stability: <TODO> paired_with: ".codex/agents/" ...

Proceed? (y / n / edit-each) ```

With edit-each, walk modules and prompt for role + stability per module. With y, write as-shown (<TODO> placeholders intact). In --noninteractive, write as-shown without prompting.

1. Write the YAML. Use a deterministic key order (the order in the

schema above). Quote strings that contain : or start with -. Use 2-space indentation. End with a single newline.

1. Validate the written file. Run the YAML parser on it; check:

• Top marker comment is exactly

# claude-leverage:architecture-map v1.

• repo.name, repo.primary_lang, repo.one_line are present

and non-empty (a <TODO> placeholder counts as "present").

• modules is a non-empty list.
• Each module has path, role, stability.
• Each path value exists on disk (warn if not — could be an

intentional placeholder for a planned module).

• stability is one of the four valid values OR a <TODO>

placeholder. If validation fails, print the error with line number and stop before writing the final version.

1. Update AGENTS.md (idempotent, ask before write). If AGENTS.md

exists and doesn't already mention architecture.yml, offer to append:

```markdown ### Architecture metadata

Machine-readable module map: `architecture.yml`. When proposing refactors that cross module boundaries, read this first for stability and public_surface constraints. ```

Skip if --no-update-agents-md is passed.

1. Report. Print path, count of modules total, count of <TODO>

placeholders remaining, suggested next step (/arch-map --validate after filling).

Validate mode (--validate)

Read architecture.yml, run the same checks as step 8, exit. Useful in CI: a future job can run claude /skill arch-map --validate to fail the build if the file drifts. Output is a structured report:

# architecture.yml validation — <YYYY-MM-DD>
 
Schema version: v1 ✓
Required fields: ✓
 
| Module | Status | Notes |
|--------|--------|-------|
| scripts/hooks/ | ok | — |
| skills/ | ok | — |
| agents/ | **TODO** | role + stability still placeholders |
| legacy/ | **missing** | path declared but not on disk |

Parser fallback

If neither python nor python3 is on PATH, or PyYAML isn't installed, fall back to a conservative regex line parser inside the skill body:

• Recognize top-level keys, two-space-indented children.
• Recognize lists via - prefix.
• Reject multi-line scalars, anchors, aliases, merge keys, flow style.

The schema is intentionally flat enough that this is fine.

If even that fails (file structure is too foreign), print the parse error and STOP. Don't try to "fix" the file — that's the user's job.

Hard rules

• Never overwrite existing module entries. Re-running in extend

mode preserves them byte-for-byte. If the user wants to revise a module, they edit the file by hand.

• Never invent `role` or `stability`. Both are user-supplied or

<TODO> placeholders. The skill drafts, the user confirms.

• Never auto-generate `depends_on` from imports. Import-level deps

belong in /repo-map's madge/pydeps block. depends_on here is architectural (user-decided), not derived.

• Preserve the schema marker line. The top

# claude-leverage:architecture-map v1 comment is load-bearing.

• Stop on parse error. A corrupted architecture.yml is the

user's call to fix; the skill never rewrites a file it can't parse.

Tunables

• --depth N — directory walk depth (1–3, default 1).
• --validate — schema-only mode; write nothing, exit non-zero on

failure.

• --target <path> — non-default file location (default

<repo-root>/architecture.yml).

• --no-update-agents-md — skip the AGENTS.md pointer step.
• --noninteractive — write the draft as-shown without per-module

prompts.

What this skill does NOT do

• Auto-generate a dependency graph from code. That's

/repo-map's madge/pydeps block. This skill captures the architectural dependency the user names, not the import graph.

• Replace AGENTS.md per directory. Per-directory AGENTS.md

remains the primary prose layer for module-internal conventions and gotchas. architecture.yml is structured metadata about the module's role in the system, not its internal workings.

• Track current commit / branch. This file is architectural and

changes when the architecture changes — not on every code commit.

• Validate `depends_on` is acyclic. Cycle detection is future

work for /stack-check integration.

• Auto-fire on directory changes. Per ADR 0004's philosophy:

user/agent-invoked, no auto-fire hook. The agent recognizes the moment.

Codex parity

Same SKILL.md ships in Codex via scripts/install-codex.sh. Codex host writes the same YAML; the format is tool-agnostic.

Future / not in scope here

• /stack-check could validate architecture.yml schema as part of

its repo-walk, flag <TODO> placeholders > 30 days old, and warn on depends_on cycles. Tracked as a future enhancement.

• /repo-map could read architecture.yml to color-code mermaid

nodes by stability. Future enhancement.

• A JSON-schema sidecar (architecture.schema.json) for IDE

validation in editors that support it. Out of scope for v1.