ZFlow

Build software with AI, reliably.

npx zflow-ai@latest

Works with Claude Code, OpenCode, Gemini CLI, and Codex.

What is ZFlow?

ZFlow structures your AI coding workflow. You describe what to build, and ZFlow handles research, planning, execution, and verification — each in a fresh context with exactly the information needed.

You see a few commands. Behind the scenes: structured prompts, parallel agents, state management, and atomic commits.

Install

npx zflow-ai@latest

The installer prompts you to choose:

1. Runtime — Claude Code, OpenCode, Gemini CLI, Codex, or all
2. Location — Global (all projects) or local (current project only)

Verify installation:

• Claude Code / Gemini CLI: /flow:help
• OpenCode: /zf-help
• Codex: $zf-help

Note: Codex uses skills (skills/zf-*/SKILL.md) rather than custom prompts.

Non-Interactive Install

Skip prompts by specifying runtime and location flags. Useful for Docker, CI, and scripts.

npx zflow-ai --claude --global    # Claude Code  -> ~/.claude/
npx zflow-ai --claude --local     # Claude Code  -> ./.claude/
npx zflow-ai --opencode --global  # OpenCode     -> ~/.config/opencode/
npx zflow-ai --gemini --global    # Gemini CLI   -> ~/.gemini/
npx zflow-ai --codex --global     # Codex        -> ~/.codex/
npx zflow-ai --codex --local      # Codex        -> ./.codex/
npx zflow-ai --all --global       # All runtimes

Flags: --global (-g) or --local (-l) for location. --claude, --opencode, --gemini, --codex, or --all for runtime.

Global npm Install

Install the package permanently to avoid re-downloading each time:

npm install -g zflow-ai
zflow

Development Install

For testing local modifications:

git clone <your-repo-url>
cd zflow
node bin/install.js --claude --local

Updating

npx zflow-ai@latest        # npx
npm update -g zflow-ai      # global npm install

Permissions

Recommended: Skip Permissions

ZFlow is designed for frictionless automation. Stopping to approve date and git commit 50 times defeats the purpose.

claude --dangerously-skip-permissions

Alternative: Granular Permissions

Add to your project's .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(date:*)", "Bash(echo:*)", "Bash(cat:*)", "Bash(ls:*)",
      "Bash(mkdir:*)", "Bash(wc:*)", "Bash(head:*)", "Bash(tail:*)",
      "Bash(sort:*)", "Bash(grep:*)", "Bash(tr:*)",
      "Bash(git add:*)", "Bash(git commit:*)", "Bash(git status:*)",
      "Bash(git log:*)", "Bash(git diff:*)", "Bash(git tag:*)"
    ]
  }
}

Docker / Containers

If file reads fail with tilde paths (~/.claude/...), set CLAUDE_CONFIG_DIR before installing:

CLAUDE_CONFIG_DIR=/home/youruser/.claude npx zflow-ai --global

Uninstalling

npx zflow-ai --claude --global --uninstall
npx zflow-ai --opencode --global --uninstall
npx zflow-ai --codex --global --uninstall

Replace --global with --local for project-level installs. This removes all ZFlow commands, agents, hooks, and settings while preserving your other configurations.

Workflow

/flow:start  ->  /flow:ask  ->  /flow:design  ->  /flow:build  ->  /flow:test  ->  /flow:ship

| Step | Command | What happens | |------|---------|--------------| | Start | /flow:start | Describe your idea. ZFlow asks questions, researches the domain, extracts requirements, and creates a phased roadmap. | | Ask | /flow:ask 1 | Shape the implementation. ZFlow identifies gray areas and captures your decisions before planning. | | Design | /flow:design 1 | Researches how to build it, creates atomic task plans, and verifies them against requirements. | | Build | /flow:build 1 | Executes plans in parallel waves. Each task gets a fresh context and its own atomic commit. | | Test | /flow:test 1 | Walk through what was built. If something's wrong, ZFlow diagnoses it and creates fix plans. | | Ship | /flow:ship | Archive the milestone and tag the release. Start the next one with /flow:next. |

Quick Mode

/flow:quick

For small tasks that don't need full planning. Same agents, atomic commits, state tracking — just faster. Add --discuss for context gathering or --full for verification.

How ZFlow Works

Full Project Lifecycle

                    ┌─────────────────────────────────────────┐
                    │              NEW PROJECT                │
                    │  /flow:start                            │
                    │  Questions -> Research -> Requirements  │
                    │  -> Roadmap                             │
                    └────────────────────┬────────────────────┘
                                        │
                    ┌───────────────── PHASES ─────────────────┐
                    │                                         │
                    │   /flow:ask N      Lock in preferences  │
                    │        │                                │
                    │   /flow:design N   Research + Plan      │
                    │        │                                │
                    │   /flow:build N    Parallel execution   │
                    │        │                                │
                    │   /flow:test N     Manual UAT           │
                    │        │                                │
                    │   More phases? ──── Yes ─── loop back   │
                    │        │ No                             │
                    └────────┼────────────────────────────────┘
                             │
                    ┌────────▼────────────────────────────────┐
                    │  /flow:audit     Verify completeness    │
                    │  /flow:ship      Archive + tag release  │
                    └────────┬────────────────────────────────┘
                             │
                     Another milestone?
                       Yes ──── /flow:next
                       No  ──── Done!

How /flow:design Works

The design phase coordinates multiple agents to produce verified plans:

  /flow:design N
        │
        ├── 4 Phase Researchers (parallel)
        │     ├── Stack researcher
        │     ├── Features researcher
        │     ├── Architecture researcher
        │     └── Pitfalls researcher
        │              │
        │        RESEARCH.md
        │              │
        ├── Planner (reads PROJECT.md, REQUIREMENTS.md,
        │             CONTEXT.md, RESEARCH.md)
        │              │
        ├── Plan Checker ──── PASS? ──── No ── retry (up to 3x)
        │                       │
        │                      Yes
        │                       │
        └── PLAN files created

How /flow:build Works

Execution runs in dependency-ordered waves with fresh contexts:

  /flow:build N
        │
        ├── Analyze plan dependencies
        │
        ├── Wave 1 (independent plans)
        │     ├── Executor A (fresh 200K context) -> commit
        │     └── Executor B (fresh 200K context) -> commit
        │
        ├── Wave 2 (depends on Wave 1)
        │     └── Executor C (fresh 200K context) -> commit
        │
        └── Verifier
              └── Check codebase against phase goals
                    ├── PASS -> VERIFICATION.md (success)
                    └── FAIL -> Issues logged for /flow:test

Nyquist Validation

During design, ZFlow maps automated test coverage to each phase requirement before any code is written. This ensures that every committed task has a feedback mechanism to verify it within seconds.

The researcher detects your existing test infrastructure, maps each requirement to a specific test command, and identifies test scaffolding needed before implementation (Wave 0 tasks). The plan-checker enforces this as a verification dimension: plans where tasks lack automated verify commands will not be approved.

Output: {phase}-VALIDATION.md — the feedback contract for the phase.

Disable: Set workflow.nyquist_validation: false in /flow:settings for rapid prototyping where test infrastructure isn't the focus.

Retroactive Validation — /flow:validate

For phases executed before Nyquist validation existed, or for codebases with only traditional test suites:

  /flow:validate N
        │
        ├── Detect state (VALIDATION.md exists? SUMMARY.md exists?)
        ├── Discover: scan implementation, map requirements to tests
        ├── Analyze gaps: which requirements lack automated verification?
        ├── Present gap plan for approval
        ├── Spawn auditor: generate tests, run, debug (max 3 attempts)
        └── Update VALIDATION.md
              ├── COMPLIANT — all requirements have automated checks
              └── PARTIAL — some gaps escalated to manual-only

The auditor never modifies implementation code — only test files and VALIDATION.md. If a test reveals an implementation bug, it's flagged as an escalation for you to address.

When to use: After executing phases planned before Nyquist was enabled, or after /flow:audit surfaces compliance gaps.

Brownfield Workflow (Existing Codebase)

Scan your codebase before starting a project to give ZFlow full context:

  /flow:scan
        │
        ├── Stack Mapper       -> codebase/STACK.md
        ├── Arch Mapper        -> codebase/ARCHITECTURE.md
        ├── Convention Mapper  -> codebase/CONVENTIONS.md
        └── Concern Mapper     -> codebase/CONCERNS.md
                │
        /flow:start   (questions now focus on what you're ADDING)

Command Reference

Core Workflow

| Command | Purpose | When to Use | |---------|---------|-------------| | /flow:start | Full project init: questions, research, requirements, roadmap | Start of a new project | | /flow:start --auto @idea.md | Automated init from a document | Have a PRD or idea doc ready | | /flow:ask [N] | Capture implementation decisions | Before planning, to shape how it gets built | | /flow:design [N] | Research + plan + verify | Before executing a phase | | /flow:build <N> | Execute all plans in parallel waves | After planning is complete | | /flow:test [N] | Manual UAT with auto-diagnosis | After execution completes | | /flow:audit | Verify milestone met its definition of done | Before completing milestone | | /flow:ship | Archive milestone, tag release | All phases verified | | /flow:next [name] | Start next version cycle | After completing a milestone |

Navigation & Session

| Command | Purpose | When to Use | |---------|---------|-------------| | /flow:status | Show status and next steps | Anytime — "where am I?" | | /flow:resume | Restore full context from last session | Starting a new session | | /flow:pause | Save context handoff | Stopping mid-phase | | /flow:help | Show all commands | Quick reference | | /flow:update | Update ZFlow with changelog preview | Check for new versions |

Phase Management

| Command | Purpose | When to Use | |---------|---------|-------------| | /flow:add | Append new phase to roadmap | Scope grows after initial planning | | /flow:insert [N] | Insert urgent work (decimal numbering) | Urgent fix mid-milestone | | /flow:remove [N] | Remove future phase and renumber | Descoping a feature | | /flow:assumptions [N] | Preview Claude's intended approach | Before planning, to validate direction | | /flow:gaps | Create phases for audit gaps | After audit finds missing items | | /flow:research [N] | Deep ecosystem research only | Complex or unfamiliar domain | | /flow:validate [N] | Retroactive test coverage audit | After phases built without Nyquist | | /flow:add-tests [N] | Generate tests for a completed phase | After build, to boost coverage |

Utilities

| Command | Purpose | When to Use | |---------|---------|-------------| | /flow:scan | Analyze existing codebase | Before /flow:start on existing code | | /flow:quick | Ad-hoc task with ZFlow guarantees | Bug fixes, small features, config changes | | /flow:debug [desc] | Systematic debugging with persistent state | When something breaks | | /flow:todo [desc] | Capture an idea for later | Think of something during a session | | /flow:todos | List pending todos | Review captured ideas | | /flow:settings | Configure workflow toggles and model profile | Change model, toggle agents | | /flow:profile <profile> | Quick profile switch | Change cost/quality tradeoff | | /flow:patch | Restore local modifications after update | After /flow:update with local edits | | /flow:clean | Archive phase directories from completed milestones | Housekeeping | | /flow:health | Diagnose planning directory issues | Something seems broken |

Security

| Command | Purpose | When to Use | |---------|---------|-------------| | /flow:security-init | Configure security deny patterns based on your tech stack | Before running a security audit, or at project start | | /flow:security-audit | Comprehensive OWASP Top 10 security audit with structured report | Before release, after major changes, or periodic reviews |

Usage Examples

New Project (Full Cycle)

claude --dangerously-skip-permissions
/flow:start              # Answer questions, configure, approve roadmap
/clear
/flow:ask 1              # Lock in your preferences
/flow:design 1           # Research + plan + verify
/flow:build 1            # Parallel execution
/flow:test 1             # Manual UAT
/clear
/flow:ask 2              # Repeat for each phase
...
/flow:audit              # Check everything shipped
/flow:ship               # Archive, tag, done

New Project from a Document

/flow:start --auto @prd.md   # Auto-runs research/requirements/roadmap from your doc
/clear
/flow:ask 1                   # Normal flow from here

Existing Codebase

/flow:scan                    # Analyze what exists (parallel agents)
/flow:start                   # Questions focus on what you're ADDING
# (normal phase workflow from here)

Quick Bug Fix

/flow:quick
> "Fix the login button not responding on mobile Safari"

Resuming After a Break

/flow:status                  # See where you left off and what's next
# or
/flow:resume                  # Full context restoration from last session

Preparing for Release

/flow:audit                   # Check requirements coverage, detect stubs
/flow:gaps                    # If audit found gaps, create phases to close them
/flow:ship                    # Archive, tag, done

Mid-Milestone Scope Changes

/flow:add                     # Append a new phase to the roadmap
/flow:insert 3                # Insert urgent work between phases 3 and 4
/flow:remove 7                # Descope phase 7 and renumber

Security Audit

/flow:security-init            # Detect tech stack, configure deny patterns
/flow:security-audit           # Full OWASP Top 10 audit with structured report

Reports are saved to .planning/security/YYYY-MM-DD-HHMMSS-security-audit.md.

Speed vs Quality Presets

| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier | |----------|------|-------------|---------|----------|------------|----------| | Prototyping | yolo | coarse | budget | off | off | off | | Normal dev | interactive | standard | balanced | on | on | on | | Production | interactive | fine | quality | on | on | on |

Configuration

Settings live in .planning/config.json. Set during /flow:start or change with /flow:settings.

Core Settings

| Setting | Options | Default | Effect | |---------|---------|---------|--------| | mode | interactive, yolo | interactive | yolo auto-approves decisions; interactive confirms at each step | | granularity | coarse, standard, fine | standard | How finely scope is sliced: 3-5, 5-8, or 8-12 phases | | model_profile | quality, balanced, budget | balanced | Model tier per agent (see breakdown below) |

Full Schema

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "zf/phase-{phase}-{slug}",
    "milestone_branch_template": "zf/{milestone}-{slug}"
  }
}

Planning Settings

| Setting | Default | Effect | |---------|---------|--------| | planning.commit_docs | true | Whether .planning/ files are committed to git | | planning.search_gitignored | false | Add --no-ignore to broad searches to include .planning/ |

If .planning/ is in .gitignore, commit_docs is automatically false regardless of config.

Workflow Toggles

| Setting | Default | Effect | |---------|---------|--------| | workflow.research | true | Domain investigation before planning | | workflow.plan_check | true | Plan verification loop (up to 3 iterations) | | workflow.verifier | true | Post-execution verification against phase goals | | workflow.nyquist_validation | true | Test coverage mapping during design; plan-check enforcement |

Disable these to speed up phases in familiar domains or when conserving tokens.

Git Branching

| Strategy | Creates Branch | Scope | Best For | |----------|---------------|-------|----------| | none (default) | Never | N/A | Solo development, simple projects | | phase | At each /flow:build | One phase per branch | Code review per phase, granular rollback | | milestone | At first /flow:build | All phases share one branch | Release branches, one PR per version |

Template variables: {phase} = zero-padded number (e.g., 03), {slug} = lowercase hyphenated name, {milestone} = version (e.g., v1.0).

Model Profiles (Per Agent)

| Agent | quality | balanced | budget | |-------|-----------|------------|----------| | zf-planner | Opus | Opus | Sonnet | | zf-roadmapper | Opus | Sonnet | Sonnet | | zf-executor | Opus | Sonnet | Sonnet | | zf-phase-researcher | Opus | Sonnet | Haiku | | zf-project-researcher | Opus | Sonnet | Haiku | | zf-research-synthesizer | Sonnet | Sonnet | Haiku | | zf-debugger | Opus | Sonnet | Sonnet | | zf-codebase-mapper | Sonnet | Haiku | Haiku | | zf-verifier | Sonnet | Sonnet | Haiku | | zf-plan-checker | Sonnet | Sonnet | Haiku | | zf-integration-checker | Sonnet | Sonnet | Haiku |

Profile philosophy:

• quality — Opus for all decision-making agents, Sonnet for read-only verification. Best when quota is available and the work is critical.
• balanced — Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
• budget — Sonnet for anything that writes code, Haiku for research and verification. Best for high-volume work or less critical phases.

Troubleshooting

| Problem | Solution | |---------|----------| | Commands not found | Restart your runtime or re-run npx zflow-ai@latest | | Docker path issues | Set CLAUDE_CONFIG_DIR=/home/user/.claude before installing | | Uninstall | npx zflow-ai --claude --global --uninstall |

"Project already initialized"

You ran /flow:start but .planning/PROJECT.md already exists. This is a safety check. To start over, delete the .planning/ directory first.

Context degradation during long sessions

Clear your context window between major commands (/clear in Claude Code). ZFlow is designed around fresh contexts — every subagent gets a clean 200K window. If quality drops in the main session, clear and use /flow:resume or /flow:status to restore state.

Plans seem wrong or misaligned

Run /flow:ask [N] before planning. Most plan quality issues come from Claude making assumptions that CONTEXT.md would have prevented. You can also run /flow:assumptions [N] to preview Claude's approach before committing to a plan.

Execution fails or produces stubs

Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.

Lost track of where you are

Run /flow:status. It reads all state files and tells you exactly where you are and what to do next.

Need to change something after execution

Don't re-run /flow:build. Use /flow:quick for targeted fixes, or /flow:test to systematically identify and fix issues through UAT.

Model costs too high

Switch to budget profile: /flow:profile budget. Disable research and plan-check agents via /flow:settings if the domain is familiar.

Working on a sensitive / private project

Set commit_docs: false during /flow:start or via /flow:settings. Add .planning/ to .gitignore. Planning artifacts stay local and never touch git.

ZFlow update overwrote my local changes

Since v1.17, the installer backs up locally modified files to zf-local-patches/. Run /flow:patch to merge your changes back.

Subagent appears to fail but work was done

A known workaround for a Claude Code classification bug. ZFlow's orchestrators spot-check actual output before reporting failure. If you see a failure message but commits were made, check git log — the work may have succeeded.

Recovery Quick Reference

| Problem | Solution | |---------|----------| | Lost context / new session | /flow:resume or /flow:status | | Phase went wrong | git revert the phase commits, then re-plan | | Need to change scope | /flow:add, /flow:insert, or /flow:remove | | Milestone audit found gaps | /flow:gaps | | Something broke | /flow:debug "description" | | Quick targeted fix | /flow:quick | | Plan doesn't match your vision | /flow:ask [N] then re-plan | | Costs running high | /flow:profile budget + /flow:settings to toggle agents off | | Update broke local changes | /flow:patch | | Need a security review | /flow:security-init then /flow:security-audit |

Project File Structure

.planning/
  PROJECT.md                # Project vision and context (always loaded)
  REQUIREMENTS.md           # Scoped v1/v2 requirements with IDs
  ROADMAP.md                # Phase breakdown with status tracking
  STATE.md                  # Decisions, blockers, session memory
  config.json               # Workflow configuration
  MILESTONES.md             # Completed milestone archive
  research/                 # Domain research from /flow:start
  todos/
    pending/                # Captured ideas awaiting work
    done/                   # Completed todos
  security/                 # Security audit reports
  debug/                    # Active debug sessions
    resolved/               # Archived debug sessions
  codebase/                 # Brownfield codebase mapping (from /flow:scan)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md         # Atomic execution plans
      XX-YY-SUMMARY.md      # Execution outcomes and decisions
      CONTEXT.md            # Your implementation preferences
      RESEARCH.md           # Ecosystem research findings
      VERIFICATION.md       # Post-execution verification results
      XX-VALIDATION.md      # Nyquist test coverage contract

AI is powerful. ZFlow makes it reliable.