Brummel
4f83305525
Add `specify` as a third co-equal entry path into the dev cycle: it produces an approved spec from already-settled sources (an exhaustive issue, a long in-context design discussion, or a design brainstorm just ratified) with review but no interview. This is the producing half of a deliberate deciding/producing split — `brainstorm` shrinks to optional discovery, `specify` becomes the sole spec-production gate before `planner`, mirroring the RED->GREEN split that keeps tdd/debug honest. What moved: - brainstorm/SKILL.md: stripped of the hard-gate, the acceptance criterion, write-spec, self-review, grounding-check, user-review, and planner-handoff steps; terminal state is now handing a ratified design narrative to specify. Steps renumbered 1-5 (production steps left). - specify/SKILL.md (new): the production core, with a precondition gate (Step 1.5) that bounces to brainstorm the moment the sources do not resolve a load-bearing decision — the same discipline tdd uses. - The grounding-check agent moved brainstorm/agents/ -> specify/agents/ (no-orphan-agents: it lives under its dispatcher), refs repointed. - boss/SKILL.md: Entry-path reflection is now three-way (tdd / specify / brainstorm). specify dispatches autonomously (bounded, no interview) and pauses at its user-review gate; only a fresh brainstorm cycle stays a pre-dispatch bounce-back. - pipeline.md, README, profile-schema, the profile template, and the migration layout updated so every pipeline rendering agrees; specify is a CORE node (not opt-in, unlike tdd) carrying gates: [planner]. Design alternative rejected: parallel sibling skills sharing a docs/spec-production.md (extract-to-doc). Chosen extract-and-chain instead — the shared surface is ~70%, so a shared doc would either become the skill body or drift; chaining keeps one executed home for the gates. Verification (prose repo, no test suite): the spec's internal- consistency grep suite (no two-path drift, no direct brainstorm->planner edge, specify referenced in every rendering, grounding-check single home under specify, specify structural completeness) all green. Orchestrator inspection additionally fixed two dead step-refs the plan under-scoped (a "(Step 4)" lift-validation pointer and a "Skipping Step 7 self-review" red flag, both pointing at steps brainstorm no longer has) and corrected six pre-existing brainstorm->planner renderings in pipeline.md and tdd that predated this cycle. Known follow-ups (non-blocking): the committed spec writes `skills/specify/` in places (typo; skill dirs are repo-top-level) — to be corrected separately. The grounding-check hard-gate was degenerate for this very cycle (this repo has no profile and no test suite); the skip is documented in the spec and the session.
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# 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
|
|
├── 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.
|
|
|
|
`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).
|