aloop (Aladdin's Loop) turns one line of intent into planned, test-first, gate-verified code on Claude Code, Codex, OpenCode and DeepSeek Harness. You approve the plan. Cheap workers build it in isolated git worktrees. Deterministic hooks decide what is accepted, so no model is trusted to say "done": a gate has to see it.
/plugin marketplace add adeelahmad/aloop # inside Claude Code
/plugin install aloop@aloop-marketplace
/aladdin add CSV export to the report # or just ask in your own wordsAbout a dollar and ten minutes per tested feature in measured runs, on Rust, Python, Go and JS.
Quick start · How it works · Mission layer · Principles · Evidence · Roadmap
| 🔴 → 🟢 Test-first by construction | 🚦 Models explore. Gates decide. | 🪙 Cheap by design |
|---|---|---|
| Every task starts with a failing test (RED) that a hook proves fails. GREEN is a claim a gate checks, not a sentence a model says. | Deterministic hook gates block a stop or a tool call and hand the reason back. A gate that crashes blocks; a BLOCK is never downgraded. | Workers get their task's contract and tests, never the whole repo, so most of the work runs on the cheapest model. A whole sprint costs about a dollar. |
Formerly agentic-agile; the old names keep working (upgrading). New here? What this project is · Roadmap · Operator playbook · The site
- 🧭 The mission layer (M9, in progress). Set a mission ("the world's best to-do app"),
a budget and a cadence, confirm the baseline once, and walk away. Fixed roles research the
market, turn user journeys into a reproducible evaluation, derive the next goal from the gap
list and hand it to Aladdin as intents. Shipped:
aloop missioninit, approval, journeys, baseline, research, judges, assess, evaluate, ethics, principles, goals and the Aladdin handoff, the six fixed roles with their path-guard gates, thetickloop with its cron line, the/aloop:missionskill and opt-in GA4 telemetry. Next: the end-to-end mission run. More below. - 🚪 One-way and two-way doors (draft, #86). Core principles for every agent, inspired by Amazon's Leadership Principles: a reversible decision is the agent's to make and record; an irreversible one is stopped by a gate until the human authorizes it. More below.
- 🐋 A fourth host: DeepSeek Harness. The same gates and roles, the mission layer's included, on
the official DeepSeek Harness (
dsh), next to Claude Code, Codex and OpenCode, tested in CI on dsh's real runtime. A measured live run is next (it needs a DeepSeek key). - 🌐 Any language. RED is verified on Rust, Python, Go and JS (live runs 21 and 37 to 41), and on existing code: runs 42 and 43 extend and change a tested library without touching its seed tests.
- 🔁 Renamed. agentic-agile is now aloop (Aladdin's Loop), on the way to Aladdin 1.0.
A one-line intent, start to merged code, in a real Claude Code session with the approval given
up front. Reproduce any row with make e2e-live YES=1 INTENT=<intent> (about a dollar each;
HOST=codex or HOST=opencode runs the same loop on those hosts):
| Intent | Result | Time | Cost |
|---|---|---|---|
| a Rust semver parser (run 21) | 12/12 checks, every dispatch on the project's model | 8m17s | $0.66 |
| a Rust word-frequency tool, two dependent stories (run 27) | 13/13 checks, 1 supervisor wake | 9m54s | $0.70 |
| a Python slugify package, pytest (run 37) | 12/12 checks, RED run by the declared pytest | 9m42s | $0.69 |
a Go Roman-numeral package, go test (run 39) |
12/12 checks | 7m52s | $0.56 |
a JS camelCase module, node --test (run 41) |
12/12 checks, 1 supervisor wake | 6m45s | $0.56 |
| extend an existing crate, brownfield (run 42) | 13/13 checks, the seed's tests untouched and green | 7m11s | $0.67 |
| change an existing, tested function (run 43) | 13/13 checks, 3 lines in parse, signature kept |
9m10s | $0.67 |
| a wc-like CLI app, tested by running it (run 46) | 13/13 checks, 3 tasks, the merged binary works | 15m19s | $0.99 |
Every time and cost in the table above is a row in docs/evidence/README.md, with the
command that reproduces it; what each run found and fixed is logged in
ROADMAP §0 (M0.8 for runs 1–35, M8 from run 36). The numbers come from the harness
(run-summary reads the session's own result lines), 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:
| Step | What the agent does | What the gate checks |
|---|---|---|
| 🔴 RED | writes the tests the plan named | they fail by assertion, and no production code changed (gate-red-verify) |
| 🟡 SCAFFOLD | declares the symbols the tests need | each exists exactly once, as a SUB-AGENT-TODO panic stub (gate-scaffold-verify) |
| 🟢 GREEN | makes the tests pass | inside the task's files only, with zero suppressions (gate-green-verify) |
| 🔍 STRUCTURAL-REVIEW | looks for duplicates and orphans | symbol uniqueness from ctx-symbols |
| ✅ FINAL-GATE | runs the sprint's whole matrix once | every planned test is 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 missing, and GREEN is then a claim the gate can check,
not a sentence the model can say. It also keeps workers small: each one gets its task's contract,
its tests and the resolved change targets (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), commit on main during a sprint, or dispatch with its backends missing (gate-tooling), on a model the project did not pick, or before the human approved the sprint's plan, or granted it autonomy, in a line they typed (gate-dispatch); - 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, and 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.
Missionary Aladdin Genie: milestone M9, in progress. The spec and task graph are in ROADMAP §4.12; the track notes in plugin/mission/README.md.
Aladdin builds what you ask for. The mission layer decides what to ask for next. You set a
mission, which is bigger than a goal, plus a budget, a cadence and a mode (autonomous or
spoon-fed). You confirm the starting baseline and the direction in plain language, once. You never
write a metric or a journey. The loop is IBM's autonomic MAPE-K cycle over a committed knowledge
base (docs/agents/mission/):
flowchart TB
M["🧭 Mission<br/>set once by you"] --> R["Research<br/>market and rivals"]
R --> J["User journeys<br/>scripted, sourced"]
J --> B["Baseline<br/>measured twice, you confirm"]
B --> A["Assess<br/>current state"]
A --> E{"Evaluate<br/>gap list"}
E -- "goal met: raise the bar" --> R
E -- "gaps" --> G["Goal<br/>ethics + principles"]
G --> I["Aladdin intents"]
I --> S["Sprint<br/>RED → GREEN → gates"]
S --> A
Every element has a deterministic check (aloop mission <area> check: exit 0 pass, 2 block,
3 needs the human). The mission is sealed by its sha256 and counts only under the human's own
approval of that exact content: aloop mission approve records only when a prompt the human typed
(captured by the UserPromptSubmit hook) has a line such as approve msn_… 3f2a9c1b, whose code is the
first 8 hex of the content's sha256, so an agent cannot approve its own change (M9.17). The records the
gates decide from (approvals, measurements, assessments, retirements, goals) are rows in a
hash-chained, committed ledger, so an edited or backdated row, or one removed before the newest,
fails the check. The ethics verdicts, the tick --force grant, mission.budget_exhausted and the
project's stop (aloop stop) are ledger rows too, so a clone decides the same; a removed newest row is
caught only where the run log survives (M9.24, M10.4). The confirmed definition of "best" is the
mission's RED: a baseline whose journeys all pass already is refused. Usage telemetry (GA4,
opt-in) informs goals and is never a gate.
| Track | What | Status |
|---|---|---|
| Core | aloop mission init / approve / check / status, the sealed mission, the ledger |
✅ shipped |
| Journeys, baseline, assess, evaluate | user journeys as the evaluation, a frozen baseline, the gap list | ✅ shipped |
| Research and judges | sourced claims with archived snapshots; LLM judges on pinned models and a frozen rubric, decided by majority | ✅ shipped |
| Ethics and principles | clear / gray / hard-line review of every goal, consent bound to its sha256; the principles below | ✅ shipped |
| Telemetry | GA4 set up by the agents through its API, opt-in, minimum-sample rule | ✅ shipped |
| Roles and gates | the six fixed roles, their model routes, and two gates (role path guards, artifact checks) | ✅ shipped |
| Goals → intents | the top gaps become a goal, one Intent Contract per gap, handed to Aladdin | ✅ shipped |
| Loop and skill | tick, a zero-token due, the cron line, budget caps, /aloop:mission |
✅ shipped |
| End to end | an offline scripted mission cycle in CI, then a live one | ⏳ next |
The goal principles shipped in M9.7 (plugin/mission/principles.md,
ROADMAP §4.12): every goal carries their hashed block (aloop mission principles show / hash / check).
Today the door rule holds at intake: intent check (run by gate-intake) blocks a run while an ask
question, one that is irreversible, security-sensitive or intent-changing, has no recorded answer
(ROADMAP §4.1). A gate for doors met mid-run is in a draft PR,
#86.
Agents that drive goals follow a short set of principles inspired by Amazon's Leadership Principles, chosen because they pull against each other and so keep the flywheel turning. No principle can relax an invariant.
🚪 Is the door one-way or two-way? A two-way door is reversible: a branch, a draft PR, a file, a retry, a re-plan. The agent decides, records the call with a one-line reason, and keeps going. A one-way door cannot be walked back by the time anyone reads about it: a production change, a deletion, a message sent outside the project, a weakened gate or test. The agent asks the human once, with a recommended option, and the action waits for the human's recorded yes.
| Principle | In practice |
|---|---|
| The autonomic loop | monitor, analyze, plan, execute, then measure again |
| Own the outcome | "done" is the user's goal, not the current step |
| Verify, don't assume | done is a passing gate verdict, never a sentence |
| Ship small, ship often | one task, one RED proof, one worktree |
| Raise the bar | a met goal sends the loop back to the mission for a higher one |
| Disagree, then commit | a decision record with a reason and evidence |
| Leave it better | log it, don't fix it, outside the task's scope |
| Know when to stop and ask | the clarification table: assume, default, ask or spike |
| Grow adoption | real use (journeys completed, users coming back), never engagement tricks |
| Keep it simple | the simplest change that closes the gap: fewest moving parts and tokens, no new service or dependency without a measured need |
Tension pairs: customer obsession vs frugality, bias for action vs dive deep, think big vs deliver results, grow adoption vs keep it simple.
# 1) Have a Rust toolchain >= 1.85 (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/aloop
/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)
# 3) Say what you want
/aladdin add CSV export to the reportCodex: from a clone, plugin/bin/aloop install codex (agent TOMLs and aloop on PATH), then
codex plugin marketplace add adeelahmad/aloop, codex plugin add aloop@aloop-marketplace, and trust
the hooks once in Codex's /hooks. OpenCode: plugin/bin/aloop install opencode renders
everything. DeepSeek Harness: plugin/bin/aloop install dsh --project . renders a dsh profile,
then run dsh --profile aloop. Every way you get full parity (hooks, agents, gates, time box, ledger,
stats, handoff). See plugin/README.md → Codex and OpenCode
and → DeepSeek Harness.
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-symbolsandmd-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 (on PATH inside host sessions; in your own terminal afteraloop install codex|opencode|dshlinks it into~/.local/bin, or from a clone asplugin/bin/aladdin);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.
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/aloop
/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.
| Host | Install | Gates | Isolation | Status |
|---|---|---|---|---|
| Claude Code | /plugin install aloop@aloop-marketplace |
native hooks | host worktrees (isolation: "worktree") |
✅ reference host, every measured run |
| Codex | aloop install codex + codex plugin add aloop@aloop-marketplace (trust in /hooks) |
native hooks | task-worktree + aloop bind |
✅ hooks emulated in CI; live run pending |
| OpenCode | aloop install opencode |
outer (the plugin wraps every tool call) | task-worktree + aloop bind |
✅ plugin end to end in CI; live run pending |
DeepSeek Harness (dsh) |
aloop install dsh, then dsh --profile aloop |
native (a plugin on dsh's own deny, block and steer points) | task-worktree + aloop bind (denial) |
✅ plugin end to end in CI, also on the real dsh runtime; live run pending (needs a DeepSeek key) |
One HostAdapter interface behind every host (aloop host describe); the same conformance suite
runs on each (make test-hosts), and a sprint can move between them from portable state.
TheNoteBook, a full Go backend, was built with this plugin (v0.8, June 2026, then named
agentic-agile) from a README + /agentic-agile:init (today /aloop:init) + a handful of prompts. Measured by the owner
from the Claude Code transcript and the resulting repo; it predates the evidence ledger, so it
has no ledger row:
| 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) and 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.
Live runs: make smoke-live YES=1 (hook wiring, ~$0.004) and make e2e-live YES=1 (the whole
loop, ~$1; each run writes summary.json and a row for docs/evidence/). Offline: make ci, which runs Rust fmt/clippy/tests, shellcheck, 57 Python/Node suites plus every mission-*.test.py,
the gate conformance fixtures (make conformance) and eval-suite validation. Every ROADMAP
requirement is tracked with its test in docs/TRACKING.md.
Every run leaves an aladdin.event/1 stream (.aladdin/logs/events.jsonl): intent received,
plan approved, task dispatched, gate verdicts, worktrees merged, commits created, decisions with
their one-line rationale and authority, and 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, mission …)
agents/ the 15 roles (Aladdin's 9 + the mission layer's 6) · skills/ the supervisor playbooks (aloop, aladdin, init, mission)
hooks/ hooks.json (aloop:<role> matchers) · hosts/ capabilities, routes, the OpenCode and dsh plugins
mission/ the mission layer's areas (journeys, baseline, assess, evaluate …) and their schemas
schemas/ KDL schemas for the planning artifacts · tools/ ctx-symbols + md-db sources
docs/ OVERVIEW.md ROADMAP.md TRACKING.md, the evidence ledger, brand/
Prerequisites
| 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.85) |
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.
Development (Makefile)
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 # CI's offline checks: fmt-check · lint · test · eval-validate · test-hosts · conformance
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 · test-hosts · conformance). Bypass with SKIP_HOOKS=1
(e.g. SKIP_HOOKS=1 git commit …) for an intentional WIP commit or a known-failing
local dependency.
Versioning, changelog and CI
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.
.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 and dsh plugins end-to-end, the dsh one also on the real (pinned) dsh runtime against a scripted model (no network, no tokens).
- macos: the same host tests and the conformance fixtures on macOS, where temp dirs sit behind a symlink and the userland is BSD.
- plugin: JSON sanity on the manifest + marketplace, eval-suite validation, version
lockstep, then
claude plugin validate ./plugin --strict.
| Milestone | What | Status |
|---|---|---|
| M0 to M7 | hygiene, trustworthy state, budgets that plan, clean boundaries, intent contracts, narrow context, audit, any host | ✅ shipped in v0.12.0 |
| M8, Aladdin 1.0 | /aladdin and the CLI, the site, measured public runs on every host |
🔄 in progress |
| M9, mission layer | Missionary Aladdin Genie: missions, journeys, baseline, goals | 🔄 in progress |
| Next | the door gate (#86), Codex, OpenCode and DeepSeek Harness public runs | 🔄 in progress |
The full spec, every requirement's status and the reason behind each call: docs/ROADMAP.md and docs/TRACKING.md.
- With no
standards.mdmatrix the gates default to Rust. Python, Go and JS run the matrix the standards role writes, and RED is checked by their declared runner (pytest,go test,node --test/npm); any other stack runs its matrix, but RED checks only the exit code. - 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. Codex, OpenCode and DeepSeek Harness have no measured public run yet. - The mission layer has not run end to end yet: every part is shipped, but the offline and live mission runs (M9.13) are still to come.
- Run data lives in
.aladdin/, whose own.gitignorekeeps everything butconfig.yaml(the human's file) out of git. A project that still has.agentic/keeps using it untilaloop layout migrate.docs/agents/and theAGENTIC_*keys keep their pre-rename names.
Issues and PRs are welcome: start with CONTRIBUTING.md, and report a vulnerability privately as SECURITY.md describes. Agents working on this repo follow the flywheel in CLAUDE.md: tests first, a draft PR, and the evidence in the PR.
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.