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.