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 starting | 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 (alternative to `brainstorm`) | 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 the user can point back at, sketches the
layout of the data structures the code touches alongside the
flow, reduces the irrelevant to stubs, omits low-level
mechanics, and never runs longer than one screen. 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.