CLAUDE.md@.claude · diff

git:20261011.879e485 to git:20261106.663bb55

1 added, 0 removed. Audit A to A.

# CLAUDE.md

Entry point for an agent working on devcycle's own source (not on a repo devcycle is

running against).

## What this is

devcycle is a Claude Code plugin. `commands/*.md` are its runtime entry points (what

`/devcycle:*` loads), `playbooks/*.md` are the behavior specs each stage follows, and

`references/*.md` are the shared mechanism docs those playbooks and commands point to

instead of restating. There is no build step and no `package.json` — scripts run directly

under Node. The pinned Node version is in `.nvmrc`.

## Commands you'll actually run

- `node scripts/validate.mjs`

- `node scripts/redaction-check.mjs`

- `node scripts/duplication-check.mjs`

- `node scripts/xref-check.mjs`

- `node scripts/temp-dir-check.mjs` — fails on any temp directory created outside

`scripts/temp-dir.mjs`'s `makeTempDir`, which is what owns removing it again

- `node --test tests/unit/*.test.mjs`

- `claude plugin test .` — the hooks module's TypeScript tests under `tests/mod/`, run from the repo root; CI runs it on both pinned Claude Code versions

- `node scripts/doctor.mjs` (local only)

- `node scripts/find-state-files.mjs` — enumerates every `.devcycle/state.md` for `/devcycle:continue`'s resume discovery; Node-walks the tree so the gitignored `.devcycle/` can't hide a state file

## Done means

Every gate in `CONTRIBUTING.md` § Before opening a PR passes. A single test file runs as

`node --test tests/unit/<name>.test.mjs`. `scripts/citation-grammar.mjs` and

`scripts/context-report.mjs` are local worklist and report tools; the rules they surface are

gated by `scripts/validate.mjs` (its citation-grammar and closure-budget checks).

## Rules that fail late

- A `${CLAUDE_PLUGIN_ROOT}`-prefixed path is a read; a bare path names an owner —

`references/README.md` § Citation grammar.

- One owner per concept: move a rule, don't copy it — `CONTRIBUTING.md` § One owner per concept.

- Line and closure ceilings live in `tests/fixtures/*budget*.json` and move, up or down, only with

a `docs/decisions/README.md` entry naming the new figure (`scripts/validate.mjs` check 28).

+ - A PR body names an issue — `Closes #n` for a full fix, `Refs #n` to leave it open, or a `No issue` line; a closing keyword only takes effect once the release PR carries it to `main` — `CONTRIBUTING.md` § Closing issues.

- `docs/devcycle/promotions/` and `docs/devcycle/maintenance-findings/` are ledgers written by

`/devcycle:learn` and `/devcycle:maintain` — not hand-edited, not read wholesale.

## Before you trust a doc

Docs here have been wrong before — content read from a stale cache looked authoritative

and wasn't. Verify a doc's claim against the live repo directly: `commands/`, `playbooks/`,

`references/`, and `docs/README.md`.

## Structure changes and doc changes move together

A code or structure change here is not done until `README.md`, the relevant `docs/` page,

and the hub index reflect it — in the same change, not a follow-up.