docs: retire the stale migration tracker, make layout drift-proof

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.
This commit is contained in:
2026-06-04 23:36:47 +02:00
parent fd9d73c3b0
commit 8d375d5622
2 changed files with 18 additions and 59 deletions
+6 -5
View File
@@ -139,8 +139,9 @@ plugin.
## Status
Migration from AILang's in-tree `~/dev/ailang/skills/` is in
progress. The `boss` skill is the landed pilot; the remaining
seven skills follow. See `docs/migration.md` for the per-skill
and per-agent migration checklists and the expected final
layout.
The migration from AILang's in-tree `~/dev/ailang/skills/` into
this plugin is complete — the pipeline skills, the `specify` and
`tdd` entry paths, the `boss` orchestrator, and the utility and
conversational skills documented above have all landed.
`docs/migration.md` records the repo-layout convention and the
per-skill and per-agent authoring checklists.
+12 -54
View File
@@ -1,7 +1,8 @@
# Migration
This document tracks the migration from AILang's in-tree
`~/dev/ailang/skills/` into this plugin.
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
@@ -9,60 +10,17 @@ under `agents/`. Agents live with their dispatching skill —
this is what makes the "no orphan agents" rule structurally
true rather than only documented.
The `boss` skill is the migration pilot (landed); the remaining
seven skills follow once the pattern is approved.
## Repo layout
## Expected layout after migration
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.
```
~/dev/skills/
├── README.md
├── INSTALL.md
├── install.sh
├── uninstall.sh
├── docs/
├── templates/
├── boss/ (pilot: landed)
│ └── SKILL.md
├── brainstorm/
│ └── SKILL.md
├── specify/
│ ├── SKILL.md
│ └── agents/
│ └── grounding-check.md
├── planner/
│ ├── SKILL.md
│ └── agents/
│ └── plan-recon.md
├── implement/
│ ├── SKILL.md
│ └── agents/
│ ├── implement-orchestrator.md
│ ├── implementer.md
│ ├── spec-reviewer.md
│ ├── quality-reviewer.md
│ └── tester.md
├── audit/
│ ├── SKILL.md
│ └── agents/
│ ├── architect.md
│ └── bencher.md
├── debug/
│ ├── SKILL.md
│ └── agents/
│ └── debugger.md
├── fieldtest/
│ ├── SKILL.md
│ └── agents/
│ └── fieldtester.md
└── docwriter/
├── SKILL.md
└── agents/
└── docwriter.md
```
`boss` has no agents — it is itself the dispatcher of the
others, not a dispatcher-of-subagents.
`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