116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# Draft CLI Vocabulary Design
|
|
|
|
## Status
|
|
|
|
Implemented. This design generalized the two capability-specific draft
|
|
CLI verbs:
|
|
|
|
- `wf draft create-from-capability`
|
|
- `wf draft add-step-from-capability`
|
|
|
|
They are replaced at the CLI layer by:
|
|
|
|
- `wf draft create --capability <qualified_name>`
|
|
- `wf draft add-step --capability <qualified_name>`
|
|
|
|
The long commands are removed from the CLI, docs, and skills rather than kept
|
|
as aliases. The focused bind/remove surface is threaded through API, RPC, and
|
|
MCP layers; CLI/docs/skills expose only the concise command vocabulary.
|
|
|
|
## Problem
|
|
|
|
Agents keep trying CLI shapes that match common command vocabulary:
|
|
|
|
```powershell
|
|
wf draft create --capability local.report.extract_report ...
|
|
wf draft add-step --capability local.report.render_markdown_report ...
|
|
```
|
|
|
|
Before this change, the product exposed:
|
|
|
|
```powershell
|
|
wf draft create-from-capability ...
|
|
wf draft add-step-from-capability ...
|
|
```
|
|
|
|
The long names were precise but hostile to discovery. Skills had to warn agents
|
|
that `wf draft create --capability` did not exist, which showed that the CLI
|
|
shape was wrong.
|
|
|
|
## New CLI Shape
|
|
|
|
Create a workspace:
|
|
|
|
```powershell
|
|
wf draft create <workspace_id> `
|
|
--capability <qualified_name> `
|
|
--name <draft_name> `
|
|
--title <workspace_title>
|
|
```
|
|
|
|
Add a capability step:
|
|
|
|
```powershell
|
|
wf draft add-step <workspace_id> `
|
|
--revision <n> `
|
|
--step <step_id> `
|
|
--capability <qualified_name> `
|
|
--from-step <prev_step> `
|
|
--from-outcome ok `
|
|
--route ok=__end__ `
|
|
--input input.text=local.text `
|
|
--bind-output result=state.result
|
|
```
|
|
|
|
`--capability` is required for both commands in this slice. Future core step
|
|
types can extend `add-step` with `--type condition`, `--type foreach`, or
|
|
similar flags, but this slice only renames the current capability-backed
|
|
operations.
|
|
|
|
## Removal Policy
|
|
|
|
Remove these CLI commands:
|
|
|
|
- `wf draft create-from-capability`
|
|
- `wf draft add-step-from-capability`
|
|
|
|
Do not keep aliases. These names made sense as implementation descriptions, but
|
|
they now actively fight agent behavior. Removing them keeps `wf draft --help`
|
|
smaller and prevents skills from teaching two ways to do the same operation.
|
|
|
|
Keep these programmatic method names for now:
|
|
|
|
- `create_draft_workspace_from_capability`
|
|
- `add_step_from_capability`
|
|
- `workflow.draft_workspaces.create_from_capability`
|
|
- `workflow.draft_workspaces.add_step_from_capability`
|
|
- `wf.workflow.create_draft_workspace_from_capability`
|
|
- `wf.workflow.add_step_from_capability`
|
|
|
|
Those surfaces are outside the immediate CLI vocabulary problem and have older
|
|
test/docs coverage. A future transport vocabulary cleanup can rename them if
|
|
there is evidence that MCP/RPC callers struggle with the same names.
|
|
|
|
## Documentation Policy
|
|
|
|
Live user-facing docs and skills should teach only:
|
|
|
|
```powershell
|
|
wf draft create ... --capability ...
|
|
wf draft add-step ... --capability ...
|
|
```
|
|
|
|
Historical docs may keep old command names. Live docs that mention the old CLI
|
|
names must either be updated or clearly mark them as historical context.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `wf draft create --capability ...` creates the same workspace as the old
|
|
command.
|
|
- `wf draft add-step --capability ...` adds the same capability-backed step as
|
|
the old command.
|
|
- `wf draft --help` lists `create` and `add-step`, not the long
|
|
`*-from-capability` CLI commands.
|
|
- Skills no longer say “there is no `wf draft create --capability` alias.”
|
|
- Existing RPC/MCP tests keep passing without programmatic surface renames.
|