Brummel
8e72aa5c36
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.
130 lines
5.7 KiB
Markdown
130 lines
5.7 KiB
Markdown
# 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 path `debug → 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,
|
|
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 `specify` may post a reconciliation
|
|
comment or create a seeding issue via the tracker's comment / create
|
|
commands — 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.
|