Brummel
8e72aa5c36
Step 1.5's issue-less in-context case used to fall back unconditionally to the human sign-off: with no tracker issue, the `scope-fork` juror had no auditable source for an in-context fork resolution and (correctly) blocked, so auto-sign was structurally unreachable on that path. Close it the same way the lagging-issue case is closed — give the juror an auditable artefact instead of weakening the gate. When the cycle has no seeding issue, the orchestrator now creates one recording each resolved fork WITH provenance (a record of the user's decision, never a fresh orchestrator one). A new tracker issue is independent and auditable — unlike the self-referential spec-note the old text rejected — so it, not the orchestrator's confidence, is what the juror checks. The provenance gate is unchanged: no real user statement is a Step-1.5 bounce, not a manufactured issue; the orchestrator writes, the juror enforces. Also thread a `seeding_issue` field through the scope-fork carrier so the juror can actually find the issue to read (the lagging issue, the newly created one, or `none`). Without it the juror had no issue index and the record was invisible — a latent gap the lagging-issue path shared. - specify Step 1.5: issue-less branch creates a provenance-bearing seeding issue; body names the work (no forward ref to the unwritten spec); explicit create command; capture-the-index instruction. - specify Step 6 + handoff table: seeding_issue carrier field. - spec-skeptic: juror reads seeding_issue from the carrier; accepts provenance in a created issue's body, not only in a comment. - consistency: README, pipeline.md, design.md.
160 lines
8.6 KiB
Markdown
160 lines
8.6 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 | code + tests, uncommitted in working tree | 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 |
|
|
|
|
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;
|
|
Opus 4.8 Workflows fan out at the top level but do not lift it)
|
|
- 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.
|