workflow-todo-state

name	workflow-todo-state
description	Create or retrofit reusable named workflow state machines for multi-step agent projects. Use when a project needs recoverable workflow state files, multiple workflow definitions, phase gates, restart-safe agent workflows, explicit skipped/blocked states, workflow routing rules, or reusable workflow templates across repositories.

Workflow Todo State

Use this skill to make long-running agent workflows recoverable from named workflow state files. The pattern combines human-readable Markdown checklists with machine-readable YAML frontmatter and a deterministic state script.

Quick Start

Install into another project:

skills/workflow-todo-state/scripts/install.sh /path/to/target-project --agent-dir .agent --with-skill --init-layout --update-agents

Use --profile <name> for any built-in layout in profiles/*.yaml, or --agent-dir, --skills-dir, and --entry-file for a custom layout. The Codex profile correctly separates .agents/skills from .codex; omitting profile options keeps the historical .claude + CLAUDE.md default.

Then:

1. Create workflow definitions under <agent-dir>/workflows/{workflow-id}/.
2. Add routing.yaml to every workflow directory as the source of truth for its trigger conditions and state file pattern.
3. Generate the routing registry with <agent-dir>/scripts/sync-workflow-routing.sh.
4. Create run state files under workspace/workflow-runs/{task-or-feature}.workflow.md.
5. Create or update the state file from references/basic-state-template.md.
6. Ensure every phase has exactly one status line:

   > [P0] ⬜ 未开始
   

7. Make every workflow skill or agent route the task, then read the relevant workflow state file before starting work.
8. Update state only through the script:

   <agent-dir>/scripts/todo-state.sh "${WORKFLOW_STATE_FILE}" start P1
   <agent-dir>/scripts/todo-state.sh "${WORKFLOW_STATE_FILE}" complete P1
   <agent-dir>/scripts/todo-state.sh "${WORKFLOW_STATE_FILE}" skip P2 "not needed"
   <agent-dir>/scripts/todo-state.sh "${WORKFLOW_STATE_FILE}" block P3 "waiting for user input"
   

Recommended Layout

Use separate files for workflow definitions and workflow runs:

.agent/
  workflows/
    feature-development/
      workflow.md
      state-template.md
      routing.yaml
    release-check/
      workflow.md
      state-template.md
      routing.yaml
  rules/
    workflow-routing.md
  scripts/
    sync-workflow-routing.sh
workspace/
  workflow-runs/
    payment-refactor.workflow.md
    release-v1-2.workflow.md

Do not name every run todo.md when a project can have multiple workflows. Prefer descriptive state files:

• {feature-name}.workflow.md
• {task-name}.workflow.md
• {workflow-id}-{run-id}.workflow.md

Use todo.md only for a single-purpose project where one workflow will ever exist.

Required State File Shape

Each reusable workflow state file should contain:

• YAML frontmatter with workflow_id, workflow_name, workflow_version, state_file_type, run_id, task, created_from, current_phase, current_status, mode, blocked_reason, quality_gate, quality_gate_owner, and quality_gate_due.
• A visible line beginning with > 当前阶段：.
• One unique phase status line per phase, using > [PN] ....
• An ## 异常记录 table if skip or block should append history.

See references/basic-state-template.md for a minimal portable state template, references/workflow-routing-template.md for routing rules, and references/integration.md for retrofit instructions.

Routing Metadata and Synchronization

Each workflow directory must contain a minimal scalar routing.yaml:

workflow_id: feature-development
required: true
when_to_use: "Implementing or changing a product feature"
triggers: "new feature; bug fix; refactor"
excludes: "read-only question; inspect-only request"
state_file_pattern: "workspace/workflow-runs/feature-{task}.workflow.md"

workflow_id must match its directory name. Keep values on one line and do not use |, because they are rendered into a Markdown table.

After every workflow create, change, rename, or deletion, run:

<agent-dir>/scripts/sync-workflow-routing.sh
<agent-dir>/scripts/sync-workflow-routing.sh --check

The first command regenerates only the marked block in <agent-dir>/rules/workflow-routing.md; the second is suitable for pre-commit or CI and fails when the registry is stale.

State Rules

• start PN requires all previous phases to be ✅ 已完成 or ⏭️ 跳过.
• complete PN requires the phase to be 🔲 进行中 {in_progress} (legacy emoji-only states remain readable).
• Completing the final phase requires quality_gate: passed. A temporary waived gate also requires a non-empty owner and due date.
• skip PN refuses completed phases and records a reason.
• block PN marks an open phase in progress, writes current_status: blocked, and records a reason; completed and skipped phases are terminal.
• After complete or skip, the script advances current_phase to the next ⬜ 未开始 phase, or to done when no pending phase remains.
• Treat run states as active coordination data. After completion, archive or remove them according to the target repository policy; durable history belongs in changelogs, release notes, or ADRs.

When Retrofitting A Project

Keep the change small:

1. Add the script.
2. Add <agent-dir>/workflows/, workspace/workflow-runs/, and <agent-dir>/rules/workflow-routing.md.
3. Add routing.yaml to every existing workflow, then run sync-workflow-routing.sh.
4. Add frontmatter and unique phase lines to existing state files.
5. Replace ad hoc sed or manual status edits in skills/agents with todo-state.sh.
6. Add a project entry rule: before any mutating action, route the task; if a required workflow matches, create or resume its run and start the current phase.
7. Run sync-workflow-routing.sh --check in pre-commit or CI.
8. Test one happy path, one blocked/invalid transition, and one stale-routing failure.

Do not force a project to adopt this exact workflow structure. Preserve local phase names, output files, and user confirmation gates.