docs(orchestration): use br-first Beads workflow

AGENTS.md

@@ -108,26 +108,34 @@ 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).
-- 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.
+### 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.
+- 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`.
 
 ### 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).
@@ -137,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
@@ -453,16 +460,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. 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.
+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.
 
-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
@@ -473,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>
@@ -484,8 +492,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.
@@ -530,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