Brummel
26e9630496
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing). Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign. Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
5.7 KiB
Design
Why split plugin from project
The skills system originally evolved inside the AILang project,
where it grew organically against AILang's specific paths,
build commands, vocabulary, and contracts. Lifting it into a
plugin requires a clean separation between what is universal
(belongs in the plugin) and what is project-specific (belongs
in the project's CLAUDE.md).
The litmus test: would a sentence in a SKILL or agent body
still make sense in a Python web project, a Rust CLI, and a
TypeScript library? If yes, plugin. If it mentions cargo,
crates/, docs/design/INDEX.md, Form A, or any project-specific
identifier, it goes to the project's CLAUDE.md — either as a
project fact (the few mechanical facts the skills consume) or as
sittenkodex (domain contracts, anti-patterns).
There is no separate profile file. An earlier design had a
per-project dev-cycle-profile.yml, but it was never parsed — it
was prose the skill bodies told the model to read, and almost every
slot was constant across projects, dead, or derivable. So the
constant parts became fixed conventions (conventions.md) and the
genuinely-varying parts moved into each project's CLAUDE.md.
Plugin layer (universal)
The plugin owns:
- Pipeline form — the directed graph of phases:
design → plan → execute → review → close, with the bug-driven side pathdebug → execute (mini). - Hard-gates — spec before plan, plan before implement, audit before cycle-close. Skipping rules are codified per skill.
- Agent template — every agent file follows the same structure: frontmatter (name, description, tools), Iron Law, standing reading list, numbered process, status protocol, output format, common rationalisations, red flags.
- TDD as an independent inner-loop discipline — the implementer agent carries TDD even when the plan task forgot to script a RED-first step.
- RED-first bug fixes — non-negotiable for any observable misbehaviour; the debug skill is the gate.
- Status protocol —
DONE / DONE_WITH_CONCERNS / PARTIAL / BLOCKED / NEEDS_CONTEXT, plus reviewer-specific terminal states. - Working-tree-as-quarantine — agents write artefacts to the working tree, never commit. Only the orchestrator commits.
- main HEAD sacrosanct — no reset, no revert, by any actor. main moves forward only via orchestrator commits.
- No nested subagent dispatch — a hard Claude Code platform constraint; the implement-orchestrator runs phases as sequential role-switches inside its own context. Opus 4.8 added Workflows as an orthogonal top-level fan-out mechanism but did not lift this constraint — a workflow script orchestrates from the top level, yet the agents it spawns still cannot spawn further agents.
- No orphan agents — every agent lives under the skill that dispatches it.
- Output budget discipline — agents have word budgets on their reports.
Fixed conventions (universal)
The constants that used to be configurable but were the same in
every project are now plugin conventions, named directly in skill
and agent bodies and documented once in conventions.md:
spec dir docs/specs, plan dir docs/plans, 4-digit per-directory
naming, the vocabulary cycle / iteration / milestone / contract,
standing reading (CLAUDE.md + git log -10), git discipline
(only-orchestrator commits, main sacrosanct), Gitea + closes #N,
and the whole pipeline graph (see pipeline.md).
Project facts (project-specific)
The handful of facts that genuinely vary per project live in the
project's 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,
spec-validation parsers, by-role standing reading, the issue-tracker
repo slug and commands, and spec auto-sign. The template is in
../templates/CLAUDE.md.fragment; the per-fact reference is the
table in conventions.md.
Resolution model
The plugin uses convention-and-fact prompts, not template rendering and not a config parser. Each SKILL.md and agent file is generic prose that either names a fixed convention directly or points at a project fact:
Write the spec to
docs/specs. Use the project's build command (its CLAUDE.md project facts).
The project's CLAUDE.md is always in context (it is standing
reading #1), so the model resolves the facts at read-time. This
avoids a build step and keeps a single source of truth in the repo.
Sittenkodex split
The plugin does not carry project-specific anti-patterns,
feature-acceptance gates, or domain contracts. Those belong in
the project's own CLAUDE.md. The plugin only carries the
universal discipline constants (only-orchestrator commits,
main sacrosanct, no orphan agents, agents-don't-call-agents)
which are conditions for the plugin's own correctness.
The relationship:
- Plugin (this repo): mechanics, universal discipline, fixed conventions
- Project CLAUDE.md: project facts — the few mechanical facts the skills consume (code roots, build/test, tracker slug, …) — plus sittenkodex (domain-specific anti-patterns and acceptance criteria)
What's out of scope for this plugin
- Issue-tracker integration: the plugin reads the project's
issue-tracker commands (the repo slug, list command, and
single-issue-with-comments command, all in its CLAUDE.md project
facts) and invokes them, and
specifymay post a reconciliation comment via the tracker's comment command — but the plugin does not directly call Gitea / GitHub / Linear APIs. Every read and write goes through the configured shell command, so the plugin remains transport-agnostic.