Map Modules

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.

1. Go bottom-up: characterize leaf modules (no upstream) first, then parents.
2. 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.

1. Apply the granularity stop rule — don't make a contract per tiny file; stop

when a module is one boundary / one purpose.

1. Present the drafts for review. Extraction is a proposal; the user corrects

intent the code doesn't state. Do not commit contracts silently.

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

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

1. Generate .contract-tree/tree.md from those contracts.
2. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nicolasapr
• Source: nicolasapr/contract-tree
• License: MIT

Install and usage instructions live in the source repository linked above.