swarm-flow

swarm-flow

swarm-flow turns Claude Code, Codex, and other coding agents into a governed software delivery workflow.

It takes a plain-language request like "build this feature" or "review this PR" and runs it through explicit phases: intake, discovery, planning, design, implementation, validation, documentation, and delivery. Each phase has specialist agents, required artifacts, approval gates, hooks, and preview-safe connectors.

It is not a prompt pack and it is not an autonomous merge bot. swarm-flow treats AI-assisted software delivery as an artifact-driven state machine.

swarm-flow is the layer between "vibe coding" and fully autonomous deployment: fast enough for solo builders, explicit enough for teams.

Quick Start

The fastest way to try swarm-flow is to install the agent plugin, then ask your agent to start a governed run from a normal feature request.

Claude Code

Once this repository is public, install from the Claude Code plugin marketplace:

/plugin marketplace add seshxn/swarm-flow
/plugin install swarm-flow@swarm-flow-marketplace

Then start a run:

/swarm Allow admins to bulk reassign cases by region, with audit history and role checks.

Local fallback:

git clone https://github.com/seshxn/swarm-flow.git
cd swarm-flow
npm install
npm run build
npm link

Then in Claude Code:

/plugin install /absolute/path/to/swarm-flow

Codex

Install the Codex skill from a clone:

git clone https://github.com/seshxn/swarm-flow.git ~/.codex/swarm-flow
cd ~/.codex/swarm-flow
npm install
npm run build
npm link
./scripts/install-codex-skill.sh

Restart Codex, then make a normal delivery request in a target repository:

Allow admins to bulk reassign cases by region, with audit history and role checks.

For project-level default behavior, initialize agent instructions in the target repository:

swarm-flow init --agent all

CLI Development

If you are contributing to swarm-flow itself or want to inspect the runtime directly:

npm install
npm test
npm run build

node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js flows list
node packages/cli/dist/index.js skills list

Start a feature run:

node packages/cli/dist/index.js start "Allow admins to bulk reassign cases in batches with audit logging"

Inspect it:

node packages/cli/dist/index.js status
node packages/cli/dist/index.js resume
node packages/cli/dist/index.js phase
node packages/cli/dist/index.js context pack
node packages/cli/dist/index.js agents plan
node packages/cli/dist/index.js artifact add feature_brief path/to/feature-brief.md
node packages/cli/dist/index.js policy check
node packages/cli/dist/index.js complete intake
node packages/cli/dist/index.js artifacts
node packages/cli/dist/index.js preview jira
node packages/cli/dist/index.js runs list

Agent Integrations

swarm-flow includes local integration bundles for Claude Code and Codex:

• plugins/claude-code: Claude Code slash-command prompts such as /swarm, /swarm-resume, and /swarm-preview.
• plugins/codex: Codex plugin manifest plus a swarm-flow skill designed to trigger from normal delivery requests.

The CLI can also plan host-neutral subagent dispatch manifests:

swarm-flow agents plan
swarm-flow agents plan --phase planning
swarm-flow agents plan --output .runs/run-123/context/subagent-dispatch.json

Each manifest includes the run, phase, role-card path, recommended worktree name, owned files or scope, required outputs, context pack path, and handoff instructions. Claude Code and Codex can read that JSON and spawn their own native subagents outside the CLI; swarm-flow only writes the manifest and context pack.

Inspect them from the CLI:

swarm-flow integrations list
swarm-flow integrations show claude-code
swarm-flow integrations show codex

For project-level default behavior, initialize agent instructions in the target repository if you have not already:

swarm-flow init --agent all

After that, agents should treat non-trivial requests like "Allow admins to bulk reassign cases by region" as swarm-flow runs by default. The CLI also supports explicit overrides when needed:

swarm-flow start "Allow admins to bulk reassign cases by region, with audit history and role checks."
swarm-flow start feature --title "Bulk case reassignment" --goal "Allow admins to reassign cases by region"

See docs/integrations.md.

Why It Exists

Most agent tooling optimizes for generating code. Real engineering teams need more than code generation: