cadence
CLAUDE.md2 starsChanged 52 days agoMITView on GitHub
Operating manual for AI agents working in this repository. Read it before touching anything. Most conventions here are backed by an enforcement layer — a git hook, a CI job, a doc-content test, or a CADENCE gate — so violating them doesn't just annoy the operator, it fails the build. Where a rule has no mechanical enforcement, that is stated, and the operator's review is the backstop. CADENCE is a draft/build/settle framework for AI-assisted development with configurable quality gates. It…
- Reads credentials
- Deletes or force-pushes
- Installs packages
- Commits and pushes
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- phase-buildSkill
- pr-landSkill
- release-cutSkill
- systematic-debuggingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 1 is distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Do not reconstruct release history from memory or from this file — it lives in packages/*/CHANGELOG.md, GitHub Releases, git log, and …
- Very specific: line 179
When deliberately running parallel agents, isolate to a worktree/branch from task 1, not reactively after noticing a files: conflict.
- Very specific: line 209
End with a handoff: Before a session closes meaningful work, write a cadence handoff doc: TL;DR, what landed, carry-forward gotchas, next …
- Distinctive: line 223
Escalate to the advisor: before committing to any of the judgment calls the gate matrix can't automate for you:
- Very specific: line 235
Before promoting a recommendation to shipped or writing a handoff — a cheap second look before the record becomes durable
- Very specific: line 257
.githooks/pre-commit— the doc-sync gate: if a commit changes the canonical version (packages/core/package.json), both CLAUDE.md (the … - Very specific: line 278
CADENCE's own gates: when working through the loop: coherence check, structural verifier, build-test-must-pass, per-AC test coverage, …
- Very specific: line 410
Before closing an audit session, enumerate every critical/P0 finding it identified and check each against …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Operating manual for AI agents working in this repository. Read it before touching anything. Most conventions here are backed by an enforcement layer — a git hook, a CI job, a doc-content test, or a CADENCE gate — so violating them doesn't just annoy the operator, it fails the build. Where a rule has no mechanical enforcement, that is stated, and the operator's review is the backstop.
What this repo is
CADENCE is a draft/build/settle framework for AI-assisted development with
configurable quality gates. It is a meta-tool: it scaffolds and runs the
DRAFT→BUILD→SETTLE loop on consumer projects, and uses that same loop on
itself. The .cadence/ directory at the repo root is not example data —
it is the live state of CADENCE planning CADENCE.
The project's core thesis: an AI agent's self-report of "done" is not proof. Gates re-derive completion from real state (tests, diffs, task records) and refuse to settle when the evidence doesn't back the claim. You are an AI agent working inside the tool built to distrust AI agents — every rule in this manual follows from that thesis, and most of the failure modes listed at the bottom are some flavor of violating it.
Current version: 1.74.0 across all five published packages (lockstep).
Do not reconstruct release history from memory or from this file — it lives
in packages/*/CHANGELOG.md, GitHub Releases,
git log, and .cadence/phases/*/. When a release bumps
packages/core/package.json, the version line above must be updated in
the same commit (the doc-sync gate below aborts the commit otherwise, and CI
re-asserts it on every OS).
Read these before working (in order)
CONTEXT.md— the canonical vocabulary and its forbidden aliases. Read it before exploring code; reviews, docs, and doc tests are written against this glossary.DESIGN.md— locked decisions (D1–D12, §12–§14), anti-goals, and deliberately rejected alternatives. LOCKED decisions are not open for relitigation; if a task seems to require reversing one, stop and say so instead of quietly doing it.docs/concepts.md— the loop, profiles × tiers, the full gate matrix.docs/reference/commands.md,docs/reference/config.md— CLI + config.AGENTS.md+docs/agents/— issue tracker (GitHub viaghCLI), triage labels (needs-triage,needs-info,ready-for-agent,ready-for-human,wontfix), domain-doc protocol.
Common commands
This is a pnpm + turbo monorepo. Run everything from the repo root.
pnpm install # one-time setup
pnpm build # turbo build, all packages
pnpm test # turbo test, all packages (vitest)
pnpm typecheck # tsc --noEmit, all packages
pnpm lint # eslint, all packages
# Single-package work:
pnpm --filter @thomas-powers-jr/cadence-core test
pnpm --filter @thomas-powers-jr/cadence-core build
pnpm --filter @thomas-powers-jr/cadence-host-claude-code typecheck
# Run a single test file or grep test name:
pnpm --filter @thomas-powers-jr/cadence-core test -- path/to/file.test.ts
pnpm --filter @thomas-powers-jr/cadence-core test -- -t "name fragment"Node >=22 is required. package.json pins pnpm@9.12.0. The local CLI is
node packages/core/bin/cadence.cjs <subcommand> (after pnpm build).
A developer's PATH pnpm may resolve to a newer globally-installed major
(e.g. v11.x); its launcher prints a warning about its own behavior ("The
pnpm field in package.json is no longer read by pnpm...") before
self-switching and delegating to this repo's packageManager-pinned
pnpm@9.12.0, which reads and applies pnpm.overrides correctly — trust
the lockfile, not the launcher's warning.
Architecture
Six packages, one engine, three surface categories (CLI · host adapters ·
MCP). Source of truth is pnpm-workspace.yaml + each package's
package.json.
| Package | Role |
@thomas-powers-jr/cadence-core | The engine. CLI (cadence binary), DRAFT→BUILD→SETTLE state machine, all gates, parsers, renderers. ~All logic lives here. |
@thomas-powers-jr/cadence-types | Zod schemas + TypeScript types. Pure data layer — no logic, no I/O. Imported by every other package. |
@thomas-powers-jr/cadence-host-claude-code | Claude Code adapter (reference HostAdapter). Installs lifecycle hooks + slash commands; shims host events to the core dispatcher. |
@thomas-powers-jr/cadence-host-codex | OpenAI Codex CLI adapter, second HostAdapter contract consumer. |
@thomas-powers-jr/cadence-host-toolkit | Shared toolkit for the two host adapters (phase 222): the hook-routing algorithm's shape, the slash-command catalog, install.ts's managed-marker merge logic, and locate-self.ts. Depended on by both adapters as workspace:*; never imported by core. |
@thomas-powers-jr/cadence-testkit | private, dev-only. Mock host + ephemeral-repo fixtures + assertions used by every package's tests. Never published. |
Five packages publish to npm; testkit is intentionally private.
host-toolkit had its first npm publish in the 1.51.1 release. Releases are
cut with
changesets and the manual
Release workflow (.github/workflows/release.yml, workflow_dispatch) —
npm publish is always operator-triggered, never automatic.
Dependency arrows are strict: adapters translate lifecycle events only
and never duplicate engine logic (packages/host-claude-code/src/event-map.ts
shim.ts); core never imports host code — where core needs a host action it spawns the host package as a subprocess (thestart/init --wire-hostlauncher discipline). MCP (cadence mcp serve) exposes the imperative loop only, over stdio; ambient edit-time gates need host hooks.host-toolkitfollows the same direction: both adapters depend on it, core never does — it holds host-adapter-shared plumbing, not engine logic.
The loop and its artifacts
IDLE → SPEC → DRAFT → BUILD → SETTLE → IDLE (SPEC optional). Per-phase
artifacts live in .cadence/phases/<phase>/<id>-{SPEC,DRAFT,PROGRESS,SUMMARY,
PLAN-REVIEW,...}.{md,json}. Two state files are regenerated on every state
write: .cadence/state.json (machine-readable) and .cadence/STATE.md
(derived human view — never hand-edit).
A DRAFT's body has a fixed shape — keep it when authoring or editing one:
## Objective (one paragraph) · ## Acceptance Criteria (### AC-N: <name>
as Given/When/Then prose) · ## Tasks (### TN: <name> with - files: /
- action: / - verify: / - done: AC-N lines, optional - depends:) ·
## Boundaries (an explicit "Do NOT touch / Do NOT add" list). Prefer the
structured writers (cadence draft new --template …,
draft set-objective/add-ac/add-task) over hand-editing — a hand-typed
heading typo has silently corrupted AC/task sequencing before.
Gates
The gate universe (14 gates: 3 always-fire + 11 deltas) is defined in
packages/core/src/gates/engine.ts. The full matrix and bypass flags are in
docs/concepts.md — when changing gates, update engine.ts and
docs/concepts.md together; do not duplicate the table anywhere else.
Three AI verifier providers (mock, anthropic, local) live under
packages/core/src/verify/. mock is the default: deterministic, offline,
and a placeholder, not real verification — operator-facing docs must
keep saying so (a doc test enforces the framing).
Know what settle run --auto actually proves: it derives per-AC PASS from
task terminal status + coverage evidence, and build-test-must-pass runs the
configured verification.testCommand. If no test command is configured it
prints a loud notice and cannot corroborate the suite — that notice is a
signal to fix config or verify manually, not background noise.
How the operator works — match this workflow
The repo owner drives work through CADENCE's own loop and expects an agent session to do the same. The shape of a healthy session:
- Orient before acting.
git fetch origin --prune,git status --short --branch,gh pr list, thencadence resume(read-only) to replay the freshest.cadence/handoff/SESSION-*.md, andcadence progress/cadence recommendfor the next suggested action. Handoff docs carry explicit "do not" lines and carry-forward gotchas — obey them; they override your instincts. Their state blocks say "pre-filled — verify, don't retype": check live git/npm/GitHub before trusting any replayed fact. Never run two sessions against the same phase/draft at once; if resuming after a session that looks stuck or crashed, confirm the old one is actually dead first, then resume in place — reattach to its worktree/session — rather than spinning up a fresh session or worktree against the same draft (see "The Zombie Session" below). - A unit of work is a phase, dogfooded. New work is usually sourced
from a Praxis recommendation (
cadence recommend), converted to a phase, and run as SPEC/DRAFT → BUILD → SETTLE with real gates. Do not build features "outside the loop" unless the operator says so. The process is locked to CADENCE — do not migrate it to GSD or any other framework (borrowing a point-tool skill at an irreversible juncture is the only sanctioned exception). - TDD is the house style (
CONTRIBUTING.md). Every feature and bugfix starts with a failing test, then implementation, then commit. Tests live inpackages/<pkg>/tests/mirroringsrc/. Use@thomas-powers-jr/cadence-testkitephemeral-repo fixtures rather than rolling your own. - Non-trivial phases run subagent-driven in an isolated worktree
(
.claude/worktrees/<slug>; prefer the native worktree tools over manualgit worktree add): one implementer + one independent reviewer per task, then a final whole-branch review that must come back clean before merge. When deliberately running parallel agents, isolate to a worktree/branch from task 1, not reactively after noticing afiles:conflict. - Every completion claim is re-verified independently. Subagent (or
your own) "done" is confirmed by reading the diff and re-running the full
suite + typecheck + lint yourself — never by accepting the worker's
report. Releases likewise: after the Release workflow reports success,
independently confirm
npm viewversions, the git tag, and the GitHub release. - Single-commit settle convention. A completed phase produces exactly
one commit: source + tests + docs + phase artifacts (
.cadence/phases/**) together, once the loop's own gates have verified the work — no separatechore: settlecommit after it. The moment verification passes, promote any recommendation the phase closes toshipped(cadence recommendation promote <id> --status=shipped --ref "...") in that same commit, then push — don't defer the promotion to a later pass.state.jsonandSTATE.mdare gitignored by default and never enter the commit — thestateAtSettlefield inSUMMARY.json/SUMMARY.mdis their audit-trail replacement. Operator-owned, not hook-enforced. Supersedes the prior two-commit split (feature commit, then a separate settle commit) as of 2026-07-22. - Land via branch + PR, squash-merged.
mainis branch-protected: three status checks are required —ci-success(ci.yml),security-success(security.yml) andcodeql-success(codeql.yml) — andenforce_adminsis on, so even the owner cannot push a red commit directly, and a red security or CodeQL run blocks the merge just as a red test leg does. Conventional-commit subjects carrying the phase id, e.g.feat: wave-based subagent dispatch (phase 159) (#149). One logical change per PR. Feature PRs add their own.changeset/*.md— do not defer changesets to the release PR (that slipped once and cost the release phase five retroactive changesets). - End with a handoff. Before a session closes meaningful work, write a
cadence handoffdoc: TL;DR, what landed, carry-forward gotchas, next action. Assume the next reader is a fresh session with zero context.
Model selection
Session default is Sonnet at xhigh effort with an Opus advisor available
mid-turn (~/.claude/settings.json: model: sonnet + advisorModel: opus +
effortLevel: xhigh, set 2026-07-30). The advisor reads the full conversation
— every tool call, every result, every dead end — and returns judgment, not
edits. General mechanics, escalation heuristics, and its tool-less limitation
live in the global ~/.claude/CLAUDE.md ("Opus advisor pattern"); this
section covers only what's specific to working in CADENCE.
Escalate to the advisor before committing to any of the judgment calls the gate matrix can't automate for you:
- Authoring or amending a DRAFT's Acceptance Criteria / Task breakdown, or a SPEC, before it goes to review
- Interpreting a LOCKED
DESIGN.mddecision, resolving a phase-collision or worktree-placement ambiguity, or deciding whether a gate bypass is genuinely warranted - Reconciling conflicting subagent completion claims before trusting a "done" report — see "The Self-Report Trust" below, the failure mode this whole repo is built to catch
- Two architectural approaches are live and the tiebreaker isn't mechanical
- Before promoting a recommendation to
shippedor writing a handoff — a cheap second look before the record becomes durable
The advisor does not satisfy CADENCE's own independence requirements —
the whole-branch review before settle (item 4 above), or a second look on a
subagent's "done" claim. It shares this session's transcript and therefore
its blind spots. Get a real independent look from a fresh-context subagent
(Agent(..., model: "opus")) or a separate host (CADENCE_HOST_CLI_BIN=codex)
instead — never a self-review, and never an advisor consult standing in for
one. This is the same reason cadence spec approve's built-in review gate
silently falls back to mock when run from inside a headless Claude Code
session: it detects it's already nested in a headless claude invocation
(packages/core/src/verify/host-cli-client.ts, the self-invocation guard)
and refuses to spawn a second one rather than risk unbounded recursion. When
that happens, dispatch a real independent review manually — don't treat the
mock fallback's pass as one.
Enforcement layers — what will stop you
.githooks/pre-push(wired viagit config core.hooksPath .githooks): runspnpm turbo run lint typecheck test buildbefore any push updatingrefs/heads/main. Bypass with--no-verifyonly when you mean it..githooks/pre-commit— the doc-sync gate: if a commit changes the canonical version (packages/core/package.json), bothCLAUDE.md(the version line near the top) andCHANGELOG.md(its newest## [x.y.z]heading) must mention the new version string or the commit aborts. The pure checker is.githooks/check-doc-sync.sh;packages/core/tests/docs/doc-sync-hook.test.tsre-asserts the invariant in CI. The pre-push hook re-checks it as a backstop.- CI (
.github/workflows/ci.yml): the same four-command pipeline on Ubuntu + macOS + Windows on Node 22, aggregated into theci-successcheck. It is one of three required checks onmain, alongsidesecurity-success(.github/workflows/security.yml: secret scan,pnpm auditand the lockfile-overrides check) andcodeql-success(.github/workflows/codeql.yml); the record isdocs/security/audit-exceptions.md. - Doc-content tests (
packages/core/tests/docs/*.test.ts+ host packages): executable assertions that named docs match code truth — the command reference vs the registered CLI command set, slash-command counts vs installed files, config docs vs schema defaults, README claims vs behavior, the canonical "one core engine and three surface categories" vocabulary. If a behavior or doc change fails one, fix the pair — never loosen the test. - CADENCE's own gates when working through the loop: coherence check,
structural verifier,
build-test-must-pass, per-AC test coverage, boundary enforcement, the phase-collision guard, and the rest of the matrix.
Code conventions
- TypeScript strictness:
tsconfig.base.jsonturns onstrict,noUncheckedIndexedAccess, andexactOptionalPropertyTypes. Indexed access isT | undefined; optional fields cannot be explicitly set toundefined(omit the key — conditional spread). ESLint enforcesconsistent-type-imports— useimport type { ... }. - Pure core / impure shell. The house pattern everywhere: a pure,
dependency-injected function (
planInit,detectPhaseCollision,buildExplanation,resolveInteractivity, …) taking all external facts as arguments, plus a thin impure wrapper that gathers those facts. New logic follows this split — it is what makes the TDD style cheap. - Best-effort introspection never throws. Git/fs/env observation code (occupancy scans, handoff discovery, doctor checks) degrades to "no information" on any failure. Only a genuinely detected problem is a hard failure.
- Refuse + suggest, never silently mutate. On a conflict (phase collision, clobbering write) the engine refuses loudly, names the conflict, and suggests the fix. It never auto-renumbers, auto-overwrites, or silently falls back.
- stdout is a contract; diagnostics go to stderr.
--jsonoutput and the MCP stdio protocol own stdout. Warnings, banners, notices, and the structured logger (getLogger(), default-silent) write to stderr only. - Zero-runtime-dependency bias. The logger is homegrown; the MCP SDK is lazy-loaded off the CLI hot path. Do not add a runtime dependency without the operator's explicit sign-off.
- Additive, backward-compatible schema changes. New Zod fields get
.default(...)/.optional(); pre-existing artifacts must keep parsing. YAGNI is applied deliberately, and rejected scope is recorded in DESIGN.md ("dropped, not deferred"), not just omitted. - Vitest workers are capped.
vitest.shared.tsis the single source of truth for test timeouts (20s; 90s on win32) and a core-aware worker cap of at most 12 (resolveMaxWorkers). Each package'svitest.config.tsmerges it and adds onlyinclude. - Test ↔ AC linkage. Under the coverage gate each AC must be referenced
by its
AC-Ntoken in a test file — and inassertionmode (the default for new inits) the token must sit inside an assertingit()/test()block. Tests exercising this live inpackages/core/tests/verify/. - Tests never call real providers.
mockonly (plus theCADENCE_PROMPTER_SCRIPTseam for interactive flows); nothing in the suite may depend onanthropicorlocal.
Named failure modes
Each entry: a mistake a capable-but-unguided model makes in this repo, and the rule that prevents it — with the enforcement layer where one exists.
State, artifacts, and history
- The Freshen Reflex. Regenerating or tidying
.cadence/ROADMAP.md,MILESTONES.md, orphases/*because they look stale. → These are live planning records of real work; edit only when the work itself requires it. When a plan-time assumption proves false, the fix is an inline "As built" amendment, not a rewrite. (Operator review only — which is exactly why this is written down.) - The Hand-Edited STATE.md. Fixing
.cadence/STATE.mddirectly. → It is a derived render, regenerated on every state write; the edit is discarded on the next write. Change state through the CLI. (Gitignored by default — the file is still live on disk and still gets clobbered by hand-edits.) - The Mid-Loop Sweep.
git restore-ing or otherwise discarding uncommitted.cadence/state.json/STATE.mddirt while a loop is active. → That dirt is live telemetry — the current loop position. Both files are gitignored by default and never committed; leave them alone until the loop transitions naturally, don't hand-revert them mid-loop. - The Helpful Stage.
git add -Asweeping in local-only files:.agents/,launch/,.claude/scheduled_tasks.lock, accumulated uncommittedSESSION-*.mdhandoffs (swept periodically in deliberate housekeeping PRs, not ad hoc), or.claude/settings.jsonafter a--localinstall (machine-absolute paths). → Stage explicitly; handoff docs list what stays local. In particularlaunch/COMPETITIVE.mdis local-only by explicit decision — never commit, force-add, push, or PR it. - The Stale Handoff Replay. Acting on a handoff doc's state block or
recommendation list without checking the live repo. →
cadence resumeis read-only by design (D10); livestate.jsonandoriginare authoritative. Sibling git worktrees each hold a fully private.cadence/— check.claude/worktrees/*/.cadence/handoff/before assuming the primary checkout's state is complete. - The .keel Cleanup. "Modernizing"
.keel/paths or pre-Phase-12 KEEL references in design docs. → The KEEL→CADENCE rename (Phase 12,v0.2.0-rc.1, 2026-05-14) is a load-bearing transition narrative;DESIGN.md §8.3even preserves rejected names. Leave history alone.
Language
- The Bare "standard". Writing "standard" unqualified. → It is both a
profile and a tier, and
standard × standardis a real cell. Always "standard profile" or "standard tier" (CONTEXT.md, Flagged ambiguities). - The Phase/Slice Conflation. Calling one loop-trip a "phase". → A
phase is the numbered directory/theme; a slice is one trip through the
loop (
17-02). DESIGN.md's legacy "Phase 17.2" prose means the slice. - The Synonym Drift. Substituting "mode" for profile, "step" for task,
"the brain" for Praxis, "retry loop" for convergence. →
CONTEXT.mdlists the avoided aliases per term; use the canonical word. - The Verifier Catch-All. Calling every AI gate "the verifier". → The
verifier is specifically the
--deepper-AC agent; the umbrella term is review agent — andstructural-verifier, despite its name, does no behavioral verification at all.
Verification honesty (the thesis, applied to you)
- The Self-Report Trust. Accepting a subagent's "task complete, all tests passing" — or your own recollection of one — as done. → Re-verify independently: read the diff, re-run the full suite + typecheck + lint yourself. Subagents in this repo have twice claimed all-green over real failures, and shipped an ordering bug the independent review caught.
- The Token Drop. Satisfying the coverage gate by mentioning
AC-Nin a comment. → Write a real test that asserts the behavior;assertioncoverage mode exists precisely to refuse comment-only mentions. Gaming the gate defeats the product. (Enforced: test-coverage gate.) - The Convenient Bypass. Reaching for
--force,--allow-*, orgit push --no-verifyto get green. → Bypasses exist for operators who mean it; they are loud and recorded in the SUMMARY (gateBypasses). Fix the root cause; if a bypass is genuinely right, say so explicitly. - The Mock Mirage. Treating a green
deep-verifyunder themockprovider as real verification. → Mock is a deterministic placeholder;cadence doctorreports whether real verification is wired. - The Speculative Stamp. Hardcoding a next version number or release date into docs mid-feature. → Version strings enter docs in the release phase via changesets. A whole-branch review has caught exactly this.
- The Premature "Done". Claiming success from memory or a partial run. → State what was run and show the outcome; if tests fail, report the failure verbatim. In this repo the claim of done is the product surface under test.
- The Unlogged Audit Finding. A strategic-audit session (an agent
auditing the existing codebase/implementation against prior findings)
surfacing a critical/P0 finding and then closing without filing it. →
Before closing an audit session, enumerate every critical/P0 finding it
identified and check each against
.cadence/intelligence/recommendations.json(matching by title/area/ evidence keyword — a mechanicalledger-diffstep); file anything with no matching rec viacadence recommendation addbefore the session ends. Precedent: the v1.47.0 audit's assurance-levels P0 was partially executed from memory and never reached the ledger — half of it later shipped under other names beforerec-20260724-002caught the gap anddec-20260724-001picked this fix (2026-07-24). (Operator review only — no automated enforcement for the diff step itself; the doc-content test only proves the instruction exists, not that a session followed it.)
Code discipline
- The Per-Test Band-Aid. Adding a per-test timeout or retry to quiet a
flake. →
vitest.shared.tsis the single source for timeouts/workers; the band-aids were tried and reverted (Phase 32.1). Root-cause it. - The Undefined Assignment.
obj.field = maybeUndefinedon an optional field. →exactOptionalPropertyTypesrejects it; omit the key. (Enforced: typecheck.) - The Unchecked Index.
arr[i].propwithout narrowing. →noUncheckedIndexedAccessmakes indexed accessT | undefined. (Enforced: typecheck.) - The Runtime Type Import.
import { SomeType }for a type-only use. →import type { ... }. (Enforced: lint.) - The stdout Leak.
console.logfor a diagnostic. → stdout belongs to--jsonand the MCP protocol; diagnostics go to stderr or the logger seams. (The hook context-payloadconsole.logis the one intentional stdout contract.) - The Engine-in-Adapter. Implementing gate/loop logic inside a host adapter. → Adapters map lifecycle events to abstract events; the engine decides. (Enforced: adapter-contract conformance + prompt-parity golden fixtures.)
- The Host-in-Core.
import-ing host-adapter code from core. → Core spawns host packages as subprocesses; the dependency arrow never points core→host. - The Testkit Leak. Adding
cadence-testkitas a runtime dependency or publishing it. → Dev-only,private, forever. - The Live-Provider Test. A test that needs
ANTHROPIC_API_KEYor a local model. → Tests usemock; offline determinism is non-negotiable. - The Throwing Observer. Letting a git/fs introspection helper throw and take a command down. → Observation code is best-effort: contribute nothing on failure, never block the command.
- The Quiet Fallback. Falling back (to mock, to a default, to a skip) without telling anyone. → Every fallback and auto-bypass in this codebase prints a loud stderr notice and/or records provenance in the SUMMARY. Match that pattern.
Docs
- The Doc Drift. Changing gate behavior, CLI flags, or config schema
without the paired doc edit. →
engine.ts↔docs/concepts.md; command changes ↔docs/reference/commands.md(a marker-block test diffs it against the registered command set); config fields ↔docs/reference/config.md. (Enforced:packages/core/tests/docs/*.) - The Version-Silent Bump. Bumping
packages/core/package.jsonwithout updating this file's version line. → (Enforced: doc-sync hook + CI test.) - The Hardcoded Count. Writing "14 slash commands" as a literal from
memory. → Counts and command lists are asserted against code truth
(
docs-command-count.test.ts); derive them, then write. - The Untested Version Reference. Assuming a green
pnpm turbo run testproves every doc is in sync at release time. → The automated doc-content tests only assert thatCLAUDE.md/README.mdmention the new version; docs likeDESIGN.mdcarry their own version references (DESIGN.md's "Current architecture (as of vX.Y.Z)" line slipped once, v1.43.0 cut) that no test covers. Therelease-cutskill's step 3, Doc- sync verification, is the mandatory backstop: run the full doc-content test surface explicitly, then grep the repo for the previous version string and triage every hit. Run it on every release. (Operator review only — no automated enforcement for the grep sweep.)
Git and process
- The Direct Push. Pushing to
mainbecause the change is "trivial". → Branch protection requiresci-success,security-successandcodeql-success, and applies to admins too; a direct-push hole once let an OS-specific CI red sit undetected for six phases. Branch + PR, always. (Enforced: GitHub branch protection.) - The Wrong-Checkout Commit. Committing to the primary checkout when the
work belongs to a worktree (or vice versa) — a subagent has done exactly
this. → Verify
git rev-parse --show-topleveland the branch before committing; phase worktrees live under.claude/worktrees/. - The Zombie Session. Resuming a stuck or crashed session by spinning up
a fresh session or worktree against the same phase/draft, instead of
confirming the old one is actually dead first. → Two sessions racing the
same draft corrupt
PROGRESS.json/state.jsonnon-deterministically. Confirm the old session is dead (no live terminal/process still holding it), then resume in place — reattach to the existing session/worktree — rather than starting fresh elsewhere.cadence doctor'sphase-freshnesscheck flags very recent per-taskPROGRESS.jsonactivity as a signal to go check, not proof either way. - The Assumed Consent. Running destructive git (
git reset --hard, force-push, history rewrite) or self-merging a PR you opened, on the strength of a generic "continue" or "use best judgment". → Restate the exact command and its blast radius and get explicit operator confirmation first. No exceptions. - The Stale Status Check. Trusting a
git statusrun minutes earlier before a shared-tree git operation (stash, reset, checkout ontomain) that mutates state other work may now depend on. → Re-checkgit statusimmediately before the operation, not from a check done earlier in the session — an intervening subagent, background build, or second terminal can change the tree in between. - The Multi-Phase Commit. Bundling more than one phase's work into a single commit or PR. → Single-commit settle convention means one phase's source + tests + docs + artifacts land together — not multiple phases squashed into one shot. One phase, one commit, one PR.
- The Deferred Changeset. Merging a feature PR without a
.changeset/*.md. → The feature PR carries its changeset; the release PR only consumes them. - The Release Re-Run.
gh run rerun --failedon theReleaseworkflow after a red or ambiguous run. → That re-runspnpm -r publishand fails on already-published versions. Since phase 323 the release-integrity step waits out registry propagation itself (about 10 minutes of polling), so a red there deserves investigation rather than a shrug. First verify reality independently —npm viewall five packages,git ls-remote --tags,gh release view— and only act on what is actually missing. - The Auto-Renumber. Resolving a phase-number collision by silently
picking a new number. → The guard's contract is refuse + suggest
(
max(observed)+1); the operator decides. Never bypass the local same-directoryexistsSyncrefusal. - The Windows Panic. Treating a Windows-local test failure as caused by
your change. → The dev box is Windows but Linux CI is canonical; a few
Windows-local failures are known environment issues (pnpm/tempRepo/spawn
races). Check CI before debugging. Related traps: the git hooks are bash;
child_process.spawnofnpxneedsshell: trueon win32; path separators have broken tests before — compare paths with the existing helpers (isSameWorktree), not string equality. - The Flake Reflex (both directions). Endlessly re-running a genuinely
red CI leg, or re-investigating a known flake from scratch. → Known
reference: a macOS/Node22 timeout flake in
settle-codereview-convergence.test.ts. Re-run once only when a single leg is red and the diff can't plausibly touch it; otherwise investigate.
Historical naming
Pre-Phase-12 artifacts under .keel/ are intentionally preserved as a
transition narrative. The project was renamed KEEL → CADENCE in Phase 12
(v0.2.0-rc.1, 2026-05-14). DESIGN.md §8.3 lists rejected names.
<!-- deja:start -->deja
ACTION: before writing a new function/component, call deja_find (oracle MCP)
to check whether an equivalent already exists in the repo. ACTION: before
adding a new dependency, call deja_check_dep to check whether an existing
dependency or project function already covers it. deja_peek reads a
candidate's full source.
Note: these are MCP tools — if they only appear by name in a deferred-tools
list, call ToolSearch first (e.g. select:deja_find,deja_check_dep,deja_peek)
to load them before you can call them.
Edits are also gated automatically against near-duplicates
(PreToolUse/PostToolUse hooks) — a block means reuse the existing function,
or use the deja:new override token for a genuine intentional rewrite.
<!-- deja:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

