agentleFS
lifemixturelifemixture/ai-orchestration-repo/.claude/skills/system-map/SKILL.md

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

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
  1. Very specific:

    Read repos.yaml. It is the registry: every service, its url, branch, role, stack, summary.

    line 26
  2. Very specific:

    Do this yourself, in the main context.

    line 81
  3. Very specific:

    Except when the code contradicts the registry: If a service has no seam *and* what you found disagrees with its role or summary in …

    line 103
  4. Distinctive:

    Keep each file under ~35 lines.

    line 111
  5. Distinctive:

    Update only the factual sections you own, by heading, and never delete prose you did not write:

    line 127
  6. Distinctive:

    Never overwrite a non-empty value: those are human decisions.

    line 142
  7. Distinctive:

    Match the language of the repository's existing docs: when writing prose.

    line 150
  8. Very specific:

    Never create, modify, or commit anything under projects/.

    line 151

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

OutputPurpose
.claude/rules/services/<svc>.mdOne seam file per service. Path-scoped, so it enters context only when the agent touches that service
docs/system/architecture.mdFactual map of how the system is cut up (the why stays human-written)
docs/system/infrastructure.mdPer-service deployment surface (shared infra stays human-written)
repos.yamlProposed 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

  1. Read repos.yaml. It is the registry: every service, its url, branch, role, stack, summary.
  2. Parse the arguments: --only a,b restricts to those services; --full forces a rescan of everything.
  3. For each service resolve git -C projects/<svc> rev-parse --short HEAD, then read the reflects: field in the frontmatter of any existing .claude/rules/services/<svc>.md. If they match, skip that service unless --full was passed — this is what makes routine refreshes cheap.
  4. Drift check: report directories present in projects/ but absent from repos.yaml, and manifest entries with no checkout (run setup.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.
  5. Print will scan N of M services with 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:line evidence. A claim without evidence is dropped.
  • Say unknown rather 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.name against every other service's consumes → consumers per service.
  • Match every calls.target against 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_registry entry, 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 role or summary in repos.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 order and Breaking changes are not derivable by scanning — leave them as TODO(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 their TODO(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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.