Skills/docs/migration.md

Migration

This document tracks the migration from AILang's in-tree ~/dev/ailang/skills/ into this plugin.

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.

The boss skill is the migration pilot (landed); the remaining seven skills follow once the pattern is approved.

Expected layout after migration

~/dev/skills/
├── README.md
├── INSTALL.md
├── install.sh
├── uninstall.sh
├── docs/
├── templates/
├── boss/                          (pilot: landed)
│   └── SKILL.md
├── brainstorm/
│   ├── 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.

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).