Brummel
8d375d5622
closes #5 migration.md and the README Status section described an AILang->plugin migration as "in progress" with "the remaining seven skills" pending — long since false; the whole roster has landed. The architect flagged both at the specify cycle close as pre-existing debt. Rather than re-listing every skill (which is exactly what drifted — the "Expected layout after migration" ASCII tree had to mirror each new skill and didn't), the fix removes the enumerating renderings: - migration.md: reframed as a record of the completed migration. The per-skill ASCII layout tree is replaced by the structural rule (every top-level SKILL.md dir is a skill; agents live beside it under agents/; the repo root is the authoritative roster). The per-skill and per-agent authoring checklists are kept verbatim — they retain value for new skills. Result: no enumeration, so nothing to drift. - README Status: "migration in progress / remaining seven follow" -> "migration complete"; the doc reference now points at the layout convention and authoring checklists, not an "expected final layout". Decision on the issue's open question (update vs retire): neither pure form. The tracker's enumerating parts are retired; its still-useful convention and checklists are preserved drift-proof.
66 lines
2.7 KiB
Markdown
66 lines
2.7 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.
|
|
|
|
## 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 profile-slot references in prose.
|
|
4. Strip project vocabulary (`AILang`, `Form A`, `.ail.json`,
|
|
`Boss`); use the profile's vocabulary slots.
|
|
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 a reference to the profile's
|
|
`standing_reading` section.
|
|
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).
|