Flow

Built for codebases you didn't start clean. Discipline in the system. Execution in the model.

Flow is a spec-driven agentic development workflow for solo developers. It carries planning discipline, cross-session memory, and verification in the system — so messy codebases get mapped accurately and worked within, not pretended clean.

Flow installs command and agent contracts for OpenCode, Codex App / CLI, and Zed Editor on macOS, Linux, and Windows. For Pi, Flow ships as a native Pi package: the /flow prompts, the three package-owned roles, and the flow_agent / flow_tools tools, managed entirely by Pi. Child creation is performed by each host's native subagent mechanism; when that capability is unavailable, Flow fails closed instead of doing the work inline.

---

Table of Contents

• Quick Start
• Install
• How It Works
• Commands
• Agents
• Safety
• Model Agnosticism
• Configuration
• Folder Structure
• Troubleshooting
• Contributing
• License
• Acknowledgement

---

Quick Start

Any repo — new or existing

cd path/to/your-repo
npx @linggihlukis/flow --opencode   # or --codex / --zed / --all
# restart or reload your runtime, then:
/flow-init   # detects greenfield vs brownfield, maps, scaffolds
/flow "your first Work Item goal — one sentence"

Every Work Item

/flow "goal sentence — one Work Item"   ← Plan → Execute → Review → Complete
/flow-status                              ← where am I, is the map stale
/flow-map [--scope dir] [--symbols]       ← refresh .flow/map.json when stale

---

Install

npx @linggihlukis/flow --opencode     # OpenCode
npx @linggihlukis/flow --codex        # Codex App / CLI
npx @linggihlukis/flow --zed          # Zed Editor (shares ~/.agents/skills with Codex)
npx @linggihlukis/flow --all          # all three (dedupes shared skills once)

Flag	Description
--update	Update in place (runtime artifacts overwritten; .flow/ data preserved)
--uninstall	Remove Flow commands/agents/skills (preserves .flow/ scaffold)
--yes	Non-interactive — skip prompts without TTY
--dry-run	Preview project scaffold/AGENTS.md changes with --scaffold
--force	With --scaffold, proceed when .flow/work-items/ is non-empty (existing Work Items are kept)
--update-agents	With --scaffold, update the Flow section in AGENTS.md

Update from inside your project:

npx @linggihlukis/flow@latest --update

Install is global-only: tools live in ~/.flow/tools, the scaffold (.flow/ + AGENTS.md marker) lives in your repo and belongs to /flow-init. Updates never touch .flow/state.md, .flow/memory.md, .flow/map.json, or .flow/work-items/.

Upgrading from 0.4.x is breaking: --update refreshes runtime artifacts and tools but does not migrate project .flow/ data. 0.4 milestone/phase state (state.json, config.json, milestones/, codebase/, milestone-shaped state.md) is not compatible with 0.5. Back up .flow/, remove obsolete 0.4 artifacts, and run /flow-init for a clean 0.5 scaffold (carry durable memory over manually). /flow-status reports whether current state validates.

Runtime	Global path
OpenCode	~/.config/opencode/commands/
Codex App / CLI	~/.agents/skills/ + ~/.codex/agents/ (TOML agents)
Zed Editor	~/.agents/skills/ (shared with Codex — written once)
Pi	~/.pi/agent/npm/node_modules/@linggihlukis/flow/ (managed by Pi)

Pi (native package)

pi install npm:@linggihlukis/flow    # /flow prompts + flow_agent + flow_tools, managed by Pi
pi update npm:@linggihlukis/flow     # update the Pi package only
pi remove npm:@linggihlukis/flow     # remove the Pi package; project .flow/ data is preserved

Pi owns its managed package directory and never touches ~/.flow/tools/, OpenCode, Codex, or Zed artifacts. The legacy installer never touches the Pi package or Pi settings. Project .flow/ data is shared by both installations and is never modified by installing, updating, or removing either one. Updating both installations requires two explicit commands:

pi update npm:@linggihlukis/flow
npx @linggihlukis/flow@latest --update

---

How It Works

/flow-init             →  once per repo — Detect → Map → Infer → Propose → Write
       ↓
/flow "goal"          →  every Work Item — Plan → Execute → Review → Complete
       ↓
     Plan    →  Planner role reads map + memory + source → plan.md + tasks/
     Execute →  Executor role per task: Read → Change → Verify → Report (one commit)
     Review  →  Reviewer role reads cold → accepted | revise
       ↓
repeat per Work Item — scales by tasks (1 → N), not ceremony

• Work Items are the fundamental unit — one goal, one work-item.md contract. No milestones or phases.
• Tasks are atomic execution units: one deliverable, one runnable Verify (non-zero on fail), Depends on: none | task-NN. The hard contract (Context / Implementation Steps / Files / Verify / Done Condition / Depends on, plus lifecycle status) is machine-validated; Read First, Scope, confidence, and commit message are optional guidance.
• memory.md is cross–Work Item truth (Facts / Decisions / Lessons), curated not appended. Only /flow writes it, applying validated Reviewer proposals after approval.
• map.json is a file-level structural index (flow-map-v1), git-aware and sensitive-safe. Symbols (--symbols) and hashes (--hash) are opt-in. The map narrows discovery; source is always truth.
• state.md records lifecycle position (active_work_item, status, updated_at, git_commit, per-repo execution context). Only /flow mutates it.

The tool layer (bin/flow-tools.js + bin/lib/) is a deterministic dispatcher: contract validation, Work Item allocation, task gates, Git safety checks, and memory apply. It never spawns agents — the host owns execution.

---

Commands

Four only.

Command	What it does
/flow-init	Once per repo — Detect → Map → Infer → Propose → Write. Flags: --yes, --dry-run, --force, --scope <dir>
/flow "goal"	Every Work Item — create/continue → Plan → Execute → Review → Complete
/flow-map	Refresh .flow/map.json. Flags: --scope, --symbols and --hash (opt-in)
/flow-status	Show state.md + Work Items + map staleness + memory count

For a new goal, /flow confirms a concrete goal, constraints, and binary Done Condition, then calls the narrow work-item create primitive (--actor flow). It allocates the next work-item-NNN, writes only work-item.md plus empty tasks/, and returns planning_required: true — no plan.md, no state activation until Planner output validates.

---

Agents

Agent	When	What it does
Planner role	Plan stage	Research evidence + plan.md + atomic task files. Never edits source.
Executor role	Per task	Implements one task, runs Verify, commits, reports. Never touches state/memory.
Reviewer role	Review stage	Cold contract + evidence check, failure diagnosis; proposes memory changes but never writes them.

The Reviewer combines critic, verifier, and debugger in one pass — no separate agents, no extra handoffs. Tasks failing the minimal contract are rewritten before execution; there is no override. If the host cannot create a required child, /flow stops and reports the capability failure. No inline fallback, no sequential fallback.

---

Safety

• Confirm before creating — /flow stops on missing or ambiguous goal, constraints, or Done Condition rather than inventing placeholders.
• Evidence before code — confirmed findings land in plan.md ## Discoveries with evidence; unresolved items stay in ## Unknowns, never promoted to memory.
• Task gate — every task passes deterministic verification, declared-scope, and Git safety (repo root, branch, HEAD) checks before its one commit. Failed gates route or block; never bypassed.
• Protected branches — the Executor stops for explicit user confirmation before staging or committing on main/master.
• Ownership — only /flow writes state.md and memory.md. Children report through host sessions.
• Child permissions (known debt) — hosts still grant children shell and file tools, so ownership is enforced by instruction plus the --actor flow gate, not host permissions. Fail closed where safe operation depends on it.

Failure	Action
Task fails verification	Stop at the gate, route to the responsible role
Agent confused or looping	Stop, report the host or contract problem
Task doesn't match codebase reality	Stop, document divergence, surface options

---

Model Agnosticism

Flow is model-agnostic: no config.json, no model routing. Reliability comes from evidence plus bounded tasks plus explicit verification, not from model choice. Stronger models produce better plans and sharper Verify commands; the validator and gate enforce the minimum regardless.

Guarantee	Why it holds
State persists across sessions	Written to disk after every meaningful action
One task, one commit	Enforced by the gate, not by inference
Human-gated checkpoints	No model can skip them
Curated memory	Only validated, approved proposals applied

---

Configuration

No configuration by default. Two opt-ins:

• Symbols — map index --symbols needs tree-sitter-wasms + web-tree-sitter@0.20.8 in ~/.flow/tools. Default indexing is file-level and needs nothing. New languages are picked up from installed tree-sitter-*.wasm files on --update.
• Index scope — map index skips node_modules, .git, .flow, and vendor. Everything else is scanned.

---

Folder Structure

Commit .flow/ to git — it is your project's persistent memory.

project-root/
├── AGENTS.md                              ← system rules, every agent reads first
└── .flow/
    ├── state.md                           ← active_work_item + status + git context
    ├── memory.md                          ← Facts / Decisions / Lessons
    ├── map.json                           ← file-level index (refresh via /flow-map)
    └── work-items/
        └── work-item-NNN/
            ├── work-item.md               ← the contract (goal, constraints, done condition)
            ├── plan.md                    ← the solution record
            └── tasks/
                └── task-XX.md             ← atomic task (runnable Verify; revise in place)

Runtime tools live in ~/.flow/tools/ (managed by the installer — do not edit). Never add .flow/ to .gitignore.

---

Troubleshooting

Commands not showing up? Restart your runtime after installing. Check the runtime paths above.

npx serving a stale version? Always update with @latest: npx @linggihlukis/flow@latest --update.

Flow cannot delegate a child agent? Fail-closed by design — the host owns child creation and install files alone can't verify it. Report the host limitation; Flow never performs Planner, Executor, or Reviewer work inline.

map index --symbols fails? Symbols are opt-in. File-level indexing needs no WASM. For symbols, run:

cd ~/.flow/tools
npm install js-yaml web-tree-sitter@0.20.8 tree-sitter-wasms

Parser.init is not a function means the wrong web-tree-sitter version is installed; pin 0.20.8.

---

Contributing

Solo-maintained. Issues and feature requests welcome — open a GitHub issue.

---

License

MIT

---

Acknowledgement

Developed with reference to GSD by TÂCHES, which shaped early thinking about spec-driven agentic workflows. Flow has since become a different system with different goals and architecture.