| name | workflow-mcp |
| description | Use only when creating, resuming, inspecting, updating, completing, or writing artifacts for an authorized .workflow plan or audit run through the bundled Workflow MCP tools. It is an operations contract, not a reason to create workflow artifacts. |
Workflow MCP
Use the matching MCP tool for deterministic .workflow/ state and artifact operations whenever it is available. This is the normal path, not a preference. MCP does not generate substantive content, launch agents, merge worktrees, run verification, or replace judgment.
.workflow/ is the default artifact root. When workflow_status reports a
configured root from mcp-config.yml, treat the reported path as authoritative;
do not assume or manually recreate the default directory.
Tool Surface
workflow_status
workflow_plan_create, workflow_plan_update, workflow_plan_complete, workflow_plan_artifact_write
workflow_plan_commitment_propose, workflow_plan_commitment_confirm
workflow_audit_create, workflow_audit_update, workflow_audit_complete, workflow_audit_artifact_write
workflow_handoff_write
workflow_findings_normalize
Loading this skill never authorizes a new plan/audit. The active primary workflow and action boundary decide whether artifacts may exist.
Core Contract
- Pass an absolute
workspace_root when cwd may be a parent or sibling workspace.
- Call
workflow_status at start/resume, after compaction, or when active state is uncertain; do not call it before every phase merely for reassurance.
- New authorized work uses
workflow_plan_create or workflow_audit_create. Existing unfinished work uses the matching update tool. Do not reopen completed runs without an explicit request.
- Use artifact tools only for allowed run-relative paths. Pass exactly one of
content or json.
- Normalize structured findings before storing them.
- Finish realized runs with
workflow_plan_complete or workflow_audit_complete; phase-only updates do not clear the root active pointer.
Commitment reflection is platform-neutral state and same-model judgment. Use the propose/confirm tools for material plans before execution and after material scope divergence. A Codex Stop hook may enforce missing state, but skills and MCP remain complete without it; Claude Code and other clients must never be instructed to find or wait for that hook.
Before creating artifacts in a git repository, ensure .workflow/ is ignored unless explicitly versioned.
State Updates
Use the operation names and payload fields exposed by the live tool schema. For task status, use upsert_task with a full task object or complete_task with task_id. For chunks, use lifecycle operations rather than inventing setters.
If a call fails with an unsupported operation, schema, payload, or validation error, read the nearest supported-operation hint, correct the same MCP call, and retry. Do not switch to manual files while the matching tool remains available.
Read references/operations.md only when creating a run, manipulating chunks/handoffs, recovering an operation error, or diagnosing installed-package drift.
Fallback And Stop
Manual .workflow/ writes are fallback only when the matching MCP tool is unavailable. Preserve the same layout and state semantics and report the fallback.
Stop after the requested deterministic operation succeeds. Do not inspect unrelated artifacts or add workflow stages.