diff --git a/AGENTS.md b/AGENTS.md index 702dae28..6541088f 100644 --- a/AGENTS.md +++ b/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 ` 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 --json` before changing files. +- Claim work with `br update --claim --json` or `br update --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 --json` so ready work stays accurate. +- Close completed work with `br close --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 --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/- -b /- origin/main cd ../agentv.worktrees/- ``` -- 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/- - 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 --json`. +2. Claim it with the upstream bead-aware launcher when launching a worker, or with `br update --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 --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 @@ -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