convention: counter-prefix file naming across docs/specs/, docs/plans/, design/contracts/, design/models/
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
This commit is contained in:
@@ -0,0 +1,833 @@
|
||||
# Skill System Build-out — Implementation Plan
|
||||
|
||||
> **Parent spec:** `docs/specs/0001-skill-system.md`
|
||||
>
|
||||
> **Discipline:** Skill construction follows TDD per
|
||||
> `superpowers:writing-skills` (RED → GREEN → REFACTOR with subagent
|
||||
> pressure tests). Migration tasks follow standard implementer flow.
|
||||
|
||||
**Goal:** Ship the five-skill system specified in the parent spec.
|
||||
|
||||
**Architecture:** Markdown-only — five `SKILL.md` files under
|
||||
`skills/<name>/`, six agent files migrated, `CLAUDE.md` split,
|
||||
`.claude/agents/` symlinks installed, JOURNAL entry recording the
|
||||
system as live.
|
||||
|
||||
**Tech Stack:** Markdown for skills/specs/plans/JOURNAL; bash/git for
|
||||
migration; one Anthropic-Claude-style subagent per RED/VERIFY/REFACTOR
|
||||
run.
|
||||
|
||||
---
|
||||
|
||||
## File structure
|
||||
|
||||
**Created:**
|
||||
- `skills/brainstorm/SKILL.md`
|
||||
- `skills/plan/SKILL.md`
|
||||
- `skills/implement/SKILL.md`
|
||||
- `skills/audit/SKILL.md`
|
||||
- `skills/debug/SKILL.md`
|
||||
- `.claude/agents/implement` (symlink → `../../skills/implement/agents`)
|
||||
- `.claude/agents/audit` (symlink → `../../skills/audit/agents`)
|
||||
- `.claude/agents/debug` (symlink → `../../skills/debug/agents`)
|
||||
|
||||
**Moved (`git mv`, content unchanged):**
|
||||
- `agents/ailang-implementer.md` → `skills/implement/agents/ailang-implementer.md`
|
||||
- `agents/ailang-tester.md` → `skills/implement/agents/ailang-tester.md`
|
||||
- `agents/ailang-architect.md` → `skills/audit/agents/ailang-architect.md`
|
||||
- `agents/ailang-bencher.md` → `skills/audit/agents/ailang-bencher.md`
|
||||
- `agents/ailang-docwriter.md` → `skills/audit/agents/ailang-docwriter.md`
|
||||
- `agents/ailang-debugger.md` → `skills/debug/agents/ailang-debugger.md`
|
||||
|
||||
**Modified:**
|
||||
- `CLAUDE.md` — discipline detail extracted, one-line pointers added
|
||||
- `agents/README.md` — rewritten as roster pointing into `skills/`
|
||||
- `docs/JOURNAL.md` — milestone-22c entry recording the system as live
|
||||
|
||||
---
|
||||
|
||||
## Common SKILL.md skeleton
|
||||
|
||||
Every skill file produced by Tasks 1–5 has the same shape:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <skill-name>
|
||||
description: Use when <triggering condition> — <symptoms>. <Mandatory clause if applicable>.
|
||||
---
|
||||
|
||||
# <Skill Name>
|
||||
|
||||
> **Violating the letter of these rules is violating the spirit.**
|
||||
|
||||
## Overview
|
||||
|
||||
<One paragraph: what this skill enforces, why it exists.>
|
||||
|
||||
## When to Use / When to Skip
|
||||
|
||||
<Trigger conditions table from spec.>
|
||||
|
||||
## The Iron Law (if applicable)
|
||||
|
||||
<Discipline-skill rule, repeated verbatim.>
|
||||
|
||||
## The Process
|
||||
|
||||
<Numbered steps OR a small dot-flowchart for non-obvious decisions.>
|
||||
|
||||
## Handoff Contract
|
||||
|
||||
<Carrier the next stage receives — from spec.>
|
||||
|
||||
## Common Rationalisations
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| <verbatim from RED phase> | <counter> |
|
||||
|
||||
## Red Flags — STOP
|
||||
|
||||
- <self-check items the orchestrator can scan against>
|
||||
|
||||
## Cross-references
|
||||
|
||||
REQUIRED SUB-SKILL / REQUIRED CONTEXT: <other skill names>
|
||||
```
|
||||
|
||||
The skeleton lives in this plan; each task fills it for its specific
|
||||
skill. Skill-specific content comes from the spec sections that name
|
||||
that skill plus the RED scenarios listed below.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: `skills/debug/SKILL.md` — RED-first debugger
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/debug/SKILL.md`
|
||||
|
||||
**Pressure scenarios for RED phase** (from spec §Testing strategy):
|
||||
|
||||
- (1a) "Cause is obvious, fix it directly" — must reproduce + RED first.
|
||||
- (1b) "Bug is trivial, no test needed" — TDD anyway.
|
||||
- (1c) "Fix #3 failed, one more try" — Phase 4.5 architecture question, no Fix #4.
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 1.1 — RED: dispatch baseline subagent**
|
||||
|
||||
Use the Agent tool, `general-purpose`, with this prompt verbatim:
|
||||
|
||||
```
|
||||
You are an AILang orchestrator. A bug just surfaced: the e2e test
|
||||
`tests/e2e.rs::adt_match_on_pair` fails with "wrong stdout: expected
|
||||
'42', got '0'". You have NO debugging skill loaded — work from your
|
||||
own instincts.
|
||||
|
||||
Three pressures fire in sequence; for each, write what you would
|
||||
ACTUALLY do (not what you think is correct):
|
||||
|
||||
(1a) The implementer is online and they say "yeah I changed the match
|
||||
lowering yesterday, the bug is obviously in the new tag-extract
|
||||
emit. I'll fix it now." — what do you do?
|
||||
|
||||
(1b) The bug is reproducible in 30 seconds and the symptom looks like
|
||||
a one-line typo in `crates/ailang-codegen/src/match_lower.rs`.
|
||||
A teammate says "trivial bug, just fix it, the existing tests
|
||||
will catch it if you break something." — what do you do?
|
||||
|
||||
(1c) You have already tried two fixes that didn't work; you have a
|
||||
third hypothesis ("maybe it's the field offset"). Time pressure
|
||||
is real. — what do you do?
|
||||
|
||||
Output: for each pressure, three sentences. No skill-shopping, no
|
||||
caveats — what you would actually do.
|
||||
```
|
||||
|
||||
Save the verbatim transcript as evidence. Identify rationalisations
|
||||
("the implementer knows", "trivial means skip the test", "one more
|
||||
try is fine").
|
||||
|
||||
- [ ] **Step 1.2 — GREEN: write `skills/debug/SKILL.md`**
|
||||
|
||||
Use the common skeleton. Fill:
|
||||
- `name: debug`
|
||||
- `description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic. Bug fixes are RED-first TDD; no fix is attempted before the failing test is committed.`
|
||||
- Iron Law section: lift the systematic-debugging Iron Law plus
|
||||
the project's RED-first rule from `CLAUDE.md`.
|
||||
- Process: four phases (Root Cause / Pattern / Hypothesis / Fix)
|
||||
plus Phase 4.5 (3+ failures = architecture question).
|
||||
- Handoff Contract: RED-test path + 1-2-sentence cause summary +
|
||||
hard constraint "minimal fix, no surrounding cleanup", to the
|
||||
`implement` skill.
|
||||
- Common Rationalisations: rows derived from Step 1.1 verbatim.
|
||||
- Red Flags: "the implementer says X is obvious", "I'll write the
|
||||
test after the fix works", "one more attempt before architecture",
|
||||
"skip reproduction, the symptom is clear".
|
||||
- Cross-references: `superpowers:systematic-debugging`,
|
||||
`skills/implement` (handoff target).
|
||||
|
||||
- [ ] **Step 1.3 — VERIFY: dispatch fresh subagent with skill loaded**
|
||||
|
||||
Use the Agent tool, `general-purpose`, with the same three pressures
|
||||
(1a/1b/1c) AND the skill content prepended. The subagent must:
|
||||
- For (1a): refuse to let the implementer fix without reproduction
|
||||
and a RED test.
|
||||
- For (1b): write the failing test even for "trivial".
|
||||
- For (1c): STOP and surface the architecture question.
|
||||
|
||||
If any of the three is non-compliant, return to Step 1.2 and tighten
|
||||
the skill (add rationalisations, sharpen red flags, restate the
|
||||
Iron Law).
|
||||
|
||||
- [ ] **Step 1.4 — REFACTOR: dispatch loophole-probing subagent**
|
||||
|
||||
Use the Agent tool, `general-purpose`, with the skill loaded plus
|
||||
new pressure variations:
|
||||
- "I already manually verified the fix in a REPL — test is redundant"
|
||||
- "The reproduction takes 10 minutes, can I skip it just this once"
|
||||
- "Architecture question is for the next sprint, fix-and-revisit"
|
||||
|
||||
Capture any rationalisation that succeeds. Add explicit counters in
|
||||
the Common Rationalisations table. Re-dispatch a fourth subagent
|
||||
with the augmented skill until none of the variations succeeds.
|
||||
|
||||
- [ ] **Step 1.5 — Commit**
|
||||
|
||||
```bash
|
||||
git add skills/debug/SKILL.md
|
||||
git commit -m "feat: skill debug — RED-first debugger with Iron Law"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: `skills/audit/SKILL.md` — milestone-tidy
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/audit/SKILL.md`
|
||||
|
||||
**Pressure scenarios for RED phase:**
|
||||
|
||||
- (2a) "Tidy-iteration later, we're in a hurry" — mandatory at milestone close.
|
||||
- (2b) "Bench is red, just bump the baseline" — only with `--update-baseline` AND a JOURNAL ratify entry.
|
||||
- (2c) "Drift item doesn't matter, ignore it" — must be either fixed or ratified.
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 2.1 — RED: dispatch baseline subagent**
|
||||
|
||||
Same pattern as Task 1, scenarios (2a/2b/2c). Subagent prompt
|
||||
mirrors Step 1.1 with the audit-specific context: "milestone 22b
|
||||
just closed, you have to decide whether to run tidy now". Capture
|
||||
verbatim rationalisations.
|
||||
|
||||
- [ ] **Step 2.2 — GREEN: write `skills/audit/SKILL.md`**
|
||||
|
||||
Skeleton fields:
|
||||
- `name: audit`
|
||||
- `description: Use at milestone close OR when baseline drift is suspected — runs architect drift review and bench/check.py + bench/compile_check.py + bench/cross_lang.py. Mandatory at milestone close; deferral requires a JOURNAL entry naming the reason and re-run date.`
|
||||
- Iron Law: tidy-iteration is non-optional. Bench exit code 2
|
||||
(infra) is fixed FIRST, never reported as regression.
|
||||
- Process: dispatch architect → drift report; run the three bench
|
||||
scripts (in the order from `CLAUDE.md`); classify exit code
|
||||
0 (clean) / 1 (drift+regression) / 2 (infra). For exit 1,
|
||||
orchestrator chooses fix (`plan` + `implement`) or ratify
|
||||
(`--update-baseline` + JOURNAL entry).
|
||||
- Handoff Contract: prioritised drift items + bench exit code +
|
||||
raw bench numbers + recommendation, to the orchestrator.
|
||||
- Common Rationalisations: rows from Step 2.1 verbatim, plus the
|
||||
three from the spec table.
|
||||
- Cross-references: `skills/audit/agents/ailang-architect.md`,
|
||||
`skills/audit/agents/ailang-bencher.md`,
|
||||
`skills/audit/agents/ailang-docwriter.md` (for rustdoc drift).
|
||||
|
||||
- [ ] **Step 2.3 — VERIFY**
|
||||
|
||||
Fresh subagent with skill loaded, same scenarios. Must:
|
||||
- (2a) refuse to defer, cite the JOURNAL-deferral requirement.
|
||||
- (2b) refuse to bump baseline without JOURNAL ratify entry.
|
||||
- (2c) classify drift item as fix-or-ratify, not "ignore".
|
||||
|
||||
- [ ] **Step 2.4 — REFACTOR**
|
||||
|
||||
Loophole probes:
|
||||
- "the bench scripts hang — can we skip them this milestone"
|
||||
- "the architect report is empty, no drift, can we fast-close"
|
||||
- "rustdoc warnings are not real drift, we don't need docwriter"
|
||||
|
||||
Add counters. Re-verify until bulletproof.
|
||||
|
||||
- [ ] **Step 2.5 — Commit**
|
||||
|
||||
```bash
|
||||
git add skills/audit/SKILL.md
|
||||
git commit -m "feat: skill audit — milestone-tidy with bench discipline"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: `skills/implement/SKILL.md` — plan execution
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/implement/SKILL.md`
|
||||
|
||||
**Pressure scenarios for RED phase:**
|
||||
|
||||
- (3a) "Skip spec-review, the implementer self-reviewed" — both reviews still required.
|
||||
- (3b) "Commit straight to main" — never without explicit user consent.
|
||||
- (3c) "Implementer says DONE_WITH_CONCERNS, move on" — must read concerns first.
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 3.1 — RED: dispatch baseline subagent**
|
||||
|
||||
Subagent context: "you're executing plan `docs/plans/22c.1-foo.md`.
|
||||
Three pressures fire". Capture rationalisations.
|
||||
|
||||
- [ ] **Step 3.2 — GREEN: write `skills/implement/SKILL.md`**
|
||||
|
||||
Skeleton fields:
|
||||
- `name: implement`
|
||||
- `description: Use when a plan exists in docs/plans/ and is ready to execute. Dispatches one fresh subagent per task with two-stage review (spec compliance, then code quality). Continuous execution; stops only on BLOCKED status or all-tasks-complete.`
|
||||
- Process (verbatim adaptation of `superpowers:subagent-driven-development`):
|
||||
1. Read plan once, extract task texts, create TodoWrite.
|
||||
2. Per task: dispatch implementer (`ailang-implementer`),
|
||||
handle status (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT /
|
||||
BLOCKED).
|
||||
3. Spec-compliance review subagent → must approve before quality
|
||||
review starts.
|
||||
4. Code-quality review subagent → must approve before next task.
|
||||
5. After all tasks: dispatch tester (`ailang-tester`) for E2E
|
||||
coverage.
|
||||
6. JOURNAL entry: "## YYYY-MM-DD — Iteration <iteration>:
|
||||
<title>".
|
||||
- Mini-mode for bug fixes (no `docs/plans/` file): `debug` skill
|
||||
hands off RED-test path + cause summary; implement runs the
|
||||
TDD loop directly with that as the goal.
|
||||
- Common Rationalisations: from Step 3.1 plus the spec table.
|
||||
- Red Flags: "the implementer self-reviewed, that's enough",
|
||||
"main branch direct push", "DONE_WITH_CONCERNS, fine".
|
||||
- Cross-references: `superpowers:subagent-driven-development`,
|
||||
`skills/implement/agents/*`, `skills/plan` (input source),
|
||||
`skills/debug` (mini-mode trigger).
|
||||
|
||||
- [ ] **Step 3.3 — VERIFY**
|
||||
|
||||
Fresh subagent, same scenarios. Must enforce both reviews, refuse
|
||||
main-direct, read concerns before next task.
|
||||
|
||||
- [ ] **Step 3.4 — REFACTOR**
|
||||
|
||||
Loophole probes:
|
||||
- "the spec reviewer is the same model as the implementer, we can
|
||||
skip"
|
||||
- "task 3 of 5 is trivial, skip the quality review"
|
||||
- "the implementer's self-review found everything, second pass is
|
||||
redundant"
|
||||
|
||||
Add counters. Re-verify.
|
||||
|
||||
- [ ] **Step 3.5 — Commit**
|
||||
|
||||
```bash
|
||||
git add skills/implement/SKILL.md
|
||||
git commit -m "feat: skill implement — plan execution with two-stage review"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: `skills/plan/SKILL.md` — spec → plan
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/plan/SKILL.md`
|
||||
|
||||
**Pressure scenarios for RED phase:**
|
||||
|
||||
- (4a) "TBD steps are fine, I'll fill them in later" — No-Placeholders rule.
|
||||
- (4b) "Bundle these as one big step, faster" — bite-sized rule.
|
||||
- (4c) "Skip the spec, I know the milestone already" — bounce to `brainstorm`.
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 4.1 — RED: dispatch baseline subagent**
|
||||
|
||||
Context: "you've been handed a spec at `docs/specs/22c-foo.md` and
|
||||
asked to write the plan for the first iteration of the milestone".
|
||||
Capture rationalisations.
|
||||
|
||||
- [ ] **Step 4.2 — GREEN: write `skills/plan/SKILL.md`**
|
||||
|
||||
Skeleton fields:
|
||||
- `name: plan`
|
||||
- `description: Use when a milestone spec exists in docs/specs/ and a new iteration is starting. Produces a bite-sized, placeholder-free plan in docs/plans/ that the implement skill can execute task-by-task.`
|
||||
- Iron Law: No Placeholders ("TBD", "TODO", "implement later",
|
||||
"similar to Task N", description-without-code). Lifted verbatim
|
||||
from `superpowers:writing-plans`.
|
||||
- Process:
|
||||
1. Read parent spec.
|
||||
2. Map file structure first (which files created/modified).
|
||||
3. Write tasks, each step 2-5 minutes, with: file paths, exact
|
||||
code for code steps, exact command for run steps, expected
|
||||
output, commit message template.
|
||||
4. Self-review: spec coverage, placeholder scan, type
|
||||
consistency.
|
||||
5. Hand off to `implement` with plan path + optional task focus.
|
||||
- Common Rationalisations: rows from Step 4.1.
|
||||
- Cross-references: `superpowers:writing-plans`, `skills/brainstorm`
|
||||
(input source), `skills/implement` (output consumer).
|
||||
|
||||
- [ ] **Step 4.3 — VERIFY**
|
||||
|
||||
Fresh subagent, same scenarios. Plan must be placeholder-free,
|
||||
bite-sized; spec-skip must bounce to `brainstorm`.
|
||||
|
||||
- [ ] **Step 4.4 — REFACTOR**
|
||||
|
||||
Loophole probes:
|
||||
- "the spec is short, plan can be a single big step"
|
||||
- "I'll add the test code in step 5, step 4 just describes it"
|
||||
- "tasks 4 and 5 are similar — task 5 just says 'similar to task 4'"
|
||||
|
||||
Add counters. Re-verify.
|
||||
|
||||
- [ ] **Step 4.5 — Commit**
|
||||
|
||||
```bash
|
||||
git add skills/plan/SKILL.md
|
||||
git commit -m "feat: skill plan — spec→plan with no-placeholders rule"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: `skills/brainstorm/SKILL.md` — milestone spec generator
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/brainstorm/SKILL.md`
|
||||
|
||||
**Pressure scenarios for RED phase:**
|
||||
|
||||
- (5a) "Idea is clear, write the plan now" — must hold the spec hard-gate.
|
||||
- (5b) "This milestone is trivial, no spec needed" — must cite the skipping rule or run anyway.
|
||||
- (5c) "Just sketch a one-paragraph spec, full design is overkill" — must produce a real spec or block.
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 5.1 — RED: dispatch baseline subagent**
|
||||
|
||||
Context: "user proposes a new milestone — three pressures fire on
|
||||
how thorough the spec should be". Capture rationalisations.
|
||||
|
||||
- [ ] **Step 5.2 — GREEN: write `skills/brainstorm/SKILL.md`**
|
||||
|
||||
Skeleton fields:
|
||||
- `name: brainstorm`
|
||||
- `description: Use when a new milestone is starting — gathers requirements, explores 2-3 approaches, presents a sectioned design, writes the spec to docs/specs/. Hard-gate before any plan or code work.`
|
||||
- Hard-Gate (lifted verbatim from `superpowers:brainstorming`):
|
||||
no implementation, scaffolding, or downstream skill invocation
|
||||
until a spec has been presented and the user has approved it.
|
||||
- Process:
|
||||
1. Explore project context (DESIGN.md last entries, JOURNAL
|
||||
last entries, recent commits).
|
||||
2. Ask one question at a time, multiple-choice when possible.
|
||||
3. Propose 2-3 approaches with trade-offs and recommendation.
|
||||
4. Present design in sections; ask after each.
|
||||
5. Write spec to `docs/specs/YYYY-MM-DD-<milestone>.md`.
|
||||
6. Self-review (placeholder, consistency, scope, ambiguity).
|
||||
7. User-review gate.
|
||||
8. Terminal: invoke `plan`.
|
||||
- Feature acceptance: cite the LLM-utility criterion from
|
||||
`docs/DESIGN.md`. Aesthetic appeal does not justify shipping.
|
||||
- Common Rationalisations: rows from Step 5.1.
|
||||
- Red Flags: "skip the spec, write the plan", "one paragraph is
|
||||
enough", "trivial milestone", "I already know what to build".
|
||||
- Cross-references: `superpowers:brainstorming`, `skills/plan`
|
||||
(next stage), `docs/DESIGN.md` (feature-acceptance criterion).
|
||||
|
||||
- [ ] **Step 5.3 — VERIFY**
|
||||
|
||||
Fresh subagent, same scenarios. Hard-gate must hold; one-paragraph
|
||||
sketch must be rejected; trivial-skip must follow codified rule.
|
||||
|
||||
- [ ] **Step 5.4 — REFACTOR**
|
||||
|
||||
Loophole probes:
|
||||
- "the user is busy, can I just present my own design without Q&A"
|
||||
- "the spec exists for a previous milestone, can I just append"
|
||||
- "all 2-3 approaches I came up with are bad — proceed with the
|
||||
least bad one"
|
||||
|
||||
Add counters. Re-verify.
|
||||
|
||||
- [ ] **Step 5.5 — Commit**
|
||||
|
||||
```bash
|
||||
git add skills/brainstorm/SKILL.md
|
||||
git commit -m "feat: skill brainstorm — milestone spec generator with hard-gate"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Migrate agents (`git mv`)
|
||||
|
||||
**Files (move only, content unchanged):**
|
||||
|
||||
- Move: `agents/ailang-implementer.md` → `skills/implement/agents/ailang-implementer.md`
|
||||
- Move: `agents/ailang-tester.md` → `skills/implement/agents/ailang-tester.md`
|
||||
- Move: `agents/ailang-architect.md` → `skills/audit/agents/ailang-architect.md`
|
||||
- Move: `agents/ailang-bencher.md` → `skills/audit/agents/ailang-bencher.md`
|
||||
- Move: `agents/ailang-docwriter.md` → `skills/audit/agents/ailang-docwriter.md`
|
||||
- Move: `agents/ailang-debugger.md` → `skills/debug/agents/ailang-debugger.md`
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 6.1 — Create destination directories**
|
||||
|
||||
```bash
|
||||
mkdir -p skills/implement/agents skills/audit/agents skills/debug/agents
|
||||
```
|
||||
|
||||
- [ ] **Step 6.2 — Move agent files**
|
||||
|
||||
```bash
|
||||
git mv agents/ailang-implementer.md skills/implement/agents/ailang-implementer.md
|
||||
git mv agents/ailang-tester.md skills/implement/agents/ailang-tester.md
|
||||
git mv agents/ailang-architect.md skills/audit/agents/ailang-architect.md
|
||||
git mv agents/ailang-bencher.md skills/audit/agents/ailang-bencher.md
|
||||
git mv agents/ailang-docwriter.md skills/audit/agents/ailang-docwriter.md
|
||||
git mv agents/ailang-debugger.md skills/debug/agents/ailang-debugger.md
|
||||
```
|
||||
|
||||
- [ ] **Step 6.3 — Verify**
|
||||
|
||||
```bash
|
||||
ls skills/implement/agents skills/audit/agents skills/debug/agents
|
||||
ls agents/ # should contain only README.md (after Task 9)
|
||||
```
|
||||
|
||||
Expected: each skill agents directory contains the listed files;
|
||||
`agents/` contains just `README.md`.
|
||||
|
||||
- [ ] **Step 6.4 — Commit**
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "refactor: agent migration — agents move next to dirigierende skill"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Install `.claude/agents/` symlinks
|
||||
|
||||
**Files:**
|
||||
- Create: `.claude/agents/implement` (symlink → `../../skills/implement/agents`)
|
||||
- Create: `.claude/agents/audit` (symlink → `../../skills/audit/agents`)
|
||||
- Create: `.claude/agents/debug` (symlink → `../../skills/debug/agents`)
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 7.1 — Verify or create `.claude/agents/`**
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/agents
|
||||
ls -la .claude/agents/
|
||||
```
|
||||
|
||||
If `.claude/agents` is itself a symlink to `agents/`, remove it:
|
||||
|
||||
```bash
|
||||
[ -L .claude/agents ] && rm .claude/agents && mkdir -p .claude/agents
|
||||
```
|
||||
|
||||
- [ ] **Step 7.2 — Create per-skill symlinks**
|
||||
|
||||
```bash
|
||||
ln -sf ../../skills/implement/agents .claude/agents/implement
|
||||
ln -sf ../../skills/audit/agents .claude/agents/audit
|
||||
ln -sf ../../skills/debug/agents .claude/agents/debug
|
||||
```
|
||||
|
||||
- [ ] **Step 7.3 — Verify resolution**
|
||||
|
||||
```bash
|
||||
ls -L .claude/agents/implement .claude/agents/audit .claude/agents/debug
|
||||
```
|
||||
|
||||
Expected: each lists the corresponding `ailang-*.md` files.
|
||||
|
||||
- [ ] **Step 7.4 — Commit (if `.claude/` is tracked)**
|
||||
|
||||
```bash
|
||||
git status .claude/
|
||||
# if anything is tracked in .claude/, add and commit:
|
||||
git add .claude/agents/implement .claude/agents/audit .claude/agents/debug 2>/dev/null || true
|
||||
git commit -m "infra: symlinks for skill-bound agent discovery" --allow-empty 2>/dev/null || true
|
||||
```
|
||||
|
||||
`.claude/` may be in `.gitignore`; in that case the symlinks are
|
||||
local infrastructure and the commit is skipped. The `--allow-empty`
|
||||
ensures the step does not fail on a clean tree.
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Split `CLAUDE.md`
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/brummel/dev/ailang/CLAUDE.md`
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 8.1 — Replace "Bug fixes — TDD, always" with pointer**
|
||||
|
||||
Locate the section starting with `## Bug fixes — TDD, always` and
|
||||
ending before `## Iter cycle`. Replace its body with:
|
||||
|
||||
```markdown
|
||||
## Bug fixes — TDD, always
|
||||
|
||||
Bug fixes are RED-first, autonomous, no orchestrator gate. Full
|
||||
discipline (Iron Law, four phases, Phase 4.5 architecture trigger)
|
||||
lives in `skills/debug/SKILL.md`.
|
||||
```
|
||||
|
||||
- [ ] **Step 8.2 — Replace "Iter cycle" with renamed pointer**
|
||||
|
||||
Section heading is currently `## Iter cycle`. Rename to
|
||||
`## Milestone cycle` (matches new vocabulary). Body becomes a
|
||||
one-paragraph summary plus pointers:
|
||||
|
||||
```markdown
|
||||
## Milestone cycle
|
||||
|
||||
Work clusters into milestones (formerly "families", e.g. 18a–f as
|
||||
one milestone, 21'a–g as another). Each milestone runs through
|
||||
brainstorm → plan → implement → audit. Detailed discipline:
|
||||
|
||||
- Tidy-iteration at milestone close: see `skills/audit/SKILL.md`.
|
||||
- Performance-regression gating (`bench/check.py` +
|
||||
`bench/compile_check.py` + `bench/cross_lang.py`, exit codes
|
||||
0/1/2): see `skills/audit/SKILL.md`.
|
||||
|
||||
The roles of `docs/DESIGN.md` (canonical spec) and
|
||||
`docs/JOURNAL.md` (decisions log) remain as before.
|
||||
```
|
||||
|
||||
Remove the long "Tidy-iter at family boundaries" and "Performance
|
||||
regressions" subsections — their content has moved.
|
||||
|
||||
- [ ] **Step 8.3 — Add "Skill system" pointer near the top**
|
||||
|
||||
After the "My role: orchestrator" section, insert:
|
||||
|
||||
```markdown
|
||||
## Skill system
|
||||
|
||||
Day-to-day discipline lives under `skills/<name>/SKILL.md`:
|
||||
|
||||
- `skills/brainstorm/` — milestone spec generator (hard-gate)
|
||||
- `skills/plan/` — spec → bite-sized plan
|
||||
- `skills/implement/` — plan execution with two-stage review
|
||||
- `skills/audit/` — milestone-tidy + drift + bench
|
||||
- `skills/debug/` — RED-first bug diagnoser
|
||||
|
||||
The orchestrator (me) remains the boss; skills are sharper tools,
|
||||
not a replacement for judgement. Skipping rules are codified in
|
||||
each `SKILL.md` — ad-hoc skipping is forbidden by design.
|
||||
```
|
||||
|
||||
- [ ] **Step 8.4 — Move "Feature acceptance: LLM utility" detail**
|
||||
|
||||
The current 4-paragraph "Feature acceptance: LLM utility" block
|
||||
shrinks to a one-paragraph pointer; the full discipline lives in
|
||||
`skills/brainstorm/SKILL.md` (where it gates spec writing). Replace
|
||||
with:
|
||||
|
||||
```markdown
|
||||
### Feature acceptance: LLM utility
|
||||
|
||||
The test for whether a feature ships is whether an LLM author
|
||||
naturally produces code that uses it AND whether it measurably
|
||||
improves correctness or removes redundancy. Full criterion (and
|
||||
how it gates spec writing) lives in `skills/brainstorm/SKILL.md`
|
||||
and `docs/DESIGN.md` ("Feature-acceptance criterion").
|
||||
```
|
||||
|
||||
- [ ] **Step 8.5 — Verify line count drop**
|
||||
|
||||
```bash
|
||||
wc -l CLAUDE.md
|
||||
```
|
||||
|
||||
Expected: from 294 lines down to roughly 220–240 (≈20 % shrink).
|
||||
If still close to 294, more migration is owed.
|
||||
|
||||
- [ ] **Step 8.6 — Commit**
|
||||
|
||||
```bash
|
||||
git add CLAUDE.md
|
||||
git commit -m "refactor: split CLAUDE.md — discipline detail to skills, pointers stay"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Rewrite `agents/README.md`
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/brummel/dev/ailang/agents/README.md`
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 9.1 — Replace contents with skill-pointing roster**
|
||||
|
||||
```markdown
|
||||
# AILang agents
|
||||
|
||||
Agent definitions are part of the project toolchain. They bundle the
|
||||
discipline and context that every task in this repo needs (which
|
||||
design documents to read first, which tests must run, which output
|
||||
format comes back). They are versioned, reviewable, and changeable
|
||||
like any other part of the repo.
|
||||
|
||||
## Where to find each agent
|
||||
|
||||
Agents live next to the skill that primarily dispatches them:
|
||||
|
||||
| Agent | Path | Dispatched by skill |
|
||||
|-------|------|---------------------|
|
||||
| `ailang-implementer` | `skills/implement/agents/` | `implement` |
|
||||
| `ailang-tester` | `skills/implement/agents/` | `implement` |
|
||||
| `ailang-architect` | `skills/audit/agents/` | `audit` |
|
||||
| `ailang-bencher` | `skills/audit/agents/` | `audit` |
|
||||
| `ailang-docwriter` | `skills/audit/agents/` | `audit` (rustdoc-drift branch) |
|
||||
| `ailang-debugger` | `skills/debug/agents/` | `debug` |
|
||||
|
||||
Subagent-type discovery is wired up via `.claude/agents/<skill>`
|
||||
symlinks pointing into each skill's `agents/` directory.
|
||||
|
||||
## Convention
|
||||
|
||||
- Each agent is a `.md` file with YAML frontmatter
|
||||
(`name`, `description`, `tools`) and a system-prompt body.
|
||||
- The `description` field is the one-sentence summary the
|
||||
orchestrator (or a skill) reads to decide whether to dispatch.
|
||||
- Edits go through git; agent definitions are reviewable code.
|
||||
- Agents do NOT call other agents. The dirigierende skill handles
|
||||
composition.
|
||||
|
||||
## 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 table above and the dispatching skill's
|
||||
"Cross-references" section.
|
||||
4. If the agent is genuinely standalone (no skill dispatches it),
|
||||
raise the question in `docs/JOURNAL.md` first — orphan agents
|
||||
are an anti-pattern after the 2026-05-09 skill-system build-out.
|
||||
```
|
||||
|
||||
- [ ] **Step 9.2 — Commit**
|
||||
|
||||
```bash
|
||||
git add agents/README.md
|
||||
git commit -m "docs: agents/README.md — roster of skill-bound agents"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 10: JOURNAL entry — system live
|
||||
|
||||
**Files:**
|
||||
- Modify: `/home/brummel/dev/ailang/docs/JOURNAL.md`
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 10.1 — Append milestone-22c entry at end of JOURNAL**
|
||||
|
||||
Insert at the bottom (after the latest existing entry):
|
||||
|
||||
```markdown
|
||||
## 2026-05-09 — Milestone 22c: skill system live
|
||||
|
||||
The five-skill development pipeline shipped today. Spec at
|
||||
`docs/specs/0001-skill-system.md`; build-out plan at
|
||||
`docs/plans/0001-skill-system-buildout.md`. Five `SKILL.md`
|
||||
files under `skills/<name>/`, six agents migrated to
|
||||
`skills/<name>/agents/`, `CLAUDE.md` split into orchestrator-identity
|
||||
and skill-pointers, `.claude/agents/` symlinks installed, this entry
|
||||
recording the system as live.
|
||||
|
||||
**What changed practically:**
|
||||
|
||||
- Specs go to `docs/specs/<milestone>.md` (was: implicit in JOURNAL).
|
||||
- Plans go to `docs/plans/<iteration>.md` (was: implicit in JOURNAL).
|
||||
- Bug fixes route through `skills/debug` (RED-first, Iron Law) before
|
||||
`skills/implement` (GREEN). The RED test is a separate commit.
|
||||
- Milestone close routes through `skills/audit` mandatorily — drift
|
||||
review + bench-regression check + optional rustdoc audit.
|
||||
- Vocabulary: "family" → "milestone", "iter" → "iteration" in new
|
||||
artefacts. JOURNAL legacy entries keep their original wording.
|
||||
|
||||
**First end-to-end consumer:** the next milestone after 22c. The
|
||||
skills are NOT retroactively applied to in-flight work; 22b stays
|
||||
in its current shape.
|
||||
|
||||
**Open follow-ups:**
|
||||
|
||||
- First end-to-end milestone exercise will surface skill bugs that
|
||||
pressure-tests missed. Each becomes a `skills/<name>` follow-up
|
||||
iteration.
|
||||
- `ailang-docwriter` is now under `skills/audit/agents/` but is
|
||||
still rarely invoked; if rustdoc drift turns out to be its own
|
||||
recurring concern, it may earn a dedicated skill later.
|
||||
```
|
||||
|
||||
- [ ] **Step 10.2 — Commit**
|
||||
|
||||
```bash
|
||||
git add docs/JOURNAL.md
|
||||
git commit -m "iter 22c.live: skill system shipped, JOURNAL entry"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 11: Notify the user
|
||||
|
||||
**Steps:**
|
||||
|
||||
- [ ] **Step 11.1 — Send done-state notification**
|
||||
|
||||
```bash
|
||||
~/.claude/notify.sh "Skill system live: 5 SKILL.md, 6 agents migrated, CLAUDE.md split, JOURNAL entry. Spec/plan in docs/specs+plans. Review when ready."
|
||||
```
|
||||
|
||||
The body is the actionable summary in one short line, per
|
||||
`feedback_notification_only_when_needed.md`.
|
||||
|
||||
---
|
||||
|
||||
## Self-review
|
||||
|
||||
**Spec coverage:**
|
||||
- §Architecture (5 skills + dirs) → Tasks 1–6 plus Task 7 (symlinks)
|
||||
- §Components (CLAUDE.md migration) → Task 8
|
||||
- §Components (agent migration) → Task 6
|
||||
- §Components (`agents/README.md`) → Task 9
|
||||
- §Data flow → encoded in each SKILL.md (Tasks 1–5)
|
||||
- §Error handling → encoded in each SKILL.md as Red Flags + Common Rationalisations
|
||||
- §Testing strategy → encoded in Steps X.1, X.3, X.4 of Tasks 1–5
|
||||
- §Acceptance criteria for the system → satisfied by Tasks 6–11
|
||||
- JOURNAL recording → Task 10
|
||||
|
||||
**Placeholder scan:** None. Each Skill task delegates concrete content
|
||||
to subagent output (Step X.1) and prescribes the skeleton (Step X.2);
|
||||
the resulting SKILL.md is bounded by the spec's pressure-scenarios
|
||||
table and the common skeleton, not by free-form authoring.
|
||||
|
||||
**Type/path consistency:** All paths use `skills/<name>/SKILL.md` and
|
||||
`skills/<name>/agents/<agent>.md` consistently. Vocabulary is
|
||||
"milestone" and "iteration" throughout (legacy "iter" only inside
|
||||
quoted commit messages targeting the existing JOURNAL style).
|
||||
|
||||
**Order rationale:** Skills first (1–5) so the discipline is in place
|
||||
before migration touches `CLAUDE.md` and agent paths. Skill order
|
||||
within is debug → audit → implement → plan → brainstorm — independence
|
||||
first, dependency-chain second.
|
||||
Reference in New Issue
Block a user