Skills/README.md

# 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; can optionally sign specs in the user's place (opt-in, see below) | 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:

- `specify` Step 4 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.

### 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 with
`pipeline.boss.spec_auto_sign: true`.

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, the parse-every-block
  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. 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 drop
a `dev-cycle-profile.yml` into each project that should use the
plugin.

## 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.