issue-flow

Issue-Flow

Issue-Flow is a workflow plugin for coding agents. It ships an issue-driven delivery orchestrator plus a lightweight bugfix repair flow so agents can either drive a feature from issue creation to review or take a bug from reproduction to verified fix.

Issue-Flow is built to work with superpowers. Superpowers provides the core development workflows, and Issue-Flow adds a lightweight state machine around them so agent sessions can stay aligned with a single issue from start to finish.

Why Issue-Flow

• Keep agent work anchored to one issue instead of drifting across unrelated tasks
• Make progress explicit with a state machine instead of relying on hidden session context
• Support both guided approval checkpoints and uninterrupted auto-mode execution
• Reuse mature workflows from superpowers instead of reimplementing planning and execution logic
• Stay lightweight: no third-party runtime dependencies, no separate service to run

How It Works

Issue-Flow ships two workflow state machines:

issue-flow

The issue-driven workflow has two parts: a pre-worktree phase that produces a GitHub Issue number, and a persistent state machine that tracks delivery from that point on.

Pre-worktree phase (short-lived pending state in the source repo):

• issue-brainstorm turns a rough request into a design direction
• issue-create turns the design spec into a GitHub Issue number
• .issue-flow/pending.json can recover this short phase before a target worktree exists

Persistent state machine (.issue-flow/ created by issue-pick):

picked -> researching -> planned -> implementing -> committing -> pring -> reviewing -> finished

Each persistent state maps to a focused skill:

• issue-pick attaches the session to a specific issue and branch context
• issue-research captures codebase findings before planning
• issue-plan creates an implementation plan
• issue-implement carries out the plan
• issue-verify checks tests, linting, and review feedback
• issue-commit prepares clean commits
• issue-pr opens the pull request and hands off into review
• issue-finish wraps up branch and workspace state

The top-level issue-flow skill is the orchestrator. It reads the current session state and routes the agent to the next correct step.

bugfix-flow

The bugfix workflow is intentionally narrower. It is for cases where you already know there is a bug and want the agent to focus on reproducing, fixing, and verifying it before any commit or PR step.

Bugfix work usually goes directly to bugfix-pick. If it must pause before a worktree exists, .bugfix-flow/pending.json can hold that short-lived pending state in the source repo.

Persistent state machine (.bugfix-flow/ created by bugfix-pick):

picked -> implementing -> ready -> finished

Each persistent state maps to a focused skill:

• bugfix-pick creates worktree/context from either a bug description or an existing issue
• bugfix-implement applies the minimal code changes needed for the fix
• bugfix-verify runs focused verification and loops back on failure
• bugfix-finish cleans up the bugfix session after the user decides to stop

The top-level bugfix-flow skill is the orchestrator. It routes the session until verification passes, then pauses in ready so a human can decide whether to commit or open a PR.

Installation

Issue-Flow currently supports Claude Code and Codex.

Requirements

Issue-Flow depends on:

• git
• gh for GitHub issue and pull request operations
• superpowers as a runtime dependency

Claude Code

Install superpowers first:

/plugin install superpowers@claude-plugins-official

Then add the Issue-Flow marketplace and install the plugin:

/plugin marketplace add crazygit/issue-flow
/plugin install issue-flow@issue-flow-marketplace

Restart Claude Code if the new plugin does not appear immediately.

Codex

Codex installation exposes issue-flow through either a personal marketplace or the repo marketplace, and the personal installer also enables the required plugins in user-level Codex config.

The Codex bundle entry point is .codex-plugin/plugin.json.

Recommended: personal marketplace

Run the installer from this repository:

bash scripts/install-codex.sh

The script will:

• stage this repository at ~/.codex/plugins/issue-flow
• create or update ~/.agents/plugins/marketplace.json
• preserve other marketplace entries while refreshing the managed issue-flow entry in your user-level marketplace config
• create or update ~/.codex/config.toml
• preserve existing Codex plugin settings while enabling superpowers@openai-curated
• preserve existing Codex plugin settings while enabling issue-flow@<your personal marketplace id>