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