Brummel
7a58a530b1
The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.
Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
a verification/enumeration axis ahead of the settled-vs-fork question.
Each lighter arm carries a positive trigger matched by signature, not
reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
that propagates mechanically. Observe-then-bounce — make the edit,
build, run the suite; clean build AND suite green unchanged commits;
a hole bounces up (specify for a design choice, tdd for discovered
test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
mechanical/forwarding -> compiler-driven; encodes new behaviour ->
tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
not a heavy new skill ("the largest concrete win is small").
Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
phase (implementer -> spec-compliance -> quality, + tester for E2E) is
a separate top-level agent() call, so a single phase is independently
invokable and inter-phase aggregation/re-loop is code. Retires the
implement-orchestrator agent's inline-role-switch workaround (the four
phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
only the autonomous/mechanical loops moved. try-and-error is deferred.
Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.
Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).
closes #7
158 lines
7.4 KiB
Plaintext
158 lines
7.4 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.** 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> |
|
|
|
|
## 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.
|
|
- **Spec auto-sign** — optional; default off (human signature required).
|
|
Set to **enabled** to let a `/boss` run sign a spec in the user's place
|
|
through `specify`'s auto-sign gate (every objective gate green AND a
|
|
unanimous five-lens `spec-skeptic` panel; the orchestrator's own
|
|
confidence never signs). See `boss/SKILL.md` § "Spec auto-sign".
|