Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

skeleton: plugin layout + docs, skill/agent migration deferred to iter 1

Browse Source 
Establishes the repository structure for the skills plugin:
- README + INSTALL describing the two-layer split (plugin
  mechanics vs per-project profile)
- docs/design, profile-schema, pipeline, agent-template covering
  the universal discipline constants and the profile slot model
- templates/project-profile.yml as a copy-and-fill starting point
- templates/CLAUDE.md.fragment with the baseline orchestrator
  rules a project can import
- install.sh / uninstall.sh wiring skills/ + agents/ into
  ~/.claude/ via idempotent symlinks
- skills/ and agents/ directories empty except for migration
  READMEs; the actual SKILL bodies and agent files migrate
  from ~/dev/ailang/skills/ in the next iteration.

No skill or agent runs yet — this commit only stands up the
structure and documents the substitution model.
This commit is contained in:
Brummel
2026-05-28 14:20:13 +02:00
commit 253273b007
13 changed files with 1039 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent-template.md
+182
View File
@@ -0,0 +1,182 @@
# Agent template
Every agent file follows the same structure. Deviations need a
named reason in the agent's own body. The template was distilled
from the AILang in-tree agents and refined to remove project-
specific identifiers.
## File layout
```
---
name: <agent-slug>
description: <third-person, "Use when…" or role description>
tools: <comma-separated tool list>
---
> Violating the letter of these rules is violating the spirit.
## What this role is for
<one short paragraph naming the failure mode the agent exists
to prevent>
## Standing reading list
<list of always-binding documents — derived from the project
profile's `standing_reading.always` plus `standing_reading.by_role.<this-role>`>
## Carrier contract
<what the dispatching skill hands the agent: task_text, diff,
hypothesis, etc. Agents do NOT open the project's plan or spec
directories directly — context curation lives at the skill level>
## Iron Law
<the non-negotiable rules of this role, as a numbered list>
## The Process
<numbered steps>
## Status protocol
<which terminal states this agent uses, and what evidence each
state requires>
## Output format
<word-budgeted, structured>
## Common Rationalisations
| Excuse | Reality |
|--------|---------|
| … | … |
(Calibrated to the past failure modes of this role.)
## Red Flags — STOP
- If you're about to do <X>, stop.
- …
```
## Frontmatter conventions
### `name`
The agent slug, lowercase kebab-case. No project prefix (the
old `ailang-*` prefix was an AILang-only convention; the
plugin's agent path is enough disambiguator).
Examples: `architect`, `bencher`, `debugger`, `implementer`,
`tester`, `fieldtester`, `docwriter`, `grounding-check`,
`plan-recon`, `spec-reviewer`, `quality-reviewer`,
`implement-orchestrator`.
### `description`
One sentence. Third-person. Either "Use when…" or a role
description. This is what the orchestrator (or a skill) reads
to decide whether to dispatch the agent — keep it sharp.
### `tools`
Comma-separated list of Claude Code tool names. No agent
receives `Agent` in its tools (no nested subagent dispatch).
The dispatching skill composes; agents do not call other
agents.
Common tool sets:
- Read-only review (architect, spec-reviewer, quality-reviewer,
grounding-check, plan-recon): `Read, Glob, Grep, Bash`
- Implementation (implementer, tester, debugger, docwriter,
fieldtester, bencher): `Read, Edit, Write, Bash, Glob, Grep`
- Orchestrator (implement-orchestrator): `Read, Edit, Write,
Bash, Glob, Grep` — same as implementer; the orchestration
happens via sequential role-switches within its own context
## Sections in detail
### Spirit-letter lead-in
The single line `> Violating the letter of these rules is
violating the spirit.` is mandatory at the top. It exists to
forestall the "well, technically I didn't break the rule" class
of rationalisation.
### What this role is for
One short paragraph. Names the failure mode the agent exists to
prevent — not the success mode it enables. Failure-mode framing
is sharper for the model: "this role exists because past attempts
to do X without a dedicated reviewer led to Y" reads more
forcefully than "this role helps with X".
### Standing reading list
The plugin's skill body computes this from the project profile
(`standing_reading.always` + `standing_reading.by_role.<role>`)
and passes the resolved list to the agent via the carrier. The
agent's body says, prosaically: "Read everything in the standing
reading list before doing anything else."
The agent file itself does not hardcode file paths.
### Carrier contract
The carrier is the small payload the skill hands the agent. It
typically includes:
- `task_text` — the spec excerpt or plan task verbatim
- `diff` — for reviewers, the diff to review
- `hypothesis` — for the bencher, what it should test
- `bug_symptom` — for the debugger, the observable misbehaviour
- `drift_focus` — for the architect, what part of the ledger to
check
Agents do **not** open the project's plan or spec directories
directly to fish for context. Context curation lives at the
skill level so the orchestrator can see exactly what each agent
was told.
### Iron Law
Numbered list of the non-negotiable rules. These are the rules
the agent will violate if it rationalises. Calibrate to past
failure modes — abstract rules don't land; rules anchored to a
named past mistake do.
### The Process
Numbered steps. Each step is concrete — "Read X", "Run Y",
"Write to Z" — not abstract phases like "explore" or "synthesise".
### Status protocol
Specifies which terminal states the agent uses (see
`pipeline.md`) and what evidence each state requires. For
example: `DONE` requires "build green AND tests green AND no
new warnings".
### Output format
Word-budgeted. Structured — usually a small set of named
sections the orchestrator can quote in its commit body. The
budget prevents agent reports from drowning the orchestrator's
context.
### Common Rationalisations
A table of excuse → reality. Calibrated to the past failure modes
of this role. The point is to short-circuit the rationalisation
before it derails the agent's process.
### Red Flags — STOP
Bullet list of "if you're about to do this, stop" signals.
Concrete, not abstract. "If you're about to write a fix without
a failing test, stop" beats "be disciplined".
docs/design.md
+120
View File
@@ -0,0 +1,120 @@
# Design
## Why split plugin from profile
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 a per-project profile).
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/`, `design/INDEX.md`, `Form A`, or any project-specific
identifier, it goes to the profile (as a slot) or to the
project's `CLAUDE.md` (as sittenkodex).
## 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.
- **No orphan agents** — every agent lives under the skill
that dispatches it.
- **Output budget discipline** — agents have word budgets on
their reports.
## Profile layer (project-specific)
The profile fills slots that the plugin's prose references
generically. Concretely:
- **Paths**: `spec_dir`, `plan_dir`, `design_ledger`,
`design_contracts`, `design_models`, `code_roots`, `bench_dir`.
- **Commands**: `build`, `test`, `lint`, `regression` (list).
- **Vocabulary**: `cycle`, `subcycle`, `ledger_entry`.
- **Naming**: `counter_dirs`, `policy` (`stable_per_directory_4digit`
or `date_prefix` or `flat`).
- **Standing reading**: `always` (a list), `by_role` (a map
from role to list).
- **Git**: `main_sacrosanct` (bool, default true),
`only_orchestrator_commits` (bool, default true),
`issue_tracker.kind` (`gitea` / `github` / `linear` / `none`),
`issue_tracker.close_marker` (e.g. `"closes #N"`).
- **Pipeline customisations**: per-phase `mandatory_before`,
`mandatory_at`, `boss_only`, `when` (a condition tag).
The full schema lives in `profile-schema.md`. The functional
starting template is `../templates/project-profile.yml`.
## Resolution model
The plugin uses **profile-driven prompts**, not template
rendering. Each SKILL.md and agent file is generic prose that
references the profile prosaically:
> Write the spec to the directory configured under `paths.spec_dir`
> in the project profile. Use the naming policy configured under
> `naming.policy`.
When Claude Code loads the skill, the project profile is in
context (the skill body explicitly instructs the model to read
it first). The model performs the substitution 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
- **Profile** (per project): slots — paths, commands,
vocabulary, naming, git conventions, pipeline customisations
- **Project CLAUDE.md**: sittenkodex — domain-specific anti-
patterns and acceptance criteria
## What's out of scope for this plugin
- **Boss/autonomous-orchestrator mode**: AILang's `boss` skill
is gated to a user-invoked `/boss` for autonomous queue
execution. Whether that generalises across projects is
unclear (queue mechanics depend on issue-tracker semantics).
Not in the initial skeleton; possibly added later as
`skills/boss/` if a cross-project autonomous mode crystallises.
- **Issue-tracker integration**: the plugin can read the
profile's `issue_tracker.kind` and adjust commit-marker
suggestions, but does not directly call Gitea / GitHub /
Linear APIs.
docs/pipeline.md
+129
View File
@@ -0,0 +1,129 @@
# Pipeline
```
[new cycle] [bug observed]
| |
v v
brainstorm -> plan -> implement debug -> implement (mini)
(per iteration loop)
|
[cycle close]
|
v
audit --(drift)--> plan + implement (tidy iteration)
--(ratify)-> --update-baseline + ratify paragraph in audit commit body
--(clean)-+
|
[orchestrator: cycle complete? if surface-touch:]
v
fieldtest --(bug)------> debug -> implement (mini)
--(friction)-> brainstorm OR plan (tidy)
--(spec_gap)-> ratify OR tighten ledger
--(clean)----+
|
[orchestrator: surface stable across N cycles?]
v
docwriter
|
v
next cycle
```
## Phase descriptions
### brainstorm
Hard-gate before plan. Gathers requirements, explores 2-3
approaches with trade-offs, presents a sectioned design with
user approval, writes the spec to the configured `spec_dir`.
### planner
Hard-gate before implement. Produces a placeholder-free,
bite-sized implementation plan in the configured `plan_dir`
that the implement skill can execute task-by-task. Dispatches
the plan-recon agent for read-only file-structure mapping.
### implement
Dispatches the implement-orchestrator agent, which runs the
entire per-task loop (implementer phase → spec-compliance check
→ quality check) as sequential role-switches inside its own
context. Writes code, tests, and stats files directly in the
working tree as unstaged changes. On `PARTIAL` or `BLOCKED`,
also writes `BLOCKED.md` at the repo root.
### audit
Runs at cycle close. Dispatches the architect agent (read-only
drift review against the design ledger) and the bencher agent
(regression diagnostics). Reports drift and regress.
### debug
Runs whenever a bug is observed. RED-first: produces a failing
test in the working tree before any fix is attempted. Hands off
the GREEN side to the implement skill in mini mode.
### fieldtest
Optional. Orchestrator-dispatched after the audit closes clean
on a cycle that touched user-visible surface. Picks 2-4 real-
world tasks within the cycle's scope, implements them using
only the design ledger and public examples (never the language's
own implementation), runs the results, and writes a friction-
and-bug spec.
### docwriter
Optional. Orchestrator-dispatched after API surface has
stabilised across multiple cycles. Brings docstrings up to a
level where a newcomer can navigate the public API without
reading the design ledger first.
## Status protocol
Agents return one of these terminal states:
| State | Meaning |
|-------|---------|
| `DONE` | Task complete; no concerns. |
| `DONE_WITH_CONCERNS` | Task complete; flagged issues the orchestrator should weigh before committing. |
| `PARTIAL` | Task partially complete; the rest is blocked or out-of-scope. Writes `BLOCKED.md`. |
| `BLOCKED` | Task cannot proceed; explanation in report. Writes `BLOCKED.md`. |
| `NEEDS_CONTEXT` | Task cannot proceed without additional information from the orchestrator. |
Reviewer agents have role-specific states:
| Role | States |
|------|--------|
| spec-reviewer | `compliant` / `non_compliant` / `unclear` / `infra_blocked` |
| quality-reviewer | `approved` / `changes_requested` / `infra_blocked` |
## Skip rules
Skipping is codified per skill, not ad hoc. Each `SKILL.md`
documents what the skill skips and under what conditions:
- `brainstorm` is never skipped at cycle start.
- `planner` is never skipped at iteration start, except for
the bug-driven `debug → implement (mini)` side path.
- `implement` is the iteration body; not skippable.
- `audit` is mandatory at cycle close.
- `debug` is mandatory RED-first for any observable bug.
- `fieldtest` and `docwriter` are optional and orchestrator-
dispatched.
If a skill's body says it must run and the orchestrator wants
to skip it, the orchestrator records the reason in the relevant
commit body — never as undocumented practice.
## Pipeline configuration
The phase set, gating, and conditional dispatch are configured
in the project profile under `pipeline:`. A project that does
not want `fieldtest` simply omits the key. A project that wants
a different gate set (e.g. `planner` without a `brainstorm`
gate, for trivial bug-fix iterations) configures it there.
See `profile-schema.md` for the syntax.
docs/profile-schema.md
+150
View File
@@ -0,0 +1,150 @@
# Profile schema
Location: `<project-root>/.claude/dev-cycle-profile.yml`
Encoding: YAML. Each top-level key is a section. Keys are
lowercase snake_case. Lists are YAML sequences.
## `paths`
| Key | Type | Default | Description |
|---------------------|--------|------------------------|-------------|
| `spec_dir` | string | `docs/specs` | Where the brainstorm skill writes specs. |
| `plan_dir` | string | `docs/plans` | Where the planner skill writes plans. |
| `design_ledger` | string | `design/INDEX.md` | Canonical specification index (optional — projects without a design ledger can omit). |
| `design_contracts` | string | `design/contracts` | Directory of prose-authoritative contracts (optional). |
| `design_models` | string | `design/models` | Directory of onboarding whitepapers (optional). |
| `code_roots` | list | `[src]` | Code directories the architect / quality reviewer walk. |
| `bench_dir` | string | `bench` | Where regression harnesses live (optional). |
Omitted optional keys signal that the feature is unused in this
project; skills that depend on them either short-circuit or
skip the corresponding step.
## `naming`
| Key | Type | Default | Description |
|--------------------|--------|----------------------------------|-------------|
| `counter_dirs` | list | `[]` | Directories that use the counter-prefix policy. |
| `policy` | enum | `flat` | One of `stable_per_directory_4digit`, `date_prefix`, `flat`. |
| `slug_separator` | string | `-` | Separator inside the slug. |
`stable_per_directory_4digit` means each listed directory has a
per-directory counter, 4-digit zero-padded, assigned in
creation order, stable for the life of the file. New files
take the next-higher number; deleted files retire their number.
`date_prefix` uses `YYYY-MM-DD-slug.md`.
`flat` uses `slug.md`.
## `commands`
| Key | Type | Default | Description |
|----------------|--------|----------------|-------------|
| `build` | string | (required) | Build command — exit 0 means success. |
| `test` | string | (required) | Test command — exit 0 means success. |
| `lint` | string | (optional) | Lint command — exit 0 means success. |
| `regression` | list | `[]` | Regression scripts run by the audit skill. Each entry is a shell command; non-zero exit is a regress. |
## `vocabulary`
| Key | Type | Default | Description |
|----------------|--------|----------------|-------------|
| `cycle` | string | `cycle` | What a top-level work unit is called. Examples: `milestone`, `release`, `epic`. |
| `subcycle` | string | `iteration` | What a sub-unit is called. Examples: `iteration`, `sprint`, `story`. |
| `ledger_entry` | string | `contract` | What a single design-ledger entry is called. Examples: `contract`, `RFC`, `ADR`. |
Skills use these names in their generated artefacts and prose.
Picking accurate vocabulary keeps prose readable; the underlying
mechanics are identical regardless of name.
## `standing_reading`
| Key | Type | Default | Description |
|----------------|--------|----------------|-------------|
| `always` | list | `[CLAUDE.md]` | Files every agent reads at start of every dispatch. |
| `by_role` | map | `{}` | Map from role name to list of additional files. |
Role names match agent slugs: `architect`, `bencher`, `debugger`,
`implementer`, `tester`, `fieldtester`, `docwriter`,
`grounding-check`, `plan-recon`, `spec-reviewer`, `quality-reviewer`.
Entries may be shell commands as well as file paths — they are
read as opaque strings the agent should fetch / execute, e.g.
`"git log -10 --format=full"`.
## `git`
| Key | Type | Default | Description |
|------------------------------|------|---------|-------------|
| `main_sacrosanct` | bool | `true` | If true, no actor may reset or revert main. |
| `only_orchestrator_commits` | bool | `true` | If true, no agent commits; the orchestrator commits. |
| `issue_tracker.kind` | enum | `none` | One of `gitea`, `github`, `linear`, `none`. |
| `issue_tracker.close_marker` | string | `"closes #N"` | Marker the orchestrator includes in commit bodies to auto-close issues. |
| `protected_branches` | list | `[main]` | Branches that are sacrosanct in the same sense as main. |
## `pipeline`
Per-phase configuration. Each phase has its own sub-map.
```yaml
pipeline:
brainstorm:
gates: [planner] # planner cannot start until this has run
planner:
gates: [implement]
implement: {} # standard
audit:
mandatory_at: cycle_close # auto-fires at end of each cycle
fieldtest:
boss_only: true # only orchestrator dispatches
when: surface_touch # condition tag (orchestrator judgement)
docwriter:
boss_only: true
when: api_stable_across_n_cycles
debug:
trigger: bug # observable misbehaviour
red_first: true # RED test before any fix
```
Phases not listed are disabled for the project. A project that
does not want a `fieldtest` phase simply omits the key.
## Example: minimal profile
```yaml
paths:
spec_dir: docs/specs
plan_dir: docs/plans
code_roots: [src]
commands:
build: cargo build
test: cargo test
vocabulary:
cycle: milestone
subcycle: iteration
standing_reading:
always:
- CLAUDE.md
- "git log -10 --format=full"
git:
issue_tracker:
kind: github
close_marker: "closes #N"
pipeline:
brainstorm: { gates: [planner] }
planner: { gates: [implement] }
implement: {}
audit: { mandatory_at: cycle_close }
debug: { trigger: bug, red_first: true }
```
This minimal profile enables five phases, no fieldtest, no
docwriter, no design-ledger. Good starting point for a small
project.