8000 M11: autonomous by default; only one-way doors go to the human by adeelahmad · Pull Request #122 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content
7FFF
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Aloop: standing goal

**What it is.** **aloop** (Aladdin's Loop; formerly agentic-agile, heading for **Aladdin 1.0**) is a plugin for Claude Code, Codex and OpenCode that turns any intent into planned, test-first, gate-verified software. A human approves the plan, cheap workers build it in isolated worktrees, and deterministic hooks decide what is accepted. *Models explore. Gates decide.*
**What it is.** **aloop** (Aladdin's Loop; formerly agentic-agile, heading for **Aladdin 1.0**) is a plugin for Claude Code, Codex and OpenCode that turns any intent into planned, test-first, gate-verified software. A human gives the intent and answers only one-way-door questions (generation is cheap: anything reversible is decided, recorded and redone on request), cheap workers build it in isolated worktrees, and deterministic hooks decide what is accepted. *Models explore. Gates decide.*

**North star.** A one-line intent becomes merged, tested, auditable code on any host, with no human help beyond approval, at the lowest token cost.
**North star.** A one-line intent becomes merged, tested, auditable code on any host, with no human help beyond the intent and one-way-door answers, at the lowest token cost.

**Done means.** Every milestone's exit criterion is proven by a test or a measured run, CI is green, and `docs/OVERVIEW.md` and `docs/ROADMAP.md` match the code.

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
# Aladdin: intent is all you need

**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
code on Claude Code, Codex, OpenCode and DeepSeek Harness. You give the intent and answer only one-way-door questions. 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.

Expand Down Expand Up @@ -359,7 +359,7 @@ 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)
agents/ the 16 roles (Aladdin's 10 + 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
Expand Down
23 changes: 12 additions & 11 deletions docs/OVERVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ still work as aliases. The 1.0 target is **Aladdin**; see [ROADMAP.md](ROADMAP.m
## In one sentence

**aloop is a coding-agent plugin that turns a request into a planned, test-first,
gate-verified sprint: a human approves the plan, then cheap worker agents build it in
isolated git worktrees while deterministic hooks decide what is accepted.**
gate-verified sprint: the human gives the intent and answers only one-way-door questions, then cheap
worker agents build it in isolated git worktrees while deterministic hooks decide what is accepted.**

> *Models explore. Gates decide.*

Expand All @@ -26,13 +26,13 @@ The model can ignore a skill; it cannot ignore an exit code.

- Developers using **Claude Code** (reference host), **Codex**, **OpenCode** or **DeepSeek Harness** (`dsh`) who want an
agent to deliver a multi-story feature or a whole service, not a single edit.
- People who want to stay in the loop for *what* gets built and be absent for *how*.
- People who want to say *what* gets built, answer only irreversible questions, and be absent for *how*.
- Teams that care about cost: most of the work runs on cheaper models in narrow context.

## How it works

```
you ──► INIT ──► PLANNING (human-gated, Opus) ──► approve ──► EXECUTION (autonomous, Sonnet) ──► FINAL-GATE ──► stats + NEXT.md ──► /clear ──► next sprint
you ──► INIT ──► PLANNING (from the intent, Opus) ──► one-way doors? ──► EXECUTION (autonomous, Sonnet) ──► FINAL-GATE ──► stats + NEXT.md ──► /clear ──► next sprint
retrospective → intake → per wave, per task, own worktree:
standards → planner RED → SCAFFOLD → GREEN → STRUCTURAL-REVIEW
```
Expand All @@ -47,10 +47,11 @@ The model can ignore a skill; it cannot ignore an exit code.
- `standards` produces a cited coding standard;
- `planner` writes the sprint contract and, per story, the semantic plan `targets.json`
(tasks, tests, change targets) from which `tasks.md` / `validate.md` / `plan.md` are rendered.
The supervisor then **stops for approval**, and that stop is a gate: `gate-dispatch` starts no
worker until the human types the `approve SN <code>` line naming this exact plan, and a changed plan
needs a new line; or they grant the sprint autonomy (`autonomous SN <code>`, or an approved
autonomous mission), which covers its re-plans (M0.9).
- `door-classifier` tags every planned task as a one-way or two-way door (M11.10).
Autonomous is the default (M11): the human's typed intent is the sprint's grant, so `gate-dispatch`
starts workers with no approval line; only tasks tagged with a one-way door the human has not
authorized are parked, and those questions are asked together. Reviewed mode is opt-in
(`AGENTIC_AUTONOMY_MODE=reviewed`): the human types `approve SN <code>` naming this exact plan (M0.9).
3. **Execution** — human absent. For each task, a worker runs in its own git worktree:
- **RED** writes tests that must fail *by assertion* and touch no production code;
- **SCAFFOLD** creates each planned symbol exactly once, as a stub;
Expand All @@ -74,10 +75,10 @@ The model can ignore a skill; it cannot ignore an exit code.
| Part | Where | What it is |
|---|---|---|
| Supervisor playbook | [`plugin/skills/aloop/SKILL.md`](../plugin/skills/aloop/SKILL.md) | The skill the main agent runs; `aladdin` and `init` are its entry points |
| 15 roles | [`plugin/agents/`](../plugin/agents/) | `archivist`, `intake`, `standards`, `planner` (Opus) · `red-worker`, `scaffolder`, `green-worker`, `structural-reviewer`, `final-gate` (Sonnet) · the mission layer's six ([`roles.json`](../plugin/mission/roles.json), §4.12): `market-researcher`, `evaluator`, `mission-planner`, `ethics-reviewer` (planning route) · `product-tester`, `state-assessor` (worker route) |
| 16 roles | [`plugin/agents/`](../plugin/agents/) | `archivist`, `intake`, `standards`, `planner`, `door-classifier` (Opus) · `red-worker`, `scaffolder`, `green-worker`, `structural-reviewer`, `final-gate` (Sonnet) · the mission layer's six ([`roles.json`](../plugin/mission/roles.json), §4.12): `market-researcher`, `evaluator`, `mission-planner`, `ethics-reviewer` (planning route) · `product-tester`, `state-assessor` (worker route) |
| Pipeline source | [`plugin/pipeline/`](../plugin/pipeline/) | Per activity: `persona.md`, `init.template.md`, `artifacts.md`, `gate.md` |
| Hook wiring | [`plugin/hooks/hooks.json`](../plugin/hooks/hooks.json) | SessionStart, PreToolUse, PostToolUse, SubagentStart/Stop, Stop, UserPromptSubmit (transcript capture and the natural-language auto-trigger, `intent-trigger`) |
| Gates | [`plugin/bin/gate-*`](../plugin/bin/README.md) | 18 gates (15 bash; `gate-commit-author` and the mission layer's `gate-mission-scope` role path guards and `gate-mission-artifact` stop check in Python), 16 wired to hooks (`gate-plan-shape` and `gate-ledger-format` are standalone checkers); exit `0` pass, `2` block with reason |
| Gates | [`plugin/bin/gate-*`](../plugin/bin/README.md) | 19 gates (16 bash; `gate-commit-author` and the mission layer's `gate-mission-scope` role path guards and `gate-mission-artifact` stop check in Python), 17 wired to hooks (`gate-plan-shape` and `gate-ledger-format` are standalone checkers); exit `0` pass, `2` block with reason |
| Harness tools | [`plugin/bin/`](../plugin/bin/README.md) | `aladdin` / `aloop` (entry points), `intent`, `budget` (time box, envelope, breach classes; its pre hook also holds the project stop and the fetch rule, M10.3), `stop` (one stop for the whole project, M10.4), `deps`, `secrets` and `audit` (the supply-chain, secret and dependency-audit gates, M10.2), `sweep` (the orchestrator loop), `targets` (semantic plan, shadow workspace, render), `ids`, `events` (audit stream, lineage, trace), `stats` (ledger, metrics, handoff), `models` / `host` / `config` (routes, HostAdapter, portable config), `transcripts`, `intent-trigger` (natural-language auto-trigger), `run-summary` (a live run's measured record for `docs/evidence/`), `install`, `aloop-init`, worktree helpers |
| Schemas | [`plugin/schemas/*.kdl`](../plugin/schemas/) | What `md-db validate` enforces on every planning and comms artifact |
| `ctx-symbols` | [`plugin/tools/ctx-symbols/`](../plugin/tools/ctx-symbols/) | Rust, tree-sitter symbol resolver (Rust, Python, JS/TS, Go): count, locate, conflicts |
Expand Down Expand Up @@ -119,7 +120,7 @@ The model can ignore a skill; it cannot ignore an exit code.
metrics, config, the aladdin CLI, the site).
- The north-star run, `make e2e-live YES=1 [INTENT=<intent>] [HOST=codex|opencode|dsh]`: a one-line intent becomes
planned, test-first, gate-verified, merged code in a real Claude Code session with the
approval given up front. Eight intents pass every check: a Rust semver parser, a two-story
approval given up front (since M11, run 54: the intent alone, no approval line). Eight intents pass every check: a Rust semver parser, a two-story
word-frequency tool, Python `slugify`, Go `roman`, JS `camel`, two brownfield changes to a
tested crate (`extend`, `modify`) and a `cli` binary. The latest passing run of each took
6m45s–15m19s and $0.56–1.04 (runs 34–47), with every merged commit traced to its task by
Expand Down
Loading
Loading
0