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 + AGENTS.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: