diff --git a/README.md b/README.md index 5e22f3f..42e5a8c 100644 --- a/README.md +++ b/README.md @@ -155,17 +155,22 @@ python3 scripts/agent-file-locks.py claim \ # 3) Implement + verify npm test -# 4) Finish (commit + push + PR + merge) +# 4) Finish (commit + push + PR + merge + cleanup) bash scripts/agent-branch-finish.sh \ --branch "$(git rev-parse --abbrev-ref HEAD)" \ - --base dev --via-pr --wait-for-merge - -# 5) Optional: cleanup after merge -gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)" + --base main --via-pr --wait-for-merge --cleanup ``` If you use `scripts/codex-agent.sh`, the finish flow runs automatically when the Codex session exits — it auto-commits, retries once after syncing if the base moved during the run, then pushes and opens the PR. +Guardex normally prunes merged sandboxes for you as part of the finish flow. If you simply do not want a local sandbox/worktree anymore, remove that worktree directly; delete the branch too only if you are intentionally abandoning that lane: + +```sh +git worktree remove .omx/agent-worktrees/ +# Claude Code sandboxes live under .omc/agent-worktrees/ +git branch -D agent// # optional, only if you are discarding the lane +``` + Running Codex across several existing worktrees (e.g. from VS Code Source Control)? Finalize everything ready at once: ```sh @@ -489,6 +494,7 @@ Expanded flow: - `scripts/codex-agent.sh` enforces OpenSpec workspaces before launching Codex. - `scripts/agent-branch-start.sh` can scaffold both `openspec/changes//` and `openspec/plan//` when `GUARDEX_OPENSPEC_AUTO_INIT=true`. +- The collaboration section in `tasks.md` is there for real cleanup handoffs too. If the first Codex/Claude session finishes the implementation work but hits a usage limit before `agent-branch-finish --cleanup`, hand the same sandbox to another agent, let that agent finish cleanup, and record the join/handoff in the change task. Environment variables: @@ -553,7 +559,7 @@ gh workflow run sync-frontend-mirror.yml Being honest about where this still has issues: -- **Usage limit mid-task.** When an agent hits its Codex/Claude usage limit partway through, the cleanup flow currently has to be handed to a different agent. It works, but the handoff is uglier than I'd like. +- **Usage limit mid-task.** When an agent hits its Codex/Claude usage limit partway through, another agent may need to take over the same sandbox and run the remaining finish/cleanup steps. The OpenSpec collaboration checklist is there to capture that handoff, but it is still uglier than I'd like. - **Conflict-stuck probes.** Fixed in v7.0.2 — earlier versions could leak `__source-probe-*` worktrees when the sync-guard rebase hit conflicts. If you're on an older release, `gx cleanup` sweeps these. - **Windows.** Most of the hook surface assumes a POSIX shell. Use WSL or symlink-enabled git if you're on Windows. diff --git a/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/.openspec.yaml b/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/.openspec.yaml new file mode 100644 index 0000000..4b8c565 --- /dev/null +++ b/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-21 diff --git a/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/notes.md b/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/notes.md new file mode 100644 index 0000000..abd2483 --- /dev/null +++ b/openspec/changes/agent-codex-document-worktree-cleanup-handoff-2026-04-21-16-19/notes.md @@ -0,0 +1,5 @@ +# T1 Notes + +- Update the README daily workflow example so finish-time cleanup is the default merged-sandbox path. +- Document the manual `git worktree remove` escape hatch for users who simply want a local worktree gone. +- Explain that OpenSpec collaboration checklists also cover cross-agent cleanup handoffs when the original Codex/Claude session runs out of runway.