Files

T

Brummel 8e72aa5c36 feat(specify): create a seeding issue for issue-less in-context auto-sign

Step 1.5's issue-less in-context case used to fall back unconditionally
to the human sign-off: with no tracker issue, the `scope-fork` juror had
no auditable source for an in-context fork resolution and (correctly)
blocked, so auto-sign was structurally unreachable on that path.

Close it the same way the lagging-issue case is closed — give the juror
an auditable artefact instead of weakening the gate. When the cycle has
no seeding issue, the orchestrator now creates one recording each
resolved fork WITH provenance (a record of the user's decision, never a
fresh orchestrator one). A new tracker issue is independent and
auditable — unlike the self-referential spec-note the old text rejected
— so it, not the orchestrator's confidence, is what the juror checks.
The provenance gate is unchanged: no real user statement is a Step-1.5
bounce, not a manufactured issue; the orchestrator writes, the juror
enforces.

Also thread a `seeding_issue` field through the scope-fork carrier so
the juror can actually find the issue to read (the lagging issue, the
newly created one, or `none`). Without it the juror had no issue index
and the record was invisible — a latent gap the lagging-issue path
shared.

- specify Step 1.5: issue-less branch creates a provenance-bearing
  seeding issue; body names the work (no forward ref to the unwritten
  spec); explicit create command; capture-the-index instruction.
- specify Step 6 + handoff table: seeding_issue carrier field.
- spec-skeptic: juror reads seeding_issue from the carrier; accepts
  provenance in a created issue's body, not only in a comment.
- consistency: README, pipeline.md, design.md.

2026-06-16 12:50:11 +02:00

8.6 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	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	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; can optionally sign specs in the user's place (opt-in, see below)	User-invoked, never auto-dispatched

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
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

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, 4-digit per-directory naming, the vocabulary above, standing reading (CLAUDE.md + git log -10), git discipline, Gitea + closes #N, and the whole pipeline graph.

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
Spec auto-sign (off by default)

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 (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 by enabling spec auto-sign in its CLAUDE.md project facts.

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 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, specify gives the scope-fork juror an auditable source for it (Step 1.5): a provenance- bearing reconciliation comment when a seeding issue exists but lags the discussion, or a freshly created seeding issue when the cycle had none — either read via the project's issue show command, 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 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.

8.6 KiB Raw Blame History