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
186 lines
10 KiB
Markdown
186 lines
10 KiB
Markdown
# skills
|
|
|
|
A self-contained set of development-cycle skills and agents for
|
|
Claude Code. Originally distilled from the AILang project's
|
|
in-tree `skills/` directory and generalised so it can carry the
|
|
same discipline across any project.
|
|
|
|
The plugin is **mechanics**: pipeline shape, hard-gates, TDD,
|
|
RED-first bug fixing, agent-template, working-tree-as-quarantine,
|
|
status protocol. It does **not** know your project's paths,
|
|
build commands, or domain-specific contracts. Those few facts live
|
|
in the project's own `CLAUDE.md` under a `## Skills plugin: project
|
|
facts` heading; everything else is a fixed convention (see
|
|
`docs/conventions.md`). There is no separate profile file.
|
|
|
|
## What's in the box
|
|
|
|
The pipeline skills, each with the agents it primarily dispatches:
|
|
|
|
| Skill | Trigger | Output | Mandatory? |
|
|
|-------|---------|--------|------------|
|
|
| `brainstorm` | New cycle with an open design | ratified design handed to `specify` (writes no spec itself) | Optional discovery front-end |
|
|
| `specify` | Design settled in sources, or handed over by `brainstorm` | spec under `docs/specs` | Hard-gate before plan |
|
|
| `planner` | New iteration within an open cycle | plan under `docs/plans` | Hard-gate before implement |
|
|
| `implement` | Plan exists, OR a debug/tdd RED handoff | code + tests, uncommitted in working tree (via the `implement-loop` Workflow) | Standard iteration path |
|
|
| `audit` | Cycle closing OR baseline drift suspected | drift report + regression report | Mandatory at cycle close |
|
|
| `debug` | Bug observed | RED test in working tree + cause analysis | Mandatory RED-first for any bug |
|
|
| `tdd` | Test-specifiable feature / issue (third entry path, alongside `brainstorm` and `specify`) | RED executable-spec in working tree → `implement` mini-mode | Standard entry path; bounces to `brainstorm` on a design fork |
|
|
| `fieldtest` | Orchestrator-dispatched post-audit | example fixtures + friction spec | Per-cycle optional; milestone fieldtest is the closing gate for a surface-touching milestone |
|
|
| `docwriter` | API surface stable across N cycles | rustdoc / docstring sweep | Optional |
|
|
| `boss` | User types `/boss` | autonomous-orchestrator session — dispatches the other skills until done-state or bounce-back; can optionally sign specs in the user's place (opt-in, see below) | User-invoked, never auto-dispatched |
|
|
|
|
**Entry is a selector cascade, not a single door.** New feature work is
|
|
routed on a verification / enumeration axis, walked top to bottom, first
|
|
match wins: an observed bug → `debug` (RED-first, always first); a design
|
|
fork → `brainstorm`; a **behaviour-preserving type/signature edit at a
|
|
definition site** → the `compiler-driven` arm; new behaviour pinnable as
|
|
one assertion → `tdd`; everything else → spec-driven (`specify` →
|
|
`planner`). The `compiler-driven` arm is **observe-then-bounce**: make the
|
|
edit, build, run the suite — clean build AND suite green *unchanged*
|
|
commits; a hole bounces up (`specify`, or `tdd` for test-specifiable new
|
|
behaviour), a regression bounces to `debug`. It is not a standalone skill
|
|
but an arm of `implement` plus a shipped Workflow.
|
|
|
|
**The autonomous execution loops run on the Workflow substrate.** The
|
|
per-task implement loop and the compiler-driven loop are shipped as
|
|
Workflow scripts under `implement/workflows/` (`implement-loop.js`,
|
|
`compiler-driven-edit.js`), symlinked into `~/.claude/workflows/` by
|
|
`install.sh`. A Workflow orchestrates from the top level, so each per-task
|
|
phase (implementer → spec-compliance → quality) is a real,
|
|
independently-invokable `agent()` call — which retired the old
|
|
`implement-orchestrator` agent's inline-role-switch workaround. The four
|
|
phase agents survive as the agent-types the scripts dispatch. The
|
|
interactive paths (`specify`, `brainstorm`) stay prose skills — their
|
|
oracle is human intent and needs a human in the loop.
|
|
|
|
Three further **utility skills** are invoked on demand rather than as
|
|
pipeline phases: `issue` (file or update a tracker item), `glossary`
|
|
(build or maintain the project glossary — see `docs/glossary-convention.md`),
|
|
and `wiki` (write or edit a repository-wiki article — durable, project-neutral,
|
|
sourced knowledge, deliberately kept out of `docs/` and the pipeline).
|
|
|
|
One **conversational skill** stands outside the pipeline entirely:
|
|
`pseudo` (typed `/pseudo`) switches replies into commented,
|
|
human-readable pseudocode for explaining code — each answer opens
|
|
with a source-file-and-line anchor, marks notable steps with
|
|
reference markers that are pointing handles for the user (not
|
|
footnotes — explanations stay inline at the code, never in a
|
|
legend below), sketches the layout of the data structures the
|
|
code touches alongside the
|
|
flow, reduces the irrelevant to stubs, and omits low-level
|
|
mechanics. The pseudocode leans on the source language's idiom
|
|
in a language-tagged fence so it renders with syntax
|
|
highlighting, and keeps comments sparse — on their own line and
|
|
only where the code is not self-explanatory. Prose is allowed
|
|
only in a supporting role — the pseudocode block stays the
|
|
centre of every answer. It dispatches no agents.
|
|
|
|
The vocabulary is fixed. A **cycle** is one round in the
|
|
pipeline graph, and its sub-unit is an **iteration**. A
|
|
**milestone** is a distinct, higher axis — a Gitea milestone
|
|
that spans potentially many cycles and closes only when
|
|
the work it promised is complete *and* functional (see
|
|
`docs/pipeline.md` § Milestone-close gate). A cycle close is a
|
|
loop step; it is never a milestone close. A single design-ledger
|
|
entry is a **contract**. (A project with a glossary may pin
|
|
different domain nomenclature — see `docs/glossary-convention.md`.)
|
|
|
|
## The two-layer split
|
|
|
|
This repo (the **plugin**) carries everything that is universal:
|
|
|
|
- Pipeline form: `design → plan → execute → review → close`
|
|
- Hard-gates between phases
|
|
- TDD as an independent inner-loop discipline
|
|
- RED-first bug fixes
|
|
- Agent template (frontmatter / Iron Law / standing reading /
|
|
process / status / output / rationalisations / red flags)
|
|
- Status protocol: `DONE / DONE_WITH_CONCERNS / PARTIAL / BLOCKED
|
|
/ NEEDS_CONTEXT`
|
|
- Working-tree-as-quarantine and only-orchestrator-commits
|
|
- main HEAD sacrosanct
|
|
- No nested subagent dispatch (Claude Code platform constraint;
|
|
Workflows orchestrate at the top level but do not lift it — the
|
|
execution loops run as Workflow scripts so their phase agents are
|
|
top-level calls, not nested ones)
|
|
- No orphan agents
|
|
|
|
The constants that used to be configurable but were the same in
|
|
every project are now **fixed conventions** — named directly in the
|
|
skills and documented once in `docs/conventions.md`: spec dir
|
|
`docs/specs`, plan dir `docs/plans`, 4-digit per-directory naming,
|
|
the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`),
|
|
git discipline, Gitea + `closes #N`, and the whole pipeline graph.
|
|
|
|
The handful of facts that genuinely vary per project live in the
|
|
project's own `CLAUDE.md` under `## Skills plugin: project facts`:
|
|
|
|
- Code roots; build / test / lint / doc-build commands
|
|
- Regression scripts; architect sweeps
|
|
- Design ledger / glossary / contracts / models / bench / public
|
|
interface / fieldtest-examples paths
|
|
- Per-role standing reading
|
|
- Issue-tracker repo slug + list / show commands
|
|
- Spec auto-sign (off by default)
|
|
|
|
The per-fact reference is the table in `docs/conventions.md`; the
|
|
copy-and-fill template is `templates/CLAUDE.md.fragment`. There is no
|
|
profile file and no parser — the skills read these facts from the
|
|
project's `CLAUDE.md`, which is standing reading on every dispatch.
|
|
|
|
### Spec auto-sign (opt-in)
|
|
|
|
By default a `specify` dispatch in a `/boss` session pauses at its
|
|
user-review gate for the user's signature — the human approves every
|
|
spec before any plan is built. A project that wants `/boss` to run
|
|
unattended across spec boundaries can opt in by enabling spec
|
|
auto-sign in its CLAUDE.md project facts.
|
|
|
|
With it on, the orchestrator may sign a spec in the user's place, but
|
|
never on its own confidence. Signing requires two stages to clear:
|
|
|
|
- **Objective gates** — the precondition gate and a `grounding-check`
|
|
`PASS` with no human override.
|
|
- **A unanimous adversarial panel** — the `spec-skeptic` agent
|
|
dispatched five times in parallel, one per lens (`criterion`,
|
|
`grounding`, `scope-fork`, `ambiguity`, `plan-readiness`), each
|
|
trying to *refute* the spec. All five must return `SOUND`.
|
|
|
|
A `BLOCK` is never signed over. The five lenses split by what a `BLOCK`
|
|
means: an *editorial* one (`criterion`, `ambiguity`, `plan-readiness` —
|
|
the spec is under-articulated) the orchestrator repairs in a bounded
|
|
loop (edit, re-run the objective gates, re-dispatch all five lenses, up
|
|
to 2 rounds); a *design* one (`scope-fork`, `grounding` — the ground is
|
|
not settled), an `INFRA_ERROR`, any objective gate not green, or an
|
|
exhausted budget falls back to the human sign-off pause the spec would
|
|
have hit anyway. Re-dispatching all five lenses every round is the
|
|
backstop that stops an editorial repair from quietly settling a design
|
|
question. When a fork was settled in-context, `specify` gives the
|
|
`scope-fork` juror an auditable source for it (Step 1.5): a provenance-
|
|
bearing reconciliation comment when a seeding issue exists but lags the
|
|
discussion, or a freshly created seeding issue when the cycle had none —
|
|
either read via the project's issue show command, closing the blind spot
|
|
where the in-context entry path could otherwise never clear that lens.
|
|
On a clean sign the orchestrator commits the spec
|
|
(`(boss-signed)` in the subject), sends a mandatory informational notify
|
|
that names the signed capability and invites a veto, and continues to
|
|
`planner` without stopping. A later veto is a forward correction, never
|
|
a history rewind. See `specify/SKILL.md` Step 6,
|
|
`specify/agents/spec-skeptic.md`, and `boss/SKILL.md` §"Spec auto-sign".
|
|
|
|
## Install
|
|
|
|
See `INSTALL.md`. In short: clone, run `install.sh`, then add a
|
|
`## Skills plugin: project facts` section to each project's
|
|
`CLAUDE.md` (template in `templates/CLAUDE.md.fragment`).
|
|
|
|
## Status
|
|
|
|
The migration from AILang's in-tree `~/dev/ailang/skills/` into
|
|
this plugin is complete — the pipeline skills, the `specify` and
|
|
`tdd` entry paths, the `boss` orchestrator, and the utility and
|
|
conversational skills documented above have all landed.
|
|
`docs/migration.md` records the repo-layout convention and the
|
|
per-skill and per-agent authoring checklists.
|