Brummel
7a58a530b1
The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.
Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
a verification/enumeration axis ahead of the settled-vs-fork question.
Each lighter arm carries a positive trigger matched by signature, not
reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
that propagates mechanically. Observe-then-bounce — make the edit,
build, run the suite; clean build AND suite green unchanged commits;
a hole bounces up (specify for a design choice, tdd for discovered
test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
mechanical/forwarding -> compiler-driven; encodes new behaviour ->
tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
not a heavy new skill ("the largest concrete win is small").
Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
phase (implementer -> spec-compliance -> quality, + tester for E2E) is
a separate top-level agent() call, so a single phase is independently
invokable and inter-phase aggregation/re-loop is code. Retires the
implement-orchestrator agent's inline-role-switch workaround (the four
phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
only the autonomous/mechanical loops moved. try-and-error is deferred.
Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.
Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).
closes #7
81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# Migration
|
|
|
|
This document records the migration of AILang's in-tree
|
|
`~/dev/ailang/skills/` into this plugin — now complete — and the
|
|
layout convention and authoring checklists that came out of it.
|
|
|
|
Each skill is one top-level directory at the repo root,
|
|
containing a `SKILL.md` plus the agent files it dispatches
|
|
under `agents/`. Agents live with their dispatching skill —
|
|
this is what makes the "no orphan agents" rule structurally
|
|
true rather than only documented.
|
|
|
|
## Repo layout
|
|
|
|
Every top-level directory at the repo root that contains a
|
|
`SKILL.md` is a skill; if it dispatches agents, they live in an
|
|
`agents/` subdirectory beside that `SKILL.md`. The repo root is
|
|
the authoritative list of skills — this document deliberately
|
|
does not enumerate them, so it cannot drift out of sync as
|
|
skills are added or renamed.
|
|
|
|
`boss` is the exception with no `agents/`: it is itself the
|
|
dispatcher of the other skills, not a dispatcher-of-subagents.
|
|
|
|
`install.sh` walks the repo root, treats every top-level
|
|
directory that contains a `SKILL.md` as a skill, and symlinks
|
|
it into `~/.claude/skills/<name>`; if the skill has an
|
|
`agents/` subdirectory, that is symlinked into
|
|
`~/.claude/agents/<name>`. Claude Code's flat user-level
|
|
discovery still finds everything while the source tree keeps
|
|
the structural binding.
|
|
|
|
A skill that ships executable **Workflow scripts** keeps them in a
|
|
`workflows/` subdirectory beside its `SKILL.md` (e.g.
|
|
`implement/workflows/implement-loop.js`). `install.sh` symlinks each
|
|
`*.js` there into the flat `~/.claude/workflows/` directory — where the
|
|
Workflow tool resolves named workflows from — keeping the same
|
|
structural binding (the script lives with its dispatching skill) as
|
|
agents do. `uninstall.sh` removes those symlinks too. A workflow script
|
|
is the deterministic form of an autonomous execution loop; it dispatches
|
|
the skill's agent-types via top-level `agent()` calls (no nesting).
|
|
|
|
## Migration checklist per skill
|
|
|
|
1. Strip project-specific paths (`docs/specs`, `docs/plans`,
|
|
`docs/design/INDEX.md`, `crates/`, `bench/`).
|
|
2. Strip project-specific commands (`cargo build`,
|
|
`bench/check.py`).
|
|
3. Replace literals with fixed conventions named directly (see
|
|
`conventions.md`) or, where they vary per project, a reference to
|
|
the project's `CLAUDE.md` project facts.
|
|
4. Strip project vocabulary (`AILang`, `Form A`, `.ail.json`,
|
|
`Boss`); use the fixed vocabulary (cycle / iteration / milestone /
|
|
contract).
|
|
5. Strip project-specific contracts (honesty-rule,
|
|
feature-acceptance). These belong in the project's own
|
|
`CLAUDE.md`, not the plugin.
|
|
6. Verify the body still reads coherently for a generic
|
|
project — would it make sense in a Python web service?
|
|
A TypeScript library?
|
|
|
|
## Migration checklist per agent
|
|
|
|
1. Drop the `ailang-` prefix from the `name:` frontmatter
|
|
field. The skill path is the disambiguator.
|
|
2. Replace hardcoded standing-reading paths
|
|
(`docs/design/INDEX.md`, etc.) with the fixed standing reading
|
|
(`CLAUDE.md` + `git log -10`) plus, for role-specific files, a
|
|
reference to the per-role standing reading in the project's
|
|
`CLAUDE.md` project facts.
|
|
3. Replace project-specific Iron Law clauses with the universal
|
|
discipline constants; project-specific clauses go to the
|
|
project's own `CLAUDE.md`.
|
|
4. Verify the body still reads coherently for a generic project
|
|
(see the per-skill checklist above).
|
|
5. Confirm the `tools:` frontmatter list matches the agent
|
|
template's role-based conventions (read-only review vs
|
|
implementation vs orchestrator).
|
|
6. Confirm the agent does **not** have `Agent` in its tools list
|
|
(no nested subagent dispatch).
|