# Wrapper Draft Next Actions 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:** Add advisory `next_actions` to `wf.workflow.create_draft_workspace_from_capability` so LLM clients can continue safely even when they cannot easily read the docs.

**Architecture:** Keep `wrapper_hints` as the source of truth for scaffold confidence, missing decisions, and mapping warnings. Add a small typed result object that converts those hints into concrete next-tool guidance. `can_save_now` is advisory only; do not block saving or enforce policy in this slice.

**Tech Stack:** Python 3.14, Pydantic v2, FastMCP tool schemas, pytest, ruff, basedpyright.

---

## Scope

Add `next_actions` to `CreateDraftWorkspaceFromCapabilityResult` and handler payloads.

Do:

- Return machine-readable guidance from `create_draft_workspace_from_capability`.
- Make `can_save_now` advisory only.
- Recommend `wf.workflow.patch_draft_workspace` when `wrapper_hints.missing_decisions` is non-empty or confidence is low.
- Recommend `wf.workflow.validate_draft_workspace` when the scaffold looks safe enough to validate.
- Include patch examples for common missing decisions.
- Document the field and add schema tests.

Do not:

- Block `create_artifact_from_workspace`.
- Add a new tool.
- Infer raw MCP `content[0].text` automatically.
- Treat boolean output candidates as real routing semantics.
- Replace `wrapper_hints`; `next_actions` should summarize and guide, not duplicate every hint.

## Files

- Modify: `src/wf_mcp/workflow_surface/models.py`
  - Add typed `WrapperDraftNextActions` and `WrapperDraftPatchExample` Pydantic models.
  - Add `next_actions` field to `CreateDraftWorkspaceFromCapabilityResult`.
- Modify: `src/wf_mcp/workflow_surface/handlers.py`
  - Add helper that derives `next_actions` from `wrapper_hints` and workspace id/revision.
  - Include `next_actions` in `create_draft_workspace_from_capability` result.
- Test: `tests/wf_mcp/workflow_surface/test_drafts.py`
  - Assert high-confidence draft returns validate/save guidance.
  - Assert low-confidence content-block draft returns patch guidance and advisory `can_save_now=false`.
- Test: `tests/wf_mcp/server/test_config.py`
  - Assert output schema exposes `next_actions` with field descriptions.
- Modify: `docs/workflow_capabilities.md`
  - Explain `next_actions` as advisory continuation hints.
- Modify: `docs/wf_mcp_end_to_end_runbook.md`
  - Mention that clients can follow `next_actions` after draft creation.

## Data Shape

Add this output shape:

```json
{
  "next_actions": {
    "can_save_now": true,
    "recommended_next_tool": "wf.workflow.validate_draft_workspace",
    "reason": "Wrapper hints are high confidence and have no missing decisions.",
    "patch_examples": [],
    "warnings": []
  }
}
```

Low-confidence example:

```json
{
  "next_actions": {
    "can_save_now": false,
    "recommended_next_tool": "wf.workflow.patch_draft_workspace",
    "reason": "Review missing wrapper decisions before saving.",
    "patch_examples": [
      {
        "description": "Replace the output bindings after choosing workflow state fields.",
        "tool": "wf.workflow.patch_draft_workspace",
        "request": {
          "workspace_id": "echo_wrapper",
          "revision": 1,
          "patch": [
            {
              "op": "replace",
              "path": "/draft/steps/call/output",
              "value": []
            }
          ]
        }
      }
    ],
    "warnings": [
      "Raw MCP content blocks are not workflow-shaped. Use an explicit wrapper or extraction node."
    ]
  }
}
```

## Task 1: Add Result Models And Schema Test

**Files:**

- Modify: `src/wf_mcp/workflow_surface/models.py`
- Modify: `tests/wf_mcp/server/test_config.py`

- [ ] **Step 1: Add failing schema assertions**

In `tests/wf_mcp/server/test_config.py`, inside the test that already inspects `create_draft_workspace_from_capability` output schema, add:

```python
assert "next_actions" in from_capability_output["properties"]
next_actions_schema = from_capability_output["properties"]["next_actions"]
assert "recommended_next_tool" in next_actions_schema["properties"]
assert "patch_examples" in next_actions_schema["properties"]
assert "advisory" in next_actions_schema["properties"]["can_save_now"]["description"]
```

Run:

```powershell
uv run pytest tests/wf_mcp/server/test_config.py -q
```

Expected: fail because `next_actions` is not in the output schema.

- [ ] **Step 2: Add Pydantic result models**

In `src/wf_mcp/workflow_surface/models.py`, add near `CreateDraftWorkspaceFromCapabilityResult`:

```python
class WrapperDraftPatchExample(BaseModel):
    """Concrete patch-workspace example for a likely next authoring edit."""

    description: str = Field(description="Human-readable reason for this patch.")
    tool: str = Field(description="MCP tool to call for this example.")
    request: dict[str, Any] = Field(
        description="JSON request payload to pass to the tool."
    )


class WrapperDraftNextActions(BaseModel):
    """Advisory continuation hints after bootstrapping a wrapper draft."""

    can_save_now: bool = Field(
        description=(
            "Advisory only. False means the scaffold likely needs review before "
            "saving, but the server does not enforce this."
        )
    )
    recommended_next_tool: str = Field(
        description=(
            "Suggested next MCP tool, usually wf.workflow.validate_draft_workspace "
            "or wf.workflow.patch_draft_workspace."
        )
    )
    reason: str = Field(description="Short explanation for the recommendation.")
    patch_examples: list[WrapperDraftPatchExample] = Field(
        default_factory=list,
        description="Concrete JSON Patch examples for common missing decisions.",
    )
    warnings: list[str] = Field(
        default_factory=list,
        description="Non-blocking warnings copied from low-confidence wrapper hints.",
    )
```

Then update:

```python
class CreateDraftWorkspaceFromCapabilityResult(DraftWorkspaceResult):
    """Draft workspace result plus wrapper hints and advisory next actions."""

    wrapper_hints: dict[str, Any] = Field(...)
    next_actions: WrapperDraftNextActions = Field(
        description=(
            "Advisory next step guidance derived from wrapper_hints. "
            "The server does not enforce can_save_now."
        )
    )
```

- [ ] **Step 3: Run schema test**

Run:

```powershell
uv run pytest tests/wf_mcp/server/test_config.py -q
```

Expected: schema assertion passes, but runtime tests may still fail later until handler returns `next_actions`.

## Task 2: Derive Next Actions In The Handler

**Files:**

- Modify: `src/wf_mcp/workflow_surface/handlers.py`
- Modify: `tests/wf_mcp/workflow_surface/test_drafts.py`

- [ ] **Step 1: Add high-confidence behavior test**

In `tests/wf_mcp/workflow_surface/test_drafts.py`, extend `test_workflow_surface_creates_draft_workspace_from_capability_hints`:

```python
next_actions = result["next_actions"]
assert next_actions["can_save_now"] is True
assert next_actions["recommended_next_tool"] == "wf.workflow.validate_draft_workspace"
assert "high confidence" in next_actions["reason"]
assert next_actions["patch_examples"] == []
assert next_actions["warnings"] == []
```

Run:

```powershell
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py::test_workflow_surface_creates_draft_workspace_from_capability_hints -q
```

Expected: fail because handler does not return `next_actions`.

- [ ] **Step 2: Add low-confidence behavior test**

Find or create a content-block capability test near existing wrapper hint tests. Use an output schema shaped like:

```python
content_output_schema = {
    "type": "object",
    "properties": {
        "content": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "type": {"type": "string"},
                    "text": {"type": "string"},
                },
            },
        }
    },
}
```

Register a NodeSpec/capability with that output schema, call `create_draft_workspace_from_capability`, then assert:

```python
next_actions = result["next_actions"]
assert next_actions["can_save_now"] is False
assert next_actions["recommended_next_tool"] == "wf.workflow.patch_draft_workspace"
assert "missing wrapper decisions" in next_actions["reason"]
assert next_actions["patch_examples"][0]["tool"] == "wf.workflow.patch_draft_workspace"
assert next_actions["patch_examples"][0]["request"]["workspace_id"] == "content_wrapper"
assert next_actions["patch_examples"][0]["request"]["revision"] == result["revision"]
assert next_actions["warnings"]
```

Run:

```powershell
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py -q
```

Expected: fail until implementation exists.

- [ ] **Step 3: Implement helper in handler**

In `src/wf_mcp/workflow_surface/handlers.py`, add a helper near other draft helpers:

```python
def _wrapper_draft_next_actions(
    *,
    workspace_id: str,
    revision: int,
    hints: dict[str, Any],
) -> dict[str, Any]:
    """Convert wrapper_hints into advisory next-tool guidance for MCP clients."""
    confidence = str(hints.get("confidence", "low"))
    missing_decisions = hints.get("missing_decisions")
    notes = [str(note) for note in hints.get("notes", []) if isinstance(note, str)]
    has_missing = isinstance(missing_decisions, list) and len(missing_decisions) > 0
    can_save_now = confidence == "high" and not has_missing
    if can_save_now:
        return {
            "can_save_now": True,
            "recommended_next_tool": "wf.workflow.validate_draft_workspace",
            "reason": "Wrapper hints are high confidence and have no missing decisions.",
            "patch_examples": [],
            "warnings": [],
        }

    return {
        "can_save_now": False,
        "recommended_next_tool": "wf.workflow.patch_draft_workspace",
        "reason": "Review missing wrapper decisions before saving.",
        "patch_examples": _wrapper_draft_patch_examples(
            workspace_id=workspace_id,
            revision=revision,
            hints=hints,
        ),
        "warnings": notes,
    }
```

Add:

```python
def _wrapper_draft_patch_examples(
    *,
    workspace_id: str,
    revision: int,
    hints: dict[str, Any],
) -> list[dict[str, Any]]:
    """Return conservative JSON Patch examples without guessing semantics."""
    examples: list[dict[str, Any]] = []
    missing_decisions = hints.get("missing_decisions")
    if not isinstance(missing_decisions, list):
        return examples
    decision_kinds = {
        str(decision.get("kind"))
        for decision in missing_decisions
        if isinstance(decision, dict)
    }
    if {
        "choose_output_fields",
        "review_nested_output",
    } & decision_kinds:
        examples.append(
            {
                "description": (
                    "Replace output bindings after choosing which capability "
                    "outputs should be written to workflow state."
                ),
                "tool": "wf.workflow.patch_draft_workspace",
                "request": {
                    "workspace_id": workspace_id,
                    "revision": revision,
                    "patch": [
                        {
                            "op": "replace",
                            "path": "/draft/steps/call/output",
                            "value": [],
                        }
                    ],
                },
            }
        )
    if "confirm_boolean_outcomes" in decision_kinds:
        examples.append(
            {
                "description": (
                    "Review boolean output candidates before adding routing; "
                    "do not route on boolean fields automatically."
                ),
                "tool": "wf.workflow.patch_draft_workspace",
                "request": {
                    "workspace_id": workspace_id,
                    "revision": revision,
                    "patch": [],
                },
            }
        )
    return examples
```

Then change the return in `create_draft_workspace_from_capability`:

```python
return {
    **result,
    "wrapper_hints": hints,
    "next_actions": _wrapper_draft_next_actions(
        workspace_id=workspace_id,
        revision=int(result["revision"]),
        hints=hints,
    ),
}
```

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

Run:

```powershell
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py -q
```

Expected: pass.

## Task 3: Document Next Actions

**Files:**

- Modify: `docs/workflow_capabilities.md`
- Modify: `docs/wf_mcp_end_to_end_runbook.md`

- [ ] **Step 1: Update workflow capability docs**

In `docs/workflow_capabilities.md`, near the `wrapper_hints` section, add:

```markdown
`create_draft_workspace_from_capability` also returns `next_actions`.
This is advisory guidance for clients that cannot easily read the full docs.
It summarizes whether the scaffold is safe-looking enough to validate, which
tool to call next, and concrete patch examples for common missing decisions.

`next_actions.can_save_now` is not enforced. A caller can still save a low
confidence draft, but the field exists to make that risk explicit.
```

- [ ] **Step 2: Update runbook**

In `docs/wf_mcp_end_to_end_runbook.md`, near the draft-from-capability example, add:

```markdown
After `create_draft_workspace_from_capability`, inspect `next_actions`.
If `recommended_next_tool` is `wf.workflow.patch_draft_workspace`, apply or
adapt the returned `patch_examples` before saving. If it recommends
`wf.workflow.validate_draft_workspace`, validate the draft before creating an
artifact.
```

- [ ] **Step 3: Grep docs**

Run:

```powershell
rg -n "next_actions|can_save_now|patch_examples" docs/workflow_capabilities.md docs/wf_mcp_end_to_end_runbook.md
```

Expected: all three terms appear.

## Task 4: Final Verification

**Files:**

- All touched files.

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

Run:

```powershell
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py tests/wf_mcp/test_workflow_wrapper_hints.py -q
```

Expected: pass.

- [ ] **Step 2: Run touched-file lint and format check**

Run:

```powershell
uv run ruff check src/wf_mcp/workflow_surface/models.py src/wf_mcp/workflow_surface/handlers.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py
uv run ruff format --check src/wf_mcp/workflow_surface/models.py src/wf_mcp/workflow_surface/handlers.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py
```

Expected: pass.

- [ ] **Step 3: Run touched-file type check**

Run:

```powershell
uv run basedpyright --level error src/wf_mcp/workflow_surface/models.py src/wf_mcp/workflow_surface/handlers.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py
```

Expected: `0 errors`.

- [ ] **Step 4: Optional full suite**

Run when time allows:

```powershell
uv run pytest -q
```

Expected current baseline: full suite passes with the existing skip/xfail count.

## Notes For Opencode

- `can_save_now` is advisory. Do not enforce it.
- Do not add a new save gate.
- Do not generate semantic routes from boolean fields.
- Keep patch examples conservative; empty patch examples are acceptable when the missing decision cannot be safely represented.
- Avoid whole-dict assertions. Assert individual fields.
- Existing docs may be long; keep additions short.