zk-flow is a local, interactive Claude Code dynamic-/workflows system that runs software-engineering lifecycles -- research, design, implementation, review, and testing -- as orchestrated subagent workflows. You invoke a workflow from a Claude Code session (/feature "add OAuth", /review depth=standard), and zk-flow drives a pipeline of specialized subagents through ordered phases, gate loops, and fan-out steps until the work is done or a human decision is needed. No daemon, no external orchestrator, no cloud service -- it runs entirely inside Claude Code.

# 1. Clone and install
git clone https://github.com/matt-metivier/zk-flow ~/dev/zk-flow
cd ~/dev/zk-flow && npm install

# 2. Initialize bd (required — workflows fail fast without it)
bd init

# 3. Set ZK_ARTIFACTS_DIR (required — skill/persona/vault lookup fails without it)
echo 'export ZK_ARTIFACTS_DIR="$HOME/dev/zk-artifacts"' >> ~/.zshrc
source ~/.zshrc

# 4. Symlink into Claude Code global config
ln -s ~/dev/zk-flow/.claude/commands   ~/.claude/commands
ln -s ~/dev/zk-flow/.claude/workflows  ~/.claude/workflows
cp ~/dev/zk-flow/.claude/agents/*.md   ~/.claude/agents/

# 5. Build workflows
npm run build

# 6. Verify
/health   # (inside a Claude Code session rooted in ~/dev/zk-flow)

export ZK_ARTIFACTS_DIR="$HOME/dev/zk-artifacts"   # skills, vault, personas
export ZK_VAULT_DIR="$ZK_ARTIFACTS_DIR/vault"        # optional convenience alias

git clone https://github.com/matt-metivier/zk-flow.git
cd zk-flow
npm install          # runs prepare -> build.js -> generates .claude/workflows/*.js

Open Claude Code in the zk-flow directory, then run a workflow:

/feature "add rate limiting to the API"
/review depth=standard
/bugfix "login fails when email has uppercase letters"
/research "evaluate tradeoffs between Postgres and DynamoDB for this use case"

Slash commands (/feature, /review, etc.) only resolve inside the directory where .claude/commands/ lives. After running npm run build, pick one of three install options:

(a) Global install -- commands available in every repo:

cp -r .claude/commands   ~/.claude/commands
cp -r .claude/workflows  ~/.claude/workflows
cp -r .claude/agents     ~/.claude/agents

Set $ZK_ARTIFACTS_DIR in your shell profile as before. The built .claude/workflows/*.js files must be present (run npm run build first). Tradeoff: one shared version -- all repos get the same copy until you re-copy.

(b) Per-repo copy -- isolated, independently upgradeable:

cp -r /path/to/zk-flow/.claude /your/repo/.claude

Re-copy whenever you pull updates from zk-flow. Tradeoff: multiple copies to keep in sync.

(c) Symlink -- single source of truth, always current:

ln -s /path/to/zk-flow/.claude /your/repo/.claude

Any npm run build in zk-flow immediately applies everywhere the symlink is used. Tradeoff: all symlinked repos move together on every update.

zk-flow is organized in five layers: workflows (orchestration -- phase order, gate loops, fan-out, handoff boundaries), agents (subagents: a prompt + model + tools), skills (domain how-to loaded from $ZK_ARTIFACTS_DIR), schemas (JSON contracts that validate each phase's output), and memory (beads for structured run state + vault for prose knowledge). A workflow invokes agents, agents produce schema-validated JSON, and the workflow decides what runs next based on the verdict. Human approval is modeled as a handoff: the workflow writes a continuation doc and stops; you resume it explicitly.

See docs/architecture.md for the full five-layer breakdown, gate loop mechanics, the two-run feature seam, and schema validation contracts. See docs/using-schemas-externally.md for how to validate schema contracts when dispatching agents outside the /workflows runtime.

Generated files: .claude/workflows/*.js are built from src/workflows/*.src.js and are gitignored. npm run build (or npm install) regenerates them. Never edit the generated files directly.

Each phase uses an appropriate model tier by default. Override per run with model=<tier> (global) or models=<phase>:<tier>,... (per-phase):

Example: /feature model=fast "..." runs all phases on haiku (cheap demo mode). Example: /feature models=research:deep,impl:fast "..." deep research, cheap impl.

zk-flow workflows load domain skills, prose knowledge (vault), and operator personas from a companion repo at $ZK_ARTIFACTS_DIR. This is completely optional -- if the variable is unset, agents skip skill/vault lookups and run on their base prompts alone.

See docs/zk-artifacts-setup.md for setup steps and the skill frontmatter template.

npm test        # unit tests for src/fragments (pure logic) + build validity guard
npm run build   # regenerate .claude/workflows/*.js from src/workflows/*.src.js

Test suite: 9 test files covering args parsing, bd-command builders, budgets, depth map, handoff, model tiers, schemas, verdict routing, and a build validity guard that asserts every *.src.js builds clean (has export const meta, no leftover markers, no import lines, parses as valid JS).

Layout:

src/
  fragments/     pure helpers (inlined at build time: args, bd-memory, ci-loop, ...)
  workflows/     *.src.js workflow bodies (source of truth)
build.js         build script: inlines fragments, writes .claude/workflows/*.js
.claude/
  agents/        22 subagent definitions (YAML frontmatter + prompt body)
  commands/      saved slash commands (one per workflow)
  workflows/     GENERATED -- gitignored, do not edit
schemas/         JSON output contracts for each phase
docs/
  architecture.md
  workflows/     per-workflow reference docs (args, agents, schemas, mermaid diagrams)
  using-schemas-externally.md
  zk-artifacts-setup.md

Apache-2.0 -- see LICENSE.