| 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, 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
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
-
Resolve repo root. git rev-parse --show-toplevel. If not in a
git repo, STOP and report.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
Update AGENTS.md (idempotent, ask before write). If AGENTS.md
exists and doesn't already mention architecture.yml, offer to
append:
### Architecture metadata
Machine-readable module map: [`architecture.yml`](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.
-
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.
