Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4fc65ccb99643c4c276c42e812a72468d2e6755d
AILang/skills/README.md
T
Brummel 54f0ced148 workflow: delete docs/journals/ and docs/journal-archive.md 
Strict application of the "Future-Use, not Verlauf" criterion to the
two remaining journal artefacts:

- `docs/journals/` (110 files): the per-iter and audit journals from
  2026-05-11 onward. Pure history; no live reader after the previous
  sweep. Entire directory removed.
- `docs/journals/2026-05-19-design-decision-records.md`: the one file
  that had live readers (`docs_honesty_pin.rs:108`, `parse.rs:80`,
  `duplicate_ctor_pin.rs:8`, three roadmap.md mentions) and was framed
  as a "relitigation guard". On re-examination its three asserted
  pinned phrases ("Regions were considered and rejected", the
  "demands annotations *because*" rationale, the prose-render
  placeholder statement) are rationale-prose, not load-bearing
  invariants — the test pinned itself, not a system property. Any
  Decision that still holds lives in the code, `design/contracts/`,
  or `design/models/`. Removed with the rest.
- `docs/journal-archive.md` (pre-2026-05-11 history): content-frozen
  long-tail history with no live reader. Removed; if anyone ever
  needs the pre-cutoff rationale they can `git log --before=2026-05-11
  --grep=<keyword>`.

Live-file consequences:
- `docs_honesty_pin.rs` `design_md_present_tense_anchors_present`:
  the three `records.*` assertions and the `read("docs/journals/…")`
  are dropped; the contract/model anchor pins remain.
- `duplicate_ctor_pin.rs`: the "why-two-overlays rationale lives in
  docs/journals/…" comment is replaced with the rationale inline.
- `parse.rs`: the "form-refinement rationale lives in docs/journals/…"
  comment is dropped (the rule body already states the refinement).
- `roadmap.md`: the decision-records mention in the DESIGN.md →
  design/ entry's body is dropped; the journal-archive.md `context:`
  pointers across ~12 closed entries are either rephrased to point
  at the relevant iter/audit (no path), or simplified to a one-line
  comment when the iter name alone carries the story.
- `CLAUDE.md` Roles section: the `docs/journal-archive.md` slot is
  removed; vocabulary note rephrased.
- `design/INDEX.md`: the Docs bullet drops `journal-archive.md`.
- `skills/README.md` bootstrap-rationale pointer rephrased.

`docs/specs/` and `docs/plans/` (per-milestone specs and per-iteration
plans) are unaffected — they remain the structured-design artefacts
they were before this sweep.

Workspace builds, full test suite green.
2026-05-20 11:25:15 +02:00

219 lines
12 KiB
Markdown
Raw Blame History

# AILang Skill System
This directory holds the project-local development skills. A *skill*
is a `SKILL.md` plus the agents that skill primarily dispatches.
Skills formalise the AILang development cycle into named, trigger-bound
discipline so the orchestrator (me) cannot accidentally diverge from
established practice without explicitly violating a named rule.
The system was bootstrapped on 2026-05-09. See
`docs/specs/2026-05-09-skill-system.md` for the design;
the bootstrap rationale lives in the commits from that week.
## The eight skills
| Skill | Trigger | Output | Mandatory? |
|-------|---------|--------|------------|
| [`brainstorm`](brainstorm/SKILL.md) | New milestone starting | `docs/specs/<milestone>.md` | Hard-gate before plan |
| [`planner`](planner/SKILL.md) | New iteration within an open milestone | `docs/plans/<iteration>.md` | Hard-gate before implement |
| [`implement`](implement/SKILL.md) | Plan exists | Code + tests (and `BLOCKED.md` on PARTIAL/BLOCKED), all uncommitted in the working tree | Standard iteration path |
| [`audit`](audit/SKILL.md) | Milestone closing OR baseline drift suspected | Drift report + bench-regression report | **Mandatory** at milestone close |
| [`docwriter`](docwriter/SKILL.md) | API surface stabilized; rustdoc lag suspected | rustdoc updates in `///` and `//!`, uncommitted in the working tree | No — Boss-dispatched only |
| [`fieldtest`](fieldtest/SKILL.md) | Boss-dispatched post-audit field test on a milestone that touched user-visible surface | 2-4 `.ail` example fixtures + `docs/specs/<date>-fieldtest-<milestone>.md`, all uncommitted in the working tree | No — Boss-dispatched only |
| [`debug`](debug/SKILL.md) | Bug encountered (failing test, segfault, wrong stdout) | RED-test in the working tree (uncommitted) + cause analysis | **Mandatory RED-first** for any bug |
| [`boss`](boss/SKILL.md) | User-invoked only (`/boss`) | Autonomous orchestration session — dispatches existing skills until done-state or bounce-back | No — user-gated |
## Pipeline
> Inside a `/boss` session the orchestrator walks this pipeline
> autonomously. Outside `/boss`, the pipeline runs only when the
> user explicitly invokes a skill.
```
[new milestone] [bug observed]
| |
v v
brainstorm -> plan -> implement debug -> implement (mini)
(per iteration loop)
|
[milestone close]
|
v
audit --(drift)--> plan + implement (tidy iteration)
--(ratify)-> --update-baseline + ratify paragraph in audit commit body
--(clean)-+
|
[Boss: iter complete? if surface-touch:]
v
fieldtest --(bug)------> debug -> implement (mini)
--(friction)-> brainstorm OR plan (tidy)
--(spec_gap)-> ratify OR tighten design/ ledger
--(clean)----+
|
[Boss: surface stable across N milestones?]
v
docwriter (rustdoc sweep)
|
v
next milestone
```
Skipping rules are codified in each `SKILL.md`. Ad-hoc skipping is
forbidden by design.
## Agent roster
Agents live next to the skill that primarily dispatches them. There
are no orphan agents (an anti-pattern after the 2026-05-09 build-out).
| Agent | Path | Dispatched by skill |
|-------|------|---------------------|
| `ailang-grounding-check` | `brainstorm/agents/` | `brainstorm` (Step 7.5; spec grounding hard-gate) |
| `ailang-plan-recon` | `planner/agents/` | `planner` (Step 2; read-only file-structure mapping); `brainstorm` (ad-hoc Step 1 in unfamiliar territory) |
| `ailang-implement-orchestrator` | `implement/agents/` | `implement` (the dispatched agent; runs the entire per-task loop inline in its own context) |
| `ailang-implementer` | `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 2.1 (implementer mindset, carries TDD as an independent layer); not dispatched as a separate subagent |
| `ailang-spec-reviewer` | `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 2.2 (spec-compliance mindset); not dispatched as a separate subagent |
| `ailang-quality-reviewer`| `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 2.3 (quality-review mindset); not dispatched as a separate subagent |
| `ailang-tester` | `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 3 (E2E coverage); not dispatched as a separate subagent |
| `ailang-architect` | `audit/agents/` | `audit` (Step 1; drift review against the design/ ledger + spec) |
| `ailang-bencher` | `audit/agents/` | `audit` (regression diagnostics — hypothesis-driven) |
| `ailang-docwriter` | `docwriter/agents/` | `docwriter` (Boss-dispatched rustdoc sweep post-stability) |
| `ailang-debugger` | `debug/agents/` | `debug` (RED-first; hands off GREEN to `implement` mini-mode) |
| `ailang-fieldtester` | `fieldtest/agents/` | `fieldtest` (writes real-world examples in `.ail` Surface form against the design/ ledger only — never the compiler source) |
Each agent file has YAML frontmatter (`name`, `description`, `tools`)
plus a system-prompt body. The `description` field is the one-sentence
summary the orchestrator (or a skill) reads to decide whether to
dispatch.
### Agent structure
Every agent file follows the same superpowers-derived template:
- **Frontmatter:** `name`, `description` (third-person, "Use when…" or
description of role), `tools`.
- **Spirit-letter lead-in:** `> 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:** the always-binding documents (CLAUDE.md,
design/INDEX.md, `git log --format=full` for recent state, plus
role-specific anchors).
- **Carrier contract:** what the controller hands the agent (`task_text`,
`diff`, `hypothesis`, etc.). Agents do NOT open `docs/plans/` or
`docs/specs/` directly — context curation lives at the skill level.
- **Iron Law:** the non-negotiable rules of the role.
- **The Process:** numbered steps.
- **Status protocol:** structured terminal status the controller acts on.
For implementer / tester / debugger / bencher / docwriter: `DONE` /
`DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`. For reviewers:
role-specific (`compliant` / `non_compliant` / `unclear` / `infra_blocked`
for spec; `approved` / `changes_requested` / `infra_blocked` for quality).
- **Output format:** word-budgeted, structured.
- **Common Rationalisations:** excuse → reality table, calibrated to past
failure modes.
- **Red Flags — STOP:** bullet list of "if you're about to do this,
stop" signals.
### TDD as an independent layer
Note that `ailang-implementer` carries Test-Driven Development as an
*independent* discipline, not just as plan-template fallout. Even if the
plan task forgot to script a RED-first step, the implementer adds it
inline before writing production code. This mirrors the
superpowers split: `subagent-driven-development` (orchestration, outer
loop) is in `skills/implement/SKILL.md`; `test-driven-development` (per-
task, inner loop) is in `skills/implement/agents/ailang-implementer.md`.
The two skills exist at different layers and stack.
## Discovery
Two symlink sets, both tracked in git, no setup needed after clone:
**Skills** are reachable under `.claude/skills/` so Claude Code's
`Skill` tool can invoke them:
```
.claude/skills/brainstorm -> skills/brainstorm
.claude/skills/planner -> skills/planner
.claude/skills/implement -> skills/implement
.claude/skills/audit -> skills/audit
.claude/skills/docwriter -> skills/docwriter
.claude/skills/fieldtest -> skills/fieldtest
.claude/skills/debug -> skills/debug
```
**Agents** are reachable under `.claude/agents/` so subagent
dispatch can find them by `subagent_type`:
```
.claude/agents/brainstorm -> skills/brainstorm/agents
.claude/agents/planner -> skills/planner/agents
.claude/agents/implement -> skills/implement/agents
.claude/agents/audit -> skills/audit/agents
.claude/agents/docwriter -> skills/docwriter/agents
.claude/agents/fieldtest -> skills/fieldtest/agents
.claude/agents/debug -> skills/debug/agents
```
## Conventions
- **Only the Boss commits.** No skill agent — implementer,
brainstormer, planner, debugger, fieldtester, docwriter,
architect, bencher — performs `git commit`. Agents write their
artefacts (spec, plan, code, tests, fixtures, rustdoc edits, RED
tests, stats files, updated baselines, `BLOCKED.md` on PARTIAL/
BLOCKED) to the working tree as unstaged changes. The Boss
inspects with `git status` / `git diff` and commits when there
is something consistent to commit. Per-task or per-phase commits
are not a goal; the iter (or the cohesive change) is the unit
of commit. `BLOCKED.md` is never committed by convention.
- **main HEAD is sacrosanct.** No actor (Boss or agent) runs
`git reset` or `git revert` on main. main moves forward only via
Boss commits; bad work stays in the working tree where it is
still discardable via `git checkout -- <path>` (Boss-side, not
on main HEAD).
- **No orphan agents.** Every agent lives under the skill that
dispatches it. If a recurring need does not fit any skill, raise
it with the user (or in a `/boss` session, surface the question
via notify) before adding the agent.
- **Agents do not call other agents.** The dispatching skill composes
(e.g. `audit` dispatches architect, then bencher).
No agent receives the `Agent` tool in its frontmatter — Claude Code
does not permit a subagent to spawn other subagents. The
`ailang-implement-orchestrator`, which historically was framed as a
named exception, runs its per-task phases as sequential
role-switches inside its own context (implementer phase → spec
check → quality check); see `skills/implement/SKILL.md` for the
mechanism.
- **Standing reading list stays in the agent file.** The skill provides
the carrier (task text, bug symptom, drift focus, hypothesis) on top
of the agent's standing reading list (CLAUDE.md, design/INDEX.md,
`git log --format=full` for recent state, role-specific anchors).
Agents do NOT open `docs/plans/` or `docs/specs/` directly —
context curation lives at the skill level.
- **Skill and agent definitions are reviewable code.** Edits go
through git. Commit messages name why the role shifted.
## Adding a new skill
1. Decide what triggers it and what it produces.
2. Write `skills/<name>/SKILL.md` with frontmatter (`name`,
`description` starting "Use when…"). Keep the description
trigger-focused; never a workflow summary.
3. If the skill dispatches subagents, add them under
`skills/<name>/agents/` and create
`.claude/agents/<name>` as a symlink to that directory.
4. Update this file (skill table + agent roster).
5. If the skill replaces or supersedes a CLAUDE.md section,
migrate that section: leave a one-line pointer in CLAUDE.md.
## Adding a new agent
1. Decide which skill primarily dispatches it.
2. Add the `.md` file under that skill's `agents/` directory.
3. Update the agent roster above and the dispatching skill's
"Cross-references" section.
4. If the agent is genuinely standalone (no skill dispatches it),
raise the question with the user first.
Reference in New Issue View Git Blame Copy Permalink