# Map Modules

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

- **Type:** Skill
- **Install:** `agentstack add skill-nicolasapr-contract-tree-map-modules`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nicolasapr](https://agentstack.voostack.com/s/nicolasapr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nicolasapr](https://github.com/nicolasapr)
- **Source:** https://github.com/nicolasapr/contract-tree/tree/main/skills/map-modules

## Install

```sh
agentstack add skill-nicolasapr-contract-tree-map-modules
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

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

- **Author:** [nicolasapr](https://github.com/nicolasapr)
- **Source:** [nicolasapr/contract-tree](https://github.com/nicolasapr/contract-tree)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nicolasapr-contract-tree-map-modules
- Seller: https://agentstack.voostack.com/s/nicolasapr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.