awslabs / awslabs/cli-agent-orchestrator
Build a feature-focused CAO examples suite
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
## Problem
CAO exposes substantial capabilities across orchestration, worktree isolation, persistent memory, agent learning, saved workflows, external MCP operations, skills, tool restrictions, scheduling, and UI protocols. The current example gallery is broad but uneven:
- AG-UI already has a strong runnable and asserting example suite.
- Core orchestration and cross-provider examples exist, but several important features are only documented or appear indirectly inside larger scenarios.
- Workflow examples under `docs/examples/` demonstrate control-flow mechanics rather than a complete feature sample in the main gallery.
- `examples/flow` is the current `cao schedule` sample surface, but its trivia example does not demonstrate the schedule lifecycle.
- Built-in worktree isolation, memory/learning, skills, tool restrictions, and external `cao-ops-mcp` management do not have focused runnable examples.
Users should be able to learn and validate one CAO feature without first understanding an unrelated end-to-end application.
## Proposed direction
Build a feature-focused examples suite under `examples/`. Each sample should teach and validate one primary CAO capability. Supporting CAO primitives may be used, but the sample must keep one clear feature boundary.
Initial sample set:
1. Git worktree and branch isolation.
2. Persistent memory and agent learning.
3. Python-first CAO workflows.
4. External fleet management through `cao-ops-mcp`.
5. Skill installation, discovery, loading, and application.
6. Tool restriction resolution and enforcement.
7. The `cao schedule` lifecycle through the existing `examples/flow` surface.
AG-UI is intentionally excluded because `examples/ag-ui/` already provides extensive focused coverage.
## Shared sample standard
Every new or revised sample should:
- Have one primary feature and state that feature at the top of its README.
- Include a runnable entry point such as `run.sh` when the feature can be exercised non-interactively.
- Use a temporary or bundled fixture where practical rather than mutating the CAO checkout.
- Assert that the intended feature actually engaged, not merely that the command exited successfully.
- Document prerequisites, expected output/state transitions, failure behavior, and cleanup.
- Clean up sessions, terminals, worktrees, temporary files, and other resources it creates.
- Minimize provider-specific assumptions; when a provider is required, document exactly why.
- Include focused automated coverage. Live-provider tests may be separately gated, but deterministic behavior should run in normal CI when feasible.
- Link to the canonical feature documentation rather than duplicating its complete reference contract.
- Keep secrets out of profiles, fixtures, command arguments, logs, and committed artifacts.
## Work breakdown
The implementation is split into native GitHub sub-issues, one per feature-focused sample.
## Acceptance criteria
- [ ] Each planned sample has a standalone sub-issue with explicit scope and acceptance criteria.
- [ ] Each completed sample follows the shared sample standard above.
- [ ] The examples gallery or root navigation links to every completed feature sample.
- [ ] Existing examples are reused or revised where appropriate instead of creating duplicate surfaces.
- [ ] Documentation terminology consistently treats `examples/flow` as the `cao schedule` example.
- [ ] The suite does not add another AG-UI, provider-specific hello-world, plugin, fleet, or AI-DLC sample without a separately demonstrated gap.
## Non-goals
- Building a single showcase that combines every CAO capability.
- Replacing canonical feature documentation with example READMEs.
- Expanding the underlying feature implementations solely to make a sample appear complete.
- Reworking the existing AG-UI, fleet, AI-DLC portfolio, AWS, or plugin examples as part of this issue.
Contributor guide
Assessment
This issue has not been assessed yet.