Turn any intent into planned, test-first, gate-verified software on Claude Code, Codex and OpenCode. A human approves the plan, cheap workers build it in isolated worktrees, and deterministic hooks decide what is accepted.
Models explore. Gates decide.
aloop (Aladdin's Loop) turns one line of intent into planned, test-first, gate-verified software on Claude Code, Codex and OpenCode. You approve the plan; cheap workers build it in isolated git worktrees; deterministic hooks decide what is accepted. No model is trusted to say "done" — a gate has to see it.
aladdin "add CSV export to the report" # records the intent, tells you how to start
/aladdin add CSV export to the report # …or say it inside your host; /aloop is the same
Formerly agentic-agile; see Upgrading from agentic-agile. New here? What this project is · Roadmap · Operator playbook · The site
A one-line intent, start to merged code, in a real Claude Code session with the approval
given up front — reproducible with make e2e-live YES=1 (spends about a dollar):
| Intent | Result | Time | Cost |
|---|---|---|---|
| a semver parser (run 6) | 11/11 checks, tests on main, worktree branches merged --no-ff |
11m10s | $0.65 |
| a word-frequency tool, two dependent stories (run 9) | 12/12 checks | 19m42s | $1.56 |
Every run and what it found is logged in ROADMAP §0 (M0.8). The
numbers come from the harness's own stats.md, not from the model.
Do not merely give an agent a goal. Give it a failing proof of what is missing, then make it earn GREEN. Each task runs as a chain of sub-agents, each stopped by a hook that can block the stop and hand the reason back:
- RED writes the tests the plan named — and must fail them (
gate-red-verify). - SCAFFOLD declares the symbols the tests need — no bodies (
gate-scaffold-verify). - GREEN makes the tests pass touching only the task's files (
gate-green-verify). - STRUCTURAL-REVIEW checks symbol uniqueness, duplicates and orphans (
ctx-symbols). - FINAL-GATE runs the sprint's whole matrix once; every planned test must be on main.
- Intent → contract.
intaketurns your words into an internal Intent Contract (success and failure scenarios, open questions classed assume / default / ask / spike). - Planning, with you.
standardsthenplannerproduce the sprint contract and, per story,tasks.md/validate.md/plan.md— or a single semantic plan (targets.json) they are rendered from. The supervisor stops for your approval; nothing is built before Stage 2 is approved. - Execution, without you. One worktree-isolated worker per task through the chain above;
the supervisor spends no tokens watching (
sweep waitwakes on events) and acts on facts: accept, retry, re-plan, roll over, spawn. - Budgets that plan. Every attempt is boxed in tokens and minutes (soft warning, hard stop); a hard breach is classified and re-planned, never retried as-is; the sprint has its own envelope and admission control.
- Close and rotate. The harness writes
stats.mdand a canonicalhandoff.json→NEXT.md; the next session resumes from evidence (aladdin resume), on the same host or another one (host swap).
A passing test written after the code proves the code does what the code does. A failing test
written before it proves the code is targets context), never the whole repo.
Determinism is structural, not vibes. Hooks enforce what the model cannot talk its way past:
- the supervisor cannot write production source (
gate-supervisor-scope) or dispatch with its backends missing (gate-tooling); - a worker cannot leave its worktree, touch files outside its task, or pass a stop whose gate failed;
- a gate that crashes blocks (
_failclosed.sh) — never a silent pass, never a false block when a backend is absent (it degrades to a flagged, weaker check); - a host that cannot block natively is wrapped by an outer controller (
host checkfails CI otherwise). A BLOCK is never downgraded to WARN.
Models pick the route (strongest | strong | economical, resolved per host); the gates decide what lands.
# 1) Have a Rust toolchain >= 1.82 (rustup.rs or `brew install rust`). The plugin
# builds its gate backends (ctx-symbols + md-db) itself on first session start and
# puts them on PATH for every agent. (Manual alternative: ./plugin/tools/install.sh)
# 2) Add the marketplace and install the plugin (inside Claude Code)
/plugin marketplace add adeelahmad/agentic-agile
/plugin install aloop@aloop-marketplace
/reload-plugins # apply hooks without a full restart
# (for local dev, point marketplace add at your checkout instead: ./path/to/repo)The plugin is now aloop@aloop-marketplace (since v0.11.0; current v0.12.0). Swap the install once:
/plugin uninstall agentic-agile@agentic-agile-marketplace
/plugin marketplace remove agentic-agile-marketplace
/plugin marketplace add adeelahmad/agentic-agile
/plugin install aloop@aloop-marketplaceNothing in your project changes: .agentic/, docs/agents/ and the AGENTIC_* keys in
defaults.md are read as before. The old command names agentic, agentic init and
agentic-init still work as aliases of aloop. On Codex or OpenCode, re-run
aloop install <host>; it removes the pre-rename generated files.
Codex / OpenCode: plugin/bin/aloop install codex or … install opencode from a
clone — full parity (hooks, agents, gates, time box, ledger, stats, handoff). See
plugin/README.md → Codex and OpenCode.
Staying current: third-party marketplaces don't auto-update by default — run
/plugin marketplace update aloop-marketplace(or enable auto-update in/plugin→ Marketplaces), then/reload-plugins. Step 1 (the Rust-builtctx-symbols
md-db) is what makes the gates run at full strength; without it they degrade to grep.
- Just ask inside the host: the skill is model-invoked and triggers on build / fix /
improve / add requests even if you never say "agile" — or invoke
/aladdin,/aloopor/aloop:init. - From a shell:
aladdin "<intent>"records the intent;aladdin status(one line per task from the harness files, tasks to re-gate, token totals);aladdin resume(what the next session loads);aladdin report(the sprint'sstats.md);aladdin target | context | refs | callers(the semantic queries). Every tool is alsoaloop <tool>(aloop --list). - Settings live in
.aladdin/config.yaml(budgets, models, context, semantic, provenance, git);aloop config migratecreates it from an olderdocs/agents/defaults.md, which is then rendered from it.
| Host | Install | Gates | Isolation |
|---|---|---|---|
| Claude Code | /plugin install aloop@aloop-marketplace |
native hooks | host worktrees (isolation: "worktree") |
| Codex | aloop install codex |
native hooks | task-worktree + aloop bind |
| OpenCode | aloop install opencode |
outer (the plugin wraps every tool call) | task-worktree + aloop bind |
One HostAdapter interface behind all three (aloop host describe); the same conformance suite
runs on every host (make test-hosts), and a sprint can move between them from portable state.
TheNoteBook — a full Go backend — was built with this plugin from a README +
/aloop:init + a handful of prompts. Measured directly from the Claude Code
transcript and the resulting repo:
| Metric | Value |
|---|---|
| Output tokens | ~1.55M total |
| Model mix (by output) | 76% Sonnet 4.6 · 24% Opus 4.8 |
| Agent turns | ~1,140 |
| Input cache hits | 99.9% — 135M cache-read vs 0.11M fresh read |
| Produced | 18 internal packages · ~6.1K LOC production Go + ~11.3K LOC tests · 322 tests · 74 commits across 6 sprints |
That's a fully-tested ~17K-LOC backend for ~1.5M output tokens. The leanness is structural, not luck:
- Scoped context per worker — each sub-agent runs in its own git worktree carrying
only its task's contract (
init.md) + the tests, never the whole repo, so cheaper models (Sonnet did 76% of the work) handle most tasks. - Gates verify deterministically —
validate_comms,ctx-symbols,md-db, and the RED/GREEN/structural checks replace expensive model reasoning and re-reads. - Caching covers ~99.9% of input, and the hooks keep the orchestrator cheap by blocking it from doing the context-heavy work itself.
These mechanisms are codebase-agnostic — greenfield is simply what's measured here.
Live runs: make smoke-live YES=1 (hook wiring, ~$0.004) and make e2e-live YES=1 (the whole
loop, ~$1). Offline: make ci — Rust fmt/clippy/tests, shellcheck, 30 Python/Node suites,
the gate conformance fixtures (make conformance), eval-suite validation. Every ROADMAP
requirement is tracked with its test in docs/TRACKING.md.
Every run leaves an aladdin.event/1 stream (.agentic/logs/events.jsonl): intent received,
plan approved, task dispatched, gate verdicts, worktrees merged, commits created, decisions with
their one-line rationale and authority — never a transcript copy.
aloop events trace <sha> # commit → task → gates → plan → intent → approver
aloop events lineage <task> # dispatch → attempts → gates → merge
aloop events graph --format dot # the whole run as a graph
aloop stats show # tokens by class, every session of the project
Usage is reported by class (fresh input, cache read/write, output, context) and marked
estimated where a host does not report it. Commit messages are built from the task and its
change rationale.
.claude-plugin/marketplace.json marketplace catalog (source: ./plugin)
plugin/ the installable plugin (see plugin/README.md)
bin/ the tools and gates (aladdin, aloop, gate-*, budget, sweep, targets, events, host, config …)
agents/ the 9 roles · skills/ the supervisor playbooks (aloop, aladdin, init)
hooks/ hooks.json (aloop:<role> matchers) · hosts/ capabilities, routes, the OpenCode plugin
schemas/ KDL schemas for the planning artifacts · tools/ ctx-symbols + md-db sources
docs/ OVERVIEW.md ROADMAP.md TRACKING.md + the design history
| Tool | Required? | Purpose | Install |
|---|---|---|---|
| ctx-symbols | recommended | symbol uniqueness (count==1) + duplicate/orphan detection |
./plugin/tools/install.sh (builds from plugin/tools/ctx-symbols) |
| md-db | recommended | validates .md artifacts against plugin/schemas/*.kdl |
./plugin/tools/install.sh (builds from vendored plugin/tools/md-db, AGPL-3.0) |
| Rust toolchain | required to install | builds both backends; also runs the target repo's fmt/clippy/test/coverage matrix | rustup (>= 1.82) |
Both backends are optional: absent → gates WARN and fall back to grep (never a false
block, never a silent pass). See plugin/README.md for the gate
env-contract and how to retarget a non-Rust repo.
make (no target) prints all targets. Common ones:
make install # build + install ctx-symbols and md-db to ~/.local/bin
make link # register THIS repo as a local marketplace and install the plugin
make ci # everything CI runs: fmt-check · lint · test · eval-validate
make test # ctx-symbols + md-db unit tests
make lint # clippy -D warnings + shellcheck + JSON sanity
make validate # claude plugin validate ./plugin --strict
make eval-validate # validate every eval suite's JSON (no tokens)
make eval SUITE=… # run one eval suite live (YES=1 spends tokens; see scripts/eval/)
make hooks # install the tracked git hooks (.githooks → core.hooksPath)
make smoke # offline gate smoke test
make release # verify (ci+validate+version-check) then tag vX.Y.Z
make publish # push branch + tags to origin
make package # bundle the release into package/ + publish the GitHub release (gh)Git hooks (opt in with make hooks): pre-commit runs fmt-check · json · eval-validate · version-check (fast, no tokens); pre-push runs the full
make ci (fmt-check · lint · test · eval-validate). Bypass with SKIP_HOOKS=1
(e.g. SKIP_HOOKS=1 git commit …) for an intentional WIP commit or a known-failing
local dependency.
SemVer; see CHANGELOG.md. Keep the version in
plugin/.claude-plugin/plugin.json, plugin/tools/ctx-symbols/Cargo.toml, and the
top CHANGELOG.md entry in lockstep — make version-check (and make release)
enforce this. Tag releases vMAJOR.MINOR.PATCH.
git init && git add -A && git commit -m "aloop v0.1.0"
git remote add origin <your-repo-url>
make hooks # optional: enable local git hooks
make ci # green before tagging
make release # tags v0.1.0
make publish # pushes branch + tags.github/workflows/ci.yml runs on every push/PR:
- rust —
cargo fmt --check,cargo clippy -D warnings, tests forctx-symbols+md-db. - shellcheck — lints every gate script (
plugin/bin/*), errors fail the build. - hosts — byte-compiles the Python hooks, then Codex hooks emulation + the OpenCode plugin end-to-end (no network, no tokens).
- plugin — JSON sanity on the manifest + marketplace, eval-suite validation, version
lockstep, then
claude plugin validate ./plugin --strict.
- The standards matrix targets Rust by default; retarget it by editing
standards.mdand the gates (seeplugin/README.md). The loop itself is language-agnostic. - Gates run at full strength only with the Rust-built
ctx-symbols+md-db; without them they degrade to a grep fallback that is flagged as weaker. refs/callers/calleesneed a configured LSP server (AGENTIC_LSP_COMMAND); without one they say so and exit 4 rather than guess.- CI validates the plugin and runs every offline suite, but not a live session; the live runs
(
make smoke-live,make e2e-live) spend tokens and are run by hand. - The on-disk layout keeps its pre-rename names (
.agentic/,AGENTIC_*,docs/agents/) for the migration window;.aladdin/config.yamlis the human's file.
MIT — see LICENSE. ctx-symbols is harvested from the MIT-licensed
ctxconfig code-intelligence layer (see plugin/tools/ctx-symbols/README.md).
plugin/tools/md-db/ is vendored third-party source under AGPL-3.0-or-later
(decisiongraph/md-db-rs), kept under its
own LICENSE. It is built into a standalone md-db
binary the gates shell out to — the MIT plugin code links to none of it — but anyone
redistributing this repository must honor AGPL-3.0 terms for that subtree.