adeelahmad · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,17 @@
+# Aloop: standing goal
+
+**What it is.** agentic-agile (becoming **Aladdin / aloop**) 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.*
+
+**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.
+
+**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.
+
+**Flywheel (every agent, every turn):**
+1. **Orient:** read `docs/OVERVIEW.md`, ROADMAP §0, and open PRs.
+2. **Pick** the highest-value unblocked item. Red CI and bugs come first, then the current milestone.
+3. **Ship small:** branch, write tests first, open a draft PR, and drive it green.
+4. **Measure:** put the evidence (tests, run stats) in the PR.
+5. **Re-plan:** update ROADMAP status. Add any gap, risk or idea you found as an item with a one-line reason. Requirements are yours to maintain, not only the user's.
+6. **Repeat** without waiting to be asked.
+
+**Judgment.** Decide reversible things yourself and record the call. Ask only about irreversible, security-sensitive or goal-changing choices: one question, with a recommended option. Never weaken a gate, an invariant (ROADMAP §7) or a test to make progress. Prefer evidence to claims. Keep user-facing replies to 1–2 words unless more is needed.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,26 @@
+# Contributing
+
+Start with [docs/OVERVIEW.md](docs/OVERVIEW.md) (what the project is) and
+[docs/ROADMAP.md](docs/ROADMAP.md) (where it is going).
+
+## Before you open a PR
+
+```bash
+make hooks      # install the tracked pre-commit / pre-push hooks
+make ci         # what CI runs, except the live `claude plugin validate`
+make validate   # `claude plugin validate --strict` (needs the claude CLI)
+```
+
+## Rules of the road
+
+- **Gates are the product.** A change that weakens a gate, or turns a BLOCK into a WARN,
+  needs a stated reason and a test showing the old failure is still caught.
+- **Edit `plugin/pipeline/` first.** Agent files in `plugin/agents/` are assembled from it.
+- **Versions move together.** `plugin.json`, the `ctx-symbols` `Cargo.toml` and
+  `CHANGELOG.md` must agree (`make version-check`). See the versioning policy in the
+  [CHANGELOG](CHANGELOG.md).
+- **`plugin/tools/md-db/` is vendored AGPL-3.0 code.** Keep changes there minimal and
+  note them in `plugin/tools/md-db/VENDOR.md`.
+
+By contributing you agree your work is licensed under the repository's MIT license
+(AGPL-3.0 for the `md-db` subtree).
diff --git a/README.md b/README.md
@@ -35,6 +35,8 @@ block the stop and feed the failure reason back to the supervisor.
 > [`plugin/`](plugin/); the marketplace catalog is
 > [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json).
 
+**New here?** [What this project is](docs/OVERVIEW.md) · [Roadmap](docs/ROADMAP.md)
+
 ## Quick start
 
 ```bash
@@ -173,8 +175,10 @@ env-contract and how to retarget a non-Rust repo.
 ```
 .claude-plugin/marketplace.json   marketplace catalog (source: ./plugin)
 plugin/                           the installable plugin (see plugin/README.md)
-docs/                             design + architecture docs for this plugin
-  ARCHITECTURE.md DESIGN.md PLATFORM-NOTES.md KICKSTART.md
+docs/                             what it is, roadmap, design history
+  OVERVIEW.md ROADMAP.md           start here: definition + plan
+  ARCHITECTURE.md DESIGN.md KICKSTART.md   historical design package
+  PLATFORM-NOTES.md
   agentic-agile-design.html diagrams/
 DEVLOG.md                         build journal + review dispositions
 ```
@@ -227,10 +231,12 @@ make publish        # pushes branch + tags
 
 `.github/workflows/ci.yml` runs on every push/PR:
 
-- **ctx-symbols** — `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test`.
+- **rust** — `cargo fmt --check`, `cargo clippy -D warnings`, tests for `ctx-symbols` + `md-db`.
 - **shellcheck** — lints every gate script (`plugin/bin/*`), errors fail the build.
-- **plugin validate** — JSON sanity on the manifest + marketplace, then
-  `claude plugin validate ./plugin --strict` (installs the Claude Code CLI).
+- **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`.
 
 ## Status
 

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -1,5 +1,8 @@
 # agentic-agile — Plugin Architecture & Implementation
 
+> **Historical.** Part of the pre-v0.2 design package; counts, paths and status here are out of date. For the current picture read [OVERVIEW.md](OVERVIEW.md).
+
+
 How this is built as a Claude Code plugin and how every piece is wired together.
 Concrete. Reads top-to-bottom as an implementation guide.
 

diff --git a/docs/DESIGN.md b/docs/DESIGN.md
@@ -1,5 +1,8 @@
 # agentic-agile Plugin — Consolidated Design
 
+> **Historical.** Part of the pre-v0.2 design package; counts, paths and status here are out of date. For the current picture read [OVERVIEW.md](OVERVIEW.md).
+
+
 Status: DESIGN ONLY. No code yet. Every section traces to a decision made in
 conversation; open questions are marked [OPEN] and not guessed.
 

diff --git a/docs/KICKSTART.md b/docs/KICKSTART.md
@@ -1,5 +1,8 @@
 # KICKSTART — instruction for an AI agent
 
+> **Historical.** Part of the pre-v0.2 design package; counts, paths and status here are out of date. For the current picture read [OVERVIEW.md](OVERVIEW.md).
+
+
 You are picking up a DESIGN package and turning it into a working Claude Code
 plugin. This file tells you what to read, what to decide, and the exact order to
 build in. Do not improvise past the design; where something is undecided it is

diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
@@ -0,0 +1,125 @@
+# What agentic-agile is
+
+*Product definition as of v0.10.1 (2026-09-23), written from the code, not the design docs.
+Working name for the next generation: **Aladdin** / "Aladdin's Loop" (**aloop**) — see
+[ROADMAP.md](ROADMAP.md).*
+
+## In one sentence
+
+**agentic-agile 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.**
+
+> *Models explore. Gates decide.*
+
+## The problem it solves
+
+Coding agents are good at producing code and bad at proving it is right. Left alone they
+skip tests, weaken assertions, wander out of scope, rewrite each other's work and say
+"done" when they are not. Prompting harder does not fix this, because a prompt is advice.
+
+agentic-agile moves the rules out of the prompt and into **hooks**: small scripts the host
+runs on every agent event, which can block a stop or a tool call and return the reason.
+The model can ignore a skill; it cannot ignore an exit code.
+
+## Who it is for
+
+- Developers using **Claude Code** (reference host), **Codex** or **OpenCode** 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*.
+- 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
+                  retrospective → intake →                     per wave, per task, own worktree:
+                  standards → planner                          RED → SCAFFOLD → GREEN → STRUCTURAL-REVIEW
+```
+
+1. **Init** (`/agentic-agile:init`) confirms limits, models, `.gitignore`, whether
+   `docs/agents/` is tracked and the commit author, then writes `docs/agents/defaults.md`.
+2. **Planning** — with the human present. The supervisor *dispatches* (never writes):
+   - `archivist` (retrospective) distills recurring failures into `memory.md`;
+   - `intake` captures the five-part intent;
+   - `standards` produces a cited coding standard;
+   - `planner` writes the sprint contract and per-story `tasks.md` / `validate.md` / `plan.md`.
+   The supervisor then **stops for approval**.
+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;
+   - **GREEN** makes the tests pass inside the task's scope, with zero suppressions;
+   - **STRUCTURAL-REVIEW** looks for orphan, parallel or duplicate code.
+   Work merges only on a passing gate. A failed gate re-prompts the worker; repeated
+   failure goes to the supervisor.
+4. **Time box.** Every worker attempt has soft and hard limits on tokens and minutes. At
+   the hard limit the worker is stopped and the planner **splits** the task (up to
+   `MAX_REPLANS`) instead of retrying it.
+5. **Close.** `FINAL-GATE` runs the full matrix once per sprint. The harness writes
+   `sprintN/stats.md` and `docs/agents/NEXT.md`, context is cleared, and the next session
+   reloads from the handoff. Sprints are planned to be self-contained.
+
+## What is in the box
+
+| Part | Where | What it is |
+|---|---|---|
+| Supervisor playbook | [`pl
10000
ugin/skills/agentic-agile/SKILL.md`](../plugin/skills/agentic-agile/SKILL.md) | The skill the main agent runs; `init` is its entry point |
+| 9 roles | [`plugin/agents/`](../plugin/agents/) | `archivist`, `intake`, `standards`, `planner` (Opus) · `red-worker`, `scaffolder`, `green-worker`, `structural-reviewer`, `final-gate` (Sonnet) |
+| 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 |
+| Gates | [`plugin/bin/gate-*`](../plugin/bin/README.md) | 15 bash gates; exit `0` pass, `2` block with reason |
+| Harness tools | [`plugin/bin/`](../plugin/bin/README.md) | `budget` (time box), `stats` (token ledger), `transcripts` (full capture), `host-adapter`, `install`, `agentic-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 |
+| `md-db` | [`plugin/tools/md-db/`](../plugin/tools/md-db/) | Vendored Rust markdown-as-database validator (AGPL-3.0 subtree) |
+| Other hosts | [`plugin/hosts/opencode/`](../plugin/hosts/opencode/), `bin/install` | Generates agents/skills for Codex and OpenCode; same gates via `host-adapter` |
+| Evals | [`plugin/evals/`](../plugin/evals/), [`scripts/eval/`](../scripts/eval/) | Per-agent eval suites + grader/aggregator |
+
+## What it leaves on disk
+
+| Artifact | Scope | Purpose |
+|---|---|---|
+| `docs/agents/defaults.md` | project | Limits, models, author — set at init |
+| `docs/agents/memory.md` | project | Lessons promoted by the retrospective; injected into contracts |
+| `stories.md`, `sprintN/plan.md` | sprint | Stage-1 contract |
+| `sN-NN-<slug>/{tasks,validate,plan}.md` | story | Stage-2 plan |
+| `plan-ready.md` | story | Static RED → GREEN handoff |
+| `init.md` ⇄ `output.md` | story | Append-only dispatch contract and agent report |
+| `execution.log` | sprint | One-line state ledger |
+| `sprintN/stats.md`, `docs/agents/NEXT.md` | sprint | Harness-written stats and the handoff |
+| `.agentic/` | local | Transcripts, budgets, token ledger, worktree state (git-ignored) |
+
+## Where it stands
+
+**Working and tested:**
+- The full planning → execution loop on Claude Code; Codex and OpenCode via generated
+  agents and the same gates.
+- CI on every PR: Rust fmt/clippy/tests for both backends, shellcheck on every gate, Codex
+  hooks emulation + OpenCode end-to-end (18 checks), `claude plugin validate --strict`,
+  eval-suite and version-lockstep checks.
+- One measured real run (*TheNoteBook*, a Go backend): ~17K LOC, 322 tests, 74 commits in 6
+  sprints for ~1.55M output tokens, 76% of it on Sonnet. See the
+  [README](../README.md#token-efficiency-a-measured-run).
+
+**Known limits:**
+- Suppression detection is syntactic; a weakened assertion is caught only indirectly
+  (RED invariant + diff scope).
+- Without `ctx-symbols` / `md-db` the planning gates degrade to grep (WARN, never silent).
+- The default standards matrix targets Rust; other stacks need `standards.md` and gate edits.
+- The soft token limit tells workers to wrap up, budgets meter only the three build roles,
+  and every hard breach is treated as "task too large". The roadmap changes all three.
+- One public measured run; no live-session test in CI.
+
+## The docs, and which ones are current
+
+| Doc | Status | Read it for |
+|---|---|---|
+| [README](../README.md) | current | Install, usage, measured run |
+| **OVERVIEW.md** (this) | current | What the project is |
+| [ROADMAP.md](ROADMAP.md) | current | Where it is going (agentic-agile → Aladdin) |
+| [plugin/README.md](../plugin/README.md), [plugin/bin/README.md](../plugin/bin/README.md) | current | Operating the plugin; gate contract |
+| [plugin/STRUCTURE.md](../plugin/STRUCTURE.md) | current | How the plugin tree is organised |
+| [CHANGELOG.md](../CHANGELOG.md) | current | What changed per version |
+| [DESIGN.md](DESIGN.md), [ARCHITECTURE.md](ARCHITECTURE.md), [KICKSTART.md](KICKSTART.md) | historical (pre-v0.2) | The original design package; numbers and paths are out of date |
+| [PLATFORM-NOTES.md](PLATFORM-NOTES.md) | reference | Host mechanics the design relies on |
+| [DEVLOG.md](../DEVLOG.md) | historical | Build journal through v0.2 |
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -6,6 +6,31 @@
 
 ---
 
+## 0. At a glance
+
+What the project is today: [OVERVIEW.md](OVERVIEW.md). Sections 1–8 below are the full
+spec; this table is the plan. Versions are targets, not promises.
+
+| Milestone | Target | Contents | Status |
+|---|---|---|---|
+| **M0 — Hygiene** | v0.10.x | Mark `DESIGN` / `ARCHITECTURE` / `KICKSTART` historical; fix stale counts (8 → 9 roles) and the README CI section; add the `CONTRIBUTING.md` the README badge links to; one live-session smoke test of the hook wiring (open since `DEVLOG` v0.1) | in progress: docs, CONTRIBUTING and stale counts done; live smoke test open |
+| **M1 — Trustworthy state** | v0.11 | Session 1: conformance fixtures around current behaviour, canonical IDs and the reference remap (§4.5) | not started |
+| **M2 — Budgets that plan** | v0.12 | Sessions 2 and 4: budget semantics (§3.1–3.5), sprint envelope and admission control (§4.2), breach classes, failure envelope, grace rule, lesson candidates (§4.3) | not started |
+| **M3 — Clean boundaries** | v0.13 | Session 3: canonical handoff, rotation and the resume rule (§4.4) | not started |
+| **M4 — Intent in, autonomy optional** | v0.14 | Session 5: Intent Contract, clarification policy, autonomous mode (§4.1) | not started |
+| **M5 — Narrow context** | v0.15 | Session 6: semantic execution map, shadow workspace, `target` / `context` CLI (§4.6) | not started |
+| **M6 — Audit** | v0.16 | Sessions 7–8: event stream, rationale, authority, lineage query (§4.7); provider seam (§4.8) | not started |
+| **M7 — Any host** | v0.17 | Session 9: `HostAdapter`, capability matrix, `.aladdin/config.yaml`, host swap, metrics (§4.9–4.10) | not started |
+| **M8 — Aladdin 1.0** | v1.0 | Session 10: rebrand, `/aladdin` + `aladdin` CLI with aliases, README, site, measured public runs (
D80C
§4.11) | not started |
+
+**Order rationale:** identity and conformance fixtures first, so every later change is
+measured against today's behaviour; budgets and handoff next, because they shape every run;
+the semantic map and audit trail after, since they build on canonical IDs; portability and
+the rebrand last, once the conformance suite (§6) can prove parity.
+
+**Exit for each milestone:** the §5 exit criterion holds, the §6 conformance items it
+touches pass on Claude Code, and each requirement is reported per §8.
+
 ## 1. Goal
 
 Evolve **agentic-agile** into **Aladdin**. Aladdin is an intent-driven, test-driven, cross-harness system for software engineering. It takes anything from a one-line request to a full specification and turns it into planned, tested, reviewed and auditable software.

diff --git a/plugin/README.md b/plugin/README.md
@@ -156,7 +156,7 @@ All optional, each with a safe fallback (see `bin/_gatelib.sh`):
 ```
 .claude-plugin/plugin.json   manifest
 skills/agentic-agile/SKILL.md the supervisor playbook (canonical)
-agents/<role>.md             8 dispatchable personas
+agents/<role>.md             9 dispatchable personas
 hooks/hooks.json             gate wiring by agent_type (SubagentStop/Stop/PostToolUse)
 bin/                         gate bodies + _gatelib.sh + log-execution
 schemas/*.kdl                md-db schemas (agent-io / planning-artifacts / ledger)