module-design

Files (10)

• LICENSE-design-philosophy
• SKILL.md
• design-philosophy.md
• design.md
• example-contract.md
• merge.md
• removal.md
• reviewer-common.md
• reviewer-design.md
• reviewer-simplification.md

SKILL.md (first lines)

# Module docs: contract.md is permanent, the build docs are not

- **`contract.md`** — what the rest of the system may assume of this module, and the rules keeping
  it true. Permanent. Written *before* the spec.
- **`spec.md`** — scaffolding for writing the code. **Deleted when all PRs of the module land.** Never
  named `README.md`: a doomed file must not wear a durable name.
- **`boundary.md`** — everything the module touches on the outside. Written *after* the spec, in a
  separate pass. **Deleted when all PRs of the module land**, alongside the spec.

**Default home for a durable fact is the code it is about** — call-site comment, test, docstring,
`--help`, or the commit message that made the change. `contract.md` is the narrow exception; when in doubt it is not a clause.

**One-way citation:** the doomed files may cite the contract, never the reverse. A contract citing
`spec.md §Foo` breaks when the spec is deleted.

## Resolve this skill's directory first

The rest of this skill is in files next to this one, and the reviewers are spawned with their
rubrics named by path. **Resolve the directory to an absolute path now** — an agent starts cold
and cannot resolve "next to the skill you were spawned from". It is the "Base directory for this
skill" that Claude Code printed when this skill loaded — the same line whether it came from a
plugin or a symlink. **If there is no such line** (the skill arrived as text with no path
attached), **stop and tell the user** — never guess a path.

---

## Phase 1 — starting a module

`contract.md`, then `spec.md`, then `boundary.md`, then two review agents, then reconcile.
**Read `design.md` now**, before writing any of them. No implementation code until that sequence
has finished.

## Phase 2 — at merge / commit / push

The build docs are deleted here, but only after what could not be written in advance is captured —
and that is the part that gets skipped when it is done from memory. **Read `merge.md` and follow
its seven steps** in the module's last PR. Earlier PRs commit the build docs unchanged, so the
next PR's session reads them from `main`.

From heartnetkung/claude-skills, MIT.

More from heartnetkung/claude-skills