# 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; signs specs in the user's place on the `grounding-check` `PASS` (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 below the session anchor (the one narrow
  exception is the `/boss` rollback sandbox — own unpushed autonomous
  commits above the run's start anchor)
- 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`, slug-only `slug.md` naming,
the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`),
git discipline, Gitea + `closes #N`, and the whole pipeline graph.
Specs and plans are ephemeral — git-ignored, held only for the active
cycle, then shell-`rm`'d at cycle close (never committed, so there is
nothing to `git rm` and no git-history copy); the design ledger is the
durable record and no durable artefact cites a spec/plan
(`docs/conventions.md` § Lifecycle).

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

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

Under `/boss`, the orchestrator signs a spec in the user's place rather
than pausing at the sign-off gate — so a `/boss` run carries on across
spec boundaries unattended. (Outside `/boss` the user signs every spec
directly.) The autonomous signature is the **`grounding-check` `PASS`**:
an independent fresh-context agent's verdict against currently-green
tests, not the orchestrator's confidence. On `PASS` the orchestrator
keeps the signed spec as a git-ignored working file (never committed) and
records the sign on the run's reference issue, sends a mandatory
informational notify that names the signed capability and invites a
veto, and continues to `planner` without stopping. A no-override
grounding `BLOCK` / `INFRA_ERROR` routes to the human sign-off pause.

The judgement work happens **upstream**: under the bold stance, `specify`
Step 1.5 *decides* every load-bearing fork it can derive an answer for
(from the sources, the code, consistency, risk) and records the decision
on the run's reference issue, pulling an ad-hoc `spec-skeptic` lens as a
bias-breaker when it is unsure whether its leaning is judgement or bias;
only a *pure-preference* fork bounces to the human. The former obligatory
unanimous five-lens `spec-skeptic` panel is **retired** (baseline tag
`pre-autosign-rework`) — editorial roughness it would have caught is let
through deliberately, cheap to patch inline downstream. A wrong derived
call is recovered by the user's veto or, within the run, the rollback
sandbox (`boss/SKILL.md` § Direction freedom): the orchestrator may
hard-reset its *own unpushed* autonomous commits back toward the session
anchor on a dead end. 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.