complex.md defines and generates COMPLEX.md, a markdown file at the root of a repository that tells a coding agent where the structural risk in the codebase lives. Computed from the dependency graph and the commit history, not written from memory. Spec at https://complex.md/spec.
npx complex-mdOne run computes the signals, writes COMPLEX.md, and wires it in: the
integration block in the agent files, path-scoped rules, the PreToolUse and
Stop hooks, and the MCP server. The package lives in cli/. Without npx,
the skill does the same by hand: download https://complex.md/complex-md.skill.md
and run it with any coding agent inside the repo.
| Path | What |
|---|---|
prompts/generate.md |
The versioned generation prompt. Single source of truth for the CLI, the skill, and the catalog worker. |
prompts/integration.md |
The normative wiring block appended to AGENTS.md, CLAUDE.md and friends. Served at /integration.md. |
cli/ |
The complex-md npm package: signals engine, generator, wiring, hooks, MCP server, diff check. npm test inside it. |
bench/ |
Localization benchmark: does the map get an agent to the right file in fewer tool calls? Real fix history, paired arms. |
docs/ |
Research behind the spec: signal verdicts, agent context-file evidence, wiring mechanics. |
content/ |
Site pages (markdown, front matter in an HTML comment). |
skill/SKILL.tmpl.md |
Template assembled with the prompt into the downloadable skill. |
scripts/build.mjs |
Zero dependency static build to dist/. |
site/ |
Stylesheet, the one script, 404. |
Issues and pull requests are welcome. The spec changes by evidence: a new
signal or rule needs a citation or a benchmark run in bench/, and a line in
CHANGELOG.md saying why. Plain prose, no emphasis words, numbers over
adjectives; read the spec for the register.
MIT. Copyright James L. Cowan Jr.
npm run build # writes dist/Serving, registry, and deploy live in the personal-platform monorepo
(sites/complex-md submodule). Deploys go through deploy-site.sh there,
never by hand.