Files

T

Brummel 7a58a530b1 feat(pipeline): route to the lightest correct methodology; move execution loops onto the Workflow substrate

The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.

Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
  a verification/enumeration axis ahead of the settled-vs-fork question.
  Each lighter arm carries a positive trigger matched by signature, not
  reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
  that propagates mechanically. Observe-then-bounce — make the edit,
  build, run the suite; clean build AND suite green unchanged commits;
  a hole bounces up (specify for a design choice, tdd for discovered
  test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
  mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
  mechanical/forwarding -> compiler-driven; encodes new behaviour ->
  tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
  not a heavy new skill ("the largest concrete win is small").

Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
  phase (implementer -> spec-compliance -> quality, + tester for E2E) is
  a separate top-level agent() call, so a single phase is independently
  invokable and inter-phase aggregation/re-loop is code. Retires the
  implement-orchestrator agent's inline-role-switch workaround (the four
  phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
  ~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
  only the autonomous/mechanical loops moved. try-and-error is deferred.

Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.

Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).

closes #7

2026-06-17 12:27:51 +02:00

3.6 KiB

Raw Permalink Blame History

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

Strip project-specific paths (docs/specs, docs/plans, docs/design/INDEX.md, crates/, bench/).
Strip project-specific commands (cargo build, bench/check.py).
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.
Strip project vocabulary (AILang, Form A, .ail.json, Boss); use the fixed vocabulary (cycle / iteration / milestone / contract).
Strip project-specific contracts (honesty-rule, feature-acceptance). These belong in the project's own CLAUDE.md, not the plugin.
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

Drop the ailang- prefix from the name: frontmatter field. The skill path is the disambiguator.
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.
Replace project-specific Iron Law clauses with the universal discipline constants; project-specific clauses go to the project's own CLAUDE.md.
Verify the body still reads coherently for a generic project (see the per-skill checklist above).
Confirm the tools: frontmatter list matches the agent template's role-based conventions (read-only review vs implementation vs orchestrator).
Confirm the agent does not have Agent in its tools list (no nested subagent dispatch).

3.6 KiB Raw Permalink Blame History

Migration

Repo layout

Migration checklist per skill

Migration checklist per agent

3.6 KiB

Raw Permalink Blame History