name: forgeloop
description: Multi-agent iterative development engine. Breaks requirements into tasks, executes them with AI coding agents, reviews output, and iterates until quality standards are met. Use when the user wants automated, multi-step development with quality review loops, or asks to "forge", "build iteratively", "develop with review", or mentions forgeloop.

ForgeLoop — Agent-Driven Iterative Development

ForgeLoop 是一个面向 AI agent 的状态机 CLI。你（agent）驱动整个循环——ForgeLoop 只负责追踪 tasks、iterations 和 state。

核心理念：plan → execute → review → iterate，直到所有 task 达标。

When to Use

触发词： "forge", "forgeloop", "build iteratively", "分步开发", "迭代开发", "帮我做个项目"

适用场景：
- 用户有复杂需求，需要拆解成多个步骤
- 需要质量控制的多步开发（build → review → fix）
- 任何超过 3 个独立子任务的开发请求
- 用户明确要求使用 ForgeLoop

不适用场景：
- 单文件快速修改
- 简单问答或查询
- 只需 1-2 步就能完成的任务

Quick Start

三步核心流程：

# 1. 初始化 + 计划
forgeloop init /path/to/project
forgeloop plan "需求描述" --tasks-json '["任务1","任务2","任务3"]'

# 2. 执行循环：获取任务 → 执行 → 标记完成
forgeloop next --json          # 获取下一个任务
# ... 执行任务（spawn sub-agent 或直接实现）...
forgeloop done task-001 --output "实现摘要"

# 3. Review：approve 或 reject
forgeloop approve task-001
# 或
forgeloop reject task-001 --feedback "缺少错误处理"

重复步骤 2-3，直到 forgeloop next 返回 { done: true }。

Commands Reference

核心命令

计划管理命令

状态与报告命令

全局选项

Complete Workflow

Step 1: Initialize

forgeloop init /path/to/project --max-iterations 3

--max-iterations 控制每个 task 最多重试几轮（默认 3）。超过后标记为 FAILED。

Step 2: Plan

把用户需求拆解成具体的、有序的任务：

forgeloop plan "用户的需求描述" --tasks-json '["任务1","任务2","任务3"]'

Planning 原则：
- 3-8 个 task 最合适。太少粒度不够，太多管理成本高
- 顺序重要：基础设施先行，测试最后
- 每个 task 独立可验证：完成后能检查对错
- 描述要具体："用 JWT 实现用户登录 + refresh token" ✅ / "加认证" ❌
- 从文件导入：复杂计划用 --tasks-file tasks.json

计划制定后还可以动态调整：

forgeloop add-task "补充 API 文档" --after task-003
forgeloop add-task "加缓存层" --depends-on task-002,task-003
forgeloop remove-task task-005  # 只能删 PLANNED 状态的
forgeloop reorder task-006 --before task-004

Step 3: Execute Loop

# 获取下一个任务（始终用 --json 方便解析）
forgeloop next --json
# 返回: { ok, done, task: { id, description, iteration, feedback } }

对于每个任务：
1. 读取 task description 和之前的 feedback（如果是重试）
2. Spawn sub-agent（推荐）或直接实现
3. 完成后标记：

forgeloop done task-001 --output "创建了 src/index.js，含 Express 路由和中间件"

Step 4: Review

Review 工作质量，然后：

# 通过：
forgeloop approve task-001

# 不通过（会重试，直到 max-iterations）：
forgeloop reject task-001 --feedback "缺少输入验证，POST /users 没有校验 email 格式"

Step 5: Repeat

回到 Step 3。forgeloop next --json 会：
- 优先返回 REJECTED 的任务（需要重试）
- 然后返回 PLANNED 的任务
- 全部完成时返回 { done: true }

最后用 forgeloop summary 生成报告。

Task Dependencies

用 dependsOn 声明 task 间的依赖关系。next 命令会自动跳过依赖未满足的 task。

在 plan 时声明

通过 --tasks-file 可以声明依赖：

[
  { "description": "初始化项目结构", "id": "setup" },
  { "description": "实现核心 API", "dependsOn": ["setup"] },
  { "description": "写单元测试", "dependsOn": ["setup"] },
  { "description": "集成测试", "dependsOn": ["task-002", "task-003"] }
]

动态添加带依赖的 task

forgeloop add-task "加缓存层" --depends-on task-002,task-003

注意：
- ForgeLoop 会自动检测环形依赖并报错
- 被其他 task 依赖的 task 不能被 remove
- 依赖的 task 必须是 APPROVED 状态，next 才会返回依赖它的 task

Sub-Agent Best Practices

spawn 调用模板

推荐用 sub-agent 执行每个 task，保持主 agent 做 orchestration：

sessions_spawn({
  task: `## ForgeLoop ${task.id}: ${task.description}

**项目路径:** /path/to/project

### 具体要求
${detailed_requirements}

### 上下文
- 这是整体计划的第 N 步
- 前置任务已完成：task-001 (项目结构), task-002 (核心逻辑)
- 技术栈：Node.js + Express + PostgreSQL

### 上轮反馈（如有）
${task.feedback?.length ? task.feedback[task.feedback.length - 1].content : '无，首次执行'}

### 约束
- 不要修改 ${files_not_to_touch}
- 确保所有测试通过
- 代码风格遵循项目 .eslintrc`,
  label: "forgeloop-${task.id}"
})

怎么写好 task 描述

差的描述：

"加数据库"

好的描述：

"R3: 数据库层 — 用 PostgreSQL + Knex.js 实现：users 表（id, email, password_hash, created_at）；migrations 脚本；db.js 连接池封装；环境变量 DATABASE_URL 配置"

原则：
- 加编号前缀（R1, R2...）方便引用
- 列出具体产出物：哪些文件、哪些函数、哪些接口
- 指定技术选型：不要让 sub-agent 猜
- 定义完成标准：怎么算"做完了"

怎么做好 Review

Review 时检查清单：

1. 功能完整性 — task 描述中要求的每一项都实现了吗？
2. 代码质量 — 错误处理、边界情况、命名规范
3. 测试 — 有测试吗？测试能通过吗？覆盖了核心路径吗？
4. 集成 — 和已有代码兼容吗？import 路径对吗？
5. 文档 — 公共 API 有注释吗？README 更新了吗？

# Review 时可以用这些命令辅助
cd /path/to/project
git diff HEAD~1                    # 看改了什么
npm test                           # 跑测试
cat src/new-file.js               # 读代码

什么时候 Reject vs Approve

Approve 当：
- 所有要求都满足
- 代码质量可接受（不需要完美）
- 测试通过
- 不会破坏已有功能

Reject 当：
- 缺少关键功能（task 描述中明确要求的）
- 有明显 bug 或错误
- 测试不通过
- 破坏了之前 approve 的工作

Reject 的 feedback 要具体可执行：

# ❌ 差的 feedback
forgeloop reject task-003 --feedback "不行"

# ✅ 好的 feedback
forgeloop reject task-003 --feedback "1. POST /users 缺少 email 格式验证 2. 密码未 hash，直接存明文 3. 缺少 409 Conflict 响应（重复 email）"

Real-World Example: Gomoku 五子棋项目

以下展示完整的 ForgeLoop 使用流程，从 init 到所有 task 完成。

需求

"用 TypeScript 开发一个终端五子棋游戏，支持人机对战，AI 用 minimax 算法"

Init + Plan

forgeloop init /projects/gomoku --max-iterations 3
forgeloop plan "TypeScript 终端五子棋游戏，支持人机对战，AI 用 minimax" --tasks-json '[
  "R1: 项目初始化 — tsconfig.json + package.json + src/ 目录结构 + ESLint 配置",
  "R2: 棋盘数据结构 — Board class，15x15 二维数组，放子/判断合法/打印棋盘",
  "R3: 胜负判定 — checkWin 函数，检查横/竖/对角线连五，单元测试覆盖所有方向",
  "R4: 终端 UI — 用 chalk + readline 实现交互，显示坐标、当前玩家、落子提示",
  "R5: Minimax AI — alpha-beta 剪枝，深度 4，评估函数考虑连子数和开放端",
  "R6: AI 优化 — 限制搜索范围（只看已有棋子周围 2 格），加 move ordering",
  "R7: 游戏主循环 — 整合 UI + Board + AI，完整的一局流程（开局→对弈→判定→再来一局）",
  "R8: 输入验证 — 处理非法输入、已占位置、退出命令(q)、悔棋命令(u)",
  "R9: 单元测试 + 集成测试 — Jest 配置，Board/checkWin/AI 的测试，覆盖率 > 80%",
  "R10: README + 打包 — 使用说明、截图占位、npm bin 配置、chmod +x"
]'

Execute Loop（10 个 task）

# --- Task 1: 项目初始化 ---
forgeloop next --json
# → { task: { id: "task-001", description: "R1: 项目初始化..." } }

# Spawn sub-agent 执行
sessions_spawn({ task: "## ForgeLoop task-001: R1: 项目初始化...", label: "forgeloop-task-001" })

# Sub-agent 完成后
forgeloop done task-001 --output "tsconfig.json + package.json + src/ + .eslintrc 已创建"
# Review: 检查 tsconfig strict mode、package.json scripts
forgeloop approve task-001

# --- Task 2: 棋盘数据结构 ---
forgeloop next --json
# → task-002
sessions_spawn({ task: "## ForgeLoop task-002: R2: 棋盘数据结构...", label: "forgeloop-task-002" })
forgeloop done task-002 --output "Board class 实现，含 place/isValid/print 方法"
# Review: Board.print() 输出格式正确，isValid 边界检查
forgeloop approve task-002

# --- Task 3: 胜负判定 ---
forgeloop next --json
sessions_spawn({ task: "...", label: "forgeloop-task-003" })
forgeloop done task-003 --output "checkWin 实现 + 8 个单元测试"
# Review: 跑测试
forgeloop approve task-003

# --- Task 4: 终端 UI ---
forgeloop next --json
sessions_spawn({ task: "...", label: "forgeloop-task-004" })
forgeloop done task-004 --output "Terminal UI with chalk rendering"
# Review: 发现坐标显示不对
forgeloop reject task-004 --feedback "坐标标注从 0 开始，应该从 1 开始（用户友好）；棋盘右侧缺少列号标注"
# → task-004 回到队列，iteration 2

# --- Task 4 (重试) ---
forgeloop next --json
# → task-004 again, with feedback
sessions_spawn({ task: "...\n上轮反馈：坐标标注从 0 开始...", label: "forgeloop-task-004-r2" })
forgeloop done task-004 --output "修复坐标显示，加列号标注"
forgeloop approve task-004

# --- Tasks 5-10: 类似流程 ---
# ... 每个 task: next → spawn → done → review → approve/reject ...

# --- 全部完成 ---
forgeloop next --json
# → { done: true, message: "All tasks processed..." }

forgeloop summary
# 输出完整的 Markdown 报告

最终 Summary 输出

# ForgeLoop Report
- Total Tasks: 10
- Completed: 10 / 10 (100%)
- Duration: 1h 23m
- Rejections: 1 (task-004, 修复后通过)

Configuration

ForgeLoop 的配置存储在 .forgeloop/config.json：

通过 init 设置：

forgeloop init . --max-iterations 5

Task 生命周期

PLANNED → EXECUTING → REVIEWING → APPROVED ✅
                  ↑       ↓
                  ← REJECTED (retry, iteration++)
                        ↓ (超过 maxIterations)
                      FAILED ❌

Tips & Gotchas

✅ 常用技巧

• 始终用 --json 解析命令输出，避免依赖人类可读格式
• -d /path 远程操作：不用 cd，直接 forgeloop -d /other/project status
• 中途加 task：用 add-task --after task-003 插入，不需要重新 plan
• 看全局进度：forgeloop summary 输出 Markdown 报告，适合汇报给用户
• 安全重置：forgeloop reset 会自动归档当前计划，不会丢数据

⚠️ 常见错误

💡 Pro Tips

1. 第一个 task 永远是项目 setup（目录结构、配置文件、依赖安装）
2. 最后一个 task 是测试 + 文档
3. Reject 的 feedback 越详细越好 — sub-agent 只看 feedback 来修复
4. 大任务拆小：如果一个 task 需要改 5+ 个文件，考虑拆成 2 个
5. Resume 安全：状态持久化在 .forgeloop/，中断后随时恢复