ZenFlow

ZenFlow is a Claude Code plugin that structures the development process into discrete stages. Rather than a single open-ended session, each piece of work moves through defined steps: idea, plan, execution, validation, and review. Each stage is a separate command with its own inputs, outputs, and quality expectations.

The plugin includes enforcement hooks that prevent skipping stages — for example, you cannot end an execution session without running check-work first.

ZenFlow is derived from Superpowers by Jesse Vincent.

Read the Philosophy — Why zenflow frames human-AI interaction as a practice, not a productivity hack.

WARNING

This plugin is under active development. APIs, commands, and behavior may change without notice.

Installation

/plugin marketplace add brewpirate/zenflow
/plugin install zenflow@zen
/plugin install field-notes@zen
/reload-plugins

Installing field-notes alongside is recommended — zenflow:check-work invokes it automatically in Gate 5.

Setup

After installing, generate the project config:

/zenflow:init

This creates .claude/zen.local.md with YAML frontmatter for structured settings and a markdown body for freeform notes. It auto-detects your project's language, framework, documentation paths, and maps codebase sections to agents. Review the generated file and adjust before running the pipeline.

Pipeline

The core workflow moves through five stages:

idea → plan → [dispatch | exec-plan] → check-work → review

See The Pipeline for a full breakdown of each stage.

Collab — The Crown Jewel

/zenflow:collab is where the real work happens. It opens a long-running partnership session with Claude Opus — not a task executor, but a thinking partner that explores, reasons, and creates GitHub issues alongside you.

The agent stays in strategist mode: it reads code with you, surfaces trade-offs, spawns research subagents, and creates well-structured issues for implementation. The user launches Builder agents (/build #N) to implement and Reviewer agents (/review #N) to verify — every decision surfaced via AskUserQuestion. When the session gets long, a context refresh sheds dead context without losing the partnership.

See Collab for the full reference, session patterns, and worked examples.

Standalone Commands

Several commands work outside the pipeline:

• /zenflow:collab — long-running collaborative session (Opus). See Collab.
• /zenflow:bug-fix — runs a four-agent diagnostic pipeline to identify and fix a bug.
• /zenflow:docs — creates or updates project documentation.
• /zenflow:context-refresh — sheds accumulated context mid-session via a structured handoff.

Temporarily removed: /zenflow:audit, /zenflow:refactor, /zenflow:review, /zenflow:status, and the testing-anti-patterns skill were pruned on 2026-04-15 — tracked in issues #8–#12 for restoration.

Hooks

Three enforcement hooks install automatically with the plugin:

Hook	Type	Behavior
enforce-plan-mode-tools	Stop	In plan mode, prevents ending a turn without calling ExitPlanMode or AskUserQuestion
enforce-work-validation	Stop	After exec-plan or dispatch, prevents finishing without running check-work
enforce-local-plans	PreToolUse	Redirects plan writes from ~/.claude/plans/ to the project's resources/plans/ directory

See Hooks for more detail.