# Draft CLI Vocabulary Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace long draft CLI command names with `wf draft create --capability` and `wf draft add-step --capability`.

**Architecture:** This is a CLI vocabulary cleanup, not a programmatic API rename. Keep the existing Python/RPC/MCP methods and route the new Typer commands to those handlers. Remove the old long CLI commands and update live docs/skills so agents learn one command shape.

**Tech Stack:** Python 3.14, Typer CLI, pytest, ruff, basedpyright.

---

## File Map

- Modify `src/wf_cli/commands/drafts.py`: replace `create-from-capability` with `create`, replace `add-step-from-capability` with `add-step`.
- Modify `tests/wf_cli/test_app.py`: update help tests and assert old long commands are absent.
- Modify `tests/wf_cli/test_remote_target.py` and `tests/wf_cli/test_discovery_lifecycle.py`: update CLI invocations.
- Modify live docs/skills that mention the old CLI commands:
  - `docs/wf_cli.md`
  - `docs/current_roadmap.md`
  - `docs/runbooks/rpc-cli-smoke.md`
  - `docs/runbooks/python-source.md`
  - `skills/wf-cli/SKILL.md`
  - `skills/wf-workflow/SKILL.md`
  - `skills/wf-workflow/references/workflow-lifecycle.md`
  - `skills/wf-workflow/references/draft-workspaces.md`
  - `skills/wf-workflow/references/direct-plan-import.md`
  - `skills/wf-workflow/references/system-model.md`
  - `docs/superpowers/specs/2026-06-27-draft-semantic-authoring-boundary.md`
- Do not edit historical docs except by moving this plan after implementation.

---

### Task 1: Replace Create Command Shape

**Files:**
- Modify: `src/wf_cli/commands/drafts.py`
- Test: `tests/wf_cli/test_app.py`, `tests/wf_cli/test_remote_target.py`, `tests/wf_cli/test_discovery_lifecycle.py`

- [ ] **Step 1: Update failing CLI help tests**

In `tests/wf_cli/test_app.py`, replace:

```python
def test_wf_draft_create_from_capability_help_exists() -> None:
    result = runner.invoke(app, ["draft", "create-from-capability", "--help"])

    assert result.exit_code == 0
    assert "--title" in result.output
```

with:

```python
def test_wf_draft_create_help_accepts_capability_option() -> None:
    result = runner.invoke(app, ["draft", "create", "--help"])

    assert result.exit_code == 0
    output = " ".join(result.output.split())
    assert "--capability" in output
    assert "--title" in output


def test_wf_draft_help_does_not_list_old_create_from_capability() -> None:
    result = runner.invoke(app, ["draft", "--help"])

    assert result.exit_code == 0
    assert "create-from-capability" not in result.output
```

- [ ] **Step 2: Update CLI invocations in tests**

Replace command arrays like:

```python
[
    "draft",
    "create-from-capability",
    "workspace_id",
    "wf.std.constant",
]
```

with:

```python
[
    "draft",
    "create",
    "workspace_id",
    "--capability",
    "wf.std.constant",
]
```

Files to update:

- `tests/wf_cli/test_remote_target.py`
- `tests/wf_cli/test_discovery_lifecycle.py`

Use `rg -n 'create-from-capability' tests/wf_cli` to find every live test hit.

- [ ] **Step 3: Run tests and confirm failure**

Run:

```powershell
uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py tests/wf_cli/test_discovery_lifecycle.py -q -k "draft or create"
```

Expected: failures because `wf draft create` does not exist yet.

- [ ] **Step 4: Implement `wf draft create --capability`**

In `src/wf_cli/commands/drafts.py`, replace:

```python
@app.command("create-from-capability")
def create_from_capability(
    ctx: typer.Context,
    workspace_id: Annotated[str, typer.Argument(help="Draft workspace id.")],
    capability_name: Annotated[str, typer.Argument(help="Workflow capability name.")],
    name: Annotated[
        str | None, typer.Option("--name", help="Draft workflow name.")
    ] = None,
    title: Annotated[
        str | None, typer.Option("--title", help="Workspace title.")
    ] = None,
) -> None:
    """Bootstrap a draft workspace from inspect_capability wrapper hints."""
```

with:

```python
@app.command("create")
def create_from_capability(
    ctx: typer.Context,
    workspace_id: Annotated[str, typer.Argument(help="Draft workspace id.")],
    capability_name: Annotated[
        str,
        typer.Option(
            "--capability",
            help="Qualified capability name used to bootstrap the draft.",
        ),
    ],
    name: Annotated[
        str | None, typer.Option("--name", help="Draft workflow name.")
    ] = None,
    title: Annotated[
        str | None, typer.Option("--title", help="Workspace title.")
    ] = None,
) -> None:
    """Create a patchable draft workspace from one capability."""
```

Keep the handler call unchanged:

```python
context.handlers.create_draft_workspace_from_capability(...)
```

Do not keep `@app.command("create-from-capability")`.

- [ ] **Step 5: Run create-focused tests**

Run:

```powershell
uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py tests/wf_cli/test_discovery_lifecycle.py -q -k "create"
```

Expected: selected tests pass.

- [ ] **Step 6: Commit**

```powershell
git add src/wf_cli/commands/drafts.py tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py tests/wf_cli/test_discovery_lifecycle.py
git commit -m "feat: simplify draft create cli"
```

---

### Task 2: Replace Add-Step Command Shape

**Files:**
- Modify: `src/wf_cli/commands/drafts.py`
- Test: `tests/wf_cli/test_app.py`, `tests/wf_cli/test_remote_target.py`

- [ ] **Step 1: Update failing CLI help tests**

In `tests/wf_cli/test_app.py`, replace:

```python
def test_wf_draft_add_step_from_capability_help_explains_explicit_wiring() -> None:
    result = runner.invoke(app, ["draft", "add-step-from-capability", "--help"])
```

with:

```python
def test_wf_draft_add_step_help_explains_explicit_wiring() -> None:
    result = runner.invoke(app, ["draft", "add-step", "--help"])

    assert result.exit_code == 0
    output = " ".join(result.output.split())
    assert "--capability" in output
    assert "--from-step" in output
    assert "--bind-output" in output
    assert "does not guess" in output


def test_wf_draft_help_does_not_list_old_add_step_from_capability() -> None:
    result = runner.invoke(app, ["draft", "--help"])

    assert result.exit_code == 0
    assert "add-step-from-capability" not in result.output
```

- [ ] **Step 2: Update CLI invocations in tests**

Replace:

```python
[
    "draft",
    "add-step-from-capability",
    "workspace_id",
    "--revision",
    "1",
    "--step",
    "render",
    "--capability",
    "local.report.render_markdown_report",
]
```

with:

```python
[
    "draft",
    "add-step",
    "workspace_id",
    "--revision",
    "1",
    "--step",
    "render",
    "--capability",
    "local.report.render_markdown_report",
]
```

Files to update:

- `tests/wf_cli/test_app.py`
- `tests/wf_cli/test_remote_target.py`

Use `rg -n 'add-step-from-capability' tests/wf_cli` to find every live test hit.

- [ ] **Step 3: Run tests and confirm failure**

Run:

```powershell
uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py -q -k "add_step or add-step"
```

Expected: failures because `wf draft add-step` does not exist yet.

- [ ] **Step 4: Implement `wf draft add-step --capability`**

In `src/wf_cli/commands/drafts.py`, replace:

```python
@app.command("add-step-from-capability")
def add_step_from_capability(
```

with:

```python
@app.command("add-step")
def add_step_from_capability(
```

Update the docstring first line to:

```python
"""Add one capability-backed step with explicit route, input, and output wiring.
```

Keep the handler call unchanged:

```python
context.handlers.add_step_from_capability(...)
```

Do not keep `@app.command("add-step-from-capability")`.

- [ ] **Step 5: Run add-step tests**

Run:

```powershell
uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py -q -k "add_step or add-step"
```

Expected: selected tests pass.

- [ ] **Step 6: Commit**

```powershell
git add src/wf_cli/commands/drafts.py tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py
git commit -m "feat: simplify draft add-step cli"
```

---

### Task 3: Update Live Docs And Skills

**Files:**
- Modify: `docs/wf_cli.md`
- Modify: `docs/current_roadmap.md`
- Modify: `docs/runbooks/rpc-cli-smoke.md`
- Modify: `docs/runbooks/python-source.md`
- Modify: `docs/superpowers/specs/2026-06-27-draft-semantic-authoring-boundary.md`
- Modify: `skills/wf-cli/SKILL.md`
- Modify: `skills/wf-workflow/SKILL.md`
- Modify: `skills/wf-workflow/references/workflow-lifecycle.md`
- Modify: `skills/wf-workflow/references/draft-workspaces.md`
- Modify: `skills/wf-workflow/references/direct-plan-import.md`
- Modify: `skills/wf-workflow/references/system-model.md`
- Move: `docs/superpowers/plans/2026-06-28-draft-cli-vocabulary.md` to `docs/historical/superpowers/plans/2026-06-28-draft-cli-vocabulary.md`

- [ ] **Step 1: Replace old command names in live docs/skills**

Use:

```powershell
rg -n 'create-from-capability|add-step-from-capability|draft create --capability' docs skills -S -g '!docs/historical/**'
```

Update live CLI examples:

```powershell
wf draft create report_ws --capability local.report.extract_report --name report
```

```powershell
wf draft add-step report_ws --revision 3 --step render --capability local.report.render_markdown_report --route ok=__end__
```

Remove text that says:

```text
There is currently no `wf draft create --capability` alias.
```

- [ ] **Step 2: Update semantic authoring spec**

In `docs/superpowers/specs/2026-06-27-draft-semantic-authoring-boundary.md`,
replace public CLI operation names:

```markdown
- `create`
- `add-step`
- `bind`
- `branch`
- `handle`
```

Keep Python method names when the document explicitly discusses internal API
implementation details.

- [ ] **Step 3: Update roadmap**

Add a completed bullet under Priority 1:

```markdown
- Completed: draft CLI vocabulary now uses `wf draft create --capability` and
  `wf draft add-step --capability`, replacing the longer
  `*-from-capability` commands that agents repeatedly guessed around.
```

- [ ] **Step 4: Move plan to historical**

Run:

```powershell
New-Item -ItemType Directory -Force -Path docs/historical/superpowers/plans | Out-Null
Move-Item docs/superpowers/plans/2026-06-28-draft-cli-vocabulary.md docs/historical/superpowers/plans/2026-06-28-draft-cli-vocabulary.md
```

- [ ] **Step 5: Verify no stale live CLI names remain**

Run:

```powershell
rg -n 'create-from-capability|add-step-from-capability' docs skills tests src -S -g '!docs/historical/**'
```

Expected:

- No CLI command docs or tests use the old names.
- Programmatic API/RPC/MCP names may still appear, for example
  `create_draft_workspace_from_capability`, `add_step_from_capability`, and
  `workflow.draft_workspaces.add_step_from_capability`.

- [ ] **Step 6: Commit**

```powershell
git add docs skills tests src docs/historical/superpowers/plans/2026-06-28-draft-cli-vocabulary.md
git commit -m "docs: update draft cli vocabulary"
```

---

### Task 4: Final Verification

**Files:**
- No planned source edits.

- [ ] **Step 1: Run focused CLI tests**

Run:

```powershell
uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py tests/wf_cli/test_discovery_lifecycle.py -q -k "draft or create or add_step or add-step"
```

Expected: all selected tests pass.

- [ ] **Step 2: Run broader affected suites**

Run:

```powershell
uv run pytest tests/wf_cli tests/docs -q
```

Expected: all tests pass. If docs tests are not present in the current checkout,
record that and continue with the CLI tests.

- [ ] **Step 3: Run lint, format, and type checks**

Run:

```powershell
uv run ruff check
uv run ruff format --check
uv run basedpyright --level error
git diff --check
```

Expected:

- Ruff clean.
- Format clean.
- Basedpyright reports `0 errors`.
- `git diff --check` has no whitespace errors. CRLF warnings are acceptable on
  Windows.

- [ ] **Step 4: Optional smoke command**

Run:

```powershell
uv run wf --config wf.config.json draft create --help
uv run wf --config wf.config.json draft add-step --help
```

Expected:

- `create` help shows `--capability`.
- `add-step` help shows `--capability`, `--route`, `--input`, and
  `--bind-output`.

- [ ] **Step 5: Commit final cleanup if needed**

```powershell
git status --short
git add <only files changed by cleanup>
git commit -m "fix: polish draft cli vocabulary"
```

Skip this commit if the tree is already clean after Task 3.

---

## Self-Review Notes

- This plan intentionally changes only CLI command names and live docs/skills.
- It does not rename Python/RPC/MCP programmatic method names.
- It removes the old long CLI names rather than keeping aliases.
- Future work can rename RPC/MCP tools if evidence shows model confusion there too.