docs pass for new wf-cli

2026-06-01 05:45:42 +07:00
parent e4813ad15e
commit bd190a5547
6 changed files with 342 additions and 7 deletions
@@ -0,0 +1,51 @@
+---
+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 planning-session specs or implementation plans as user-facing runtime guidance.