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. When a fork was settled in-context but the seeding issue still lists it open, specify records the resolution as a provenance-bearing reconciliation comment on the issue (Step 1.5), which the scope-fork juror reads via issue_tracker.show_cmd — 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 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.