agentsclimarketplace

Map modules

Skill nicolasapr/contract-tree/skills/map-modules

Claude Code plugin: represent a project as a tree of documented modules with boundary contracts, so an agent stays oriented in large codebases and makes boundary changes a deliberate preserve-vs-cascade decision.

Install
npx -y skills add nicolasapr/contract-tree --skill map-modules

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 21 days oldThe repository was created 21 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when bootstrapping a contract tree — either extracting module contracts from an existing codebase or designing a module tree greenfield before writing code. Produces per-module `CONTRACT.md` files and the `.contract-tree/tree.md` index.

SKILL.md

3.0 KB, 673 tokens by cl100k_base, as published. Nobody here has run it

Map Modules

Bootstrap a contract tree. Two entry modes, one output: a CONTRACT.md in each module directory plus a .contract-tree/tree.md index at the repo root.

Read references/contract-format.md first — it is the canonical on-disk format. Do not invent field names.

Which mode

  • Legacy — the code already exists; extract contracts from it.
  • Greenfield — no code yet; design the tree and contracts first, then let code fill the declared entrypoints.

You can also run legacy mode on just one area of a large repo — you do not have to map everything at once.

Legacy mode (extract from code)

Read references/extraction-heuristics.md for how to find boundaries and infer fields. Then:

  1. Walk the directory tree of the target area. Identify module candidates — directories with a cohesive purpose behind a small public surface.
  2. Go bottom-up: characterize leaf modules (no upstream) first, then parents.
  3. For each module, draft a CONTRACT.md: infer entrypoints from public exports, io.input/io.output from their signatures, upstream from cross-module imports, and invariants from what the code guarantees.
  4. Apply the granularity stop rule — don't make a contract per tiny file; stop when a module is one boundary / one purpose.
  5. Present the drafts for review. Extraction is a proposal; the user corrects intent the code doesn't state. Do not commit contracts silently.
  6. Generate .contract-tree/tree.md from the approved contracts: one indented line per module, → edges pointing at each module's downstream (derived by inverting upstream), (leaf) where none.

Greenfield mode (design first)

  1. Interview the user about the top-level split: what are the root modules, and how does each divide (the "2 modules → 5 each" shape)? Keep dividing only while each piece stays one boundary / one purpose.
  2. For each planned module, write a CONTRACT.md with purpose, intended io.input/io.output, upstream, invariants, and the entrypoints the code will expose (files/symbols that don't exist yet — that's fine; they are the contract the code must fulfill).
  3. Generate .contract-tree/tree.md from those contracts.
  4. Code is then written to fill the declared entrypoints, and change-with-contracts governs later edits.

Output checklist

  • Every module directory in scope has a CONTRACT.md valid per references/contract-format.md.
  • .contract-tree/tree.md exists at the repo root, its edges match the contracts' upstream relations (inverted), and its header note names the contracts as the I/O source of truth.
  • Only upstream was authored; downstream was derived, never hand-written.

What ships with it: 2 files

7.8 KB alongside SKILL.md

references/

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.