Brummel
540741e6e9
Three minor-issues + three optional follow-ups identified by the three parallel reviewers of debug/docwriter/audit, fieldtest/planner/brainstorm, and implement. None blocking; all close calibrated gaps the bulk migration left. Minor-issues: - audit/SKILL.md: handoff field `regression_results` now explicitly carries "raw output verbatim (no rounding, no summarisation)" — restores the verbatim-numbers emphasis the original `bench_numbers` field name implied. - audit/agents/bencher.md: hypothesis examples grouped by axis (Tail-latency / Count reduction / Scalability / Overhead vs floor) with concrete numerical anchors (2× of median, ≥80%, 10-million-element, ±15%). Subjects stay domain-neutral but the calibrated bite returns. The preamble enumerates plausible subjects (allocators, query plans, request handlers, parsing strategies, codecs, caches) so the reader has concrete domains to anchor on. - implement/agents/implementer.md: "Architecture rules" section gains a 5-bullet kind-list (determinism contracts; backend / FFI constraints; schema versions; memory / resource models; effect / capability discipline) so the implementer has scaffolding to look for even when the project's CLAUDE.md is sparse. The "BLOCKED on contradiction" mechanism stays the load-bearing rule. Optional follow-ups: - brainstorm/SKILL.md Step 7.5: failure-mode procedure restores the structured backlog-issue fields (Title / Label / Body with `depends on:` and `context:` lines) and the milestone-container option for big deferred work (Gitea milestones, GitHub milestones, Linear projects). - templates/CLAUDE.md.fragment: adds an optional "Lockstep-invariant pairs" section so projects that have cross-file pairings can declare them in a way the architect agent and plan-recon agent already know to consult. Projects without such pairings omit the section; both agents handle absence gracefully. No discipline regressions; no Iron Law / Common Rationalisations / Red Flags edits. Pure scaffold-and-anchor improvements.
89 lines
3.6 KiB
Plaintext
89 lines
3.6 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.
|
|
|
|
## 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. Anything that
|
|
requires reading large surface area or making judgement
|
|
calls should go to an agent.
|
|
- **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.** Nobody (including me) runs
|
|
`git reset` or `git revert` on main. 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 main, the remedy is a forward-fix commit,
|
|
never a rewind.
|
|
|
|
## 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> |
|