Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

docs(readme): tighten intro, add promo video, table-based quick start (#44)

Yanami-2K3c1b4e1004e5
diff --git a/README.md b/README.md
index 2dcbed76..773dd54b 100644
--- a/README.md
+++ b/README.md
@@ -4,94 +4,76 @@ English | [简体中文](README.zh-CN.md)
**Make coding agents deliver through a workflow you can confirm, review, and resume—not just produce code.**
-Giving a coding agent a request is easy. The hard part is making sure it understands the goal before coding, stays within scope during implementation, and completes independent review and testing before it stops. Longer tasks also lose context, get interrupted, and leave behind a diff with little explanation of how it was produced.
+LoopForge installs into the coding agent you already use: CodeBuddy, Codex, Cursor, Claude Code, or Pi. Inside that agent it runs a role-based delivery workflow. The requirement is clarified and confirmed first, then the work is designed, implemented, reviewed by a different role from the one that wrote the code, and tested. Stages run one after another, each handled by its own role. You don't run several agents side by side. Decisions, review findings, and test results are saved along the way, so you can inspect the work and pick it up again after an interruption.
-LoopForge turns those concerns into a complete software delivery workflow. You describe the problem to solve; LoopForge chooses a path based on task complexity and guides agents through requirement clarification, solution design, implementation, independent review, and testing while preserving the important decisions and verification results.
-
-## From one request to a verifiable result
-
-1. **Understand the problem first**: the agent inspects the project and clarifies the goal, scope, and acceptance criteria instead of immediately writing code.
-2. **Confirm the boundaries before implementation**: medium and large tasks move into design and implementation only after you confirm the goal, scope, exclusions, key decisions, and acceptance criteria.
-3. **Separate delivery responsibilities**: design, implementation, review, and testing are performed in stages by agents with independent responsibilities, reducing self-review bias in a single context.
-4. **Show evidence, not just a diff**: requirements, plans, changes, review findings, and test results are saved for inspection, handoff, and retrospectives.
-5. **Continue after interruption**: workflow state is persisted so the next session can resume at the unfinished stage instead of starting over.
-
-Small changes take a streamlined single-agent path. The full multi-agent workflow is reserved for medium and large tasks that benefit from it.
-
-```text
-Your request
- │
- ├─ Small change ───────> Understand → implement → verify → deliver
- │
- └─ Medium/large task ──> Clarify and confirm → design → implement
- → independent review → test → deliver
- │
- └── State and artifacts are saved throughout
-```
+<p align="center">
+ <a href="docs/assets/loopforge-promo.mp4?raw=true">
+ <img src="docs/assets/loopforge-promo-preview.webp" alt="LoopForge in 13 seconds: one request goes through the leader, developer, code-reviewer, and test-engineer roles inside the agent you already use." width="720" />
+ </a>
+</p>
## Quick start
-Requires Node.js 20+ and Python 3.8+.
+Requires Node.js 20+ and Python 3.8+. The commands below install the default Classic Edition; choose it if you are unsure.
-The commands below install the default Classic Edition. Choose this edition if you are unsure.
+| Agent | Install | Start a workflow |
+| --- | --- | --- |
+| CodeBuddy | `npx -y loopforge-cli@latest install codebuddy` | `/start-devflow "<request>"` |
+| Codex | `npx -y loopforge-cli@latest install codex` | `$devflow-codex "<request>"` |
+| Cursor | `npx -y loopforge-cli@latest install cursor` | `/start-devflow "<request>"` |
+| Claude Code | `npx -y loopforge-cli@latest install claude` | `/start-devflow "<request>"` |
-### CodeBuddy
+For example, with Claude Code:
```bash
-npx -y loopforge-cli@latest install codebuddy
-npx -y loopforge-cli@latest status codebuddy
+npx -y loopforge-cli@latest install claude
+npx -y loopforge-cli@latest status claude
```
-Then start a workflow:
-
```text
/start-devflow "add status filtering to the order list and cover the API with tests"
```
-### Codex
+Check any installation with `npx -y loopforge-cli@latest status <agent>`. If installation or execution fails, diagnose the environment:
```bash
-npx -y loopforge-cli@latest install codex
-npx -y loopforge-cli@latest status codex
+npx -y loopforge-cli@latest doctor
```
-Then start a workflow:
-
-```text
-$devflow-codex "add status filtering to the order list and cover the API with tests"
-```
+Pi is supported through the [Portable Edition](#portable-edition).
-### Cursor
+## How it works
-```bash
-npx -y loopforge-cli@latest install cursor
-npx -y loopforge-cli@latest status cursor
-```
+1. **Understand the problem first**: the agent inspects the project and clarifies the goal, scope, and acceptance criteria instead of immediately writing code.
+2. **Confirm the boundaries before implementation**: medium and large tasks move into design and implementation only after you confirm the goal, scope, exclusions, key decisions, and acceptance criteria.
+3. **Separate responsibilities**: design, implementation, review, and testing are handled stage by stage by roles with independent responsibilities, which reduces self-review bias in a single context.
+4. **Show evidence, not just a diff**: requirements, plans, changes, review findings, and test results are saved for inspection, handoff, and retrospectives.
+5. **Continue after interruption**: workflow state is persisted so the next session can resume at the unfinished stage instead of starting over.
-Then start a workflow:
+LoopForge picks the path by task complexity. Small changes take a streamlined single-role path; the full role-based workflow is reserved for medium and large tasks that benefit from it.
```text
-/start-devflow "add status filtering to the order list and cover the API with tests"
+Your request
+ │
+ ├─ Small change ───────> Understand → implement → verify → deliver
+ │
+ └─ Medium/large task ──> Clarify and confirm → design → implement
+ → independent review → test → deliver
+ │
+ └── State and artifacts are saved throughout
```
-### Claude Code
-
-```bash
-npx -y loopforge-cli@latest install claude
-npx -y loopforge-cli@latest status claude
-```
+## Supported agents
-Then start a workflow:
+| Agent | Classic Edition (default) | Portable Edition |
+| --- | --- | --- |
+| CodeBuddy | ✓ | ✓ |
+| Codex | ✓ | ✓ |
+| Cursor | ✓ | ✓ |
+| Claude Code | ✓ | ✓ |
+| Pi | — | ✓ |
-```text
-/start-devflow "add status filtering to the order list and cover the API with tests"
-```
-
-If installation or execution fails, diagnose the environment:
-
-```bash
-npx -y loopforge-cli@latest doctor
-```
+LoopForge enables only one edition per coding agent in each project. See [`EDITIONS.md`](EDITIONS.md) for the differences and directory layout.
## What you get
@@ -117,7 +99,7 @@ Resume an interrupted Classic workflow with `/resume-devflow {task_slug}` on Cod
## See how agents work
-The Classic Edition for CodeBuddy includes a local observability dashboard. It turns the workflow evidence into a view of session activity, Token and cost trends, Skill/Rule usage, multi-agent dispatch, and Devflow stage attribution—useful for finding expensive runs, checking whether automation is actually being used, and reviewing how work moved between agents.
+The Classic Edition for CodeBuddy includes a local observability dashboard. It turns the workflow evidence into a view of session activity, Token and cost trends, Skill/Rule usage, role dispatch, and Devflow stage attribution—useful for finding expensive runs, checking whether automation is actually being used, and reviewing how work moved between roles.
![LoopForge local agent observability dashboard with demonstration data](docs/assets/agent-observability-dashboard.png)
@@ -151,70 +133,17 @@ LoopForge is especially useful when:
For one-off code completion or a tiny, fully specified edit, using a coding agent directly is often enough. Simple tasks that do enter LoopForge use its streamlined path.
-## Use the Portable Edition
-
-The quick start above installs the default Classic Edition, which is the right choice for most users. If you only want the portable Agent Skills workflow, choose the command for your coding agent below. To prevent one coding agent from loading two workflows and mixing their state or artifacts, LoopForge enables only one edition per coding agent in each project. To switch editions, run the new install command with `--force`.
-
-### CodeBuddy
-
-```bash
-npx -y loopforge-cli@latest skills install codebuddy
-```
-
-Then start a workflow:
-
-```text
-/devflow "add status filtering to the order list and cover the API with tests"
-```
-
-### Codex
-
-```bash
-npx -y loopforge-cli@latest skills install codex
-```
+## Portable Edition
-Then start a workflow:
+The Classic Edition from the quick start is the right choice for most users. If you only want the portable Agent Skills workflow, use the Portable Edition. To prevent one coding agent from loading two workflows and mixing their state or artifacts, LoopForge enables only one edition per coding agent in each project. To switch editions, run the new install command with `--force`.
-```text
-$devflow "add status filtering to the order list and cover the API with tests"
-```
-
-### Cursor
-
-```bash
-npx -y loopforge-cli@latest skills install cursor
-```
-
-Then start a workflow:
-
-```text
-/devflow "add status filtering to the order list and cover the API with tests"
-```
-
-### Claude Code
-
-```bash
-npx -y loopforge-cli@latest skills install claude
-```
-
-Then start a workflow:
-
-```text
-/devflow "add status filtering to the order list and cover the API with tests"
-```
-
-### Pi
-
-```bash
-npx -y loopforge-cli@latest skills install pi
-pi install npm:pi-subagents
-```
-
-Then start a workflow:
-
-```text
-/skill:devflow "add status filtering to the order list and cover the API with tests"
-```
+| Agent | Install | Start a workflow |
+| --- | --- | --- |
+| CodeBuddy | `npx -y loopforge-cli@latest skills install codebuddy` | `/devflow "<request>"` |
+| Codex | `npx -y loopforge-cli@latest skills install codex` | `$devflow "<request>"` |
+| Cursor | `npx -y loopforge-cli@latest skills install cursor` | `/devflow "<request>"` |
+| Claude Code | `npx -y loopforge-cli@latest skills install claude` | `/devflow "<request>"` |
+| Pi | `npx -y loopforge-cli@latest skills install pi`, then `pi install npm:pi-subagents` | `/skill:devflow "<request>"` |
See [`EDITIONS.md`](EDITIONS.md) for the complete boundaries and directory layout.
@@ -226,57 +155,18 @@ For ongoing use, install the CLI globally:
npm install --global loopforge-cli
```
-Maintenance commands for the default Classic Edition:
+Then maintain an installation with the same agent names as above (`codebuddy`, `codex`, `cursor`, `claude`, and `pi` for the Portable Edition):
```bash
-# CodeBuddy
-loopforge update codebuddy
-loopforge status codebuddy
-loopforge uninstall codebuddy
-
-# Codex
-loopforge update codex
-loopforge status codex
-loopforge uninstall codex
-
-# Cursor
-loopforge update cursor
-loopforge status cursor
-loopforge uninstall cursor
-
-# Claude Code
-loopforge update claude
-loopforge status claude
-loopforge uninstall claude
-```
+# Classic Edition
+loopforge update <agent>
+loopforge status <agent>
+loopforge uninstall <agent>
-Maintenance commands for the Portable Edition:
-
-```bash
-# CodeBuddy
-loopforge skills update codebuddy
-loopforge skills status codebuddy
-loopforge skills uninstall codebuddy
-
-# Codex
-loopforge skills update codex
-loopforge skills status codex
-loopforge skills uninstall codex
-
-# Cursor
-loopforge skills update cursor
-loopforge skills status cursor
-loopforge skills uninstall cursor
-
-# Claude Code
-loopforge skills update claude
-loopforge skills status claude
-loopforge skills uninstall claude
-
-# Pi
-loopforge skills update pi
-loopforge skills status pi
-loopforge skills uninstall pi
+# Portable Edition
+loopforge skills update <agent>
+loopforge skills status <agent>
+loopforge skills uninstall <agent>
```
Installation state is stored in `.devflow/install-state.json`. An update stops instead of overwriting user-modified or conflicting files. Use `--force` only when you intend to replace conflicts or switch editions, preferably after inspecting `loopforge plan`.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index b70316ff..7d53f94e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,93 +4,75 @@
**让编码 Agent 不只“写出代码”,而是按一套可确认、可审查、可恢复的流程完成交付。**
-把一个需求交给编码 Agent 很容易,难的是让它在动手前理解目标,在实现中不偏离范围,并在结束前完成独立审查和测试。任务一旦变长,还会遇到上下文丢失、执行中断,以及最终只剩一份难以追溯的代码变更。
+LoopForge 安装到你正在用的编码 Agent 里,支持 CodeBuddy、Codex、Cursor、Claude Code 和 Pi。它在这个 Agent 内部运行一套按角色分工的交付流程:先澄清并确认需求,再依次完成设计、实现、由另一个角色做独立 Code Review,最后测试。各阶段按顺序推进,每个阶段由对应的角色负责,不需要同时开多个 Agent。关键决策、审查意见和测试结果都会落盘,方便检查,中断后也能接着做。
-LoopForge 把这些步骤组织成一条完整的软件交付流程。你只需要描述要解决的问题;LoopForge 会根据任务复杂度选择执行方式,推动 Agent 完成需求澄清、方案设计、代码实现、独立审查和测试,并把关键决策与验证结果保存下来。
-
-## 从一句需求到可验收结果
-
-1. **先理解问题**:Agent 调研现有项目,澄清目标、范围和验收标准,而不是立即开始写代码。
-2. **确认边界后再实施**:中大型任务会在你确认目标、范围、排除项、关键决策和验收标准后,再进入设计与实现。
-3. **分工完成交付**:设计、实现、审查和测试由职责独立的 Agent 分阶段完成,减少同一上下文中的自审偏差。
-4. **用证据说明结果**:需求、方案、代码变更、审查意见和测试结果都会落盘,方便检查、复盘和交接。
-5. **中断后继续执行**:流程状态会被保存,下次可以从未完成的阶段继续,不必重新来过。
-
-小改动会走精简的单 Agent 路径,避免为简单任务引入额外流程;中大型任务才会启用完整的多 Agent 协作。
-
-```text
-你的需求
- │
- ├─ 小改动 ───────> 理解 → 实现 → 自检 → 交付
- │
- └─ 中大型任务 ───> 澄清并确认 → 设计 → 实现 → 独立审查 → 测试 → 交付
- │
- └── 全程保存状态和产物,可随时恢复
-```
+<p align="center">
+ <a href="docs/assets/loopforge-promo.mp4?raw=true">
+ <img src="docs/assets/loopforge-promo-preview.webp" alt="13 秒了解 LoopForge:一个需求在你已有的 Agent 里依次经过 leader、developer、code-reviewer、test-engineer 四个角色。" width="720" />
+ </a>
+</p>
## 快速开始
-要求 Node.js 20+ 和 Python 3.8+。
+要求 Node.js 20+ 和 Python 3.8+。以下命令安装默认的 Classic Edition,不确定选哪一种时直接用这一版。
-以下命令安装默认的 Classic Edition。不确定选哪一种时,直接使用这一版。
+| Agent | 安装 | 启动工作流 |
+| --- | --- | --- |
+| CodeBuddy | `npx -y loopforge-cli@latest install codebuddy` | `/start-devflow "<需求>"` |
+| Codex | `npx -y loopforge-cli@latest install codex` | `$devflow-codex "<需求>"` |
+| Cursor | `npx -y loopforge-cli@latest install cursor` | `/start-devflow "<需求>"` |
+| Claude Code | `npx -y loopforge-cli@latest install claude` | `/start-devflow "<需求>"` |
-### CodeBuddy
+以 Claude Code 为例:
```bash
-npx -y loopforge-cli@latest install codebuddy
-npx -y loopforge-cli@latest status codebuddy
+npx -y loopforge-cli@latest install claude
+npx -y loopforge-cli@latest status claude
```
-安装后启动:
-
```text
/start-devflow "为订单列表增加状态筛选,并补充接口测试"
```
-### Codex
+任何宿主都可以用 `npx -y loopforge-cli@latest status <agent>` 检查安装状态。如果安装或运行遇到问题,执行环境诊断:
```bash
-npx -y loopforge-cli@latest install codex
-npx -y loopforge-cli@latest status codex
+npx -y loopforge-cli@latest doctor
```
-安装后启动:
-
-```text
-$devflow-codex "为订单列表增加状态筛选,并补充接口测试"
-```
+Pi 通过 [Portable Edition](#portable-edition) 支持。
-### Cursor
+## 工作方式
-```bash
-npx -y loopforge-cli@latest install cursor
-npx -y loopforge-cli@latest status cursor
-```
+1. **先理解问题**:Agent 调研现有项目,澄清目标、范围和验收标准,而不是立即开始写代码。
+2. **确认边界后再实施**:中大型任务会在你确认目标、范围、排除项、关键决策和验收标准后,再进入设计与实现。
+3. **分工完成交付**:设计、实现、审查和测试由职责独立的角色分阶段完成,减少同一上下文中的自审偏差。
+4. **用证据说明结果**:需求、方案、代码变更、审查意见和测试结果都会落盘,方便检查、复盘和交接。
+5. **中断后继续执行**:流程状态会被保存,下次可以从未完成的阶段继续,不必重新来过。
-安装后启动:
+LoopForge 会根据任务复杂度选择路径:小改动走精简的单角色路径,避免为简单任务引入额外流程;中大型任务才启用完整的角色分工流程。
```text
-/start-devflow "为订单列表增加状态筛选,并补充接口测试"
-```
-
-### Claude Code
-
-```bash
-npx -y loopforge-cli@latest install claude
-npx -y loopforge-cli@latest status claude
+你的需求
+ │
+ ├─ 小改动 ───────> 理解 → 实现 → 自检 → 交付
+ │
+ └─ 中大型任务 ───> 澄清并确认 → 设计 → 实现 → 独立审查 → 测试 → 交付
+ │
+ └── 全程保存状态和产物,可随时恢复
```
-安装后启动:
+## 支持的 Agent
-```text
-/start-devflow "为订单列表增加状态筛选,并补充接口测试"
-```
+| Agent | Classic Edition(默认) | Portable Edition |
+| --- | --- | --- |
+| CodeBuddy | ✓ | ✓ |
+| Codex | ✓ | ✓ |
+| Cursor | ✓ | ✓ |
+| Claude Code | ✓ | ✓ |
+| Pi | — | ✓ |
-如果安装或运行遇到问题,执行环境诊断:
-
-```bash
-npx -y loopforge-cli@latest doctor
-```
+同一项目中,每个编码 Agent 只能启用一种 Edition。两者的区别和目录说明见 [`EDITIONS.md`](EDITIONS.md)。
## 你会得到什么
@@ -116,7 +98,7 @@ Classic 工作流中断后,CodeBuddy、Cursor 和 Claude Code 使用 `/resume-
## 看见 Agent 如何完成工作
-CodeBuddy 的 Classic Edition 内置本地可观测看板。它把落盘的流程证据变成可视化视图,集中呈现会话活动、Token 与成本趋势、Skill/Rule 使用情况、多 Agent 派发,以及 Devflow 阶段归因,方便定位高成本运行、确认自动化是否真正生效,并复盘任务如何在不同 Agent 之间流转。
+CodeBuddy 的 Classic Edition 内置本地可观测看板。它把落盘的流程证据变成可视化视图,集中呈现会话活动、Token 与成本趋势、Skill/Rule 使用情况、角色派发,以及 Devflow 阶段归因,方便定位高成本运行、确认自动化是否真正生效,并复盘任务如何在不同角色之间流转。
![使用演示数据的 LoopForge 本地 Agent 可观测看板](docs/assets/agent-observability-dashboard.png)
@@ -150,70 +132,17 @@ LoopForge 尤其适合这些任务:
如果只是一次性的代码补全或非常明确的微小修改,直接使用编码 Agent 通常已经足够;LoopForge 会为进入其工作流的简单任务选择精简路径。
-## 使用 Portable Edition
-
-上面的“快速开始”安装的是默认的 Classic Edition,适合大多数用户。如果只希望安装基于 Agent Skills 的可移植工作流,请根据使用的 Coding Agent 选择下面的命令。为避免同一个 Coding Agent 同时加载两套工作流,以及状态和产物相互冲突,LoopForge 在每个项目中只允许为同一 Coding Agent 启用一种 Edition。如需切换,可重新安装并添加 `--force`。
-
-### CodeBuddy
-
-```bash
-npx -y loopforge-cli@latest skills install codebuddy
-```
-
-安装后使用:
-
-```text
-/devflow "为订单列表增加状态筛选,并补充接口测试"
-```
-
-### Codex
-
-```bash
-npx -y loopforge-cli@latest skills install codex
-```
-
-安装后使用:
-
-```text
-$devflow "为订单列表增加状态筛选,并补充接口测试"
-```
-
-### Cursor
-
-```bash
-npx -y loopforge-cli@latest skills install cursor
-```
-
-安装后使用:
-
-```text
-/devflow "为订单列表增加状态筛选,并补充接口测试"
-```
+## Portable Edition
-### Claude Code
+“快速开始”安装的 Classic Edition 适合大多数用户。如果只希望安装基于 Agent Skills 的可移植工作流,可以使用 Portable Edition。为避免同一个 Coding Agent 同时加载两套工作流,以及状态和产物相互冲突,LoopForge 在每个项目中只允许为同一 Coding Agent 启用一种 Edition。如需切换,可重新安装并添加 `--force`。
-```bash
-npx -y loopforge-cli@latest skills install claude
-```
-
-安装后使用:
-
-```text
-/devflow "为订单列表增加状态筛选,并补充接口测试"
-```
-
-### Pi
-
-```bash
-npx -y loopforge-cli@latest skills install pi
-pi install npm:pi-subagents
-```
-
-安装后使用:
-
-```text
-/skill:devflow "为订单列表增加状态筛选,并补充接口测试"
-```
+| Agent | 安装 | 启动工作流 |
+| --- | --- | --- |
+| CodeBuddy | `npx -y loopforge-cli@latest skills install codebuddy` | `/devflow "<需求>"` |
+| Codex | `npx -y loopforge-cli@latest skills install codex` | `$devflow "<需求>"` |
+| Cursor | `npx -y loopforge-cli@latest skills install cursor` | `/devflow "<需求>"` |
+| Claude Code | `npx -y loopforge-cli@latest skills install claude` | `/devflow "<需求>"` |
+| Pi | `npx -y loopforge-cli@latest skills install pi`,然后 `pi install npm:pi-subagents` | `/skill:devflow "<需求>"` |
完整边界和目录说明见 [`EDITIONS.md`](EDITIONS.md)。
@@ -225,57 +154,18 @@ pi install npm:pi-subagents
npm install --global loopforge-cli
```
-默认 Classic Edition 的维护命令:
+之后用上面的宿主名(`codebuddy`、`codex`、`cursor`、`claude`,Portable Edition 另有 `pi`)维护安装:
```bash
-# CodeBuddy
-loopforge update codebuddy
-loopforge status codebuddy
-loopforge uninstall codebuddy
-
-# Codex
-loopforge update codex
-loopforge status codex
-loopforge uninstall codex
-
-# Cursor
-loopforge update cursor
-loopforge status cursor
-loopforge uninstall cursor
-
-# Claude Code
-loopforge update claude
-loopforge status claude
-loopforge uninstall claude
-```
+# Classic Edition
+loopforge update <agent>
+loopforge status <agent>
+loopforge uninstall <agent>
-Portable Edition 的维护命令:
-
-```bash
-# CodeBuddy
-loopforge skills update codebuddy
-loopforge skills status codebuddy
-loopforge skills uninstall codebuddy
-
-# Codex
-loopforge skills update codex
-loopforge skills status codex
-loopforge skills uninstall codex
-
-# Cursor
-loopforge skills update cursor
-loopforge skills status cursor
-loopforge skills uninstall cursor
-
-# Claude Code
-loopforge skills update claude
-loopforge skills status claude
-loopforge skills uninstall claude
-
-# Pi
-loopforge skills update pi
-loopforge skills status pi
-loopforge skills uninstall pi
+# Portable Edition
+loopforge skills update <agent>
+loopforge skills status <agent>
+loopforge skills uninstall <agent>
```
安装状态保存在 `.devflow/install-state.json`。检测到用户修改或文件冲突时,更新会停止而不是覆盖。只有在确认要替换冲突文件或切换 Edition 时才使用 `--force`,建议先运行 `loopforge plan` 检查变更。
diff --git a/docs/assets/loopforge-promo-preview.webp b/docs/assets/loopforge-promo-preview.webp
new file mode 100644
index 00000000..c8206052
Binary files /dev/null and b/docs/assets/loopforge-promo-preview.webp differ
diff --git a/docs/assets/loopforge-promo.mp4 b/docs/assets/loopforge-promo.mp4
new file mode 100644
index 00000000..f52a0329
Binary files /dev/null and b/docs/assets/loopforge-promo.mp4 differ