Draft v0.1 (Public-facing executive overview · Authored by ADMIN-01, 2026-05-09)
What is this? A 5-minute read for first-time visitors to understand CodeFlow's positioning, philosophy, architecture, and roadmap.
- ADMIN 5/9 10:48 — "This project folder is the CodeFlow project; we currently use Cursor's SDK and consume
fcop-mcp." (identity + tech stack)- ADMIN 5/9 10:51 — "CodeFlow's true positioning is: a lightweight AI Runtime / AI OS for multi-agent software development." (true positioning)
Original verbatim Chinese quotes + interpretation table: see design doc §0.0.
Official positioning (consistent with the design doc):
CodeFlow AI Runtime A lightweight AI Operating Runtime for multi-agent software development. Mobile-first AI Runtime for governable multi-agent software development.
| Who you are / what you want | Read which |
|---|---|
| 5 minutes to grok what CodeFlow is | This file (overview) |
| Pitching to non-technical readers / decision makers / investors | This file (overview) |
| Going to implement / write code / plan sprints | Design doc (~1900 lines) |
| Looking for specific fields / schemas / APIs | Design doc §3 |
| Want to know what to do next week | Design doc §10 |
| Want to know why this design | Design doc §0.5 / §0.6 / §0.7 |
Sync rule when editing:
- Change "what we say externally, product positioning, narrative for non-technical readers" → edit this file
- Change "implementation, field definitions, sprint plans, technical decisions" → edit the design doc
- Concept appears in both → the design doc is source of truth; this file is the simplified narrative
CodeFlow is NOT:
- An AI chat tool
- A Cursor plugin
- An auto-codegen tool
CodeFlow's true positioning:
A lightweight AI Runtime / AI OS for multi-agent collaborative software development.
Solving:
Multiple AI agents cannot collaborate stably over time.
Including:
- Agent drift
- State loss
- Lack of auditability
- Long-task chaos
- No governance mechanism
- No state recovery
Traditional agents:
State lives inside context.
Problems:
- Unstable
- Easily lost
- Not auditable
CodeFlow:
AI state → file → protocol → governable
CodeFlow does NOT depend on:
- A single model
- A single IDE
- A single agent
Instead:
Constrain agent behavior via the FCoP protocol.
What enterprises actually need is not:
A more autonomous AI.
But:
Auditable, recoverable, governable AI.
┌────────────────┐
│ Mobile Console │
└───────┬────────┘
↓
┌────────────────┐
│ CodeFlow Runtime│
└───────┬────────┘
┌───────────────┼──────────────┐
↓ ↓ ↓
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Task Store │ │ Agent Core │ │ Review Sys │
└────────────┘ └────────────┘ └────────────┘
↓
┌────────────────┐
│ Skill Runtime │
└───────┬────────┘
↓
┌────────────────────┐
│ Cursor / Claude SDK│
└────────────────────┘
Responsibilities:
- Manage Task lifecycle
- Manage Agent Sessions
- Schedule agents
- Control state transitions
- Recover from failures
INIT
↓
PLANNED
↓
EXECUTING
↓
REVIEWING
↓
APPROVED / REJECTED
↓
DONE
External state names ↔ internal protocol state names (implementation: design doc §3.3 Task Schema):
External (this doc) Internal (FCoP / Task Schema) INIT (Task file not yet created) PLANNED pendingEXECUTING dispatched→in_progressREVIEWING reviewAPPROVED → DONE doneREJECTED back to in_progress, loop ≤ N times(anomaly) blocked/cancelled
Single hard rule: every task MUST be filed. If it isn't written down, it didn't happen.
CodeFlow's Task format evolves in two stages:
Each Task is a single Markdown file, named by "sender → recipient":
fcop/tasks/
├── TASK-20260509-001-PM-to-DEV.md ← Task body
├── REPORT-20260509-001-DEV-to-PM.md ← Execution report
└── REVIEW-20260509-001-QA-on-TASK-001.md ← Review verdict
This "filename = protocol" is the core of FCoP, and v0.1 must be 100% compatible with it. Details: design doc §3.3.
As tasks grow (one Task may produce plan / execution / result artifacts), it will evolve to a directory structure:
tasks/
└── TASK-001/
├── task.md # Goal + Constraints
├── plan.md # PM breakdown
├── execution.md # DEV implementation log
├── result.md # Final artifact index
└── review.md # Review verdict
⚠️ v0.1 does NOT enforce directory format — the evolution path stays backward-compatible: file-based and folder-based Tasks can coexist as long as YAML front-matter stays consistent.Note: FCoP itself is still pre-1.0, so directory format may be promoted into the FCoP main spec in 1.1 / 2.0. Details: design doc §3.3.1.
# Goal
Implement user login.
# Constraints
- Use JWT
- Do not modify the database schema# Review
## Security
✅ No dangerous operations.
## Architecture
⚠️ Need to add token expiration mechanism.CodeFlow does NOT pursue:
A super-agent that does everything.
Instead:
Specialized role agents.
- PM Agent
- DEV Agent
- REVIEW Agent
- TEST Agent
- ARCHITECT Agent
{
"agent_id": "DEV-01",
"role": "developer",
"status": "running",
"task_id": "TASK-001"
}One of CodeFlow's core systems:
AI must be audited.
Rule-based audit:
Forbidden:
- DELETE
- DROP
- rm -rf
AI-based review:
- Does it match the task goal?
- Are there risks?
- Has the agent drifted?
Future support:
- Cursor
- Claude Code
- Codex
- VSCode Agent
A Session is no longer:
A chat window.
But:
A long-running agent process.
One of CodeFlow's biggest differentiators:
The AI Runtime is governable from a phone.
The mobile end is NOT a chat box. It is:
An AI Team Console.
TASK-001
Status: Reviewing
Owner: DEV-01
DEV-01: running
REVIEW-01: auditing
⚠️ High-risk operation:
Allow execution?
🛑 Stop all agents
FCoP is NOT a prompt.
It is:
An AI Runtime Protocol.
- Task protocol
- State protocol
- Review protocol
- Agent protocol
- Collaboration protocol
Enable:
Stable cross-agent collaboration.
This is the public-facing high-level roadmap (5 milestones). The detailed sprint plan (v0.1 → v1.0, ~26 weeks) is in design doc §10 Implementation Roadmap.
Goal:
Local zero-UI run-through: PM → DEV → REVIEW → DONE filed loop.
Includes:
- Task Runtime
- Review Engine (core)
- Session persistence
- Auto-recovery after process crash
Excluded: mobile / cloud / skill marketplace / enterprise permissions / any GUI.
Goal:
AI runs 24/7; ADMIN can approve and emergency-stop from the couch.
Includes:
- Mobile Console (4 screens: Task Flow / Agent status / Audit / Approval)
- Human-in-the-loop (high-risk ops require mobile approval)
- 🛑 Emergency Stop
Excluded: cloud nodes (deferred to v0.3+) / writing tasks from mobile / multi-device sync.
| Version | Theme | Key capability |
|---|---|---|
| v0.3 | AI Patrol | PATROL agent monitors 5 anomaly classes (drift / hang / over-permission / unresponsive / protocol violation) |
| v0.5 | Review Board | REVIEW + SECURITY + AUDIT triangle consensus; single reviewer cannot approve high-risk tasks alone |
Goal:
Freeze the Runtime Protocol (5 schemas) so the ecosystem can grow on top.
Acceptance criteria (3 of 4): ≥3 third-party implementations / 90 days no breaking change / ≥1 essay summarizing protocol evolution / pass schema fuzz tests.
Continue evolving toward:
AI Operating System — see §8 Long-term Vision.
Future enterprise workflow:
Human
↓
CodeFlow Runtime
↓
Multiple AI Agents
↓
Business Systems / IDE / Cloud
Instead of:
Human → ERP → Manual Operation
ERP's essence is "let a group of humans collaborate stably around business processes." The AI OS's essence is "let a group of AI agents collaborate stably around business processes."
| Dimension | Traditional ERP | AI OS (CodeFlow's endgame) |
|---|---|---|
| Collaboration agents | Humans + processes + forms | AI agents + protocols + Task files |
| State medium | Database + ticket system | FCoP files + Runtime state |
| Governance | Approval flows / permission matrix | Review Engine + Human-in-the-loop |
| Human intervention | Most operations | High-risk decision points (mobile approval) |
| Observability | BI reports | Runtime event stream + audit log |
It's not that AI OS will "replace" ERP — the realistic evolution is: AI OS dilutes the "humans-execute-process" portion of ERP, and ERP degrades into one of the business systems that AI agents call into.
Details: design doc §0.6.6 Endgame: AI OS may be the next-generation ERP.
AI's problem has never been "not smart enough."
It is:
"Cannot collaborate and run stably over time."
CodeFlow's goal:
Provide AI teams with Runtime, Protocol, and Governance.
| What you want to know | Jump to design doc |
|---|---|
| 1-screen exec summary | §0.0 Executive Summary |
| Why this design (AI OS prototype / 3-layer stack / moat) | §0.5 / §0.6 / §0.7 |
| What's in/out of scope for phase 1 | §0.8 First-phase scoping |
| How mobile governance works (4 screens / HITL / Emergency Stop) | §0.9 Mobile-first Governance |
| 5 Runtime Schemas (Agent/Task/Review/Session/Skill) | §3 Runtime Protocol |
| Sprint-level plan | §10 Implementation Roadmap |
| Want to run a demo | §0.8.3 Hello World acceptance script |
docs/
├── codeflow-overview.md ← Chinese
├── codeflow-overview.en.md ← English (you are here)
└── design/
└── codeflow-v2-on-fcop-sdk.md ← Full design doc (~1900 lines, ~60 min)
After reading this page, you should be able to answer the following 5 questions without looking. If any one stumps you, re-read the section it points to.
| # | Question | Section |
|---|---|---|
| 1 | What is CodeFlow NOT? Why insist "not a Cursor plugin"? | §1 |
| 2 | What does "AI state externalization" mean? What goes wrong without it? | §2.1 |
| 3 | Why is the Review Engine called a "core system"? What's the difference from generic agent frameworks without it? | §4.4 |
| 4 | Why is mobile not a chat box but an "AI Team Console"? | §5 |
| 5 | What is v0.1's single goal? Can you start v0.2 if v0.1 hasn't passed? | §7 v0.1 |
Bonus questions (if you can answer these, you're at the decision-maker level):
-
- Why is CodeFlow's true moat Agent Governability, not UI / prompt / model? → Design doc §0.6.7
-
- Why is v2's core deliverable the 5 Schemas, not an "application"? → Design doc §3 + §0.6.8 (Docker eve analogy)
Heads-up before you go:
After every major edit to this page, please re-check §0.0 Executive Summary in the design doc. These two files together form CodeFlow v2's "public face." Any change to core concepts (positioning / moat / roadmap cadence / mobile shape) requires updating both sides.