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:

wf draft create --capability local.report.extract_report ...
wf draft add-step --capability local.report.render_markdown_report ...

Before this change, the product exposed:

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:

wf draft create <workspace_id> `
  --capability <qualified_name> `
  --name <draft_name> `
  --title <workspace_title>

Add a capability step:

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:

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.

3.4 KiB Raw Blame History