Flow-Code

<div align="center">

**[English](README.md)** | **[中文](README_CN.md)**

# Flow-Code

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://claude.ai/code)

[![Version](https://img.shields.io/badge/Version-0.1.24-green)](../../CHANGELOG.md)

[![Status](https://img.shields.io/badge/Status-Active_Development-brightgreen)](../../CHANGELOG.md)

**A production-grade harness for Claude Code. Full-auto development from idea to PR.**

**Zero external dependencies. Zero questions asked.**

</div>

---

### What is Harness Engineering?

> *"The model is commodity; the harness is moat."* — [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), [OpenAI](https://openai.com/index/harness-engineering/), [Mitchell Hashimoto](https://mitchellh.com/writing/my-ai-adoption-journey)

A **harness** wraps around an AI coding agent to handle everything the model can't do alone: state management, context bridging, quality gates, multi-agent coordination, and error recovery. Flow-Code is a complete harness for Claude Code.

### How Flow-Code Compares

| Capability | Flow-Code | [compound-engineering](https://github.com/EveryInc/compound-engineering-plugin) (12.5K⭐) | [claude-mem](https://github.com/thedotmack/claude-mem) (44K⭐) | [superpowers](https://github.com/anthropics/claude-plugins-official) |
|---|---|---|---|---|
| Task DAG + state machine | ✅ 37 commands, deps, split/skip | ❌ | ❌ | ❌ |
| Parallel Teams + file lock | ✅ Agent Teams, atomic locks | ❌ | ❌ | ✅ parallel agents (no locks) |
| Three-layer quality | ✅ guard + RP + Codex adversarial | ❌ | ❌ | ❌ |
| Runtime DAG mutation | ✅ split/skip/dep rm mid-execution | ❌ | ❌ | ❌ |
| Cross-model adversarial review | ✅ GPT tries to break Claude's code | ❌ | ❌ | ❌ |
| Full-auto (zero questions) | ✅ AI decides branch/review/depth | ❌ | ❌ | ❌ |
| Context preservation | ✅ PreCompact hook | ❌ | ✅ embedding + RAG | ❌ |
| Auto draft PR | ✅ | ❌ | ❌ | ❌ |
| Zero dependencies | ✅ single Rust binary + Bash skills | ❌ Node.js | ❌ ChromaDB | ❌ Node.js |

---

## Table of Contents

- [What Is This?](#what-is-this)
- [Why It Works](#why-it-works)
- [Quick Start](#quick-start) — Install, setup, use
- [When to Use What](#when-to-use-what) — Interview vs Plan vs Work
- [Agent Readiness Assessment](#agent-readiness-assessment) — `/flow-code:prime`
- [Troubleshooting](#troubleshooting)
- [Codebase Map](#codebase-map) — Architecture documentation via parallel subagents
- [Auto-Improve](#auto-improve-autonomous-optimization) — Autonomous code optimization
- [Ralph (Autonomous Mode)](#ralph-autonomous-mode) — Run overnight
- [Features](#features) — Re-anchoring, multi-user, reviews, dependencies
- [Commands](#commands) — All slash commands + flags
  - [Command Reference](#command-reference) — Detailed input docs for each command
- [The Workflow](#the-workflow) — Planning and work phases
- [.flow/ Directory](#flow-directory) — File structure
- [flowctl CLI](#flowctl-cli) — Direct CLI usage

---

## What Is This?

Flow-Code is a **harness engineering framework** for Claude Code. One command goes from idea to draft PR — planning, parallel implementation, three-layer quality gates, and cross-model adversarial review, all fully automated.

```
/flow-code:plan "Add OAuth login"
  → AI research (adaptive scouts)
  → RP plan-review (code-aware)
  → Teams parallel workers (file locking)
  → guard per-commit (Layer 1)
  → Codex adversarial (Layer 3: GPT tries to break it)
  → auto push + draft PR
```

Everything lives in your repo as `.flow/` state. No external services. No global config. Single Rust binary + Bash skills. Uninstall: delete `.flow/`.

<table>
<tr>
<td><img src="../../assets/flow-code-plan.png" alt="Planning Phase" width="400"/></td>
<td><img src="../../assets/flow-code-work.png" alt="Implementation Phase" width="400"/></td>
</tr>
<tr>
<td align="center"><em>Planning: dependency-ordered tasks</em></td>
<td align="center"><em>Execution: fixes, evidence, review</em></td>
</tr>
</table>

---

## Epic-first task model

Flow-Code does not support standalone tasks.

Every unit of work belongs to an epic fn-N (even if it's a single task).

Tasks are always fn-N.M and inherit context from the epic spec.

Flow-Code always creates an epic container (even for one-offs) so every task has a durable home for context, re-anchoring, and automation. You never have to think about it.

Rationale: keeps the system simple, improves re-anchoring, makes automation (Ralph) reliable.

"One-off request" -> epic with one task.

---

## Why It Works

### Full-Auto by Default

Say one sentence. Flow-Code plans, implements, tests, commits, and opens a draft PR — zero questions asked. AI reads git state and `.flow/` config to make all decisions (branch, review backend, research depth) autonomously.

```bash
# Full auto: plan → implement → test → commit → draft PR
/flow-code:pl

... (truncated)