dev-flow

Unified development-flow plugin for Claude Code, Codex, and Antigravity.

The canonical workflow is the /loop-style orchestrator: issue deepening, implementation planning, human plan approval, implementation, AI council review, human-approved develop merge, E2E sweep, and persona-based requirements/product review.

npm installer

npx @masadev/dev-flow-plugin install --host claude-code
npx @masadev/dev-flow-plugin install --host codex
npx @masadev/dev-flow-plugin install --host antigravity

Use --target <path> to choose an install directory, --force to replace it, and --dry-run to preview.

Quick tutorial

This walkthrough gets one repository from install to the local queue UI.

1. Install for your agent host

Run one installer command from the repository where you want to use dev-flow:

npx @masadev/dev-flow-plugin install --host claude-code
# or
npx @masadev/dev-flow-plugin install --host codex
# or
npx @masadev/dev-flow-plugin install --host antigravity

For a local checkout of this repo, use the same CLI directly:

node bin/dev-flow-plugin.js doctor
node bin/dev-flow-plugin.js ui --readonly

2. Check prerequisites

dev-flow-plugin doctor

You want node, git, gh, bash, and jq available. The test runner has a small jq-lite fallback, but the real workflow expects GitHub CLI access.

3. Start with readonly queue UI

dev-flow-plugin ui --readonly

Open the URL printed by the command, usually http://127.0.0.1:8787. If that port is busy, the UI automatically chooses the next available port and prints it. The left pane is the work inbox; the right pane shows why an item is queued and which action is available. Readonly mode is the safest first run because it cannot write labels or comments.

4. Inspect the next item from CLI

dev-flow-plugin queue-status --json
dev-flow-plugin queue-next --json

Typical queues are:

• deepen: issue needs hearing or a human reply was received.
• planApproval: implementation plan is waiting for human approval.
• review: PR needs AI council review.
• mergeApproval: review passed, but human merge approval is still missing.
• e2e: catalog row is Not executed or Needs rerun.
• personaCandidates: persona review found an issue candidate.

5. Preview a write action before running it

dev-flow-plugin queue-action --type approve-merge --target pr --id 123 --dry-run

The command prints the exact gh operation it would run. To execute through the CLI, add --yes. The UI uses the same preview-first model in its confirmation drawer.

6. Keep the human safety gate

Automated review can add review:passed, but develop merge still requires the human-applied merge:approved label. This is intentional: the system can prepare and verify work, but it does not silently approve its own merge.

Main command names

• flow-on, flow-off, flow-tick
• discover-on, discover-off, discover-tick
• review-pr
• merge-dev
• e2e-sweep
• requirements-design
• persona-persona-review-requirements
• persona-persona-review-product
• doctor

Queue UI

dev-flow-plugin ui
dev-flow-plugin ui --readonly --port 8788
dev-flow-plugin queue-status --json
dev-flow-plugin queue-next --json
dev-flow-plugin queue-action --type approve-merge --target pr --id 123 --dry-run

The UI opens a local operations inbox, starting at http://127.0.0.1:8787 and automatically moving to the next available port if needed. It shows plan, review, rework, merge approval, E2E, and persona candidate queues. Write actions use a confirmation drawer and expose the exact gh command before execution.

Safety gates

Develop merge requires both review:passed and merge:approved. The latter is a human-applied label and is intentionally not set by the automated review flow.