Skip to content

docs: proof-of-done and dead-gate rules for agents - #66

Open
nodots wants to merge 2 commits into
developmentfrom
docs/agent-working-agreements
Open

nodots wants to merge 2 commits into
developmentfrom
docs/agent-working-agreements

Conversation

@nodots

@nodots nodots commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Extracts rules that until now lived only in session memory into the files agents actually load.

  • Write the failing test first — must fail pre-change, pass after; regression fixtures built from the real production input.
  • A test that has never executed is not a gate — no env-flag gating (RUN_GNUBG_HINTS=1), verify CI is enabled, read the skip count.
  • Boundaries that swallow things silently — persistence round-trip test before merge, serialization, declared dep range vs lockfile.
  • Deploy verification means running the feature, not inspecting artifacts.
  • npm release order — promote to main by fast-forward before publish.
  • Never pkill by substring — anchor the pattern or kill by PID.

Also drops the 15-second/30-second status-update cadence and its [HH:MM:SS] UPDATE #N format, a relic of early sessions. Stuck detection is kept.

https://claude.ai/code/session_01DEVew52GVgXWWN9Z6Vc5W7


Second commit on this branch: deletes the .cursor/ rule files. They were generated copies that drifted for a year (the 15-second rule removed in the first commit still existed in five of them, generated 2025-07-05), duplicating content already in CLAUDE.md. The single source is now the backgammon-rules plugin — a SessionStart hook for the non-negotiables plus backgammon-domain / nodots-engineering skills, installed with claude plugin install backgammon-rules@nodots-plugins.

Rules extracted from incidents that were only recorded in session memory:

- Write the failing test first; regression fixtures built from the real
  production input, not an approximation.
- A test that has never executed is not a gate: no env-flag gating,
  verify CI is enabled, read the skip count.
- Boundaries that swallow things silently: persistence round-trip,
  serialization, declared dependency ranges vs the lockfile.
- Deploy verification means running the feature, not inspecting artifacts.
- npm release order: promote to main (fast-forward) before publish.
- Never pkill by substring; anchor the pattern or kill by PID.

Also removes the 15-second/30-second status-update cadence and its
[HH:MM:SS] UPDATE #N format, a relic of early sessions. Stuck detection
is kept.

Claude-Session: https://claude.ai/code/session_01DEVew52GVgXWWN9Z6Vc5W7
…plugin

The .cursor rules were generated copies (config.json describes the
generator) that drifted for a year: a status-update rule removed in 2026
still existed in five of them, and every file duplicated content already
in CLAUDE.md.

Domain knowledge and engineering rules now live in one place:
nodots/backgammon-rules, installed as a Claude Code plugin from the
nodots-plugins marketplace.

Salvaged before deletion: the api's ESM/ts-node migration-consistency
checks (now backgammon-api/CLAUDE.md). Dropped deliberately: generic
boilerplate (REST verbs, HTTP status codes, "use HTTPS", "avoid memory
leaks") and a stale rule saying never to restart the API server, which
contradicts the current CLAUDE.md instruction to kill it before starting.

Claude-Session: https://claude.ai/code/session_01DEVew52GVgXWWN9Z6Vc5W7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant