Loop mode: /allium drives the whole loop to convergence

[yavorpanayotov]

Why

Allium's full value is the loop — spec → tests → code driven to agreement — but reaching it used to mean orchestrating several skills by hand. This PR makes the loop the default: give /allium a goal and it drives the whole loop to convergence. One command, and not even a new one — the tool's existing front door now takes a goal.

What

/allium <goal> drives the loop — the allium entry-point skill now runs the loop itself: entry-point detection → per-tick gather/act/verify/route → convergence invariant → stop conditions (6 hard / 2 no-progress / escalate, anti-cheat) → open-question park-vs-escalate → decomposition + integration pass → phase isolation → git-ignored ledger → real-verification guardrails. Layer 1 (in-session); unattended re-invocation (Layer 2) is documented as future work.

Driver procedure lives in skills/allium/references/driving-the-loop.md, which the allium skill follows. There is no separate /allium:loop command and no standalone loop skill — the loop is /allium.

Entry point — /allium biases toward the autonomous path: drive the whole loop for a goal/feature, direct-route a clear single task, and present the menu-with-hints (with a recommended starting point) only when the request is bare or ambiguous. Plus the standing nudge to suggest the next phase after a single skill finishes.

Docs — the README "The Allium loop" section + "loop in motion" transcript; the recommended-loops.md reference (gather → act → verify → repeat, spec-first and code-first walkthroughs, the convergence invariant); README skills table + count updated (five skills plus the /allium entry point).

Test hardening (scripts/test-skills.mjs) — offline groups, each mutation-verified to fail on a real break:

• consistency — version parity across manifests; skill registration identical across skills/, the test registry, and the .claude-plugin skills[] array.
• broadened links — checks README, all references/*.md, and design notes.
• loopdocs — the caps (6 / 2) and phase phrase stay consistent across the docs that restate them (now including driving-the-loop.md).
• hooks — hooks.json is valid, has a matcher, and points at a script that exists.

Version — manifests at 3.7.0.

Validation

node scripts/test-skills.mjs → 89 passed, 0 failed, 3 skipped (the 3 need --live). generate-multi-editor.mjs --check clean. CI runs the offline suite on every push.

Note for the marketplace re-vendor (follow-up)

design/loop-mode.md and design/loop-mode-local-testing.md are internal design notes (now carrying "superseded" banners). Per their lifecycle, they should not ship to end users — when re-vendoring to juxt/claude-plugins, exclude design/ from sync-allium.sh so they don't land in the published plugin.

🤖 Generated with Claude Code

[yavorpanayotov]

How to use /allium:loop (and what you'll see)

One command drives the whole loop — spec → tests → code, repeating until they agree.

You want to…	Run	It starts by…
Build a new feature	/allium:loop add gift cards to checkout	eliciting a spec, then propagate → implement → weed
Work with existing code	/allium:loop on an unspecced area	distilling a spec, then propagate → run vs code → weed
Just get oriented	/allium	recommending the loop + a starting point

• Override the entry if you know better — say distill / tend, or /allium:loop distill <area>.
• Prefer manual control? Run the phases yourself: /elicit → /propagate → implement → /weed, /tend as needs change. (Same loop, hand-driven.)
• It stops on its own (iteration caps + escalate-on-decision) and never edits a test to fake a pass.

Feedback as it goes — announce-and-proceed, no confirmation gates:

→ No spec here, code present, goal reads as new behaviour → starting with elicit  (say "distill"/"tend" to switch)
→ Gather:  eliciting spec …  (allium check runs on every edit — fix issues before propagating)
→ Act:     propagate tests → confirm RED → implement
→ Verify:  run tests → weed → allium analyse
tick 1 · tests 4/4 · weed clean · openQ 0
✓ Converged — spec, tests and code agree.

• Entry announcement — what it's starting on (proceeds immediately; interrupt to redirect).
• Phase markers — one line as each phase begins.
• Tick summary — tests / weed / open-question counts after each pass.
• Final report — what converged, anything escalated, leftover questions.
• Underneath, the harness still shows the real commands (allium check, the test run, file edits) — detail without narrating every line.

Where validation lands (following Allium's continuous-validation model):

• allium check (spec structure) runs on every spec edit via the hook/LSP — the spec must be valid before propagating, since tests are generated from it.
• weed (spec ↔ code drift) runs in Verify, once code exists.
• allium analyse (semantic gaps: dead ends, unreachable states) sharpens elicitation and re-checks the assembled spec in Verify.

Converges when: tests pass and weed is clean and no open questions remain (code-first: also when a fresh distill finds nothing new).