From 1bbc0ec7a42e3dde697d54b6cf55d3b1ce2b4eed Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 3 Jun 2026 07:38:35 +0200
Subject: [PATCH 1/3] feat(orchestration): add Beads-first worker launcher

---
 AGENTS.md                   |  34 +++--
 scripts/bead-spawn-agent.sh | 261 ++++++++++++++++++++++++++++++++++++
 2 files changed, 285 insertions(+), 10 deletions(-)
 create mode 100755 scripts/bead-spawn-agent.sh

diff --git a/AGENTS.md b/AGENTS.md
index 702dae28..4dd3f062 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -108,13 +108,19 @@ AI agents are the primary users of AgentV—not humans reading docs. Design for
 
 ## Working Style
 
-### AO-First Orchestration
-- AO (Composio Agent Orchestrator) is AgentV's live orchestration layer. In AO-managed sessions, treat AO as the source of truth for assignment, worker ownership, status, worktree lifecycle, PR claiming, and visualization.
-- Use the AO-provided worktree and branch. Do not create additional worktrees, spawn unmanaged agents, or open duplicate PRs unless the user/AO explicitly asks.
-- Report lifecycle status through AO (`ao acknowledge`, `ao report working`, `ao report fixing-ci`, `ao report addressing-reviews`, `ao report needs-input`, and PR milestone reports).
+### Beads-First Orchestration
+- Beads is AgentV's normal durable task graph. Use it for assignment, status, dependencies, handoff notes, decomposition, and resumability. Agent sessions are disposable workers that read and write the bead graph.
+- Prefer `br` (beads_rust) for Beads operations when the repository has a `br`-compatible SQLite/JSONL `.beads` store. `br` is non-invasive and never commits or pushes; after `br sync --flush-only`, manually run `git add .beads/` and commit the exported state when the bead graph is part of the change.
+- Compatibility note: the current AgentV bead graph may still be the older `bd`/Dolt store. If `br ready --json` or `br show <id> --json` returns no issues while `bd` sees the graph, use `bd` for that workspace until the store is explicitly migrated. Do not assume `br` can read `bd` state just because it auto-discovers `.beads/dolt`.
+- For worker launch, prefer `scripts/bead-spawn-agent.sh <bead-id>`. The wrapper claims the bead, records a launch note, exports `EP_TASK_ID`/`BEAD_ID`/`AGENTV_BEAD_ID`, then delegates to `ep-spawn-agent` when available or to an explicit `ntm` fallback.
+- Use `ntm` for tmux session orchestration, monitoring, and dispatch when launching or tending worker sessions. NTM project names must resolve under `ntm config get projects_base`; set `AGENTV_NTM_SESSION` when the repo worktree is not directly under that base.
+- GitHub remains the PR, CI, review, and merge surface. Do not use GitHub Issues or Projects as the internal AgentV task graph unless explicitly bridging external collaboration.
+
+### AO Compatibility
+- AO is not the normal AgentV orchestration path. If a session is explicitly AO-managed, treat AO as the source of truth for that session's ownership, worktree lifecycle, PR claiming, and visualization.
+- In AO-managed sessions, use the AO-provided worktree and branch. Do not create additional worktrees, spawn unmanaged agents, or open duplicate PRs unless the user/AO explicitly asks.
+- Report lifecycle status through AO (`ao acknowledge`, `ao report working`, `ao report fixing-ci`, `ao report addressing-reviews`, `ao report needs-input`, and PR milestone reports) only for AO-managed sessions.
 - When taking over an existing PR in AO, run `ao session claim-pr <number-or-url>` before editing. If AO or git shows another session/worktree owns it, coordinate rather than forcing checkout.
-- GitHub Issues + Projects are the default AO task graph when GitHub is acceptable: use Issues for backlog, parent/sub-issue hierarchy, and explicit blocked-by/blocking dependencies; use Projects for shared views and progress. GitHub PRs/checks remain the review, CI, and merge surface.
-- `ep-spawn-agent` is disabled for normal AO-managed AgentV work because it creates unmanaged agents/worktrees outside AO's lifecycle.
 
 ### Worktree Setup
 - In AO-managed sessions, do not create a new worktree; verify the AO worktree is based on the intended base before editing.
@@ -453,9 +459,17 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
 ### Issue Workflow
 
-Use AO for live ownership and GitHub for external collaboration. Do not duplicate claim state in a separate live tracker.
+Use Beads for live ownership and GitHub for external collaboration. Do not duplicate claim state in a separate live tracker.
 
-When working on a GitHub issue in an AO-managed session:
+When working from a bead:
+
+1. Inspect the bead with `br show <id> --json` or, for the current `bd`/Dolt compatibility store, `bd show <id> --json`.
+2. Claim it with `scripts/bead-spawn-agent.sh <id>` when launching a worker, or with `br update <id> --claim --json` / `bd update <id> --claim --json` when working manually.
+3. Keep the bead updated with notes for user-visible decisions, verification evidence, blockers, and handoff state.
+4. Push focused commits to the assigned branch and open/update the PR requested by the bead/user.
+5. Close the bead only after the scoped work is complete, pushed, and documented with verification evidence.
+
+When working on a GitHub issue in an explicitly AO-managed session:
 
 1. Trust the AO assignment. If the issue/PR appears owned by another AO session, coordinate instead of taking it over.
 2. Use the AO-provided worktree/branch and report status through AO.
@@ -484,8 +498,8 @@ Complete E2E verification before marking a PR ready for review. Never push direc
 
 ### Tracker Conventions
 
-- AO is the source of truth for live worker ownership and session status.
-- GitHub Issues + Projects are the default task graph for AO-managed work when acceptable, because they support durable backlog state, sub-issue hierarchy, and explicit blocked-by/blocking dependencies.
+- Beads is the source of truth for live worker ownership and session status.
+- GitHub Issues + Projects are external collaboration surfaces, not the default internal task graph.
 - `bug` marks defects.
 - Issues without `bug` are non-bug work by default.
 - `core`, `wui`, and `tui` are area labels.
diff --git a/scripts/bead-spawn-agent.sh b/scripts/bead-spawn-agent.sh
new file mode 100755
index 00000000..ccbd691a
--- /dev/null
+++ b/scripts/bead-spawn-agent.sh
@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/bead-spawn-agent.sh [--check] <bead-id> [launcher args...]
+
+Claim a Beads issue, record a launch note, then start a worker.
+
+Environment:
+  AGENTV_BEADS_CLI=auto|br|bd       Beads CLI to use. Default: auto.
+  AGENTV_BEADS_DB=/path/to/db       Explicit .beads database path.
+  AGENTV_LAUNCHER=auto|ep|ntm       Worker launcher. Default: auto.
+  AGENTV_NTM_SESSION=<name>         NTM project/session name for ntm fallback.
+  AGENTV_NTM_LABEL=<label>          NTM label. Default: bead id.
+  AGENTV_NTM_CODEX_COUNT=<n>        Codex panes for ntm fallback. Default: 1.
+  AGENTV_WORKER_PROMPT=<text>       Prompt for ntm fallback.
+
+The wrapper prefers br only when the current issue store is br-readable. If the
+repository still has the older bd/Dolt store, it uses bd instead of assuming br
+can read that graph.
+EOF
+}
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+have() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+repo_root() {
+  git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
+candidate_dbs() {
+  local root="$1"
+
+  if [[ -n "${AGENTV_BEADS_DB:-}" ]]; then
+    printf '%s\n' "$AGENTV_BEADS_DB"
+    return
+  fi
+
+  for path in \
+    "$root/.beads/beads.db" \
+    "$root/.beads/issues.db" \
+    "$root/.beads/dolt"; do
+    [[ -f "$path" ]] && printf '%s\n' "$path"
+  done
+
+  git worktree list --porcelain 2>/dev/null \
+    | awk '/^worktree / { sub(/^worktree /, ""); print }' \
+    | while IFS= read -r worktree; do
+      for path in \
+        "$worktree/.beads/beads.db" \
+        "$worktree/.beads/issues.db" \
+        "$worktree/.beads/dolt"; do
+        [[ -f "$path" ]] && printf '%s\n' "$path"
+      done
+    done
+
+  return 0
+}
+
+first_matching_db() {
+  local root="$1"
+  candidate_dbs "$root" | awk 'NF { print; exit }'
+}
+
+br_has_issue() {
+  local bead_id="$1"
+  local db="$2"
+  [[ "$(basename "$db")" != "dolt" ]] || return 1
+  have br || return 1
+  br --db "$db" show "$bead_id" --json >/dev/null 2>&1
+}
+
+bd_has_issue() {
+  local bead_id="$1"
+  local db="$2"
+  have bd || return 1
+  bd --db "$db" show "$bead_id" --json >/dev/null 2>&1
+}
+
+select_beads_cli() {
+  local requested="$1"
+  local bead_id="$2"
+  local db="$3"
+
+  case "$requested" in
+    br)
+      br_has_issue "$bead_id" "$db" || die "br cannot read bead $bead_id from $db"
+      printf 'br\n'
+      ;;
+    bd)
+      bd_has_issue "$bead_id" "$db" || die "bd cannot read bead $bead_id from $db"
+      printf 'bd\n'
+      ;;
+    auto)
+      if br_has_issue "$bead_id" "$db"; then
+        printf 'br\n'
+      elif bd_has_issue "$bead_id" "$db"; then
+        printf 'bd\n'
+      else
+        die "neither br nor bd can read bead $bead_id from $db"
+      fi
+      ;;
+    *)
+      die "AGENTV_BEADS_CLI must be auto, br, or bd"
+      ;;
+  esac
+}
+
+claim_bead() {
+  local cli="$1"
+  local db="$2"
+  local bead_id="$3"
+
+  if [[ "$cli" == "br" ]]; then
+    br --db "$db" update "$bead_id" --claim --json >/dev/null
+  else
+    bd --db "$db" update "$bead_id" --claim --json >/dev/null
+  fi
+}
+
+note_bead() {
+  local cli="$1"
+  local db="$2"
+  local bead_id="$3"
+  local note="$4"
+
+  if [[ "$cli" == "br" ]]; then
+    br --db "$db" comments add "$bead_id" --message "$note" --json >/dev/null
+  else
+    bd --db "$db" note "$bead_id" "$note" >/dev/null
+  fi
+}
+
+launch_with_ep() {
+  local bead_id="$1"
+  shift
+
+  have ep-spawn-agent || die "ep-spawn-agent is not on PATH"
+  EP_TASK_ID="$bead_id" BEAD_ID="$bead_id" AGENTV_BEAD_ID="$bead_id" ep-spawn-agent "$bead_id" "$@"
+}
+
+launch_with_ntm() {
+  local root="$1"
+  local bead_id="$2"
+  shift 2
+
+  have ntm || die "ntm is not on PATH"
+
+  local session="${AGENTV_NTM_SESSION:-$(basename "$root")}"
+  local label="${AGENTV_NTM_LABEL:-$bead_id}"
+  local count="${AGENTV_NTM_CODEX_COUNT:-1}"
+  local prompt="${AGENTV_WORKER_PROMPT:-Read AGENTS.md first. Work only on bead $bead_id. EP_TASK_ID=$bead_id BEAD_ID=$bead_id AGENTV_BEAD_ID=$bead_id. Inspect the bead graph before changing files, update the bead with notes, and push the scoped branch when complete.}"
+  local projects_base
+  projects_base="$(ntm config get projects_base 2>/dev/null || true)"
+
+  if [[ -n "$projects_base" && ! -d "$projects_base/$session" ]]; then
+    die "ntm session '$session' does not resolve under projects_base '$projects_base'. Set AGENTV_NTM_SESSION to a resolvable NTM project or create the NTM project first."
+  fi
+
+  EP_TASK_ID="$bead_id" BEAD_ID="$bead_id" AGENTV_BEAD_ID="$bead_id" \
+    ntm spawn "$session" --label "$label" --cod="$count" --prompt "$prompt" "$@"
+}
+
+print_check() {
+  local root="$1"
+  local db="$2"
+  local bead_id="$3"
+  local cli="$4"
+  local launcher="$5"
+  local resolved_launcher="$launcher"
+  local ntm_session="${AGENTV_NTM_SESSION:-$(basename "$root")}"
+  local projects_base
+  projects_base="$(ntm config get projects_base 2>/dev/null || true)"
+
+  if [[ "$launcher" == "auto" ]]; then
+    if have ep-spawn-agent; then
+      resolved_launcher="ep"
+    else
+      resolved_launcher="ntm"
+    fi
+  fi
+
+  cat <<EOF
+bead_id: $bead_id
+beads_cli: $cli
+database_path: $db
+launcher: $resolved_launcher
+ep_spawn_agent_available: $(have ep-spawn-agent && printf true || printf false)
+ntm_available: $(have ntm && printf true || printf false)
+ntm_session: $ntm_session
+ntm_projects_base: $projects_base
+ntm_session_resolves: $([[ -n "$projects_base" && -d "$projects_base/$ntm_session" ]] && printf true || printf false)
+EOF
+}
+
+main() {
+  [[ "${1:-}" != "-h" && "${1:-}" != "--help" ]] || {
+    usage
+    exit 0
+  }
+
+  local check_only=false
+  if [[ "${1:-}" == "--check" ]]; then
+    check_only=true
+    shift
+  fi
+
+  [[ $# -ge 1 ]] || {
+    usage >&2
+    exit 2
+  }
+
+  local bead_id="$1"
+  shift
+
+  local root db cli launcher
+  root="$(repo_root)"
+  db="$(first_matching_db "$root")"
+  [[ -n "$db" ]] || die "no .beads database found; set AGENTV_BEADS_DB"
+
+  cli="$(select_beads_cli "${AGENTV_BEADS_CLI:-auto}" "$bead_id" "$db")"
+  launcher="${AGENTV_LAUNCHER:-auto}"
+
+  case "$launcher" in
+    ep | ntm | auto) ;;
+    *) die "AGENTV_LAUNCHER must be auto, ep, or ntm" ;;
+  esac
+
+  if [[ "$check_only" == true ]]; then
+    print_check "$root" "$db" "$bead_id" "$cli" "$launcher"
+    exit 0
+  fi
+
+  claim_bead "$cli" "$db" "$bead_id"
+  note_bead "$cli" "$db" "$bead_id" "Launching worker from $(hostname) in $root via ${launcher} (coordination CLI: $cli, db: $db)."
+
+  case "$launcher" in
+    ep)
+      launch_with_ep "$bead_id" "$@"
+      ;;
+    ntm)
+      launch_with_ntm "$root" "$bead_id" "$@"
+      ;;
+    auto)
+      if have ep-spawn-agent; then
+        launch_with_ep "$bead_id" "$@"
+      else
+        launch_with_ntm "$root" "$bead_id" "$@"
+      fi
+      ;;
+  esac
+}
+
+main "$@"

From 2e3416c61cfa97536a8907049abc2c0a0f935da5 Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 3 Jun 2026 07:59:30 +0200
Subject: [PATCH 2/3] docs(orchestration): use br-only Beads workflow

---
 AGENTS.md                   |  19 ++-
 scripts/bead-spawn-agent.sh | 261 ------------------------------------
 2 files changed, 14 insertions(+), 266 deletions(-)
 delete mode 100755 scripts/bead-spawn-agent.sh

diff --git a/AGENTS.md b/AGENTS.md
index 4dd3f062..20511921 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -110,12 +110,21 @@ AI agents are the primary users of AgentV—not humans reading docs. Design for
 
 ### Beads-First Orchestration
 - Beads is AgentV's normal durable task graph. Use it for assignment, status, dependencies, handoff notes, decomposition, and resumability. Agent sessions are disposable workers that read and write the bead graph.
-- Prefer `br` (beads_rust) for Beads operations when the repository has a `br`-compatible SQLite/JSONL `.beads` store. `br` is non-invasive and never commits or pushes; after `br sync --flush-only`, manually run `git add .beads/` and commit the exported state when the bead graph is part of the change.
-- Compatibility note: the current AgentV bead graph may still be the older `bd`/Dolt store. If `br ready --json` or `br show <id> --json` returns no issues while `bd` sees the graph, use `bd` for that workspace until the store is explicitly migrated. Do not assume `br` can read `bd` state just because it auto-discovers `.beads/dolt`.
-- For worker launch, prefer `scripts/bead-spawn-agent.sh <bead-id>`. The wrapper claims the bead, records a launch note, exports `EP_TASK_ID`/`BEAD_ID`/`AGENTV_BEAD_ID`, then delegates to `ep-spawn-agent` when available or to an explicit `ntm` fallback.
+- Use `br` (beads_rust) for Beads operations. `br` is non-invasive and never commits or pushes; after `br sync --flush-only`, manually run `git add .beads/` and commit the exported state when the bead graph is part of the change.
+- Use the upstream bead-aware launcher from the EntityProcess agent plugin tooling for worker launch. The launcher should claim the bead, record a launch note, export `EP_TASK_ID`/`BEAD_ID`/`AGENTV_BEAD_ID`, then delegate to the existing `ep-spawn-agent` workflow.
 - Use `ntm` for tmux session orchestration, monitoring, and dispatch when launching or tending worker sessions. NTM project names must resolve under `ntm config get projects_base`; set `AGENTV_NTM_SESSION` when the repo worktree is not directly under that base.
 - GitHub remains the PR, CI, review, and merge surface. Do not use GitHub Issues or Projects as the internal AgentV task graph unless explicitly bridging external collaboration.
 
+### Beads Workflow
+- Start with `br ready --json` to find actionable unblocked work.
+- Inspect scope with `br show <id> --json` before changing files.
+- Claim work with `br update <id> --claim --json` or `br update <id> --status in_progress --json`.
+- Create linked follow-up work with `br create --title "..." --type task --priority 2 --json` when you discover new scope.
+- Add dependencies with `br dep add <issue> <depends-on> --json` so ready work stays accurate.
+- Close completed work with `br close <id> --reason "Completed" --json`.
+- Before handoff or commit, run `br sync --flush-only`, then stage `.beads/` along with the code changes.
+- Avoid bare `bv` in automated sessions because it opens an interactive UI. Use robot/non-interactive `bv` surfaces when graph triage is needed, then verify actionability with `br show <id> --json`.
+
 ### AO Compatibility
 - AO is not the normal AgentV orchestration path. If a session is explicitly AO-managed, treat AO as the source of truth for that session's ownership, worktree lifecycle, PR claiming, and visualization.
 - In AO-managed sessions, use the AO-provided worktree and branch. Do not create additional worktrees, spawn unmanaged agents, or open duplicate PRs unless the user/AO explicitly asks.
@@ -463,8 +472,8 @@ Use Beads for live ownership and GitHub for external collaboration. Do not dupli
 
 When working from a bead:
 
-1. Inspect the bead with `br show <id> --json` or, for the current `bd`/Dolt compatibility store, `bd show <id> --json`.
-2. Claim it with `scripts/bead-spawn-agent.sh <id>` when launching a worker, or with `br update <id> --claim --json` / `bd update <id> --claim --json` when working manually.
+1. Inspect the bead with `br show <id> --json`.
+2. Claim it with the upstream bead-aware launcher when launching a worker, or with `br update <id> --claim --json` when working manually.
 3. Keep the bead updated with notes for user-visible decisions, verification evidence, blockers, and handoff state.
 4. Push focused commits to the assigned branch and open/update the PR requested by the bead/user.
 5. Close the bead only after the scoped work is complete, pushed, and documented with verification evidence.
diff --git a/scripts/bead-spawn-agent.sh b/scripts/bead-spawn-agent.sh
deleted file mode 100755
index ccbd691a..00000000
--- a/scripts/bead-spawn-agent.sh
+++ /dev/null
@@ -1,261 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage: scripts/bead-spawn-agent.sh [--check] <bead-id> [launcher args...]
-
-Claim a Beads issue, record a launch note, then start a worker.
-
-Environment:
-  AGENTV_BEADS_CLI=auto|br|bd       Beads CLI to use. Default: auto.
-  AGENTV_BEADS_DB=/path/to/db       Explicit .beads database path.
-  AGENTV_LAUNCHER=auto|ep|ntm       Worker launcher. Default: auto.
-  AGENTV_NTM_SESSION=<name>         NTM project/session name for ntm fallback.
-  AGENTV_NTM_LABEL=<label>          NTM label. Default: bead id.
-  AGENTV_NTM_CODEX_COUNT=<n>        Codex panes for ntm fallback. Default: 1.
-  AGENTV_WORKER_PROMPT=<text>       Prompt for ntm fallback.
-
-The wrapper prefers br only when the current issue store is br-readable. If the
-repository still has the older bd/Dolt store, it uses bd instead of assuming br
-can read that graph.
-EOF
-}
-
-die() {
-  printf 'error: %s\n' "$*" >&2
-  exit 1
-}
-
-have() {
-  command -v "$1" >/dev/null 2>&1
-}
-
-repo_root() {
-  git rev-parse --show-toplevel 2>/dev/null || pwd
-}
-
-candidate_dbs() {
-  local root="$1"
-
-  if [[ -n "${AGENTV_BEADS_DB:-}" ]]; then
-    printf '%s\n' "$AGENTV_BEADS_DB"
-    return
-  fi
-
-  for path in \
-    "$root/.beads/beads.db" \
-    "$root/.beads/issues.db" \
-    "$root/.beads/dolt"; do
-    [[ -f "$path" ]] && printf '%s\n' "$path"
-  done
-
-  git worktree list --porcelain 2>/dev/null \
-    | awk '/^worktree / { sub(/^worktree /, ""); print }' \
-    | while IFS= read -r worktree; do
-      for path in \
-        "$worktree/.beads/beads.db" \
-        "$worktree/.beads/issues.db" \
-        "$worktree/.beads/dolt"; do
-        [[ -f "$path" ]] && printf '%s\n' "$path"
-      done
-    done
-
-  return 0
-}
-
-first_matching_db() {
-  local root="$1"
-  candidate_dbs "$root" | awk 'NF { print; exit }'
-}
-
-br_has_issue() {
-  local bead_id="$1"
-  local db="$2"
-  [[ "$(basename "$db")" != "dolt" ]] || return 1
-  have br || return 1
-  br --db "$db" show "$bead_id" --json >/dev/null 2>&1
-}
-
-bd_has_issue() {
-  local bead_id="$1"
-  local db="$2"
-  have bd || return 1
-  bd --db "$db" show "$bead_id" --json >/dev/null 2>&1
-}
-
-select_beads_cli() {
-  local requested="$1"
-  local bead_id="$2"
-  local db="$3"
-
-  case "$requested" in
-    br)
-      br_has_issue "$bead_id" "$db" || die "br cannot read bead $bead_id from $db"
-      printf 'br\n'
-      ;;
-    bd)
-      bd_has_issue "$bead_id" "$db" || die "bd cannot read bead $bead_id from $db"
-      printf 'bd\n'
-      ;;
-    auto)
-      if br_has_issue "$bead_id" "$db"; then
-        printf 'br\n'
-      elif bd_has_issue "$bead_id" "$db"; then
-        printf 'bd\n'
-      else
-        die "neither br nor bd can read bead $bead_id from $db"
-      fi
-      ;;
-    *)
-      die "AGENTV_BEADS_CLI must be auto, br, or bd"
-      ;;
-  esac
-}
-
-claim_bead() {
-  local cli="$1"
-  local db="$2"
-  local bead_id="$3"
-
-  if [[ "$cli" == "br" ]]; then
-    br --db "$db" update "$bead_id" --claim --json >/dev/null
-  else
-    bd --db "$db" update "$bead_id" --claim --json >/dev/null
-  fi
-}
-
-note_bead() {
-  local cli="$1"
-  local db="$2"
-  local bead_id="$3"
-  local note="$4"
-
-  if [[ "$cli" == "br" ]]; then
-    br --db "$db" comments add "$bead_id" --message "$note" --json >/dev/null
-  else
-    bd --db "$db" note "$bead_id" "$note" >/dev/null
-  fi
-}
-
-launch_with_ep() {
-  local bead_id="$1"
-  shift
-
-  have ep-spawn-agent || die "ep-spawn-agent is not on PATH"
-  EP_TASK_ID="$bead_id" BEAD_ID="$bead_id" AGENTV_BEAD_ID="$bead_id" ep-spawn-agent "$bead_id" "$@"
-}
-
-launch_with_ntm() {
-  local root="$1"
-  local bead_id="$2"
-  shift 2
-
-  have ntm || die "ntm is not on PATH"
-
-  local session="${AGENTV_NTM_SESSION:-$(basename "$root")}"
-  local label="${AGENTV_NTM_LABEL:-$bead_id}"
-  local count="${AGENTV_NTM_CODEX_COUNT:-1}"
-  local prompt="${AGENTV_WORKER_PROMPT:-Read AGENTS.md first. Work only on bead $bead_id. EP_TASK_ID=$bead_id BEAD_ID=$bead_id AGENTV_BEAD_ID=$bead_id. Inspect the bead graph before changing files, update the bead with notes, and push the scoped branch when complete.}"
-  local projects_base
-  projects_base="$(ntm config get projects_base 2>/dev/null || true)"
-
-  if [[ -n "$projects_base" && ! -d "$projects_base/$session" ]]; then
-    die "ntm session '$session' does not resolve under projects_base '$projects_base'. Set AGENTV_NTM_SESSION to a resolvable NTM project or create the NTM project first."
-  fi
-
-  EP_TASK_ID="$bead_id" BEAD_ID="$bead_id" AGENTV_BEAD_ID="$bead_id" \
-    ntm spawn "$session" --label "$label" --cod="$count" --prompt "$prompt" "$@"
-}
-
-print_check() {
-  local root="$1"
-  local db="$2"
-  local bead_id="$3"
-  local cli="$4"
-  local launcher="$5"
-  local resolved_launcher="$launcher"
-  local ntm_session="${AGENTV_NTM_SESSION:-$(basename "$root")}"
-  local projects_base
-  projects_base="$(ntm config get projects_base 2>/dev/null || true)"
-
-  if [[ "$launcher" == "auto" ]]; then
-    if have ep-spawn-agent; then
-      resolved_launcher="ep"
-    else
-      resolved_launcher="ntm"
-    fi
-  fi
-
-  cat <<EOF
-bead_id: $bead_id
-beads_cli: $cli
-database_path: $db
-launcher: $resolved_launcher
-ep_spawn_agent_available: $(have ep-spawn-agent && printf true || printf false)
-ntm_available: $(have ntm && printf true || printf false)
-ntm_session: $ntm_session
-ntm_projects_base: $projects_base
-ntm_session_resolves: $([[ -n "$projects_base" && -d "$projects_base/$ntm_session" ]] && printf true || printf false)
-EOF
-}
-
-main() {
-  [[ "${1:-}" != "-h" && "${1:-}" != "--help" ]] || {
-    usage
-    exit 0
-  }
-
-  local check_only=false
-  if [[ "${1:-}" == "--check" ]]; then
-    check_only=true
-    shift
-  fi
-
-  [[ $# -ge 1 ]] || {
-    usage >&2
-    exit 2
-  }
-
-  local bead_id="$1"
-  shift
-
-  local root db cli launcher
-  root="$(repo_root)"
-  db="$(first_matching_db "$root")"
-  [[ -n "$db" ]] || die "no .beads database found; set AGENTV_BEADS_DB"
-
-  cli="$(select_beads_cli "${AGENTV_BEADS_CLI:-auto}" "$bead_id" "$db")"
-  launcher="${AGENTV_LAUNCHER:-auto}"
-
-  case "$launcher" in
-    ep | ntm | auto) ;;
-    *) die "AGENTV_LAUNCHER must be auto, ep, or ntm" ;;
-  esac
-
-  if [[ "$check_only" == true ]]; then
-    print_check "$root" "$db" "$bead_id" "$cli" "$launcher"
-    exit 0
-  fi
-
-  claim_bead "$cli" "$db" "$bead_id"
-  note_bead "$cli" "$db" "$bead_id" "Launching worker from $(hostname) in $root via ${launcher} (coordination CLI: $cli, db: $db)."
-
-  case "$launcher" in
-    ep)
-      launch_with_ep "$bead_id" "$@"
-      ;;
-    ntm)
-      launch_with_ntm "$root" "$bead_id" "$@"
-      ;;
-    auto)
-      if have ep-spawn-agent; then
-        launch_with_ep "$bead_id" "$@"
-      else
-        launch_with_ntm "$root" "$bead_id" "$@"
-      fi
-      ;;
-  esac
-}
-
-main "$@"

From efef78102b8f8bf6a109f687d2962a5d8e03f4e3 Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 3 Jun 2026 08:47:23 +0200
Subject: [PATCH 3/3] docs(orchestration): remove AO workflow guidance

---
 AGENTS.md | 29 +++++++----------------------
 1 file changed, 7 insertions(+), 22 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 20511921..6541088f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,24 +125,17 @@ AI agents are the primary users of AgentV—not humans reading docs. Design for
 - Before handoff or commit, run `br sync --flush-only`, then stage `.beads/` along with the code changes.
 - Avoid bare `bv` in automated sessions because it opens an interactive UI. Use robot/non-interactive `bv` surfaces when graph triage is needed, then verify actionability with `br show <id> --json`.
 
-### AO Compatibility
-- AO is not the normal AgentV orchestration path. If a session is explicitly AO-managed, treat AO as the source of truth for that session's ownership, worktree lifecycle, PR claiming, and visualization.
-- In AO-managed sessions, use the AO-provided worktree and branch. Do not create additional worktrees, spawn unmanaged agents, or open duplicate PRs unless the user/AO explicitly asks.
-- Report lifecycle status through AO (`ao acknowledge`, `ao report working`, `ao report fixing-ci`, `ao report addressing-reviews`, `ao report needs-input`, and PR milestone reports) only for AO-managed sessions.
-- When taking over an existing PR in AO, run `ao session claim-pr <number-or-url>` before editing. If AO or git shows another session/worktree owns it, coordinate rather than forcing checkout.
-
 ### Worktree Setup
-- In AO-managed sessions, do not create a new worktree; verify the AO worktree is based on the intended base before editing.
-- Outside AO, for any feature, bug fix, or non-trivial repo change, work from a dedicated git worktree based on the latest `origin/main`.
+- For any feature, bug fix, or non-trivial repo change, work from a dedicated git worktree based on the latest `origin/main`.
 - Before starting implementation, run `git fetch origin` and verify your worktree `HEAD` is based on the current `origin/main` commit.
 - Do not implement from the primary checkout, from a stale local `main`, or from a branch created off an outdated base.
-- Manual setup outside AO:
+- Manual setup:
 ```bash
 git fetch origin
 git worktree add ../agentv.worktrees/<type>-<short-desc> -b <type>/<issue-or-topic>-<short-desc> origin/main
 cd ../agentv.worktrees/<type>-<short-desc>
 ```
-- If you discover you are not on a fresh worktree from the latest `origin/main` or the AO-provided base, stop and fix that first before changing code.
+- If you discover you are not on a fresh worktree from the latest `origin/main`, stop and fix that first before changing code.
 
 ### Planning
 - Use plan mode for any non-trivial task (5+ steps or architectural decisions).
@@ -152,8 +145,7 @@ cd ../agentv.worktrees/<type>-<short-desc>
 - Prefer automation: execute the requested work without extra confirmation unless blocked by missing information, safety concerns, or an irreversible/destructive action the user has not approved.
 
 ### Worker and Review Strategy
-- In AO-managed sessions, prefer AO-managed workers/harnesses for parallel work. Do not spawn unmanaged agents from inside a worker unless the user/AO explicitly delegates that orchestration.
-- For complex problems, keep this worker focused on its assigned scope and ask AO/user for coordination if additional workers are needed.
+- For complex problems, keep this worker focused on its assigned scope and create or claim additional beads when more workers are needed.
 - Before declaring a repo change complete or opening/finalizing a PR, complete manual e2e verification first (see E2E Checklist), **then** run a final review pass when warranted. E2E must pass before review — if e2e fails, fix the issue before investing time in review. The user may explicitly skip the review step.
 
 ### Autonomous Bug Fixes
@@ -478,14 +470,7 @@ When working from a bead:
 4. Push focused commits to the assigned branch and open/update the PR requested by the bead/user.
 5. Close the bead only after the scoped work is complete, pushed, and documented with verification evidence.
 
-When working on a GitHub issue in an explicitly AO-managed session:
-
-1. Trust the AO assignment. If the issue/PR appears owned by another AO session, coordinate instead of taking it over.
-2. Use the AO-provided worktree/branch and report status through AO.
-3. Keep the GitHub issue/PR updated with user-visible decisions, verification evidence, and review/CI state.
-4. Push focused commits to the assigned branch and open/update the PR requested by AO/user.
-
-Outside AO, use GitHub project state to avoid duplicate work before branching:
+When working from a GitHub issue instead of a bead, use GitHub project state to avoid duplicate work before branching:
 
 ```bash
 gh issue view <number> --repo EntityProcess/agentv --json number,title,state,projectItems,assignees,url
@@ -496,7 +481,7 @@ bun install
 cp "$(git worktree list --porcelain | head -1 | sed 's/worktree //')/.env" .env
 ```
 
-After the first meaningful commit, push and open a draft PR unless AO/user directs a different PR lifecycle:
+After the first meaningful commit, push and open a draft PR unless the user directs a different PR lifecycle:
 
 ```bash
 git push -u origin <branch-name>
@@ -553,7 +538,7 @@ Plans are temporary working materials. **Before merging the PR**, delete the pla
 
 #### Git Worktrees
 
-In AO-managed sessions, use the AO-provided worktree. Outside AO, use the sibling `../agentv.worktrees/` directory for all AgentV worktrees. This overrides any generic skill or default preference for `.worktrees/` or `worktrees/` inside the repository. Do not create new AgentV worktrees inside the repository root.
+Use the sibling `../agentv.worktrees/` directory for all AgentV worktrees. This overrides any generic skill or default preference for `.worktrees/` or `worktrees/` inside the repository. Do not create new AgentV worktrees inside the repository root.
 
 After creating a manual worktree, always run setup:
 ```bash