Brummel
4f83305525
Add `specify` as a third co-equal entry path into the dev cycle: it produces an approved spec from already-settled sources (an exhaustive issue, a long in-context design discussion, or a design brainstorm just ratified) with review but no interview. This is the producing half of a deliberate deciding/producing split — `brainstorm` shrinks to optional discovery, `specify` becomes the sole spec-production gate before `planner`, mirroring the RED->GREEN split that keeps tdd/debug honest. What moved: - brainstorm/SKILL.md: stripped of the hard-gate, the acceptance criterion, write-spec, self-review, grounding-check, user-review, and planner-handoff steps; terminal state is now handing a ratified design narrative to specify. Steps renumbered 1-5 (production steps left). - specify/SKILL.md (new): the production core, with a precondition gate (Step 1.5) that bounces to brainstorm the moment the sources do not resolve a load-bearing decision — the same discipline tdd uses. - The grounding-check agent moved brainstorm/agents/ -> specify/agents/ (no-orphan-agents: it lives under its dispatcher), refs repointed. - boss/SKILL.md: Entry-path reflection is now three-way (tdd / specify / brainstorm). specify dispatches autonomously (bounded, no interview) and pauses at its user-review gate; only a fresh brainstorm cycle stays a pre-dispatch bounce-back. - pipeline.md, README, profile-schema, the profile template, and the migration layout updated so every pipeline rendering agrees; specify is a CORE node (not opt-in, unlike tdd) carrying gates: [planner]. Design alternative rejected: parallel sibling skills sharing a docs/spec-production.md (extract-to-doc). Chosen extract-and-chain instead — the shared surface is ~70%, so a shared doc would either become the skill body or drift; chaining keeps one executed home for the gates. Verification (prose repo, no test suite): the spec's internal- consistency grep suite (no two-path drift, no direct brainstorm->planner edge, specify referenced in every rendering, grounding-check single home under specify, specify structural completeness) all green. Orchestrator inspection additionally fixed two dead step-refs the plan under-scoped (a "(Step 4)" lift-validation pointer and a "Skipping Step 7 self-review" red flag, both pointing at steps brainstorm no longer has) and corrected six pre-existing brainstorm->planner renderings in pipeline.md and tdd that predated this cycle. Known follow-ups (non-blocking): the committed spec writes `skills/specify/` in places (typo; skill dirs are repo-top-level) — to be corrected separately. The grounding-check hard-gate was degenerate for this very cycle (this repo has no profile and no test suite); the skip is documented in the spec and the session.
147 lines
7.3 KiB
Markdown
147 lines
7.3 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, vocabulary, or domain-specific contracts. Those
|
|
live in a small per-project profile file
|
|
(`.claude/dev-cycle-profile.yml`) plus the project's `CLAUDE.md`.
|
|
|
|
## 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 the configured spec dir | Hard-gate before plan |
|
|
| `planner` | New iteration within an open cycle | plan under the configured plan dir | 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 | Opt-in 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 | User-invoked, never auto-dispatched |
|
|
|
|
Two further **utility skills** are invoked on demand rather than as
|
|
pipeline phases: `issue` (file or update a tracker item) and `glossary`
|
|
(build or maintain the project glossary — see `docs/glossary-convention.md`).
|
|
|
|
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.
|
|
|
|
Vocabulary is configurable. A **cycle** is one round in the
|
|
pipeline graph; your project may call it a *release*, an *epic*,
|
|
or whatever fits, and its sub-unit (the default *iteration*) a
|
|
*sprint* or a *story*. A **milestone** is a distinct, higher
|
|
axis — a tracker container (Gitea/GitHub milestone, Linear
|
|
project) 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.
|
|
|
|
## 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
|
|
|
|
Your project carries a small **profile** that fills the slots:
|
|
|
|
- Paths: spec dir, plan dir, design ledger, code roots, bench dir
|
|
- Commands: build, test, lint, regression scripts
|
|
- Vocabulary: cycle name, sub-cycle name, ledger-entry name
|
|
- Naming: counter prefix vs date prefix vs flat, slug shape
|
|
- Standing reading list: concrete files, per role
|
|
- Git: issue tracker kind, close marker, main-protection policy
|
|
- Pipeline customisations: which phases are mandatory, when
|
|
optional ones fire
|
|
|
|
See `docs/profile-schema.md` for the full schema and
|
|
`templates/project-profile.yml` for a copy-and-fill starting point.
|
|
|
|
## Keeping a profile current
|
|
|
|
Profile slots are versioned with the plugin, not with your project.
|
|
A new optional slot lands in `docs/profile-schema.md` and as a
|
|
commented-out block in `templates/project-profile.yml` — but an
|
|
existing profile does **not** gain it automatically. Every
|
|
consuming skill treats a missing optional slot as a documented
|
|
no-op, so an out-of-date profile never breaks; it just silently
|
|
skips whatever the new slot would have enabled.
|
|
|
|
That silence cuts both ways: a profile written before a slot
|
|
existed will quietly not run the gate the slot powers, and nothing
|
|
flags it. So after pulling a plugin update, skim the commented
|
|
blocks in `templates/project-profile.yml` and the matching sections
|
|
in `docs/profile-schema.md`; any optional section your profile
|
|
lacks is a candidate to retrofit. The slot reference lives with the
|
|
plugin, never in the project — when in doubt, the schema is the
|
|
source of truth.
|
|
|
|
### Retrofitting `spec_validation`
|
|
|
|
The `spec_validation.parsers` slot maps a markdown fence label to
|
|
the tool that validates a spec code block of that kind. It powers
|
|
the parse gates that stop a spec from shipping code blocks that do
|
|
not parse against the live tool:
|
|
|
|
- `brainstorm` Step 7 self-review — the parse-every-block gate
|
|
- `planner` Step 5 self-review — the parse-the-bytes-you-inline gate
|
|
- the `grounding-check` agent's code-block parse pass
|
|
|
|
A profile written before this slot existed has no `spec_validation`
|
|
section, so all three gates are silent no-ops there. To opt in, add
|
|
the section: map each fence label your specs use (a surface
|
|
language, a JSON-against-schema block, an IR block, …) to its
|
|
`ext` + `cmd`, where `cmd` carries the `{file}` placeholder and
|
|
exits non-zero on a parse failure. A fence label with no entry is
|
|
skipped and documented, never silently trusted. See
|
|
`docs/profile-schema.md` § `spec_validation` for the shape and
|
|
`templates/project-profile.yml` for a commented example.
|
|
|
|
## Install
|
|
|
|
See `INSTALL.md`. In short: clone, run `install.sh`, then drop
|
|
a `dev-cycle-profile.yml` into each project that should use the
|
|
plugin.
|
|
|
|
## Status
|
|
|
|
Migration from AILang's in-tree `~/dev/ailang/skills/` is in
|
|
progress. The `boss` skill is the landed pilot; the remaining
|
|
seven skills follow. See `docs/migration.md` for the per-skill
|
|
and per-agent migration checklists and the expected final
|
|
layout.
|