docs: complete draft lifecycle authoring

ISSUES.md

@@ -35,19 +35,15 @@
 
 ## Draft workspace lifecycle parity
 
-- [ ] No capability-free draft workspace creation is exposed through the
+- [x] Capability-free draft workspace creation is exposed through the
-  transport-facing API, JSON-RPC, or CLI. Control-first, interrupt-first, and
+  transport-facing API, JSON-RPC, and CLI for control-first, interrupt-first,
-  subgraph-first workflows must bootstrap from an unrelated capability or be
+  end-first, and subgraph-first authoring.
-  created through a lower-level raw document path.
+- [x] A focused revision-checked operation changes the draft entry point
-- [ ] No focused operation changes the draft entry point. `WorkflowBuilder`
+  without patching `/start` directly.
-  exposes `set_entry_point`, while workspace callers must patch `/start`
+- [x] A focused contract operation replaces the complete declared workflow
-  directly after replacing the bootstrap step.
+  outcomes list.
-- [ ] No focused operation declares workflow outcomes. `wf draft add end
+- [x] A focused contract operation replaces workflow input/state/output
-  --outcome error` can add the terminal node, but core validation rejects it
+  schemas, preserving reducer metadata carried by the supplied state schema.
-  until the caller separately patches `/outcomes`.
-- [ ] No focused operation updates workflow input/state/output schemas,
-  including reducer metadata carried by the state schema, after workspace
-  creation. These modeled workflow contracts currently require RFC 6902 edits.
 - [ ] The dedicated capability-step CLI cannot set `desc`, `retry`,
   `timeout_seconds`, or literal inputs at creation, and there is no focused
   update-step operation. The generic RPC step payload can represent these

docs/current_roadmap.md

@@ -539,6 +539,11 @@ clear operator feedback before adding more architecture.
 - Completed: focused draft edit helpers are exposed through RPC/CLI, and
   `wf deploy create` is accepted as an alias for `wf deploy save`. Docs now
   distinguish draft shape from raw plan shape for agent authoring.
+- Completed: capability-free draft lifecycle authoring now spans the Python
+  API, JSON-RPC, remote client, and `wf` CLI. Callers can create an empty
+  revisioned workspace, set its entry point, and replace whole workflow
+  schemas or outcomes without RFC 6902 patches. Implementation:
+  [`draft workspace lifecycle authoring`](historical/superpowers/plans/2026-07-21-draft-workspace-lifecycle-authoring.md).
 - Completed: `wf draft set-input` and `wf draft set-output` now accept
   `--merge`, preserving existing bindings when agents split map edits across
   multiple revisions.

docs/historical/superpowers/plans/2026-07-21-draft-workspace-lifecycle-authoring.md

@@ -60,7 +60,7 @@
 - Produces: `WorkflowDraftSurface.set_draft_contract(...)`.
 - Consumes: existing `WorkflowDraftApi.create_draft_workspace` and `patch_draft_workspace` revision semantics.
 
-- [ ] **Step 1: Write failing empty-workspace API tests**
+- [x] **Step 1: Write failing empty-workspace API tests**
 
 Add tests using `_draft_api(...)`, then construct the facade explicitly with
 `facade = WorkflowApi(authoring.context)`. Pin the complete stored shape, not
@@ -95,7 +95,7 @@ assert stored["draft"] == {
 
 Add a second test with custom schemas, ordered outcomes, reducer metadata under a state property, and title. Assert the stored payload equals the supplied dictionaries. Mutate one original schema after creation and assert the other defaults/stored schemas did not change.
 
-- [ ] **Step 2: Write failing conflict and envelope-validation tests**
+- [x] **Step 2: Write failing conflict and envelope-validation tests**
 
 Cover:
 
@@ -107,7 +107,7 @@ Cover:
 
 For each rejected envelope, assert `list_draft_workspaces()` remains empty.
 
-- [ ] **Step 3: Write failing start and contract edit tests**
+- [x] **Step 3: Write failing start and contract edit tests**
 
 Cover these behaviors:
 
@@ -142,7 +142,7 @@ Fetch the full draft and assert input schema is unchanged, supplied fields are c
 Use otherwise-valid stale requests in those two tests. Invalid request
 envelopes are expected to fail before revision lookup.
 
-- [ ] **Step 4: Run the focused API tests and confirm red**
+- [x] **Step 4: Run the focused API tests and confirm red**
 
 Run:
 
@@ -152,7 +152,7 @@ uv run pytest tests/wf_api/test_drafts_service.py -q
 
 Expected: new tests fail because `WorkflowApi` and `WorkflowDraftSurface` do not expose the three lifecycle methods.
 
-- [ ] **Step 5: Implement lifecycle validation and mutation in `WorkflowDraftApi`**
+- [x] **Step 5: Implement lifecycle validation and mutation in `WorkflowDraftApi`**
 
 Add small private helpers in `src/wf_api/drafts.py`:
 
@@ -202,11 +202,11 @@ if not patch:
 return await self.patch_draft_workspace(..., patch=patch)
 ```
 
-- [ ] **Step 6: Expose exact delegation through `WorkflowApi` and `WorkflowDraftSurface`**
+- [x] **Step 6: Expose exact delegation through `WorkflowApi` and `WorkflowDraftSurface`**
 
 Add all three signatures from the design to the protocol and facade. Use `Sequence[str]` in Python interfaces; convert only at serialization/storage seams. Keep method names identical across concrete and protocol types.
 
-- [ ] **Step 7: Verify and commit Task 1**
+- [x] **Step 7: Verify and commit Task 1**
 
 Run:
 
@@ -239,7 +239,7 @@ git commit -m "feat: add draft lifecycle authoring operations"
 - Produces: `CreateEmptyDraftWorkspaceParams`, `SetDraftStartParams`, and `SetDraftContractParams`.
 - Produces: JSON-RPC methods `workflow.draft_workspaces.create_empty`, `.set_start`, and `.set_contract`.
 
-- [ ] **Step 1: Write failing RPC registration and dispatch tests**
+- [x] **Step 1: Write failing RPC registration and dispatch tests**
 
 Extend the draft RPC app tests to call:
 
@@ -264,7 +264,7 @@ contracted = await _rpc(client, "workflow.draft_workspaces.set_contract", {
 
 Assert method results use revisions 1, 2, and 3; creation and the forward start are invalid but persisted; inspection shows the replaced contract.
 
-- [ ] **Step 2: Write failing RPC envelope tests**
+- [x] **Step 2: Write failing RPC envelope tests**
 
 Use `_rpc` to submit:
 
@@ -276,7 +276,7 @@ Use `_rpc` to submit:
 
 Assert each returns a JSON-RPC parameter/error response and inspection proves the workspace revision did not change.
 
-- [ ] **Step 3: Run the focused server tests and confirm red**
+- [x] **Step 3: Run the focused server tests and confirm red**
 
 Run:
 
@@ -286,7 +286,7 @@ uv run pytest tests/wf_transport_rpc_http/test_app.py -q
 
 Expected: unknown-method failures for the three new method names.
 
-- [ ] **Step 4: Implement typed request models**
+- [x] **Step 4: Implement typed request models**
 
 In `models.py`, import `Self` from `typing`, then add Pydantic request models
 with `Field(min_length=1)` for ids/names, `revision >= 1`, optional schema
@@ -318,14 +318,14 @@ class SetDraftContractParams(RpcParamsModel):
 
 Use a shared local outcome validator for create and set-contract request models. The API repeats validation deliberately because same-process callers do not pass through Pydantic RPC models.
 
-- [ ] **Step 5: Register three thin server methods**
+- [x] **Step 5: Register three thin server methods**
 
 Import the models in `methods/drafts.py`. Each handler catches the same expected exception set as neighboring draft methods and delegates exact fields to `server.api` without rebuilding draft JSON inside the transport adapter.
 
 Re-export the three request models from `wf_transport_rpc_http.__init__` and add
 them to `__all__`, matching the package's existing public DTO convention.
 
-- [ ] **Step 6: Verify and commit Task 2**
+- [x] **Step 6: Verify and commit Task 2**
 
 Run:
 
@@ -355,7 +355,7 @@ git commit -m "feat: expose draft lifecycle rpc methods"
 - Consumes: the JSON-RPC methods from Task 2.
 - Produces: `RpcDraftClientMixin` implementations satisfying the expanded `WorkflowDraftSurface`.
 
-- [ ] **Step 1: Write failing request-payload tests**
+- [x] **Step 1: Write failing request-payload tests**
 
 Follow the existing lightweight recording-client pattern and assert exact methods and params for all three calls. Pin that tuples become ordered JSON lists:
 
@@ -373,7 +373,7 @@ assert request == {
 }
 ```
 
-- [ ] **Step 2: Write the failing complete remote lifecycle test**
+- [x] **Step 2: Write the failing complete remote lifecycle test**
 
 Against an in-process `create_rpc_app(server)` and real `RpcWorkflowApiClient`:
 
@@ -388,7 +388,7 @@ Assert the final validation result is valid, revision increased exactly once per
 edit, `compile_draft_workspace()` returns a compiled plan whose start is `gate`,
 and an inspected full draft contains no capability bootstrap step.
 
-- [ ] **Step 3: Run client tests and confirm red**
+- [x] **Step 3: Run client tests and confirm red**
 
 Run:
 
@@ -398,11 +398,11 @@ uv run pytest tests/wf_transport_rpc_http/test_client.py -q
 
 Expected: static protocol shape/type failures or missing client methods.
 
-- [ ] **Step 4: Implement the remote mixin methods**
+- [x] **Step 4: Implement the remote mixin methods**
 
 Add direct `_call(...)` methods adjacent to capability-backed creation and existing focused setters. Serialize `Sequence[str]` using `list(outcomes)` and include all optional contract keys explicitly, matching existing client payload conventions.
 
-- [ ] **Step 5: Verify static surface parity and commit Task 3**
+- [x] **Step 5: Verify static surface parity and commit Task 3**
 
 Run:
 
@@ -434,7 +434,7 @@ git commit -m "feat: add remote draft lifecycle client"
 - Consumes: the expanded `WorkflowDraftSurface` implemented locally and remotely.
 - Produces: dual-mode `wf draft create`, `wf draft set-start`, and `wf draft set-contract`.
 
-- [ ] **Step 1: Write failing help and handler-dispatch tests**
+- [x] **Step 1: Write failing help and handler-dispatch tests**
 
 Update create help expectations and add new help tests. Pin these options:
 
@@ -452,7 +452,7 @@ Use fake handlers to assert:
 - set-start forwards workspace/revision/step;
 - set-contract preserves omitted fields as `None` and passes ordered outcomes.
 
-- [ ] **Step 2: Write failing CLI validation tests**
+- [x] **Step 2: Write failing CLI validation tests**
 
 Cover:
 
@@ -465,7 +465,7 @@ Cover:
 
 Assert concise Click/Typer parameter errors and assert fake handlers receive no call.
 
-- [ ] **Step 3: Write the failing remote CLI lifecycle test**
+- [x] **Step 3: Write the failing remote CLI lifecycle test**
 
 Use `_patch_rpc_client_to_server` and the `--url http://test/rpc` pattern. Run:
 
@@ -480,7 +480,7 @@ wf draft validate control_ws
 
 Assert every command succeeds, final status is valid, final revision is 5, start is `gate`, outcomes are `['error']`, and steps contain exactly `gate` and `finish`.
 
-- [ ] **Step 4: Run CLI tests and confirm red**
+- [x] **Step 4: Run CLI tests and confirm red**
 
 Run:
 
@@ -490,7 +490,7 @@ uv run pytest tests/wf_cli/test_app.py tests/wf_cli/test_remote_target.py -q
 
 Expected: missing options/commands and missing handler-method failures.
 
-- [ ] **Step 5: Add a reusable JSON-object file parser**
+- [x] **Step 5: Add a reusable JSON-object file parser**
 
 Build on `parse_json_file` in `draft_options.py`:
 
@@ -505,7 +505,7 @@ def parse_json_object_file(path: Path, *, option_name: str) -> dict[str, Any]:
 
 Do not add schema merging or JSON Schema semantic validation in the CLI.
 
-- [ ] **Step 6: Implement dual-mode create**
+- [x] **Step 6: Implement dual-mode create**
 
 Rename the Python function from `create_from_capability` to `create_draft`. Make `--capability` optional. Parse schema files only after checking mode-specific option rules:
 
@@ -527,11 +527,11 @@ else:
 
 Keep loading the protocol-neutral CLI context so both branches work locally and remotely.
 
-- [ ] **Step 7: Implement `set-start` and `set-contract`**
+- [x] **Step 7: Implement `set-start` and `set-contract`**
 
 Add adjacent focused commands. Reject duplicate/blank outcomes at the CLI edge for concise feedback, while preserving API/RPC validation. `set-contract` must reject an empty option set before loading the context. Pass complete schema dictionaries and `tuple(outcomes)` to the surface.
 
-- [ ] **Step 8: Verify and commit Task 4**
+- [x] **Step 8: Verify and commit Task 4**
 
 Run:
 
@@ -565,7 +565,7 @@ git commit -m "feat: add draft lifecycle cli commands"
 - Documents: the exact capability-free CLI lifecycle and whole-contract replacement semantics.
 - Closes: only the four implemented items under `Draft workspace lifecycle parity` for empty creation, entry point, workflow outcomes, and workflow schemas/reducer metadata.
 
-- [ ] **Step 1: Update workflow draft documentation**
+- [x] **Step 1: Update workflow draft documentation**
 
 Add a capability-free flow before the current capability bootstrap flow:
 
@@ -580,7 +580,7 @@ wf draft validate report_ws
 
 Explain that revision 1 is intentionally invalid, forward entry points persist with diagnostics, schema files replace whole schemas, and capability binding projection remains preferable when deriving selected fields from a known node contract.
 
-- [ ] **Step 2: Update both agent skills**
+- [x] **Step 2: Update both agent skills**
 
 Teach agents to choose:
 
@@ -590,7 +590,7 @@ Teach agents to choose:
 - `bind` or capability-add projection for selected node-schema fields;
 - raw patch only for field-level schema surgery not covered by focused operations.
 
-- [ ] **Step 3: Update roadmap and issues**
+- [x] **Step 3: Update roadmap and issues**
 
 Add a completed roadmap item linking to the historical plan path. Check exactly these `ISSUES.md` items:
 
@@ -601,7 +601,7 @@ Add a completed roadmap item linking to the historical plan path. Check exactly
 
 Leave step metadata, data-shaping, revision consistency, and TypeScript parity unchecked.
 
-- [ ] **Step 4: Run focused functional verification**
+- [x] **Step 4: Run focused functional verification**
 
 Run:
 
@@ -611,7 +611,7 @@ uv run pytest tests/wf_api/test_drafts_service.py tests/wf_transport_rpc_http/te
 
 Expected: all selected tests pass.
 
-- [ ] **Step 5: Run the Python quality gate**
+- [x] **Step 5: Run the Python quality gate**
 
 Run:
 
@@ -624,7 +624,7 @@ git diff --check
 
 Expected: all commands exit 0.
 
-- [ ] **Step 6: Run independent review and fix valid findings**
+- [x] **Step 6: Run independent review and fix valid findings**
 
 Review against:
 
@@ -636,7 +636,7 @@ Review against:
 
 Re-run the smallest affected test command after each fix, then repeat Steps 4 and 5.
 
-- [ ] **Step 7: Archive the completed plan and commit**
+- [x] **Step 7: Archive the completed plan and commit**
 
 Move the plan only after implementation and verification are complete:
 

docs/workflow_drafts.md

@@ -627,7 +627,45 @@ Stateless draft tools require the caller to resend the whole draft. Draft
 workspaces are the preferred LLM authoring flow when a client will patch a
 workflow over several turns.
 
-The workspace flow is:
+### Capability-Free CLI Flow
+
+Create an empty workspace when the workflow begins with control flow, an
+interrupt, an end step, or a subgraph rather than a capability:
+
+```bash
+wf draft create report_ws --name report_workflow
+wf draft add join report_ws --revision 1 --step gate --route done=finish
+wf draft set-start report_ws --revision 2 --step gate
+wf draft add end report_ws --revision 3 --step finish --outcome error
+wf draft set-contract report_ws --revision 4 --outcome error
+wf draft validate report_ws
+```
+
+Revision 1 is intentionally incomplete and therefore invalid. Draft edits
+persist representable intermediate states together with diagnostics, so an
+entry point or route may refer forward to a step that a later revision adds.
+The final validation is the gate before saving an artifact.
+
+Pass `--input-schema-file`, `--state-schema-file`, or
+`--output-schema-file` to `draft create` or `draft set-contract` when the
+workflow contract is explicit. Each file must contain one JSON object. These
+options replace the complete selected schema; repeated `--outcome` flags
+replace the complete public outcome list. State-schema replacement preserves
+JSON Schema annotations such as reducer metadata exactly as supplied.
+
+Use capability-backed creation when the first step should derive its contract
+and wrapper hints from a known capability:
+
+```bash
+wf draft create report_ws --capability local.lda_docs.read_documents
+```
+
+For selected fields from a capability contract, prefer `wf draft add
+capability` or `wf draft bind` so schema projection remains tied to that node.
+Use `set-contract` for deliberate whole-schema/outcome replacement. Reserve
+JSON Patch for field-level schema surgery that focused commands do not cover.
+
+The capability-bootstrap MCP workspace flow is:
 
 1. `wf.workflow.create_minimal_draft_workspace`
 2. `wf.workflow.get_draft_workspace`
@@ -664,6 +702,8 @@ artifact kind to `wrapper` so clients do not need to pass `kind` manually.
 For routine edits, prefer focused commands over hand-written JSON Patch:
 
 ```bash
+wf draft set-start <workspace_id> --revision <n> --step <step_id>
+wf draft set-contract <workspace_id> --revision <n> --input-schema-file input.schema.json --state-schema-file state.schema.json --output-schema-file output.schema.json --outcome ok
 wf draft set-name <workspace_id> --revision <n> --name <name>
 wf draft set-route <workspace_id> --revision <n> --step <step_id> --outcome ok --to <target_step_or___end__>
 wf draft set-input <workspace_id> --revision <n> --step <step_id> --map input.text=text

skills/wf-cli/SKILL.md

@@ -34,10 +34,13 @@ wf cap list --format ids
 wf cap inspect <capability>
 wf cap call <capability> --input '{"field":"value"}'
 
+wf draft create <workspace_id> --name <name>
 wf draft create <workspace_id> --capability <capability>
 wf draft inspect <workspace_id> --include-draft
 wf draft patch <workspace_id> --revision <n> --input-file patch.json
 wf draft set-name <workspace_id> --revision <n> --name <name>
+wf draft set-start <workspace_id> --revision <n> --step <step_id>
+wf draft set-contract <workspace_id> --revision <n> --state-schema-file state.schema.json --outcome ok --outcome error
 wf draft set-route <workspace_id> --revision <n> --step <step_id> --outcome <outcome> --to <target>
 wf draft set-input <workspace_id> --revision <n> --step <step_id> --map input.text=text
 wf draft set-input <workspace_id> --revision <n> --step <step_id> --merge --map input.other=other
@@ -51,11 +54,25 @@ wf draft compile <workspace_id>
 wf draft bind <workspace_id> --revision <n> --step <step_id> --from local.<field> --to state.<field>
 wf draft bind <workspace_id> --revision <n> --step <step_id> --from input.<field> --to local.<field>
 wf draft add capability <workspace_id> --revision <n> --step <step_id> --capability <qualified_name> --from-step <prev> --from-outcome ok --route ok=__end__ --route error=fail --input input.text=text --bind-output result=state.result
-wf draft add interrupt <workspace_id> --revision <n> --step review --kind issue_review --outcome submitted --outcome cancelled --route submitted=next --route cancelled=revise
+wf draft add interrupt <workspace_id> --revision <n> --step review --kind issue_review \
+  --request-schema-file request.schema.json --resume-schema-file resume.schema.json \
+  --outcome submitted --outcome cancelled --route submitted=next --route cancelled=revise
 wf draft add when <workspace_id> --revision <n> --step decide --condition-file condition.json --then next --otherwise revise
 wf draft validate <workspace_id>
 wf draft save <workspace_id> --artifact <artifact_id> --version <n> --title <title>
 
+Choose `draft create --capability` when the first step should derive its
+contract and wrapper hints from a known capability. Choose `draft create
+--name` for control-first, interrupt-first, end-first, or subgraph-first
+authoring. An empty draft is expected to remain invalid until its start, steps,
+routes, and contract agree.
+
+`draft set-contract` replaces each supplied top-level schema or the complete
+outcomes list; it does not deep-merge schemas. Prefer `draft bind` or `draft add
+capability` when selected fields should be projected from a known node
+contract. Use JSON Patch only for field-level schema surgery not covered by a
+focused operation.
+
 Draft creation auto-binds required capability inputs only. Optional inputs are
 reported in wrapper-hint notes; bind them explicitly only when the workflow
 should expose them. Use `wf draft bind --from input.x --to local.x` for an

skills/wf-workflow/SKILL.md

@@ -18,9 +18,13 @@ low-level escape hatch or you already have a complete compiler/generated plan.
 2. Inspect one candidate with `wf cap inspect`.
 3. Call one candidate with `wf cap call` when payload shape or upstream source
    reachability is uncertain.
-4. Create a patchable draft workspace with
+4. Create a patchable draft workspace with `wf draft create <workspace_id>
-   `wf draft create <workspace_id> --capability <qualified_name>`.
+   --capability <qualified_name>` when the first step is a known capability, or
-5. Patch targeted fields with focused draft commands or JSON Patch.
+   with `wf draft create <workspace_id> --name <name>` for a control-first,
+   interrupt-first, end-first, or subgraph-first graph.
+5. Set the entry point or whole workflow contract with `wf draft set-start` and
+   `wf draft set-contract` when needed, then patch other targeted fields with
+   focused commands or JSON Patch.
 6. Validate with `wf draft validate`.
 7. Save an artifact with `wf draft save`, or import a complete raw plan with
    `wf artifact create-from-plan`.
@@ -38,6 +42,11 @@ low-level escape hatch or you already have a complete compiler/generated plan.
 - Treat wrapper hints as scaffolding, not semantic truth.
 - Use draft workspaces for iterative authoring; avoid rewriting full drafts.
 - Prefer focused draft edit commands before hand-writing JSON Patch.
+- Treat `set-contract` schema files and repeated outcomes as whole-field
+  replacements, not merges.
+- Prefer `draft bind` or `draft add capability` when selected schema fields
+  should be projected from a known node contract. Reserve JSON Patch for
+  field-level schema surgery not covered by focused operations.
 - If a complete raw JSON/YAML plan already exists, the CLI escape hatch is
   `wf artifact create-from-plan`; do not write helper scripts that call
   internal APIs directly.