Brummel
ea54be6535
Replace the global ~/.config/git/ignore mechanism with a committed, per-project docs/.gitignore whose entries `specs/` and `plans/` are relative to docs/. The ignore now travels with each repo instead of living in the user's global excludes. specify (Step 3) and planner (intro) create docs/.gitignore on demand if a project has not set it up yet, so a spec/plan can never become committable. conventions.md § File layout is the single source; the onboarding fragment tells a new project to set it up. The global ~/.config/git/ignore block is removed separately (it is outside this repo).
174 lines
8.3 KiB
Plaintext
174 lines
8.3 KiB
Plaintext
# 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
|
|
|
|
Two 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`).
|
|
|
|
## Spec/plan artefacts are ephemeral
|
|
|
|
`docs/specs/` and `docs/plans/` hold only the active cycle's spec and
|
|
plan, and they are **git-ignored** — never committed. This repo carries
|
|
a committed `docs/.gitignore` with the two entries `specs/` and `plans/`
|
|
(relative to `docs/`); that ignore file is the only committed part — the
|
|
spec and plan files it covers never are. If `docs/.gitignore` is missing
|
|
when the first working file is written, the writing skill creates it.
|
|
Each spec / plan is a working file: present on disk for its own cycle,
|
|
read across sessions from the working tree, and shell-`rm`'d at cycle
|
|
close by `audit` — never `git rm`'d, since it was never tracked, so no
|
|
git-history copy survives. The durable record of a past cycle is the
|
|
design ledger only, and no durable artefact cites a spec/plan by number
|
|
or path (see `~/dev/skills/docs/conventions.md` § Lifecycle).
|
|
|
|
## 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.
|