lda-wf/docs/historical/superpowers/plans/2026-06-01-wf-cli-docs-and-skill.md

wf CLI Docs And Skill 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: Create real user-facing wf CLI documentation and a small agent skill, then update wf explain cards to reference those docs instead of planning specs.

Architecture: Treat docs/superpowers/* as planning history only, not runtime/user guidance. The canonical CLI reference should live at docs/wf_cli.md; the optional repo-local skill should live at skills/wf-cli/SKILL.md and point agents to the real doc plus the safest command flow.

Tech Stack: Markdown docs, existing wf_cli.explain registry, pytest, ruff.

---

Scope

Create:

docs/wf_cli.md
skills/wf-cli/SKILL.md

Modify:

docs/README.md
src/wf_cli/explain/entries.py
tests/wf_cli/test_explain.py

Do not add command aliases in this slice. wf cap and wf deploy are the real registered command names.

Do not link wf explain runtime guidance to:

docs/superpowers/specs/*
docs/superpowers/plans/*

Those are planning artifacts, not user/operator docs.

Task 1: Add Real CLI User Documentation

Files:

• Create: docs/wf_cli.md

• Modify: docs/README.md

• Step 1: Create docs/wf_cli.md

Create docs/wf_cli.md:

# wf CLI

`wf` is the workflow platform command-line interface. It is a second front door
beside MCP: useful for shell-driven authoring, local validation, file-based
patches, and agent workflows that do better with commands than giant MCP
schemas.

`wf` uses the same config/store stack as the MCP server in v1:

```bash
wf --config wf_mcp.config.json <command>

If --config is omitted, wf_mcp.config.json is used.

Output Policy

JSON is the default output format for every command.

List/discovery commands may support:

--format json      # complete machine-readable payload
--format ids       # one identifier per line
--format compact   # one concise line per item

Detail and mutation commands are JSON-only unless documented otherwise.

There is no table format in v1.

Lifecycle

The normal CLI workflow is:

1. Inspect capabilities.
2. Create a draft workspace from a capability.
3. Inspect or patch the draft.
4. Validate the draft.
5. Save an artifact.
6. Save a deployment with source bindings.
7. Validate the deployment.
8. Run the deployment.
9. Read bounded trace detail only when debugging.

Capability Discovery

List capabilities:

wf cap list
wf cap list --source wf.std --format ids
wf cap list --query echo --format compact

Inspect one capability:

wf cap inspect wf.std.concat

inspect returns the full contract, including wrapper_hints when available. Hints are scaffolding, not semantic guarantees.

Draft Workspaces

Create a draft from a capability:

wf draft create-from-capability concat_ws wf.std.concat --name concat_ws

List and inspect drafts:

wf draft list --format compact
wf draft inspect concat_ws
wf draft inspect concat_ws --include-draft

Patch a draft with RFC 6902 JSON Patch:

wf draft patch concat_ws \
  --revision 1 \
  --input '[{"op":"replace","path":"/name","value":"concat_ws_v2"}]'

Validate:

wf draft validate concat_ws

Save as an artifact:

wf draft save concat_ws \
  --artifact concat_ws \
  --version 1 \
  --title "Concat Workflow" \
  --outcome ok \
  --binding wf.std=wf.std

Use --kind wrapper when saving a callable wrapper artifact:

wf draft save concat_ws \
  --artifact concat_wrapper \
  --version 1 \
  --title "Concat Wrapper" \
  --kind wrapper \
  --outcome ok \
  --binding wf.std=wf.std

Artifacts

List and inspect artifacts:

wf artifact list --format ids
wf artifact list --kind wrapper --format compact
wf artifact inspect concat_ws 1

Artifacts are immutable saved workflow definitions. List output is compact by design; use inspect for full details.

Deployments

Save a deployment from flags:

wf deploy save concat_ws.default \
  --artifact concat_ws \
  --version 1 \
  --binding wf.std=wf.std

Save a deployment from JSON:

wf deploy save --input-file deployment.json

List, inspect, validate, and delete:

wf deploy list --format compact
wf deploy inspect concat_ws.default
wf deploy validate concat_ws.default
wf deploy validate concat_ws.default --live
wf deploy delete concat_ws.default

--live performs opt-in upstream liveness checks. Static validation can pass even when a live external source is temporarily unreachable.

Runs And Traces

Start a deployment:

wf run start concat_ws.default \
  --input '{"items":["red","blue"],"separator":" + "}'

Inspect a run without trace detail:

wf run inspect run_123

Read a bounded trace slice:

wf run trace run_123 --from 0 --limit 25

Trace output can be large. Always request a bounded range.

Explain

Explain stable diagnostic/error codes:

wf explain source_missing
wf explain deployment_unrunnable --format markdown
wf explain --input-file validation-output.json
wf explain --list --format compact

wf explain is exact-match and docs-backed. It is not fuzzy search and does not generate prose.

Common Diagnostics

source_missing

A required logical source is not available or not bound.

Check:

wf deploy inspect <deployment_id>
wf cap list
wf deploy validate <deployment_id> --live

binding_missing

A deployment is missing a required logical-to-concrete source binding.

Check artifact requirements, then save the deployment with all required bindings:

wf deploy save <deployment_id> \
  --artifact <artifact_id> \
  --version <version> \
  --binding <logical>=<concrete>

capability_missing

The bound source does not expose a required capability.

Check:

wf cap list --source <source_id>
wf deploy inspect <deployment_id>

schema_changed

A saved dependency schema no longer matches the live capability. Inspect the live capability, patch the draft or wrapper, and save a new artifact version.

deployment_unrunnable

The deployment failed validation and should not be run yet.

Check:

wf deploy validate <deployment_id>
wf explain --input-file validation-output.json

Known Limits

• The CLI reuses wf_mcp service/config/store wiring in v1.
• Config loading registers stores and connections, but not arbitrary in-memory test NodeSpec functions.
• Targeted draft editing helpers such as wf draft step add are not in v1.
• wf does not replace MCP resources/prompts or interactive MCP clients.

- [ ] **Step 2: Add CLI doc to docs index**

Modify `docs/README.md` under `## Current Overview` or a new `## CLI` section:

```markdown
- [`wf_cli.md`](wf_cli.md): workflow platform CLI commands, output formats,
  lifecycle flow, and common diagnostics.

• Step 3: Verify doc links manually

Run:

Test-Path docs/wf_cli.md
Select-String -Path docs/README.md -Pattern 'wf_cli.md'

Expected: both show the new doc exists and is indexed.

Task 2: Add Repo-Local Agent Skill

Files:

• Create: skills/wf-cli/SKILL.md

• Step 1: Create skills/wf-cli/SKILL.md

Create skills/wf-cli/SKILL.md:

---
name: wf-cli
description: Use when authoring, validating, deploying, running, or debugging workflows through the repo-local `wf` CLI.
---

# wf CLI

Use the `wf` CLI when an agent needs a shell-friendly workflow lifecycle:

1. Discover capabilities.
2. Create or patch a draft workspace.
3. Validate the draft.
4. Save an artifact.
5. Save and validate a deployment.
6. Run the deployment.
7. Read bounded trace slices only when debugging.

Canonical docs:

- `docs/wf_cli.md`
- `docs/workflow_capabilities.md`
- `docs/workflow_drafts.md`
- `docs/workflow_artifacts.md`
- `docs/durable_run_operations.md`

## Core Commands

```bash
wf cap list --format ids
wf cap inspect <capability>

wf draft create-from-capability <workspace_id> <capability>
wf draft inspect <workspace_id> --include-draft
wf draft patch <workspace_id> --revision <n> --input-file patch.json
wf draft validate <workspace_id>
wf draft save <workspace_id> --artifact <artifact_id> --version <n> --title <title>

wf deploy save <deployment_id> --artifact <artifact_id> --version <n> --binding <logical>=<concrete>
wf deploy validate <deployment_id>
wf run start <deployment_id> --input-file input.json
wf run trace <run_id> --from 0 --limit 25

Rules

• Prefer --input-file for large JSON.
• Prefer --format ids or --format compact for discovery.
• Do not request unbounded traces.
• Do not treat wrapper hints as semantic guarantees.
• If validation fails, run wf explain <code> or wf explain --input-file <validation-output.json>.
• Do not use docs under docs/superpowers/ as user-facing runtime guidance.

- [ ] **Step 2: Do not wire skill installation**

Do not add marketplace/plugin installation logic in this slice. This repo-local
skill is a source document for future packaging; it is not automatically active
until a user installs or copies it into their agent environment.

## Task 3: Update `wf explain` Doc References

**Files:**

- Modify: `src/wf_cli/explain/entries.py`
- Test: `tests/wf_cli/test_explain.py`

- [ ] **Step 1: Add tests that all explain doc refs are user-facing and existing**

Append to `tests/wf_cli/test_explain.py`:

```python
from pathlib import Path


def test_explain_related_docs_do_not_point_to_planning_artifacts() -> None:
    for entry in DEFAULT_EXPLAIN_REGISTRY.list_full_entries():
        for related_doc in entry.related_docs:
            assert "docs/superpowers/" not in related_doc


def test_explain_related_doc_files_exist() -> None:
    repo_root = Path(__file__).resolve().parents[2]
    for entry in DEFAULT_EXPLAIN_REGISTRY.list_full_entries():
        for related_doc in entry.related_docs:
            path_text = related_doc.split("#", 1)[0]
            if path_text.startswith("docs/"):
                assert (repo_root / path_text).exists(), path_text

• Step 2: Add registry full-entry accessor

Modify src/wf_cli/explain/registry.py:

    def list_full_entries(self) -> list[ExplainCard]:
        """Return full cards for internal validation/tests."""
        return list(self._entries.values())

• Step 3: Update explain cards to use docs/wf_cli.md

Modify src/wf_cli/explain/entries.py:

related_docs=[
    "docs/wf_cli.md#deployments",
    "docs/workflow_capabilities.md",
],

Use these mappings:

source_missing          -> docs/wf_cli.md#common-diagnostics, docs/workflow_capabilities.md
source_unreachable      -> docs/wf_cli.md#deployments, docs/wf_mcp_troubleshooting.md
binding_missing         -> docs/wf_cli.md#deployments, docs/workflow_artifacts.md
capability_missing      -> docs/wf_cli.md#capability-discovery, docs/workflow_capabilities.md
schema_changed          -> docs/wf_cli.md#common-diagnostics, docs/schema_validation.md
deployment_unrunnable   -> docs/wf_cli.md#common-diagnostics, docs/current_roadmap.md

• Step 4: Run explain tests

Run:

uv run pytest tests/wf_cli/test_explain.py -q

Expected: pass.

Task 4: Verification

Files:

• No new files unless lint/format requires cleanup.

• Step 1: Run focused CLI tests

Run:

uv run pytest tests/wf_cli -q

Expected: all CLI tests pass.

• Step 2: Run focused lint

Run:

uv run ruff check src/wf_cli tests/wf_cli

Expected: no lint errors.

• Step 3: Run focused format check

Run:

uv run ruff format --check src/wf_cli tests/wf_cli

Expected: no formatting changes required. If this fails, run:

uv run ruff format src/wf_cli tests/wf_cli

Then rerun the format check.

• Step 4: Run docs path check

Run:

Test-Path docs/wf_cli.md
Test-Path skills/wf-cli/SKILL.md
rg -n "docs/superpowers/" src/wf_cli/explain docs/wf_cli.md skills/wf-cli/SKILL.md

Expected:

• docs/wf_cli.md exists.
• skills/wf-cli/SKILL.md exists.
• rg finds no docs/superpowers/ runtime guidance references in those paths.

Self-Review Checklist

• wf explain cards no longer link to docs/superpowers/specs or docs/superpowers/plans.
• docs/wf_cli.md contains the lifecycle that the CLI actually supports today.
• docs/README.md points to the new CLI doc.
• The skill is repo-local documentation only; no install/packaging behavior was added.
• Tests verify explain-card doc refs are not stale.