[iancooper]

Summary

Brings Darker's /spec commands up to date with Brighter's.

One task list and a shiftable review gear

• /spec:ralph-tasks is removed. /spec:ralph-implement now runs the approved tasks.md, the same file /spec:implement uses, and requires .tasks-approved. It picks how to handle each task from its leading label, and marks a task it can't classify [!] instead of guessing.
• New /spec:gear shows or shifts the TDD review gear, stored in the gitignored, per-spec specs/{spec}/.current-gear:
  • review-before (approval stop armed) is the default. A missing or unparseable file, or a task outside the gear's scope, falls back to it.
  • /spec:implement resolves the gear before every task and accepts --review-before / --review-after.
  • /spec:ralph-implement sets review-after and stops cleanly when the gear is shifted back down.
• review-after removes only the approval pause. RED-first, the full test suite, the two-commit shape (the change, then a docs: tick) and the test conventions all still apply.
• New CHARACTERISE task shape: when a test already passes, RED is shown by a named, temporary change to production code, which is then reverted.
• A standalone /test-first and /bugfix:test always stop for approval. CLAUDE.md and testing.md are updated to match.
• Brighter's rationale: ADR 0071.

ADR metadata

• All 22 ADRs gain YAML frontmatter. The schema, status vocabulary and a Darker tag list are in .agent_instructions/adr_frontmatter.md. ADR bodies are unchanged.
• docs/adr/index.md is generated from the frontmatter and should not be edited by hand.
• New read_adr_metadata / write_adr_metadata skills, wired into /adr, /spec:design (prior-art lookup, stamping frontmatter, regenerating the index) and /spec:approve design (status change, supersession).

Shared ADR contract

• .agent_instructions/documentation.md gains the ADR contract that /adr, /spec:design and /spec:review all follow:
  • one skeleton, with headings used verbatim
  • Terms
  • readability rules: behaviour before structure, the orienting table or diagram first, citations kept together, sentence rules
  • correcting an ADR
  • diagram rules, including the mermaid traps and decision-ladder tables
  • checks before committing: a mermaid render, an escaped-markdown grep, and readability counts
  • writing tone for design documents
• /spec:design hands drafting to a Plan sub-agent on opus. The sub-agent checks its references against the codebase and returns the ADR plus a proposed summary and tags. The main agent validates the draft against the skeleton, runs the checks, stamps the frontmatter, regenerates the index, and adds the new ADR to each sibling ADR's "Where this ADR sits" table.
• /adr uses the same skeleton and checks.
• /spec:review design grades structure and readability, renders the diagrams, and checks writing tone, the sibling tables and the shared one-sentence rule.
• Brighter's full-shape example ADRs are linked on GitHub. Darker's existing ADRs predate the skeleton and are not restructured here.

Release notes

• New /spec:write_release_notes writes or replaces a spec's marked section in a new root release_notes.md.
• /spec:design recommends it when an ADR records a breaking change, and /spec:review design flags a breaking change with no section.

Other

• /spec:tasks hands drafting to a Plan sub-agent on opus, which returns the task list plus a coverage cross-reference.
• /spec:review tasks checks that labels come first, that the approval-gate line is present, and that each CHARACTERISE task names its mutation.
• /spec:review gains a "Working the findings — fix issues, not lines" step. Each finding is worked as a concept: every statement of that concept is edited together, the old wording is searched for again, and a narrow contradiction check runs before re-review.
• testing.md gains the "narrow and deep" guidance on when widening a module's public surface is legitimate, and why InternalsVisibleTo is rejected.

Code review phase

• /spec:review code [--base=ref] reviews the branch diff against the approved requirements, ADRs and tasks, and against Darker's code-style and testing conventions. It checks that the sync, async and streaming pipelines change together.
• Findings go to review-code.md with a verdict. When all three spec phases are approved, /spec:review with no arguments runs the code review.

Contributor guide

• New root AGENTIC_CODING.md, adapted from Brighter's. It explains how to contribute with a coding agent: choosing a workflow, the spec workflow and review gears, the bugfix workflow, PROMPT.md across sessions, and reviewing agent-authored PRs.
• New CONTRIBUTING.md with human-facing guidelines, adapted from Brighter's and from Darker's .agent_instructions. Its project-structure section matches the current src/ and test/ layout.
• Linked from README.md and CLAUDE.md. PROMPT-*.md and RALPH_STOP are now gitignored.

Not included

• /spec:show-me is still under review in Brighter.
• The GENERATE task shape: Darker has no test generator.
• The existing ralph-tasks.md files in specs 011, 013 and 014 are left as history.

For reviewers

• The ADR summaries and tags were backfilled by an agent; please check 0010, 0013 and 0015 most carefully.
• release_notes.md is a new root file. Darker previously kept release notes only in GitHub releases and per-spec drafts.

🤖 Generated with Claude Code