skeleton: plugin layout + docs, skill/agent migration deferred to iter 1
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:
@@ -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".
|
||||
Reference in New Issue
Block a user