Files

T

Brummel 08bc2aa027 refactor(pipeline): specs/plans are gitignored working files, never committed

Per-cycle specs and plans stop being git-tracked commit-then-git-rm
artefacts and become git-ignored working files: created on disk for the
active cycle, read across sessions from the working tree, and shell-rm'd
at cycle close by audit. Nothing is committed, so there is no
git-history copy — the durable record of a cycle's intent is the design
ledger only, and no durable artefact (code, test, doc, ledger) may cite
a spec/plan by number or path.

- conventions/pipeline/design/README: invert the git-tracked -> git-rm
  -> git-history-recovery model to gitignored -> shell-rm -> ledger-only.
- naming: drop the NNNN file counter; files are slug.md (fieldtest specs
  keep a fieldtest- prefix as the cycle-close discriminator).
- cycle number: separated from the (now-gone) file number, sourced from
  the feat(NNNN)/audit(NNNN) commit subjects, which cycle commits carry.
- specify/planner/fieldtest/fieldtester: no commit step; fieldtest splits
  fixtures (committed as code) from its spec (gitignored), with the
  cross-cycle rule that a fieldtest- spec belongs to the next cycle.
- boss: auto-sign auditability moves from the (boss-signed) commit
  subject to the run's reference issue; rollback reverts only code.
- audit: new Step 5 shell-rm's the cycle spec+plan after the architect
  reads them, sparing fieldtest- specs.

Companion machine config (outside this repo): the global git excludes
(~/.config/git/ignore) gains docs/specs/ and docs/plans/ so the ignore
applies to every project at once.

2026-07-02 11:35:06 +02:00

10 KiB

Raw Blame History

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.

10 KiB Raw Blame History