awslabs / awslabs/cli-agent-orchestrator
docs: the workflows lifecycle still tells readers to hand-write the spec file, bypassing the guarded write path
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
Split out of #583. Scoped out of that Bolt's `authoring-docs-truth` unit by decision: that unit's
remit was to fix statements the Bolt made *false*, and this is a statement that is still literally
true but now points at the wrong path.
## What the doc says
`docs/workflows.md` § "The lifecycle" opens with:
> Every workflow follows the same path. **No step is optional.**
>
> 1. **Author** — write the `.py` file to `~/.aws/cli-agent-orchestrator/workflows/.py`.
The quickstart above it does the same, showing a file written directly into the workflows directory.
## Why that is now a problem
#583 Bolt 3 added a guarded server-side write path — `cao workflow create` / `update` and the
`workflow_create` / `workflow_update` MCP tools. Everything protective lives on that path:
- path containment (the write cannot escape the spec directory);
- the source size cap;
- validation and the lint gate **before** the file lands, so CAO never writes a spec it would refuse
to run;
- an atomic `mkstemp` + `os.replace`, so no reader sees a half-written spec;
- a pre-write tier-collision check — without it, a `foo.py` created beside an existing `foo.yaml`
lands successfully and then every `get_workflow("foo")` raises `TierCollisionError`, i.e. the file
is unreachable the moment it is written.
A reader following the documented lifecycle gets **none** of these. The tier-collision case is the
sharpest: the doc warns "you must not create a same-stem `hello.yaml` sibling", which makes avoiding
it the reader's job, when `create` now checks it for them.
The reference tables do list the new verbs and tools (corrected in the Bolt 3 PR), so the surfaces are
discoverable. What is missing is the narrative: nothing tells a reader that the hand-write is now the
unguarded option.
## Suggested change
Rewrite lifecycle step 1 to present `cao workflow create --from-file` as the normal path, keep the
hand-write as an explicitly-acknowledged alternative with its trade-offs named, and add a short
worked authoring sequence (validate a draft → create → approve → run). `skills/cao-workflow/SKILL.md`
already carries this for agents, so the content exists and needs a human-facing counterpart rather
than fresh invention.
Contributor guide
Research direction
Start with the lifecycle and quickstart sections in docs/workflows.md, then read skills/cao-workflow/SKILL.md for the existing authoring guidance. Update the narrative to make cao workflow create --from-file the normal path, explain the hand-write alternative and its trade-offs, and add the validate → create → approve → run sequence. Done means the human-facing workflow matches the guarded path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100