\n\nA Claude Code plugin that drives agents through YAML-defined state machines. The engine tracks state, enforces guards, manages nested sub-workflow stacks, and visualizes everything in a web dashboard.\n\n\n\n## Features\n\n- **FSM-based state machines** — define workflows in YAML with states, transitions, and prompts\n- **Stack-based sub-workflows** — states can push nested workflows (max depth 10), auto-pop on completion\n- **Three-tier loading** — bundled templates < global (`~/.claude/workflows/`) < project (`.claude/workflows/`)\n- **Snapshot isolation** — workflow definitions frozen at session start; hot-reloads don't affect running sessions\n- **Runtime overlays** — modify workflows on the fly without touching YAML files\n- **Action states** — `exec` runs shell commands, `fetch` makes HTTP requests, with auto-routing by exit code or HTTP status\n- **Web dashboard** — real-time session monitoring with DAG graph visualization\n- **19 bundled workflows** — complete agent lifecycle from routing to reflection, including long-running batch orchestration\n- **20 bundled skills** — reusable knowledge modules auto-provisioned on first run\n- **SessionStart hook** — auto-provisions missing skills and injects workflow context\n\n## Quick Start\n\n### From Community Plugins (recommended)\n\nThe plugin is listed in the [claude-plugins-community](https://github.com/anthropics/claude-plugins-community/) catalog:\n\n```bash\n/plugin marketplace add https://github.com/anthropics/claude-plugins-community\n/plugin install workflow\n```\n\n### From npm\n\nCreate a `marketplace.json` and add it as a source, or install directly:\n\n```bash\n# 1. Add a marketplace with this plugin\n/plugin marketplace add \n\n# 2. Install\n/plugin install workflow@\n```\n\nSee [Creating a marketplace](https://code.claude.com/docs/en/plugin-marketplaces) for how to set up an npm-based marketplace with this plugin:\n\n```json\n{\n \"name\": \"workflow\",\n \"source\": { \"source\": \"npm\", \"package\": \"claude-mcp-workflow\" }\n}\n```\n\n### Manual (for development)\n\n```bash\ngit clone https://github.com/AxGord/claude-workflow.git\ncd claude-workflow\nnpm install\nnpm run build\nclaude --plugin-dir ./\n```\n\n### Install channels\n\nSupported marketplace sources: the **npm package** (`claude-mcp-workflow`) and a **local directory**. A marketplace entry that points at the git repository (git URL as a plugin source) is **not** supported — `build/` is gitignored, so a git-sourced install has no compiled MCP server to run. (Cloning for development works — see above — because you run `npm run build` yourself.)\n\n## Recommended CLAUDE.md Snippet\n\nThe engine only helps when the agent actually starts a workflow. Add this to your `~/.claude/CLAUDE.md`:\n\n```markdown\n- **ALWAYS** start every conversation by calling `mcp__plugin_workflow_wf__start()` (no arguments) before doing anything else, including answering the user\n - **EXCEPTION**: If you are a sub-agent spawned by the Task tool, do NOT call `start()` without arguments — the parent agent manages the workflow session. Follow the start instructions from the parent's preamble instead\n```\n\n## Recommended Permissions\n\nAuto-allow the workflow tools so the agent is not interrupted with a permission prompt on every transition. In `~/.claude/settings.json`:\n\n```json\n{\n \"permissions\": {\n \"allow\": [\n \"mcp__plugin_workflow_wf__list\",\n \"mcp__plugin_workflow_wf__start\",\n \"mcp__plugin_workflow_wf__status\",\n \"mcp__plugin_workflow_wf__transition\",\n \"mcp__plugin_workflow_wf__context_set\",\n \"mcp__plugin_workflow_wf__modify\",\n \"mcp__plugin_workflow_wf__create\",\n \"mcp__plugin_workflow_wf__delete\",\n \"mcp__plugin_workflow_wf__sessions\"\n ]\n }\n}\n```\n\n`abort` is deliberately **not** allowlisted: sub-agents inherit permissions, and an auto-allowed `abort` would let a sub-agent silently kill its parent's session. Keep it behind a manual prompt.\n\n## How It Works\n\n```\nAgent Engine Storage\n │ │ │\n ├── start() ───────────────►├─ snapshot workflows ─────────►├ session.json\n │◄── initial state prompt ──┤ │\n │ │ │\n ├── transition() ──────────►├─ validate & advance ─────────►├ update JSON\n │◄── new state prompt ──────┤ (push/pop sub-workflows) │\n │ │ │\n ├── transition() ──────────►├─ terminal state? ────────────►├ mark complete\n │◄── done ──────────────────┤ (auto-pop to parent) │\n```\n\n1. `start()` — creates a session, snapshots all workflow definitions, returns the initial state prompt\n2. `transition()` — validates the transition, advances state, handles sub-workflow push/pop, returns the new prompt\n3. Every mutation is atomically persisted to JSON (temp file + rename + lockfile)\n4. Dashboard visualizes sessions and workflow graphs at `localhost:3100`\n\n## Workflow YAML\n\n```yaml\nname: my-workflow\ndescription: \"Example workflow\"\ninitial: start\nmax_transitions: 50\n\nstates:\n start:\n prompt: \"Analyze the task and decide on approach\"\n transitions:\n implement: write_code\n explore: research\n\n research:\n sub_workflow: explore # pushes nested workflow\n on_complete: write_code # returns here on success\n on_fail: start # returns here on failure\n\n write_code:\n prompt: \"Write the implementation\"\n transitions:\n done: finish\n\n finish:\n terminal: true\n outcome: complete # or \"fail\"\n```\n\n## Action States\n\nStates can run shell commands or HTTP requests automatically — the agent doesn't participate, the engine handles execution and routes to the next state based on the result.\n\n### `exec` — run a shell command\n\n```yaml\nrun_tests:\n type: exec\n command: \"npm test\"\n cwd: \"{{context.cwd}}\"\n timeout: 30000\n on_success: analyze\n on_error: fix\n success_prompt: \"Tests passed:\\n{{stdout}}\"\n error_prompt: \"Tests failed (exit {{exit_code}}):\\n{{stderr}}\"\n```\n\n### `fetch` — make an HTTP request\n\n```yaml\ncheck_api:\n type: fetch\n url: \"http://localhost:8888/ping\"\n method: GET\n timeout: 5000\n retry:\n max: 60\n interval: 500\n on_success: ready\n on_error: wait\n success_prompt: \"API ready: {{body}}\"\n error_prompt: \"Not responding: {{error}}\"\n```\n\n### Routing\n\nAction states route via `on_success`/`on_error`, or by specific codes using `cases`:\n\n```yaml\nrun_tests:\n type: exec\n command: \"npm test\"\n cases:\n \"0\": all_passed\n \"1\": tests_failed\n \"2\": no_tests_found\n default: unknown_error\n```\n\n### Template variables\n\nAll prompts support `{{mustache}}` templates. Context values are available everywhere via `{{context.key}}`. After action execution, result variables are also available:\n\n| Source | Variables |\n|--------|-----------|\n| `exec` | `{{stdout}}`, `{{stderr}}`, `{{exit_code}}`, `{{pid}}` (background) |\n| `fetch` | `{{status}}`, `{{body}}`, `{{error}}` |\n\nAction states can be chained — `exec` → `exec` → `fetch` → `prompt` — up to 20 steps without agent involvement.\n\n## Three-Tier Loading\n\nWorkflows load from three sources in ascending priority — later tiers override earlier ones:\n\n| Tier | Path | Purpose |\n|------|------|---------|\n| Bundled | `templates/` (plugin root) | Base workflows shipped with the plugin |\n| Global | `~/.claude/workflows/` | User customizations shared across projects |\n| Project | `.claude/workflows/` | Project-specific workflows |\n\nA project workflow named `coding` overrides the bundled `coding` template. Same-name global workflows sit in between.\n\n## Bundled Workflows\n\n| Workflow | Description |\n|----------|-------------|\n| `master` | Single entry point — analyzes task, loads skills, routes to sub-workflows |\n| `coding` | Code writing pipeline: think → delegate → write → review → verify |\n| `bug-fix` | Standard bug fix: classify → diagnose → fix → verify |\n| `new-feature` | New feature implementation with planning and testing |\n| `debugging` | Diagnose first, fix never (until diagnosed) |\n| `code-review` | Code review with per-file deep analysis |\n| `explore` | Codebase exploration — understand structure, trace code, find patterns |\n| `investigate` | Resolve unknowns before deciding on action |\n| `planning` | Explore, design plan, record workflow context |\n| `testing` | Testing verification — unit tests first, then integration |\n| `web-research` | Check existing knowledge, then delegate to web subagents |\n| `reflection` | Self-reflection after significant tasks — evaluate, classify, act |\n| `subagent` | Lightweight routing for sub-agents (no chat/plan/reflect) |\n| `file-code` | Per-file coding — spawned by coding/bug-fix for each file |\n| `file-review` | Per-file deep review — spawned by code-review for each file |\n| `review-push` | Review uncommitted changes, then commit and push to GitHub |\n| `github-init` | Initialize git repo and create private GitHub repository |\n\n\n\n## Bundled Skills\n\nSkills are reusable knowledge modules loaded by workflows via `Skill()`. Auto-provisioned to `~/.claude/skills/` on first run if missing. Edit your local copy to override the bundled version — the hook never overwrites existing files.\n\n**Methodology**\n\n| Skill | Description |\n|-------|-------------|\n| `preferences` | Template for personal coding preferences (fill in your own) |\n| `architecture` | Simplicity-first architecture decisions |\n| `task-delegation` | When and how to delegate to subagents |\n| `coding-skill-selector` | Select and load coding skills by file extensions and domains |\n| `workflow-authoring` | Reference for creating workflows with exec/fetch action states |\n\n**Languages**\n\n| Skill | Description |\n|-------|-------------|\n| `lang-haxe` | Haxe language gotchas (incl. macros, null safety, hxcpp) |\n| `lang-python` | Python language gotchas |\n| `lang-as3` | AS3 / AIR 51 language gotchas |\n\n**Domains**\n\n| Skill | Description |\n|-------|-------------|\n| `domain-yolo` | YOLO object detection model selection |\n| `domain-pixi` | Pixi.js v8 masking and graphics gotchas |\n| `domain-reid` | Person re-identification ML gotchas |\n| `domain-gamedev` | Game dev precision and physics gotchas |\n\n**Platforms & Tooling**\n\n| Skill | Description |\n|-------|-------------|\n| `target-openfl-native` | OpenFL/hxcpp native target gotchas |\n| `build-cmake` | CMake build system gotchas |\n| `ci-github-actions` | GitHub Actions workflow gotchas |\n| `aws-lambda` | AWS Lambda .NET deployment gotchas |\n| `mcp-setup` | MCP server setup and troubleshooting |\n| `claude-code-config` | Claude Code configuration gotchas |\n\n**Utility**\n\n| Skill | Description |\n|-------|-------------|\n| `math` | Math overflow boundary gotchas |\n| `web-reading` | Fetch web content via subagents |\n\n## MCP Tools\n\nAll tools are registered under the `wf` server. Full tool prefix: `mcp__plugin_workflow_wf__`.\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list` | List all available workflow definitions | — |\n| `start` | Start a workflow, return initial prompt | `workflow`, `actor`, `parent_session_id` |\n| `status` | Get current state, stack, transitions, history | `session_id` |\n| `transition` | Advance to next state (auto push/pop sub-workflows) | `session_id`, `transition` |\n| `context_set` | Save key-value data in session context | `session_id`, `key`, `value` |\n| `modify` | Runtime overlay — add/change/remove states and transitions | `session_id`, `add_state`, `add_transition` |\n| `create` | Create new workflow definition (saves YAML) | `name`, `definition`, `scope` |\n| `delete` | Delete a workflow definition | `name`, `scope` |\n| `abort` | Abort workflow, pop all stack frames | `session_id` |\n| `sessions` | List all sessions (active first) | — |\n\n## Dashboard\n\nThe web dashboard runs on `localhost:3100` and provides real-time monitoring:\n\n- **Sessions panel** — active sessions plus the most recent finished ones (terminal history is capped)\n- **Workflow list** — all loaded workflows with state counts\n- **Session detail** — state history, stack depth, context data\n- **Workflow graphs** — interactive DAG visualization rendered with dagre\n\n### REST API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/sessions` | List all sessions |\n| `GET` | `/api/session/:id` | Get session detail |\n| `POST` | `/api/session/:id/abandon` | Abandon a session |\n| `GET` | `/api/workflows` | List all workflow definitions |\n\n## Configuration\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `WORKFLOW_DIR` | `~/.claude/workflows/` | Global workflow YAML directory |\n| `STATE_DIR` | `~/.claude/workflow-state/` | Session JSON persistence |\n| `DASHBOARD_PORT` | `3100` | Web dashboard HTTP port |\n| `DASHBOARD_HOST` | `127.0.0.1` | Web dashboard bind address |\n\n## Status Line\n\nShow the active workflow and state in Claude Code's status bar:\n\n\n\nAdd this snippet to your statusline script:\n\n```sh\n# Workflow status — add to your ~/.claude/statusline-command.sh\nwf_state_dir=\"$HOME/.claude/workflow-state\"\nif [ -d \"$wf_state_dir\" ]; then\n for f in \"$wf_state_dir\"/*.json; do\n [ -f \"$f\" ] || continue\n slen=$(jq -r '.stack | length' \"$f\" 2>/dev/null)\n if [ \"$slen\" -gt 0 ]; then\n cpid=$(jq -r '.context.claude_code_pid // 0' \"$f\" 2>/dev/null)\n [ \"$cpid\" != \"$PPID\" ] && continue\n wf=$(jq -r '.stack[.active_frame].workflow // \"\"' \"$f\" 2>/dev/null)\n st=$(jq -r '.stack[.active_frame].current_state // \"\"' \"$f\" 2>/dev/null)\n printf \"\\033[96m\\xE2\\x9A\\x99 %s:%s\\033[0m\" \"$wf\" \"$st\"\n break\n fi\n done\nfi\n```\n\nThen in `~/.claude/settings.json`:\n\n```json\n{\n \"statusLine\": {\n \"type\": \"command\",\n \"command\": \"bash ~/.claude/statusline-command.sh\"\n }\n}\n```\n\n## Development\n\n```bash\nnpm run build # tsc → compiles src/ to build/\nnpm run dev # tsc --watch\nnpm start # node build/index.js\nnpm test # vitest run\n```\n\n### Architecture\n\n| File | Responsibility |\n|------|---------------|\n| `src/index.ts` | Entry point — resolves dirs, wires components, starts stdio transport |\n| `src/engine.ts` | FSM core — start, transition, abort, context, stack push/pop |\n| `src/loader.ts` | YAML loading + Zod validation + fs.watch hot-reload |\n| `src/storage.ts` | JSON persistence with atomic writes and lockfile mutex |\n| `src/modifier.ts` | Runtime overlays + create (YAML writer) |\n| `src/tools.ts` | MCP tool registrations + response formatting |\n| `src/executor.ts` | Action state execution — shell commands (`exec`) and HTTP requests (`fetch`) |\n| `src/template.ts` | Mustache-style `{{var}}` template rendering for action parameters |\n| `src/dashboard.ts` | Express REST API + static file serving |\n| `src/types.ts` | Zod schemas, TypeScript types, constants |\n\n## License\n\nMIT\n",
"bytes": 15668,
"sha": "3f9273c1132afb2cfa977e03a77a8de65332e49a662e6296a0b1c332a3cfd806",
"repo_slug": "axgord/claude-workflow",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_axgord_claude_workflow_workflow_ab44d5c2/readme"
}
![\"Claude](\"docs/banner.png\")
\n![\"npm\"](\"https://img.shields.io/npm/v/claude-mcp-workflow\")
![\"License\"](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-5.7-3178c6\"){kind=icon}
![\"Claude](\"https://img.shields.io/badge/Claude_Code-Plugin-ff6600\"){kind=icon}