system-map
Skill0 starsChanged 3 months agoMITView on GitHub
Reverse-engineer the system from the repos in projects/ and write the agent-facing map — one seam file per service under .claude/rules/services/, plus the factual sections of docs/system/. Scans services in parallel subagents, joins producers to consumers centrally, and leaves what it cannot derive as an explicit TODO.
- Reads credentials
5 other projects use a version of this.
Adopted by
Most recently taken up by
- rivendale/hsi-operatortheir own version, first seen Nov 7, 2026
- tslateman/skillstheir own version, first seen Oct 11, 2026
- brian-bell/agent-skillstheir own version, first seen Sep 26, 2026
- atleronningen/skillstheir own version, first seen Aug 2, 2026
- mmaripanguec/dev-sdd-kittheir own version, first seen Jul 21, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- mmaripanguec/dev-sdd-kit★ 2same name
- rivendale/hsi-operator★ 2same name
- brian-bell/agent-skills★ 1same name
- tslateman/skills★ 1same name
- atleronningen/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- feature-buildSkill
- feature-build-step-by-stepSkill
- feature-code-reviewSkill
- feature-plan-reviewSkill
- feature-planSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 4 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Read repos.yaml. It is the registry: every service, its url, branch, role, stack, summary.
- Very specific: line 81
Do this yourself, in the main context.
- Very specific: line 103
Except when the code contradicts the registry: If a service has no seam *and* what you found disagrees with its role or summary in …
- Distinctive: line 111
Keep each file under ~35 lines.
- Distinctive: line 127
Update only the factual sections you own, by heading, and never delete prose you did not write:
- Distinctive: line 142
Never overwrite a non-empty value: those are human decisions.
- Distinctive: line 150
Match the language of the repository's existing docs: when writing prose.
- Very specific: line 151
Never create, modify, or commit anything under projects/.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
You are building the agent-facing map of the whole system by reverse-engineering
the service repositories checked out under projects/. Arguments: $ARGUMENTS
What you produce:
| Output | Purpose |
.claude/rules/services/<svc>.md | One seam file per service. Path-scoped, so it enters context only when the agent touches that service |
docs/system/architecture.md | Factual map of how the system is cut up (the why stays human-written) |
docs/system/infrastructure.md | Per-service deployment surface (shared infra stays human-written) |
repos.yaml | Proposed values for empty stack / role / summary fields only |
Never write anything into projects/. Sub-repos are autonomous and must not
know this orchestrator exists.
Step 0 — Registry, scope, drift
- Read
repos.yaml. It is the registry: every service, itsurl,branch,role,stack,summary. - Parse the arguments:
--only a,brestricts to those services;--fullforces a rescan of everything. - For each service resolve
git -C projects/<svc> rev-parse --short HEAD, then read thereflects:field in the frontmatter of any existing.claude/rules/services/<svc>.md. If they match, skip that service unless--fullwas passed — this is what makes routine refreshes cheap. - Drift check: report directories present in
projects/but absent fromrepos.yaml, and manifest entries with no checkout (runsetup.sh). A third kind of drift — services the code depends on that are in neither — can only be found by scanning, and is reported in Step 5. - Print
will scan N of M serviceswith the list, and get a go-ahead before spending the scan. A run that silently costs 40 subagents will never be run twice.
Step 1 — Scan each in-scope service (parallel subagents)
Spawn one subagent per service, concurrently. An isolated context per service is both cheap and immune to compaction mid-scan. Give each subagent the service path, its manifest entry, and these instructions:
- Declared artifacts first: OpenAPI / AsyncAPI / proto / GraphQL schemas,
package manifests, README, CI config, IaC,
.env.example. Grep application code for publish/subscribe or HTTP-client calls only where no declaration exists — that is the difference between a cheap and an expensive run. - Every fact carries
file:lineevidence. A claim without evidence is dropped. - Say
unknownrather than infer. Anything written here is about to become an automatically-loaded instruction, so a plausible guess is worse than a gap. - Read only this service. Cross-service questions are answered in Step 2.
- Return only this YAML, nothing else:
service: orders-api
stack: node/nest
summary: one line, what this service is responsible for
exposes: [{kind: http, sig: "POST /orders", evidence: "src/orders.controller.ts:24"}]
publishes: [{name: order.created, version: 2, evidence: "src/events.ts:11"}]
consumes: [{name: payment.settled, evidence: "src/handlers/payment.ts:8"}]
calls: [{target: billing, via: "env BILLING_URL", evidence: ".env.example:4"}]
third_party: [{name: stripe, evidence: "package.json:31"}]
infra: {runtime: docker, ci: github-actions, iac: none, evidence: "Dockerfile:1"}
refs_outside_registry:
[{name: legacy-api, why: "shares the Postgres schema during migration",
evidence: "CLAUDE.md:13"}]
unknown: ["no event schemas found — names taken from string literals"]refs_outside_registry is the one field you cannot infer from the filesystem: a
service nobody listed was never cloned, so nothing on disk hints that it exists. Look
for it in base-URL env vars, shared databases, generated clients pointing at sibling
paths, compose files, and the repository's own CLAUDE.md or README naming a
sibling. Return an empty list if there is none; never invent a neighbour.
Step 2 — Join the results (no subagents)
Do this yourself, in the main context. It is pure data work, and it is the whole
point of the skill: a subagent looking at orders-api cannot know who listens to
order.created, because that answer lives in other repositories.
- Match every
publishes.nameagainst every other service'sconsumes→ consumers per service. - Match every
calls.targetagainst services'exposes→ callers per service. - A name that is consumed but produced by nobody in the manifest is either external or a missing repo → flag it, do not silently drop it.
- Collect every
refs_outside_registryentry, deduplicated by name, into the registry gap list. Report it in Step 5 as a question, not a blocker: some will be genuine holes that will bite the next feature, and some will be abandoned predecessors a team stopped maintaining years ago. You cannot tell the difference from the code, and guessing wrong in either direction is worse than asking. Your job is only to make sure nobody has to notice it on their own.
Step 3 — Compose, confirm, write the seam files
Build each file from templates/service.md.
- Skip services with no seam — nothing published, no consumers, no callers, no third party. A near-empty rule file for a leaf service is pure noise.
- Except when the code contradicts the registry. If a service has no seam and
what you found disagrees with its
roleorsummaryinrepos.yaml— an empty scaffold registered as a working component, a proxy that proxies nothing, a documented dependency that does not exist — then write the file anyway, and let it say so with evidence. A service that is not what the registry claims is the most expensive thing an agent can assume, and this file is the only place that correction is delivered at the moment it matters. Apply this consistently: two scaffolds in the same run must both get a file, or neither should. - Keep each file under ~35 lines. Only one of these loads at a time — the one
whose service the agent just touched — so the cost is per service, not cumulative.
That is what the budget buys; spend it on facts that change what an agent does, and
put anything longer in
docs/system/, which is read deliberately. - Fill only what Step 1 and Step 2 established.
Deploy orderandBreaking changesare not derivable by scanning — leave them asTODO(human). Never guess an ordering. - Stamp
reflects:with the service's current short SHA.
Then show what you are about to write — new files in full, existing files as a diff — and confirm with AskUserQuestion before writing. These files are not ordinary docs: they load into context automatically and the agent treats them as instructions, so they get a review gate that a doc would not need.
Step 4 — System-level synthesis
Update only the factual sections you own, by heading, and never delete prose you did not write:
docs/system/architecture.md→## Service map,## Event graph,## Call graph. You can describe how the system is cut up; you cannot derive why. Leave the rationale headings untouched, with theirTODO(human)if still unfilled.docs/system/infrastructure.md→## Deployment surface(per service: runtime, CI, IaC). Shared infrastructure — accounts, clusters, domains, environments — lives in no sub-repo and cannot be scanned. Leave it to a human.
The approval diff from Step 3 covers these files too.
Step 5 — Manifest fill
Propose values for empty stack, role and summary fields in repos.yaml.
Never overwrite a non-empty value: those are human decisions.
Principles
- Evidence or
unknown. Nothing else reaches a file. - Not derivable →
TODO(human). A labelled gap beats a plausible fabrication. - Seams only. Anything true inside one service belongs in that service's own repo, not here. This orchestrator records only what is true between repos.
- Match the language of the repository's existing docs when writing prose.
- Never create, modify, or commit anything under
projects/.
Output
Report: services scanned vs skipped-as-unchanged vs skipped-as-no-seam; seam files
created and updated; drift found between repos.yaml and projects/; and a list of
every TODO(human) now waiting on a person — that list is the real handoff.
Then, separately and last, the registry gap: services the code depends on that are
in neither the manifest nor projects/, each with the evidence and one line on why it
matters. Ask whether each should join the registry or be dismissed as history. This is
the finding a directory listing can never produce, and the one most likely to sink a
future feature — feature-plan scopes from repos.yaml, so a service missing there is
a service the plan will never know it is about to break.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

