docs: clarify workflow agent skills

2026-06-16 21:16:58 +07:00
parent be2239e716
commit 64bf182d7c
7 changed files with 240 additions and 4 deletions
@@ -23,14 +23,19 @@ Canonical docs:
 - `docs/workflow_artifacts.md`
 - `docs/durable_run_operations.md`

+If the workflow object model is unclear, read
+`skills/wf-workflow/references/system-model.md` before choosing commands.
+
 ## Core Commands

 ```bash
+wf --config wf.config.json status
 wf cap list --format ids
 wf cap inspect <capability>
 wf cap call <capability> --input '{"field":"value"}'

 wf draft create-from-capability <workspace_id> <capability>
+# There is currently no `wf draft create --capability` alias.
 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>
@@ -50,6 +55,9 @@ wf run trace <run_id> --from 0 --limit 25

 ## Rules

+- Use explicit `--config <path>` for examples, challenge workspaces, and
+  non-root configs. The default is `wf.config.json` in the current working
+  directory.
 - Prefer `--input-file` for large JSON.
 - Prefer `--format ids` or `--format compact` for discovery.
 - Use `wf cap call` as a cheap smoke test before creating a draft.
@@ -61,3 +69,5 @@ wf run trace <run_id> --from 0 --limit 25
 - Do not use planning-session specs or implementation plans as user-facing runtime guidance.
 - Do not confuse draft shape with raw plan shape: drafts use `steps/routes/use`;
  raw plans use `nodes/edges/node`.
+- `wf schema` is currently only an empty command group; do not rely on it for
+  workflow plan shape until subcommands exist.
@@ -63,17 +63,22 @@ Useful patterns:

 ```bash
 # PowerShell preview
-Get-Content skills/wf-workflow/references/workflow-lifecycle.md -TotalCount 40
+Get-Content skills/wf-workflow/references/system-model.md -TotalCount 80

 # Targeted search
 rg -n "trace|resume|binding_missing|wrapper_hints" skills/wf-workflow/references
 ```

+- `references/system-model.md`: short explanation of how sources,
+  capabilities, drafts, artifacts, deployments, runs, bindings, and traces fit
+  together.
 - `references/workflow-lifecycle.md`: end-to-end lifecycle and tool order.
 - `references/capabilities-and-wrappers.md`: raw capability vs workflow
  capability, wrapper artifacts, and content-block handling.
 - `references/draft-workspaces.md`: draft shape, mappings, patches, and save
  path.
+- `references/direct-plan-import.md`: complete workflow plan JSON shape for
+  `wf artifact create-from-plan`.
 - `references/troubleshooting.md`: missing source/capability, unrunnable
  deployment, run/trace issues.

@@ -0,0 +1,128 @@
+# Direct Plan Import Reference
+
+Use direct plan import only when you already have a complete workflow plan. For
+interactive authoring, prefer draft workspaces and focused edit commands.
+
+## Command Path
+
+```bash
+wf artifact create-from-plan workflow.plan.json \
+  --artifact <artifact_id> \
+  --version 1 \
+  --title "Workflow Title" \
+  --outcome ok \
+  --binding <logical_source>=<concrete_source>
+
+wf deploy save <deployment_id> \
+  --artifact <artifact_id> \
+  --version 1 \
+  --binding <logical_source>=<concrete_source>
+
+wf deploy validate <deployment_id>
+wf run start <deployment_id> --input-file input.json
+```
+
+The `--binding` on `artifact create-from-plan` records required logical sources
+on the artifact. The `--binding` on `deploy save` makes the deployment runnable.
+For non-platform sources, use both unless a command explicitly says otherwise.
+
+## Complete Plan Shape
+
+The plan file is the low-level workflow model. It is not a draft workspace.
+
+```json
+{
+  "name": "report_case_study",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "path": { "type": "string" }
+    },
+    "required": ["path"]
+  },
+  "state_schema": {
+    "type": "object",
+    "properties": {
+      "notes": { "type": "string", "reducer": "wf.std.replace" },
+      "report": { "type": "object", "reducer": "wf.std.replace" }
+    }
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "report": { "type": "object" }
+    },
+    "required": ["report"]
+  },
+  "outcomes": ["ok"],
+  "start": "read",
+  "nodes": [
+    {
+      "id": "read",
+      "type": "node",
+      "node": "local.report.read_notes",
+      "input": [
+        {
+          "path": { "root": "input", "parts": ["path"] },
+          "target": { "root": "local", "parts": ["path"] }
+        }
+      ],
+      "output": [
+        {
+          "source": { "root": "local", "parts": ["text"] },
+          "target": { "root": "state", "parts": ["notes"] }
+        }
+      ]
+    },
+    {
+      "id": "extract",
+      "type": "node",
+      "node": "local.report.extract_report",
+      "input": [
+        {
+          "path": { "root": "state", "parts": ["notes"] },
+          "target": { "root": "local", "parts": ["text"] }
+        }
+      ],
+      "output": [
+        {
+          "source": { "root": "local", "parts": [] },
+          "target": { "root": "state", "parts": ["report"] }
+        }
+      ]
+    }
+  ],
+  "edges": [
+    { "from": "read", "outcome": "ok", "to": "extract" },
+    { "from": "extract", "outcome": "ok", "to": "__end__" }
+  ],
+  "output": [
+    {
+      "path": { "root": "state", "parts": ["report"] },
+      "target": { "root": "local", "parts": ["report"] }
+    }
+  ]
+}
+```
+
+## Field Rules
+
+- Top level uses `nodes` and `edges`, not draft `steps` and `routes`.
+- Each node object uses `"node": "<capability_name>"`, not draft field `use`.
+- Node input mappings use `path -> target`.
+- Node output mappings use `source -> target`.
+- Top-level workflow output mappings use `path -> target`.
+- `__end__` is the terminal edge target.
+- Reducers live in `state_schema.properties.<field>.reducer`.
+
+## Common Mistakes
+
+- Do not use `wf draft create --capability`; current CLI command is
+  `wf draft create-from-capability <workspace_id> <capability>`.
+- Do not pass draft JSON to `artifact create-from-plan`.
+- Do not omit deployment bindings for ordinary sources. Platform sources such
+  as `wf.std` may be omitted or self-bound, but configured sources usually need
+  explicit deployment bindings.
+- If a challenge asks what you read, source files, tests, and examples count as
+  product code. Report `product_code: true` if you inspected them for plan shape
+  or capability behavior.
@@ -0,0 +1,82 @@
+# Workflow System Model
+
+Use this before choosing commands. The platform separates authoring, binding,
+and execution so agents can plan with stable records instead of improvising
+tool calls.
+
+## Core Objects
+
+- **Source**: an owner of callable capabilities, such as `wf.std`,
+  `local.report`, `local.browser_click`, or an MCP connection. Sources may be
+  built in, configured Python sources, MCP sources, or future provider types.
+- **Capability**: a graph-facing callable contract exposed by a source. It has
+  input/output schemas and outcomes. Build workflows from workflow
+  capabilities, not raw provider internals.
+- **Draft workspace**: mutable, revisioned authoring state. Use it when you are
+  building or editing a workflow interactively.
+- **Artifact**: immutable saved workflow or wrapper version. Use it when the
+  graph should become durable and reusable.
+- **Deployment**: mutable environment binding for an artifact version. It maps
+  logical sources used by the artifact to concrete sources available now.
+- **Run**: durable execution record for a deployment. It stores status, output,
+  diagnostics, and a bounded trace history.
+
+## Why Bindings Exist
+
+A workflow artifact should not hard-code every concrete account or source
+instance. It records logical source requirements. A deployment decides which
+live source satisfies each requirement.
+
+Example:
+
+```text
+artifact requires: local.browser_click
+deployment binds: local.browser_click -> local.browser_click
+```
+
+Platform sources such as `wf.std` are special: they can be omitted or self-bound.
+Configured sources usually need explicit deployment bindings.
+
+## Authoring Paths
+
+Use the guided draft path when editing step-by-step:
+
+```bash
+wf draft create-from-capability <workspace_id> <capability>
+wf draft set-input ...
+wf draft set-output ...
+wf draft validate <workspace_id>
+wf draft save <workspace_id> --artifact <artifact_id> --version 1 --title <title>
+```
+
+Use direct plan import only when you already have a complete workflow plan:
+
+```bash
+wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version 1 --title <title>
+```
+
+Draft shape and direct plan shape are different. Drafts use `steps/routes/use`;
+direct plans use `nodes/edges/node`.
+
+## Execution And Trace
+
+`wf run start` executes a deployment and returns a run summary. `trace_count` is
+the number of stored trace frames for that run, not a success score. In a
+three-node serial workflow, a successful run commonly has `trace_count: 3`.
+
+Use trace commands only with explicit bounds:
+
+```bash
+wf run trace <run_id> --from 0 --limit 25
+```
+
+## Agent Reporting
+
+If a challenge asks whether product code was read, count source files, tests,
+and examples as product code. Reading `tests/...` to learn plan shape means
+`product_code: true`.
+
+Do not run repository-wide `ruff`, `basedpyright`, or test suites unless the
+task asks for repo changes. For workflow operation tasks, validate with `wf`
+commands: capability inspection, draft/deployment validation, run status, and
+bounded trace reads.
@@ -47,7 +47,7 @@ wf artifact create-from-plan workflow.plan.json \

 Do not pass draft JSON to `artifact create-from-plan`. Drafts use `steps`,
 `routes`, and step field `use`. Raw plans use `nodes`, `edges`, and node field
-`node`.
+`node`. See `direct-plan-import.md` for the exact shape.

 Then continue with the normal deployment and run steps:

@@ -4,6 +4,9 @@ import typer

 app = typer.Typer(
    name="schema",
-    help="Print expected input shapes for wf commands.",
+    help=(
+        "Work in progress: intended to print expected input shapes for wf "
+        "commands, but currently has no schema subcommands."
+    ),
    no_args_is_help=True,
 )
@@ -78,7 +78,15 @@ def test_wf_cap_list_help_exists() -> None:

    assert result.exit_code == 0
    assert "--format" in result.output
-    assert "--source" in result.output
+
+
+def test_wf_schema_help_marks_command_group_as_wip() -> None:
+    result = runner.invoke(app, ["schema", "--help"])
+
+    assert result.exit_code == 0
+    output = result.output.lower()
+    assert "work in progress" in output
+    assert "no schema subcommands" in output


 def test_wf_source_list_help_exists() -> None: