awslabs / awslabs/cli-agent-orchestrator

Example: demonstrate Git worktree isolation for delegated workers

Open
#589 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.