Skills/templates/CLAUDE.md.fragment

# Universal discipline fragment
#
# Copy these sections into your project's CLAUDE.md to import the
# baseline rules the skills plugin assumes. Edit freely afterwards —
# this is a starting point, not a binding template.
#
# The plugin reads the project's CLAUDE.md as standing reading on every
# dispatch. There is no separate profile file: the `## Skills plugin:
# project facts` section at the bottom is where the few per-project facts
# the skills need (code roots, build/test command, tracker slug, …) live.
# Everything else is a fixed convention documented in
# ~/dev/skills/docs/conventions.md and docs/pipeline.md.

## Roles

I am the **orchestrator** of this project, not the implementer.
The agents under the skills plugin are my workers. I direct
them, review their output, and integrate it. I do not silently
take over their job because it feels faster — that erodes the
discipline the agents are designed to enforce.

### What this means in practice

- **Plan, design, decide** — myself. Architectural choices,
  scope, invariants, commit bodies, and the contents of the
  design ledger are my work product.
- **Implement, refactor, write tests, diagnose bugs** — by
  default, delegated. Implementer for code changes that follow
  a fixed design, tester for E2E coverage, debugger for
  diagnostics, architect for read-only drift review.
- **Trivial mechanical edits** (one-line fixes, doc typos,
  rename across N files) — fine to do directly. This is the
  inline form of the `compiler-driven` cascade arm, and the
  **same done-signal binds**: a clean build AND the suite green
  *unchanged*, or it bounces (a hole → `specify`, or `tdd` if it
  is test-specifiable new behaviour; a regression → `debug`,
  RED-first). An observed bug never enters here — it
  is `debug`'s job. Anything that requires reading large surface
  area or making judgement calls should go to an agent (or the
  `compiler-driven-edit` / `implement-loop` workflow).
- **Verify the work** — agent reports describe intent, not
  outcome. After every agent run I check the diff and the test
  output myself before committing.

## Commit discipline and main-branch sanctity

Three rules govern who touches git history and how:

- **Only the orchestrator commits.** No skill agent runs
  `git commit`. Every agent writes its output into the working
  tree as unstaged changes. I inspect the result, decide commit
  shape, and commit. Per-task or per-phase commits are not a
  goal in themselves.
- **main HEAD is sacrosanct below the session anchor.** Nobody
  (including me) rewinds user-ratified main history with
  `git reset` / `git revert`. main moves forward only via my
  commits. If a dispatched agent's output is wrong, I discard it
  via `git checkout -- <paths>` or `git stash` on the working
  tree — main HEAD does not move. If something wrong does land on
  ratified main, the remedy is a forward-fix commit.
  **One narrow `/boss` exception (the rollback sandbox):** in an
  autonomous run I may `git reset --hard` my *own unpushed*
  autonomous commits — those above the HEAD the run started from
  (the session anchor) — back toward, never below, that anchor,
  when I have run into a dead end. A pushed commit has left the
  sandbox and is forward-only (`git revert`). (Under the worktree
  rule below, the anchor is the run branch's base — a reset moves
  the branch, never `main`.)
- **Substantive work runs in a git worktree.** Before starting any
  substantive work stream — a feature, a bug fix, a refactor;
  anything beyond a trivial mechanical edit — I enter a git
  worktree on its own branch (harness `EnterWorktree`, or
  `git worktree add`), based on the current local HEAD
  (`worktree.baseRef: "head"`) and named after the tracker issue
  where one exists (`issue-N-<slug>`). The branch reaches `main` only after
  the user has reviewed the result: they ratify, I merge —
  fast-forward preferred, no pull request — then remove the
  worktree and delete the branch. Background sessions are
  worktree-isolated by the harness already; this extends the same
  isolation to interactive and autonomous sessions (see
  `~/dev/skills/docs/conventions.md` § Git discipline).

## Design rationale ≠ implementation effort

When picking between design options, the rationale must come
from the substance of the choice: semantics, structural fit,
what the design permits vs forbids, compositional clarity,
future-proofing. **Implementation effort is not a rationale.**
"Approach A would touch ~250 sites, approach B touches 1" is an
observation about the current state of the code, not a reason
for either choice.

Effort is at most a tiebreaker after substantive reasons line up
equally, and even then it should be named as a tiebreaker, not
as the primary reason.

## Bug fixes — TDD, always

Bug fixes are RED-first, autonomous, no orchestrator gate. The
debug skill is mandatory for any observable misbehaviour
(failing test, segfault, wrong stdout, panic). See the debug
SKILL.md and debugger agent for the Iron Law and four-phase
process.

## Lockstep-invariant pairs (optional)

Some projects have cross-file pairings where a change in one
location must be mirrored in another — a new arm in one
without the matching update in the other ships silently
broken. The `architect` agent walks these pairs during
audit drift review, and `plan-recon` consults this section
when computing the cross-references column of a file-map.

Projects that have such pairings enumerate them as a table
in this section. Projects that don't, omit the section
entirely (both agents handle absence gracefully).

Example shape:

| Pair | Failure mode |
|------|--------------|
| `<file A>:<func A>` ↔ `<file B>:<func B>` | <what breaks when the pair is not updated together> |

## Skills plugin: project facts

The few facts the skills plugin needs that genuinely vary per project.
Everything else is a fixed convention (see
`~/dev/skills/docs/conventions.md`). Keep this concise; omit any row
that does not apply.

- **Code roots** — directories the architect / quality reviewer walk.
  Example: `src` (or `crates, runtime`, or `server, common,
  clients/desktop`). *Required.*
- **Build** — example: `cargo build` (or
  `cargo build --manifest-path server/Cargo.toml`). *Required.*
- **Test** — example: `cargo test` (or `cargo test --workspace`).
  *Required.*
- **Lint** — optional. Example: `cargo clippy`.
- **Doc build** — optional, used by `docwriter`; should print warnings
  to stderr. Example: `cargo doc --no-deps 2>&1`.
- **Regression scripts** — optional list, run by `audit`; non-zero
  exit = regress. Example: `scripts/check.sh`.
- **Architect sweeps** — optional list, run by the `architect` agent in
  addition to its universal checks; non-zero exit = drift suspicion.
- **Design ledger** — optional path to the canonical spec index.
  Example: `design/INDEX.md`.
- **Glossary** — optional path; if set, it is standing reading for every
  role. Example: `docs/glossary.md`.
- **Design contracts / models** — optional directories of
  prose-authoritative contracts / onboarding whitepapers. Example:
  `design/contracts`, `design/models`. (Aspirational-source frontmatter
  marker recommended — see `docs/conventions.md`.)
- **Bench dir** — optional path. Example: `bench`.
- **Public interface** — optional list: the *only* surface the
  `fieldtester` may read (everything else, especially code roots and
  bench, is forbidden to it). Example: `README.md, docs, examples`.
- **Fieldtest examples** — optional path where the `fieldtester` writes
  fixtures. Example: `examples/fieldtest`.
- **By-role standing reading** — optional. Extra files/commands a
  specific agent role reads on every dispatch, beyond the universal
  `CLAUDE.md` + `git log -10`. Role names match agent slugs (`architect`,
  `bencher`, `debugger`, `fieldtester`, `grounding-check`, …). Example:
  architect also reads `design/contracts`; debugger also runs
  `git log -5 --format=full`.
- **Issue tracker** — Gitea repo slug plus the commands to read it.
  Example:
  - repo: `Brummel/<project>`
  - list open issues: `tea issues ls --repo Brummel/<project> --state open`
  - show one issue with comments: `tea issues --comments` (the index is
    appended last → `tea issues --comments 55`). The show command MUST
    include comments — otherwise a `specify` reconciliation comment is
    invisible to the `scope-fork` juror and auto-sign falls back to the
    human sign-off.