awslabs / awslabs/cli-agent-orchestrator

docs: the workflows lifecycle still tells readers to hand-write the spec file, bypassing the guarded write path

Open Beginner friendly
#698 0 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.