Brummel
253273b007
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.
5.3 KiB
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 verbatimdiff— for reviewers, the diff to reviewhypothesis— for the bencher, what it should testbug_symptom— for the debugger, the observable misbehaviourdrift_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".