\n\n# IX Flow\n\n[](https://discord.gg/6qsdhSPE)\n\n`ix-flow` runs agent workflows. A workflow is a small state machine — phases, transitions,\nand human gates — that your agent advances step by step, pausing for your approval where it\nmatters. You **author** a workflow; your **agent runs it** by calling `ix-flow`.\n\nWorkflows are packaged as **skills**: a flow definition plus instructions that tell the\nagent how to run it. [`quoin`](https://github.com/agent-ix/quoin), for example, ships\nspec skills that drive `ix-flow` — you invoke the skill, and the agent does the rest.\n\n## Install\n\nInstall the CLI your agent calls:\n\n```bash\nnpm i -g @agent-ix/ix-flow\n```\n\nThen add the plugin to your coding agent. The same two skills — **ix-flow** (runs a workflow)\nand **ix-flow-create** (authors a new one) — install into **Claude Code, OpenAI Codex,\nopencode, and GitHub Copilot**. Pick your agent below. No Anthropic API key is required —\nyour existing agent subscription is used.\n\n\nClaude Code\n\nRun these inside Claude Code (they add the `/ix-flow` and `/ix-flow-create` commands):\n\n```text\n/plugin marketplace add agent-ix/ix-flow\n/plugin install ix-flow@ix-flow\n```\n\n\n\n\nOpenAI Codex\n\n```bash\ncodex plugin marketplace add agent-ix/ix-flow\ncodex plugin add ix-flow\n```\n\nOr browse and install ix-flow from the `/plugins` menu inside the Codex TUI.\n\n\n\n\nopencode\n\nInstall the skills with the GitHub CLI (requires `gh` ≥ 2.90.0). `--all` installs\nboth skills; `--scope user` makes them available in every repo:\n\n```bash\ngh skill install agent-ix/ix-flow --all --scope user --agent opencode\n```\n\n\n\n\nGitHub Copilot\n\nWith the Copilot CLI:\n\n```bash\ncopilot plugin marketplace add agent-ix/ix-flow\ncopilot plugin install ix-flow@ix-flow\n```\n\nOr install the skills with the GitHub CLI (requires `gh` ≥ 2.90.0):\n\n```bash\ngh skill install agent-ix/ix-flow --all --scope user --agent github-copilot\n```\n\n\n\nAuthor your own workflow below, or install one like `quoin` that ships its own.\n\n> A clean-room, repeatable check of the Claude Code install path lives in [`smoke/`](./smoke) —\n> run `make install-smoke`.\n\n## Author a workflow\n\nA workflow is two files in a skill directory:\n\n```\nrelease/\n SKILL.md # instructs the agent how to run the flow\n workflows/\n release/\n def.yaml # the flow: phases, transitions, gates\n```\n\n**The flow** (`def.yaml`) declares the states and the moves between them. Here a change goes\n`draft → in_review → approved`, with the final step gated on human approval:\n\n```yaml\nname: release\nversion: 0.1.0\ninitialPhase: draft\nphases:\n - { name: draft }\n - { name: in_review }\n - { name: approved, terminal: true }\ntransitions:\n - { from: draft, to: in_review, defaultGate: auto }\n - { from: in_review, to: approved, defaultGate: hitl } # pauses for approval\n```\n\n**The skill** (`SKILL.md`) tells the agent how to run that flow:\n\n```markdown\n---\nname: release\ndescription: Drive a change from draft through review to release.\nmetadata:\n ix-flow-workflows: ./workflows\n---\n\n# /release\n\nStart from the run status and follow the reported next actions. Advance the run through its\nphases, and stop at the human gate until the change is approved.\n```\n\nRun `/ix-flow-create` and your agent scaffolds both files for you. See\n[`docs/guide.md`](docs/guide.md) for the full authoring reference; a complete, runnable\nversion of this workflow is in [`examples/release`](examples/release).\n\n## Use a workflow\n\nRun `/ix-flow ` and your agent drives the run — creating it, advancing through the\nphases, and pausing at gates for your approval:\n\n```text\nYou: /ix-flow release\nAgent: ▸ created run, advanced draft → in_review → reached the approval gate\n \"Ready to release. Approve?\"\nYou: approve\nAgent: ▸ recorded approval, advanced to approved\n \"Released.\"\n```\n\nUnder the hood the agent calls `ix-flow` to track the run and enforce the gate. Runs\npersist, so the agent can resume one across sessions.\n\n## Concepts\n\n- **Flow** — a workflow definition: phases, transitions, gates, invariants (`def.yaml`).\n- **Skill** — the agent's instructions for running a flow (`SKILL.md`).\n- **Run** — one live instance of a flow, identified by a run id.\n- **Phase** — a named state; a run sits in exactly one phase at a time.\n- **Gate** — a `hitl` transition that pauses for human approval.\n- **Invariant** — a predicate that must hold before a transition succeeds.\n\nSee [`docs/guide.md`](docs/guide.md) for the full guide — gates, invariants, interviews,\nartifact templates, the run lifecycle, and the complete command reference.\n\n## Development\n\n```bash\npnpm install\npnpm run build\npnpm test\npnpm run lint\n```\n\nThis package builds on `@agent-ix/ix-cli-core` from the standalone `ix-cli-core` repo.\n\n### Evals\n\nBeyond the unit tests, `ix-flow` uses the shared\n[`@agent-ix/cli-agent-evals`](../cli-agent-evals) toolkit to drive real coding-agent\nCLIs through each workflow skill end-to-end. The suite definition lives in\n[`cli-agent-evals.config.mjs`](cli-agent-evals.config.mjs); project-specific fixtures,\nprompts, and assertions remain under [`evals/`](evals/).\n\nLive runs use `agent-pty` + tmux and cost tokens/minutes, so they are opt-in:\n\n```bash\nmake evals # canary subset (one scenario per family)\nmake evals-all # full corpus (EV-001..EV-022)\nmake eval FILTER=EV-013\nmake evals-rebuild\n```\n\nDirect CLI form:\n\n```bash\nnode ../cli-agent-evals/bin/cli-evals.js run \\\n --suite ./cli-agent-evals.config.mjs \\\n --canary \\\n --agent claude \\\n --model sonnet\n```\n\nAgent plugin setup for authoring/running evals from an agent:\n\n```bash\nclaude plugin marketplace add agent-ix/cli-agent-evals\nclaude plugin install cli-agent-evals\n\ncodex plugin marketplace add agent-ix/cli-agent-evals\ncodex plugin add cli-agent-evals\n\ngh skill install agent-ix/cli-agent-evals --all --scope user --agent opencode\ngh skill install agent-ix/cli-agent-evals --all --scope user --agent github-copilot\n```\n\nMinimal integration pattern:\n\n```js\nimport { defineSuite } from \"../cli-agent-evals/dist/index.js\";\nimport { SCENARIOS } from \"./evals/scenarios/index.mjs\";\n\nexport default defineSuite({\n name: \"ix-flow\",\n rootDir: import.meta.dirname,\n scenarios: SCENARIOS,\n});\n```\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n",
"bytes": 6625,
"sha": "225a704cd8383a41d54fd314e860daeb66ea05bc40debe91f800c68aa79cd9c5",
"repo_slug": "agent-ix/ix-flow",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_agent_ix_ix_flow_spec_index_md_9296dd6c/readme"
}
![\"IX](\"logo.png\")
\n