awslabs / awslabs/cli-agent-orchestrator
Example: demonstrate Git worktree isolation for delegated workers
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
Parent: #588
## Goal
Add a focused runnable example for CAO's built-in per-worker Git worktree isolation through `assign(..., use_worktree=true)`.
The example should make the isolation and cleanup contract observable: workers start from committed `HEAD` on generated `cao/` branches, the caller's checkout remains unchanged, committed work can be integrated explicitly, and terminal deletion tears down the checkout.
## Scope
- Add `examples/worktrees/` with a README, runnable entry point, focused profiles, and a temporary fixture repository.
- Launch at least two delegated workers with `use_worktree=true` so independent checkouts can be observed concurrently.
- Have workers report their terminal ID, absolute working directory, branch, and commit SHA.
- Assert the generated `.cao/worktrees/` path and `cao/` branch naming.
- Assert that worker edits do not appear in the main checkout before integration.
- Demonstrate explicit integration of committed worker output.
- Delete the worker terminals and verify worktree cleanup.
- Cover the clear failure returned when the resolved working directory is not inside a Git repository.
- Explain that worktrees start from committed `HEAD`; uncommitted caller changes are not inherited.
## Acceptance criteria
- [ ] The sample runs against a temporary Git repository and never mutates the CAO checkout.
- [ ] Two workers can operate concurrently without sharing a checkout or branch.
- [ ] The main checkout remains clean until a worker commit is explicitly integrated.
- [ ] Each worker returns enough identity to locate and inspect its branch and commit.
- [ ] Cleanup removes worktree directories and safely deletes branches with no unmerged commits.
- [ ] The README states that uncommitted/untracked worker content is discarded at teardown and that CAO does not merge, cherry-pick, push, or open a PR automatically.
- [ ] Non-Git-directory failure behavior is demonstrated and asserted.
- [ ] Focused deterministic tests cover setup, isolation assertions, and cleanup; any live-provider test is separately gated.
## Non-goals
- Reimplementing the AI-DLC portfolio worktree manager.
- Adding a global worktree default or `cao worktrees` CLI.
- Demonstrating workflows, memory, learning, AG-UI, or provider comparison.
Contributor guide
Research direction
Read parent issue #588 and the existing assign(..., use_worktree=true) entry point before creating examples/worktrees/. Start with the runnable entry point and focused deterministic tests against a temporary Git repository. Done means the README and example demonstrate concurrent isolation, explicit integration, non-Git failure behavior, and terminal cleanup without mutating the CAO checkout.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- devtools, documentation, testing, tooling
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 63/100