adeelahmad · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
   "name": "agentic-agile-marketplace",
   "owner": { "name": "Adeel Ahmad" },
-  "description": "Agentic agile planning + autonomous TDD execution for Claude Code, with deterministic hook gates.",
+  "description": "Agentic agile planning + autonomous TDD execution for Claude Code, Codex and OpenCode, with deterministic hook gates.",
   "plugins": [
     {
       "name": "agentic-agile",

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,8 +1,9 @@
 # CI — the checks `make ci` + `make validate` run, mirrored on every push/PR.
-# Documented in README.md ("Continuous integration"). Three independent jobs:
+# Documented in README.md ("Continuous integration"). Four independent jobs:
 #   rust       — ctx-symbols + md-db: fmt-check, clippy -D warnings, tests
 #   shellcheck — lints every gate script (errors fail the build)
 #   plugin     — JSON sanity + eval-suite validation + `claude plugin validate --strict`
+#   hosts      — Codex hooks emulation + OpenCode plugin end-to-end (no network, no tokens)
 name: CI
 
 on:
@@ -48,6 +49,22 @@ jobs:
       - name: Lint gate scripts
         run: make shellcheck
 
+  hosts:
+    name: hosts (codex hooks · opencode plugin)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Byte-compile the Python hook scripts
+        run: make pycheck
+      - name: Codex hooks emulation + OpenCode plugin end-to-end
+        run: make test-hosts
+
   plugin:
     name: plugin (json · evals · validate)
     runs-on: ubuntu-latest

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,93 @@ bundled `ctx-symbols` crate together under one SemVer line:
 Keep `plugin.json` `version`, the `ctx-symbols` `Cargo.toml` `version`, and the git
 tag in lockstep. Tag releases as `vMAJOR.MINOR.PATCH`.
 
+## [0.10.0] - 2026-09-23
+
+### Added
+- **Tools install themselves and are always on PATH.** New `SessionStart` hook
+  `bin/ensure-tools` builds `md-db` + `ctx-symbols` from the bundled source into the
+  plugin data dir (background, once per plugin version; `--sync` to force) and tells the
+  model where every tool is. `bin/md-db` / `bin/ctx-symbols` are PATH shims (the
+  platform puts the plugin's `bin/` on PATH for every session and sub-agent) that exec
+  the real binary. Agents now call `selfcheck`, `md-db`, `budget`, … by bare name, and
+  the prompts tell them never to search. `gate-tooling` tries to install before blocking.
+- **Per-attempt time box (tokens + wall clock).** New `bin/budget`: soft limits (default
+  40k tokens / 10 min) warn the worker inside its tool results; hard limits (60k / 15
+  min) deny further tool calls except the output.md report, release the worker's
+  SubagentStop gate unverified, and surface a KILL to the supervisor via `budget watch`.
+  Configurable per project (`docs/agents/defaults.md`, via init) and per task
+  (`budget:` line in tasks.md).
+- **Orchestrator loop: dispatch → sleep → sweep.** The supervisor dispatches background
+  workers, sleeps on `budget watch`, then `TaskStop`s workers past their hard limit.
+- **Mid-sprint re-plan route.** A task killed at its hard limit is not retried: the
+  sprint pauses, the planner is dispatched with `mode: replan`
+  (`pipeline/planning/02-planner/replan.template.md`) to split it (`split_from:`),
+  leaving done tasks untouched, and the sprint resumes. Capped per task lineage
+  (`AGENTIC_MAX_REPLANS`, default 2; `budget replans`). New execution.log phases
+  `budget` and `replan`.
+- **Self-contained sprints.** The planner prompt requires every sprint to be completable
+  on its own (context is cleared between sprints); `gate-stage2-complete` blocks
+  references to a later sprint's stories and work deferred into a later sprint. The
+  harness asks for `/clear` at each sprint boundary.
+
+- **Init confirms the project setup with the human.** `/agentic-agile:init` runs
+  `agentic-init --show` (limits, models, the `.gitignore` edit, whether `docs/agents/` is
+  tracked — default no — and the commit author — default the human's git identity, no
+  Claude trailers), asks, then `agentic-init --apply` writes `docs/agents/defaults.md`,
+  the managed `.gitignore` lines and the repo-local git author. The hooks read limits
+  from that file; the SessionStart hook re-applies the `.gitignore` lines every session.
+- **`gate-commit-author`** (PreToolUse · Bash): denies commits with another author,
+  identity overrides, or Claude co-author/attribution trailers (unless opted in).
+- **One fixed layout** (`bin/_paths.sh` / `_paths.py`): run data lives only in
+  `<project>/.agentic/{transcripts,budget,ledger,logs,state}`; no model-chosen or
+  per-worktree path, no task.env override. Capture hooks write nothing in a repo that
+  isn't an agentic-agile project.
+- **Token ledger + sprint stats + handoff, by the harness** (`bin/stats`): Stop and
+  SubagentStop rebuild `.agentic/ledger/<session>.jsonl` from the transcripts (main +
+  sub-agents). When FINAL-GATE passes, `gate-final` runs `stats sprint-close`:
+  `sprintN/stats.md` (tasks, attempts, gate passes/blocks, budget stops, re-plans,
+  tokens per sprint/session/project, by role and model, human messages) and
+  `docs/agents/NEXT.md` (orchestrator handoff). The next Stop shows the human the totals
+  and asks for `/clear`; the SessionStart hook loads `NEXT.md` into the fresh context.
+  `stats show` prints totals any time. Every gate verdict is logged to
+  `.agentic/logs/gates.jsonl`.
+
+- **Codex and OpenCode support — full feature parity.** `agentic install codex|opencode
+  [--project DIR|--global] [--uninstall]` renders the 9 role agents (Codex TOML /
+  OpenCode markdown), skills and the init command from this plugin's own sources.
+  - **Codex** loads this repo's `.claude-plugin` manifests and `hooks/hooks.json`
+    natively (same events, `CLAUDE_PLUGIN_ROOT`); hooks were made Codex-aware:
+    `apply_patch` edits (supervisor scope, report-only writes at the hard limit),
+    rollout token usage (`.jsonl`/`.zst`, cumulative totals), sub-agent rollouts found
+    by thread id.
+  - **OpenCode** gets a generated plugin (`hosts/opencode/agentic-agile.js`) that maps
+    its hooks onto the same scripts: deny by throwing, context appended to tool output,
+    `session.abort` for the hard stop, the role gate on the `task` result (a block
+    re-prompts the sub-agent up to 3 rounds), usage written Claude-shaped for the ledger,
+    the handoff in the system prompt, `bin/` on PATH via `shell.env`.
+  - **Worker isolation without built-in worktrees:** `agentic task-worktree add
+    <TASK_ID>` + the worker's first command `agentic bind <path>`; `host-adapter` then
+    confines it (Codex: commands/patches outside the worktree are denied; OpenCode:
+    rewritten into it) and the SubagentStop gate runs inside the bound worktree.
+  - `agentic` — one dispatcher for every tool (`agentic selfcheck`, `agentic init …`),
+    linked into `~/.local/bin` where the host has no plugin PATH.
+  - `_usage.py` — one token reader for all three hosts (budget + ledger).
+  - CI job `hosts`: Codex hook-runner emulation (14 checks) + OpenCode plugin against a
+    mock client (18 checks) — `make test-hosts`.
+
+### Changed
+- **The hard-limit kill is deterministic:** after one chance to write its report and 3
+  refused calls, the time-box hook stops the worker itself (PostToolUse
+  `continue: false`); `budget watch` reports `STOPPED`, with `TaskStop` only a backstop.
+- `gate-final` also checks `plan-ready.md` in the sprint's main-tree docs (a worker
+  worktree has `docs/agents/` sparse-checked out).
+- The supervisor may not hand-edit `defaults.md`, `NEXT.md` or `stats.md`.
+- **Models:** planning agents (intake, standards, planner, archivist) default to
+  `claude-opus-5-5`; execution agents and the orchestrator skill default to `sonnet`.
+  Per-project override via `AGENTIC_MODEL_PLANNING` / `AGENTIC_MODEL_WORKER` in defaults.md.
+- Gates detect backends with `ensure-tools --resolve` (the real binary), not
+  `command -v` (which would now find the shim).
+
 ## [0.9.0] - 2026-07-03
 
 ### Added

diff --git a/Makefile b/Makefile
@@ -65,16 +65,30 @@ clippy: ## Clippy with warnings-as-errors
 .PHONY: shellcheck
 shellcheck: ## Lint gate scripts (skipped with a warning if shellcheck is absent)
 	@command -v shellcheck >/dev/null \
-	  && shellcheck -S error -e SC1091 plugin/bin/_gatelib.sh plugin/bin/gate-* plugin/bin/log-execution \
+	  && shellcheck -S error -e SC1091 plugin/bin/_gatelib.sh $$(grep -l "^#!/usr/bin/env bash" plugin/bin/gate-*) plugin/bin/log-execution \
 	       plugin/bin/selfcheck plugin/bin/transcripts plugin/bin/worktree-create plugin/bin/worktree-remove \
+	       plugin/bin/worktree-hygiene plugin/bin/ensure-tools plugin/bin/md-db plugin/bin/ctx-symbols \
+	       plugin/bin/session-start plugin/bin/_paths.sh plugin/bin/agentic plugin/bin/bind plugin/bin/task-worktree \
 	  || echo "WARN: shellcheck not installed; skipping (CI enforces it)"
 
+.PHONY: pycheck
+pycheck: ## Byte-compile the Python hook scripts
+	@python3 -m py_compile plugin/bin/budget plugin/bin/stats plugin/bin/agentic-init plugin/bin/gate-commit-author plugin/bin/_paths.py \
+	    plugin/bin/_usage.py plugin/bin/host-adapter plugin/bin/install \
+	  && rm -rf plugin/bin/__pycache__ && echo "python ok"
+
+.PHONY: test-hosts
+test-hosts: ## Codex hooks emulation + OpenCode plugin end-to-end (no network, no tokens)
+	@command -v node >/dev/null && node --check plugin/hosts/opencode/agentic-agile.js
+	python3 scripts/test/codex-hooks.test.py
+	@command -v node >/dev/null && node scripts/test/opencode-plugin.test.mjs || { echo "node not found — skipped OpenCode test (CI runs it)"; }
+
 .PHONY: json
 json: ## Validate plugin.json + marketplace.json
 	@python3 -c "import json;json.load(open('plugin/.claude-plugin/plugin.json'));json.load(open('.claude-plugin/marketplace.json'));print('JSON ok')"
 
 .PHONY: lint
-lint: clippy shellcheck json ## Run all linters
+lint: clippy shellcheck pycheck json ## Run all linters
 
 .PHONY: test
 test: ## Run ctx-symbols + md-db unit tests
@@ -87,7 +101,7 @@ validate: json ## claude plugin validate --strict
 	claude plugin validate ./plugin --strict
 
 .PHONY: ci
-ci: fmt-check lint test eval-validate ## Run everything CI runs (except the live claude install)
+ci: fmt-check lint test eval-validate test-hosts ## Run everything CI runs (except the live claude install)
 
 # ── Evals ──────────────────────────────────────────────────────────
 .PHONY: eval-validate

diff --git a/README.md b/README.md
@@ -37,10 +37,9 @@ block the stop and feed the failure reason back to the supervisor.
 ## Quick start
 
 ```bash
-# 1) Build + install the gate backends (ctx-symbols + md-db, both from source)
-#    requires a Rust toolchain >= 1.82 (rustup.rs or `brew install rust`)
-./plugin/tools/install.sh
-#    ensure ~/.local/bin (or ~/.cargo/bin) is on PATH
+# 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
@@ -49,6 +48,10 @@ block the stop and feed the failure reason back to the supervisor.
 #    (for local dev, point marketplace add at your checkout instead: ./path/to/repo)
 ```
 
+**Codex / OpenCode:** `plugin/bin/agentic 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](plugin/README.md#codex-and-opencode).
+
 > **Staying current:** third-party marketplaces don't auto-update by default — run
 > `/plugin marketplace update agentic-agile-marketplace` (or enable auto-update in
 > `/plugin` → Marketplaces), then `/reload-plugins`. Step 1 (the Rust-built `ctx-symbols`
@@ -86,8 +89,18 @@ Once started:
    STRUCTURAL-REVIEW per wave, then a once-per-sprint FINAL-GATE, each enforced by a
    deterministic hook gate.
 
-The gate backends (`ctx-symbols`, `md-db`) must be on PATH — see step 1 above. Without
-them the gates WARN and fall back to grep (never a false block, never a silent pass).
+The gate backends (`ctx-symbols`, `md-db`) are built and put on PATH automatically on
+the first session (step 1). Until they exist, planning gates WARN and fall back to grep
+(never a false block, never a silent pass); execution waits for them.
+
+Planning agents run on Opus 5.5 and everything else (orchestrator and workers) on
+Sonnet. Every worker attempt is time-boxed (tokens + minutes, soft warning then hard
+stop), and a task that overruns is split mid-sprint by the planner rather than retried.
+Each sprint is planned to be self-contained, so context can be cleared between sprints.
+Budgets, models, the `.gitignore` and the commit author are confirmed with you at
+`/agentic-agile:init` and saved in `docs/agents/defaults.md`. When a sprint closes the
+harness writes `sprintN/stats.md` (tasks, attempts, gate blocks, tokens, human messages)
+and `docs/agents/NEXT.md`, which reloads the orchestrator after `/clear`.
 
 ## What it does
 

diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
@@ -1,10 +1,10 @@
 {
   "name": "agentic-agile",
-  "version": "0.9.0",
-  "description": "Two-stage agile planning (interactive, human-gated) + two-phase TDD execution (autonomous, hook-enforced), with md-db/KDL artifact validation, ctx-symbols structure checks, per-task transcripts, and a planning retrospective that distills durable memory.",
+  "version": "0.10.0",
+  "description": "Two-stage agile planning (interactive, human-gated) + two-phase TDD execution (autonomous, hook-enforced), with md-db/KDL artifact validation, ctx-symbols structure checks, per-task transcripts, and a planning retrospective that distills durable memory. Runs on Claude Code, Codex and OpenCode.",
   "author": { "name": "Adeel Ahmad" },
   "license": "MIT",
   "homepage": "https://github.com/adeelahmad/agentic-agile",
   "repository": "https://github.com/adeelahmad/agentic-agile",
-  "keywords": ["agile","tdd","orchestration","hooks","sub-agents","worktrees","md-db","ctx-symbols","transcripts","retrospective","memory"]
+  "keywords": ["agile","tdd","orchestration","hooks","sub-agents","worktrees","md-db","ctx-symbols","transcripts","retrospective","memory","codex","opencode"]
 }