# `wf schema` Command 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 the uncommitted `wf schema` prototype with a catalog-backed command that emits compact JSON outlines by default and valid self-contained JSON Schema with `--verbose`.

**Architecture:** Pydantic `TypeAdapter.json_schema()` remains the only schema generator. A focused `wf_cli.schema_catalog` module indexes root schemas and Pydantic `$defs`, projects a bounded non-validating outline, and wraps component definitions in a complete verbose document. The Typer command is a thin JSON-emitting adapter with aliases, catalog listing, and nonzero errors.

**Tech Stack:** Python 3.14, Pydantic v2 `TypeAdapter`, `jsonschema.Draft202012Validator`, Typer, pytest.

---

## File Structure

- Create `src/wf_cli/schema_catalog.py`: schema generation, catalog indexing,
  compact projection, and verbose document construction.
- Replace `src/wf_cli/commands/schema.py`: thin Typer command.
- Modify `src/wf_cli/app.py`: register optional-argument schema command without
  forced help on no arguments.
- Create `tests/wf_cli/test_schema.py`: focused catalog/CLI behavior.
- Modify `tests/wf_cli/test_app.py`: remove stale WIP assertion.
- Modify `skills/wf-cli/SKILL.md`: document the usable public schema surface.
- Modify `skills/wf-workflow/references/direct-plan-import.md`: point raw-plan
  authors to schema discovery.
- Modify `skills/wf-workflow/references/draft-workspaces.md`: point draft
  authors to schema discovery.
- Modify `pyproject.toml` and `uv.lock`: remove the prototype-only `cachetools`
  dependency.

### Task 1: Lock CLI Behavior With Failing Tests

**Files:**
- Create: `tests/wf_cli/test_schema.py`
- Modify: `tests/wf_cli/test_app.py:82-88`

- [ ] **Step 1: Replace the stale WIP test**

Replace `test_wf_schema_help_marks_command_group_as_wip` with:

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

    assert result.exit_code == 0
    output = result.output.lower()
    assert "compact workflow schema outline" in output
    assert "--verbose" in output
    assert "draft" in output
    assert "raw" in output
    assert "core" in output
```

- [ ] **Step 2: Add catalog, compact, verbose, and error tests**

Create `tests/wf_cli/test_schema.py`:

```python
from __future__ import annotations

import json
from collections.abc import Iterator
from typing import Any

from jsonschema import Draft202012Validator
from typer.testing import CliRunner

from wf_cli.app import app


runner = CliRunner()


def _json_result(*args: str) -> dict[str, Any]:
    result = runner.invoke(app, ["schema", *args])
    assert result.exit_code == 0, result.output
    payload = json.loads(result.output)
    assert isinstance(payload, dict)
    return payload


def _local_refs(value: object) -> Iterator[str]:
    if isinstance(value, dict):
        for key, item in value.items():
            if key == "$ref" and isinstance(item, str) and item.startswith("#/$defs/"):
                yield item.removeprefix("#/$defs/")
            else:
                yield from _local_refs(item)
    elif isinstance(value, list):
        for item in value:
            yield from _local_refs(item)


def test_schema_without_name_lists_sorted_catalog() -> None:
    payload = _json_result()
    listed = _json_result("list")

    assert payload == listed
    names = [entry["name"] for entry in payload["schemas"]]
    assert names == sorted(names)
    assert {"WorkflowDraft", "RawWorkflowPlan", "Workflow", "NodeUse"} <= set(names)
    aliases = {
        alias: entry["name"]
        for entry in payload["schemas"]
        for alias in entry["aliases"]
    }
    assert aliases == {
        "core": "Workflow",
        "draft": "WorkflowDraft",
        "raw": "RawWorkflowPlan",
    }


def test_schema_compact_alias_is_json_outline_without_refs() -> None:
    payload = _json_result("raw")

    assert payload["name"] == "RawWorkflowPlan"
    assert payload["kind"] == "schema_outline"
    assert payload["properties"]["nodes"]["items"]["one_of"] == [
        "NodeUse",
        "SubgraphNode",
        "ConditionNode",
        "ForeachNode",
        "JoinNode",
        "EndNode",
        "InterruptNode",
    ]
    assert "$ref" not in json.dumps(payload)
    assert "NodeUse" in payload["related"]
    assert payload["full_schema_command"] == "wf schema raw --verbose"


def test_schema_compact_component_is_queryable() -> None:
    payload = _json_result("NodeUse")

    assert payload["name"] == "NodeUse"
    assert payload["properties"]["input"]["items"]["one_of"] == [
        "InputPathBinding",
        "InputValueBinding",
    ]
    assert "$ref" not in json.dumps(payload)


def test_schema_verbose_root_is_valid_json_schema() -> None:
    payload = _json_result("raw", "--verbose")

    Draft202012Validator.check_schema(payload)
    definitions = payload.get("$defs", {})
    assert set(_local_refs(payload)) <= set(definitions)
    assert payload["title"] == "RawWorkflowPlan"


def test_schema_verbose_component_is_self_contained() -> None:
    payload = _json_result("NodeUse", "--verbose")

    Draft202012Validator.check_schema(payload)
    assert payload["$ref"] == "#/$defs/NodeUse"
    definitions = payload["$defs"]
    assert set(_local_refs(payload)) <= set(definitions)
    Draft202012Validator(payload).validate(
        {"id": "call", "type": "node", "node": "local.report.read_notes"}
    )


def test_schema_unknown_name_fails_with_suggestion() -> None:
    result = runner.invoke(app, ["schema", "Node"])

    assert result.exit_code != 0
    assert "unknown schema 'Node'" in result.output
    assert "NodeUse" in result.output
```

- [ ] **Step 3: Run tests to verify the prototype fails**

Run:

```powershell
uv run pytest tests/wf_cli/test_schema.py tests/wf_cli/test_app.py -q
```

Expected: failures because output is Python repr, catalog listing is absent,
component verbose output is incomplete, unknown names return zero, and the old
help text was removed without replacement tests.

- [ ] **Step 4: Commit the red tests**

```powershell
git add tests/wf_cli/test_schema.py tests/wf_cli/test_app.py
git commit -m "test: define wf schema command contract"
```

### Task 2: Build The Pydantic-Backed Schema Catalog

**Files:**
- Create: `src/wf_cli/schema_catalog.py`
- Test: `tests/wf_cli/test_schema.py`

- [ ] **Step 1: Add catalog unit coverage**

Append:

```python
from wf_cli.schema_catalog import schema_catalog


def test_schema_catalog_resolves_aliases_and_components() -> None:
    catalog = schema_catalog()

    assert catalog.resolve("raw") == "RawWorkflowPlan"
    assert catalog.resolve("RawWorkflowPlan") == "RawWorkflowPlan"
    assert catalog.resolve("NodeUse") == "NodeUse"
    assert catalog.entry("draft").kind == "root"
    assert catalog.entry("NodeUse").kind == "definition"
```

- [ ] **Step 2: Run the catalog test and confirm it fails**

```powershell
uv run pytest tests/wf_cli/test_schema.py::test_schema_catalog_resolves_aliases_and_components -q
```

Expected: import failure for `wf_cli.schema_catalog`.

- [ ] **Step 3: Implement catalog construction**

Create `src/wf_cli/schema_catalog.py` with these public types and functions:

```python
from __future__ import annotations

from copy import deepcopy
from dataclasses import dataclass
from difflib import get_close_matches
from functools import cache
from typing import Any, TypeAlias

from jsonschema import Draft202012Validator
from pydantic import TypeAdapter

from wf_api.models import RawWorkflowPlan
from wf_artifacts.drafts.models import WorkflowDraft
from wf_core.models.workflow import Workflow


JsonObject: TypeAlias = dict[str, Any]
SCHEMA_DIALECT = Draft202012Validator.META_SCHEMA["$id"]
ROOT_MODELS: dict[str, type[Any]] = {
    "WorkflowDraft": WorkflowDraft,
    "RawWorkflowPlan": RawWorkflowPlan,
    "Workflow": Workflow,
}
ALIASES = {
    "draft": "WorkflowDraft",
    "raw": "RawWorkflowPlan",
    "core": "Workflow",
}


@dataclass(frozen=True, slots=True)
class SchemaEntry:
    name: str
    aliases: tuple[str, ...]
    kind: str
    description: str | None


@dataclass(frozen=True, slots=True)
class SchemaCatalog:
    roots: dict[str, JsonObject]
    definitions: dict[str, JsonObject]
    aliases: dict[str, str]

    def resolve(self, name: str) -> str:
        canonical = self.aliases.get(name, name)
        if canonical in self.roots or canonical in self.definitions:
            return canonical
        choices = sorted({*self.aliases, *self.roots, *self.definitions})
        suggestion = get_close_matches(name, choices, n=1)
        message = f"unknown schema {name!r}"
        if suggestion:
            message += f". Did you mean {suggestion[0]!r}?"
        raise KeyError(message)

    def schema(self, name: str) -> JsonObject:
        canonical = self.resolve(name)
        source = self.roots.get(canonical, self.definitions.get(canonical))
        if source is None:  # defensive: resolve already checked this
            raise KeyError(canonical)
        return deepcopy(source)

    def entry(self, name: str) -> SchemaEntry:
        canonical = self.resolve(name)
        schema = self.schema(canonical)
        aliases = tuple(sorted(alias for alias, target in self.aliases.items() if target == canonical))
        return SchemaEntry(
            name=canonical,
            aliases=aliases,
            kind="root" if canonical in self.roots else "definition",
            description=schema.get("description"),
        )

    def entries(self) -> list[SchemaEntry]:
        names = sorted({*self.roots, *self.definitions})
        return [self.entry(name) for name in names]


@cache
def schema_catalog() -> SchemaCatalog:
    roots = {
        name: TypeAdapter(model).json_schema(mode="validation", by_alias=True)
        for name, model in ROOT_MODELS.items()
    }
    combined = TypeAdapter(WorkflowDraft | RawWorkflowPlan | Workflow).json_schema(
        mode="validation", by_alias=True
    )
    raw_definitions = combined.get("$defs", {})
    if not isinstance(raw_definitions, dict):
        raise RuntimeError("combined workflow schema has no object $defs table")
    definitions = {name: deepcopy(value) for name, value in raw_definitions.items()}
    for root in roots.values():
        root_definitions = root.get("$defs", {})
        if not isinstance(root_definitions, dict):
            raise RuntimeError("workflow root schema has non-object $defs")
        for name, value in root_definitions.items():
            existing = definitions.get(name)
            if existing is not None and existing != value:
                raise RuntimeError(f"conflicting workflow schema definition: {name}")
            definitions.setdefault(name, deepcopy(value))
    return SchemaCatalog(roots=roots, definitions=definitions, aliases=dict(ALIASES))
```

- [ ] **Step 4: Run catalog tests**

```powershell
uv run pytest tests/wf_cli/test_schema.py::test_schema_catalog_resolves_aliases_and_components -q
```

Expected: pass.

- [ ] **Step 5: Commit the catalog**

```powershell
git add src/wf_cli/schema_catalog.py tests/wf_cli/test_schema.py
git commit -m "feat: add workflow schema catalog"
```

### Task 3: Implement Compact Outlines And Verbose Documents

**Files:**
- Modify: `src/wf_cli/schema_catalog.py`
- Test: `tests/wf_cli/test_schema.py`

- [ ] **Step 1: Add projection and verbose helper tests**

Append:

```python
from wf_cli.schema_catalog import compact_schema_outline, verbose_schema_document


def test_compact_outline_replaces_local_refs_with_names() -> None:
    payload = compact_schema_outline("NodeUse")

    assert payload["properties"]["input"]["items"]["one_of"] == [
        "InputPathBinding",
        "InputValueBinding",
    ]
    assert "$ref" not in json.dumps(payload)


def test_verbose_component_uses_generated_definitions() -> None:
    payload = verbose_schema_document("NodeUse")

    assert payload["$schema"] == Draft202012Validator.META_SCHEMA["$id"]
    assert payload["$ref"] == "#/$defs/NodeUse"
    assert "InputPathBinding" in payload["$defs"]
```

- [ ] **Step 2: Run and confirm helper tests fail**

```powershell
uv run pytest tests/wf_cli/test_schema.py -k "compact_outline or verbose_component_uses" -q
```

Expected: import failures for the helpers.

- [ ] **Step 3: Add compact projection**

Append to `schema_catalog.py`:

```python
PRESENTATION_KEYS = (
    "type",
    "description",
    "default",
    "enum",
    "const",
    "minimum",
    "maximum",
    "exclusiveMinimum",
    "exclusiveMaximum",
    "minLength",
    "maxLength",
    "minItems",
    "maxItems",
)


def _ref_name(ref: str) -> str:
    prefix = "#/$defs/"
    if not ref.startswith(prefix):
        return ref
    return ref.removeprefix(prefix)


def _compact_node(schema: object, related: set[str]) -> object:
    if not isinstance(schema, dict):
        return deepcopy(schema)
    ref = schema.get("$ref")
    if isinstance(ref, str):
        name = _ref_name(ref)
        if name != ref:
            related.add(name)
        return name

    result: JsonObject = {}
    for key in PRESENTATION_KEYS:
        if key in schema:
            result[key] = deepcopy(schema[key])
    required = schema.get("required")
    if isinstance(required, list):
        result["required"] = deepcopy(required)
    properties = schema.get("properties")
    if isinstance(properties, dict):
        result["properties"] = {
            name: _compact_node(value, related)
            for name, value in properties.items()
        }
    if "items" in schema:
        result["items"] = _compact_node(schema["items"], related)
    for source_key in ("oneOf", "anyOf"):
        branches = schema.get(source_key)
        if not isinstance(branches, list):
            continue
        result["one_of"] = [_compact_node(branch, related) for branch in branches]
        break
    discriminator = schema.get("discriminator")
    if isinstance(discriminator, dict) and isinstance(discriminator.get("propertyName"), str):
        result["discriminator"] = discriminator["propertyName"]
    return result


def compact_schema_outline(name: str) -> JsonObject:
    catalog = schema_catalog()
    canonical = catalog.resolve(name)
    schema = catalog.schema(canonical)
    related: set[str] = set()
    body = _compact_node(schema, related)
    if not isinstance(body, dict):
        body = {"schema": body}
    return {
        "name": canonical,
        "kind": "schema_outline",
        **body,
        "related": sorted(related - {canonical}),
        "full_schema_command": f"wf schema {name} --verbose",
    }
```

- [ ] **Step 4: Add verbose document construction**

Append:

```python
def verbose_schema_document(name: str) -> JsonObject:
    catalog = schema_catalog()
    canonical = catalog.resolve(name)
    if canonical in catalog.roots:
        document = catalog.schema(canonical)
        document.setdefault("$schema", SCHEMA_DIALECT)
    else:
        document = {
            "$schema": SCHEMA_DIALECT,
            "$ref": f"#/$defs/{canonical}",
            "$defs": deepcopy(catalog.definitions),
        }
    Draft202012Validator.check_schema(document)
    return document


def schema_catalog_payload() -> JsonObject:
    return {
        "schemas": [
            {
                "name": entry.name,
                "aliases": list(entry.aliases),
                "kind": entry.kind,
                "description": entry.description,
            }
            for entry in schema_catalog().entries()
        ]
    }
```

- [ ] **Step 5: Run helper tests**

```powershell
uv run pytest tests/wf_cli/test_schema.py -k "compact or verbose or catalog" -q
```

Expected: helper-level tests pass; CLI tests may still fail until Task 4.

- [ ] **Step 6: Commit projection helpers**

```powershell
git add src/wf_cli/schema_catalog.py tests/wf_cli/test_schema.py
git commit -m "feat: project compact and verbose workflow schemas"
```

### Task 4: Wire The Typer Command

**Files:**
- Replace: `src/wf_cli/commands/schema.py`
- Modify: `src/wf_cli/app.py:79-84`
- Test: `tests/wf_cli/test_schema.py`
- Test: `tests/wf_cli/test_app.py`

- [ ] **Step 1: Replace the prototype command**

Replace `src/wf_cli/commands/schema.py` with:

```python
from __future__ import annotations

import typer

from wf_cli.io import emit_json
from wf_cli.schema_catalog import (
    compact_schema_outline,
    schema_catalog,
    schema_catalog_payload,
    verbose_schema_document,
)


def schema_command(
    name: str | None = typer.Argument(
        None,
        help="Schema name or alias. Omit it, or use `list`, to list names.",
    ),
    verbose: bool = typer.Option(
        False,
        "--verbose",
        "-v",
        help="Print complete valid JSON Schema; output may be large.",
    ),
) -> None:
    """Print a compact workflow schema outline or full JSON Schema."""
    if name is None or name == "list":
        emit_json(schema_catalog_payload())
        return
    try:
        schema_catalog().resolve(name)
    except KeyError as exc:
        message = exc.args[0] if exc.args else str(exc)
        raise typer.BadParameter(message, param_hint="NAME") from exc
    emit_json(
        verbose_schema_document(name)
        if verbose
        else compact_schema_outline(name)
    )
```

- [ ] **Step 2: Register no-argument catalog behavior**

In `src/wf_cli/app.py`, use:

```python
app.command("schema")(schema.schema_command)
```

Do not pass `no_args_is_help=True`; no arguments now list the catalog.

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

```powershell
uv run pytest tests/wf_cli/test_schema.py tests/wf_cli/test_app.py -q
```

Expected: all pass.

- [ ] **Step 4: Smoke the real command**

```powershell
uv run wf schema
uv run wf schema raw
uv run wf schema NodeUse
uv run wf schema raw --verbose
uv run wf schema Node
```

Expected: first four print JSON; final command exits nonzero and suggests
`NodeUse`.

- [ ] **Step 5: Commit CLI wiring**

```powershell
git add src/wf_cli/commands/schema.py src/wf_cli/app.py tests/wf_cli/test_schema.py tests/wf_cli/test_app.py
git commit -m "feat: expose workflow schema catalog in cli"
```

### Task 5: Remove Prototype Dependency And Update Agent Instructions

**Files:**
- Modify: `pyproject.toml`
- Modify: `uv.lock`
- Modify: `skills/wf-cli/SKILL.md`
- Modify: `skills/wf-workflow/references/direct-plan-import.md`
- Modify: `skills/wf-workflow/references/draft-workspaces.md`

- [ ] **Step 1: Remove `cachetools`**

Run:

```powershell
uv remove cachetools
```

Expected: `cachetools` disappears from direct project dependencies and lockfile
project metadata. It may remain transitively only if another dependency needs
it.

- [ ] **Step 2: Replace the stale CLI skill rule**

In `skills/wf-cli/SKILL.md`, replace the WIP statement with:

```markdown
- Use `wf schema` to list workflow document/component shapes.
- Use `wf schema draft`, `wf schema raw`, or `wf schema <Component>` for compact
  JSON guidance before authoring.
- Add `--verbose` only when a complete JSON Schema document is required; it may
  be large.
```

- [ ] **Step 3: Add schema discovery to draft and raw-plan references**

Near the top of `direct-plan-import.md`, add:

```markdown
Before writing a plan, inspect the current public shape:

    wf schema raw
    wf schema NodeUse
    wf schema InputPathBinding
    wf schema OutputBinding

Use `wf schema raw --verbose` only when the complete validation schema is
required.
```

Near the top of `draft-workspaces.md`, add the equivalent draft commands:

```markdown
Before writing or patching a draft, inspect the current public shape:

    wf schema draft
    wf schema DraftUseStep
```

- [ ] **Step 4: Verify user-facing skills contain no stale WIP statement**

```powershell
rg -n "empty command group|no schema subcommands|do not rely on it" skills
```

Expected: no matches referring to `wf schema`.

- [ ] **Step 5: Run focused verification**

```powershell
uv run pytest tests/wf_cli/test_schema.py tests/wf_cli/test_app.py -q
uv run ruff check src/wf_cli/schema_catalog.py src/wf_cli/commands/schema.py src/wf_cli/app.py tests/wf_cli/test_schema.py tests/wf_cli/test_app.py
uv run ruff format --check src/wf_cli/schema_catalog.py src/wf_cli/commands/schema.py src/wf_cli/app.py tests/wf_cli/test_schema.py tests/wf_cli/test_app.py
uv run basedpyright --level error src/wf_cli/schema_catalog.py src/wf_cli/commands/schema.py src/wf_cli/app.py tests/wf_cli/test_schema.py tests/wf_cli/test_app.py
git diff --check
```

Expected: tests pass, lint/typecheck are clean, and only accepted Windows CRLF
warnings appear from `git diff --check`.

- [ ] **Step 6: Commit dependency/docs cleanup**

```powershell
git add pyproject.toml uv.lock skills/wf-cli/SKILL.md skills/wf-workflow/references/direct-plan-import.md skills/wf-workflow/references/draft-workspaces.md
git commit -m "docs: teach agents workflow schema discovery"
```

### Task 6: Final Review And Plan Archive

**Files:**
- Modify: `docs/current_roadmap.md`
- Move after completion: `docs/superpowers/plans/2026-06-22-wf-schema-command.md` to `docs/historical/superpowers/plans/2026-06-22-wf-schema-command.md`

- [ ] **Step 1: Add the completed roadmap note**

Add under the current product/agent UX milestones:

```markdown
- Completed: `wf schema` now lists workflow document/component models, emits
  compact JSON outlines for agent discovery, and emits valid self-contained
  JSON Schema with `--verbose`.
```

- [ ] **Step 2: Run the complete focused test command once more**

```powershell
uv run pytest tests/wf_cli/test_schema.py tests/wf_cli/test_app.py -q
```

Expected: all pass.

- [ ] **Step 3: Move the completed plan to historical docs**

```powershell
New-Item -ItemType Directory -Force docs/historical/superpowers/plans | Out-Null
Move-Item docs/superpowers/plans/2026-06-22-wf-schema-command.md docs/historical/superpowers/plans/2026-06-22-wf-schema-command.md
```

- [ ] **Step 4: Commit roadmap and archive**

```powershell
git add docs/current_roadmap.md docs/superpowers/plans/2026-06-22-wf-schema-command.md docs/historical/superpowers/plans/2026-06-22-wf-schema-command.md
git commit -m "docs: record wf schema command completion"
```