CLAUDE.md@.claude git:20261106.663bb55A

Immutable. This exact content never changes and is served at /api/v1/blob/d23c6fce507b8245.

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