Contract tree

Skill nicolasapr/contract-tree/skills/contract-tree

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 contract-tree

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 working in a codebase that has (or should have) a contract tree — a `.contract-tree/tree.md` index and per-module `CONTRACT.md` files. Explains the module-tree + boundary-contract model and routes to map-modules, change-with-contracts, or check-drift.

SKILL.md

2.6 KB, 547 tokens by cl100k_base, as published. Nobody here has run it

Contract Tree

Large codebases overwhelm agents: as a project grows you lose track of how modules fit together, and a change to one module ripples into others you can't see. A contract tree fixes this by making each module's boundary explicit and cheap to read, so you orient with a few targeted reads instead of scanning everything, and boundary changes become a deliberate decision instead of an accident.

Mental model

Module = directory. Any directory holding a CONTRACT.md is a module; subdirectories with their own contract are submodules.
Boundary contract (CONTRACT.md) — each module declares its purpose, I/O, the modules it depends on (upstream), its invariants, and its code entrypoints. This is the source of truth.
Index (.contract-tree/tree.md) — a regenerable map of the whole tree plus the resolved dependency graph, so you can compute what depends on what with a single read. If the index and a contract disagree, the contract wins.

See ../map-modules/references/contract-format.md for the exact on-disk format, and references/principles.md for why the model works — a CONTRACT.md is a Design-by-Contract spec (precondition/postcondition/invariant), boundary changes are classified by backward compatibility (SemVer), blast radius is change impact analysis, and coupling strength is read as connascence.

Routing — which sub-skill

Situation	Skill
No contract tree yet, or a new area to document — extract contracts from existing code, or design a module tree greenfield before writing code	map-modules
About to change code in a repo that has a contract tree	change-with-contracts
Suspect the contracts have gone stale (e.g. after a large merge) — audit contract-vs-code	check-drift

If a repo has no .contract-tree/ at all and you are about to change code, run map-modules first (at least for the area you are touching), then change-with-contracts.

Sync discipline (applies to every flow)

A change that alters a module's boundary updates that module's CONTRACT.md in the same task. A stale contract is a bug, not a backlog item — because every other flow trusts the contract. When in doubt about whether the tree still matches reality, run check-drift.

What ships with it: 1 file

6.5 KB alongside SKILL.md

references/

principles.md6.5 KB