Forge Loop

Forge Loop 是一套跨项目复用的 Agent 软件开发工作流。核心思路是：共享工作流集中维护，业务项目只安装很薄的本地适配层和项目上下文。

Workflow Design Principles

• 简约：流程精简，只保留必要执行节点，不添加冗余低功效逻辑。
• 稳定：流程执行稳定，行为表现一致，避免同类任务在不同 Agent 或不同轮次中产生无理由分歧。
• 高效：智能识别需求类型，在保证交付质量的基础上精简流程；通过 subagents 并行化执行，提升编码效率。
• 节俭：高效利用模型上下文，尽量减少中间产物生成，只保留精华，降低无效信息传输。

Model Recommendation

Forge Loop 会在路由阶段同时给出模型档位建议，避免所有任务都默认占用最高智能模型：

• low：低复杂度、小改动、影响面小、局部验证闭环明确的 Quick Lane 改动。
• balanced：需要一定分析能力的小 bug 修复、普通 spike、窄范围实现和局部 review。
• high：Feature Iteration、架构 spike、共享契约、跨模块、范围不清或高风险任务。

这套建议会结合项目 .ai/workflow-config.md 里的 Agent Environment 识别当前是 Codex 还是 Claude Code，并读取各自的 Low / Balanced / High Model 配置；若配置为 auto，则回退到对应平台默认档位。

Quick Start

推荐通过 npm CLI 初始化业务项目：

# Codex
npx @shawnxie666/forge-loop init --agent codex

# Claude Code
npx @shawnxie666/forge-loop init --agent claude-code

# 不确定使用哪个 Agent
npx @shawnxie666/forge-loop init

初始化后，在业务项目中直接说：

/forge 把登录按钮文案改成 Continue

Claude Code 会通过项目级 .claude/skills/*/SKILL.md 直接加载 /forge 和 /forge-* 命令。Codex 使用用户级 skill：@shawnxie666/forge-loop init --agent codex 会安装 ~/.codex/skills/forge-loop/SKILL.md，该 skill 再读取项目内 .forge-loop/commands/*.md。

检查安装是否完整：

npx @shawnxie666/forge-loop doctor --project .

Structure

forge-loop/
├── package.json
├── bin/
│   └── forge-loop.js        # npm CLI
├── core/                    # 共享核心
│   ├── AGENTS.core.md
│   ├── CLAUDE.core.md
│   └── .ai/
│       ├── adapters/
│       ├── skills/
│       ├── workflows/
│       └── templates/
├── templates/project/       # 业务项目本地适配层模板
└── scripts/init-project.sh  # 兼容 shell 初始化脚本

Recommended Project Setup

CLI 默认会把共享核心安装到业务项目本地缓存，避免 Agent 依赖全局 npm 包路径或临时 npx 缓存路径。这个缓存默认写入 .agent-workflow/，并自动加入 .gitignore，不建议提交到业务仓库：

your-project/
├── .agent-workflow/              # 本地缓存，默认不提交
│   └── forge-loop/
│       ├── version
│       └── core/
├── AGENTS.md                     # 本地薄入口
├── CLAUDE.md                     # Claude Code 薄入口，claude-code/full profile 生成
├── .claude/
│   └── skills/                   # Claude Code 原生 slash commands，本地缓存，默认不提交
├── .forge-loop/
│   └── commands/                 # Forge Loop 命令定义，本地缓存，默认不提交
└── .ai/
    ├── project-context.md
    ├── workflow-config.md
    └── overrides.md

Initialize A Project

在目标项目根目录初始化：

cd /path/to/your-project
npx @shawnxie666/forge-loop init --agent codex

或者指定项目路径：

npx @shawnxie666/forge-loop init /path/to/your-project --agent claude-code

也可以显式指定初始化 profile：

npx @shawnxie666/forge-loop init --profile minimal
npx @shawnxie666/forge-loop init --profile codex
npx @shawnxie666/forge-loop init --profile claude-code
npx @shawnxie666/forge-loop init --profile full

如果你的团队希望把 workflow core 固定在业务仓库里，可以显式 vendoring：

npx @shawnxie666/forge-loop init --vendor-core

本仓库本地开发时也可以直接运行：

node bin/forge-loop.js init /path/to/your-project

初始化会：

• 安装共享 core/ 到目标项目 .agent-workflow/forge-loop/core 作为本地缓存。
• 默认把 .agent-workflow/、.forge-loop/、.claude/skills/ 写入 .gitignore，避免把缓存和工具适配层提交到业务仓库；始终忽略 .forge-loop/state/ 这类本地运行态。
• 按 profile 安装 AGENTS.md、CLAUDE.md、.ai/*、.forge-loop/commands/、.claude/skills/。
• 当 --agent codex 时，安装 Codex 用户级 skill 到 ~/.codex/skills/forge-loop/。
• 创建 specs/、tasks/、docs/ 产物目录骨架。
• 自动探测项目名称、Git 分支、技术栈和常用命令。
• 写入 .ai/project-context.md，供 Codex、Claude Code 等通用 Agent 使用。

What To Commit

默认推荐提交最小项目上下文和工作流产物，不提交共享 core 缓存或工具适配缓存。

建议提交：

• AGENTS.md
• .ai/workflow-config.md
• .ai/project-context.md
• .ai/overrides.md
• docs/agents/、docs/adr/、.out-of-scope/ 的轻量项目知识骨架
• specs/、tasks/、docs/ 目录骨架和后续工作流产物
• .gitignore 中 Forge Loop 相关忽略规则

可选提交：

• CLAUDE.md，如果团队希望仓库内保留 Claude Code 入口说明。

默认不建议提交：

• .agent-workflow/forge-loop/core/
• .agent-workflow/forge-loop/version
• .forge-loop/commands/
• .forge-loop/state/
• .claude/skills/

新环境如果没有 .agent-workflow/forge-loop/core/，运行：

npx @shawnxie666/forge-loop upgrade --project .

只有当你显式使用 --vendor-core，才建议把 .agent-workflow/ 一起提交，用于完全固定 workflow core 版本。

如果你希望工具适配层也进入仓库，使用 --profile full；其他 profile 默认把 .forge-loop/ 和 .claude/skills/ 当作可再生成的本地缓存。

Init Profiles

| Profile | 生成内容 | 默认提交策略 | | --- | --- | --- | | minimal | AGENTS.md、.ai/*、specs/、tasks/、docs/、.out-of-scope/ | 只提交项目上下文和产物 | | codex | minimal + .forge-loop/commands/ | .forge-loop/ 默认忽略；--agent codex 会额外安装用户级 Codex skill | | claude-code | minimal + CLAUDE.md + .forge-loop/commands/ + .claude/skills/ | .forge-loop/ 和 .claude/skills/ 默认忽略 | | full | 全部项目适配层 | 适配层可提交，core 仍默认不提交 |

--agent codex 默认使用 codex profile；--agent claude-code 默认使用 claude-code profile；未指定 agent 时默认使用 minimal profile。

Commands

npm 包命令：

forge-loop init [project-root] [--agent auto|codex|claude-code] [--profile minimal|codex|claude-code|full] [--vendor-core] [--force]
forge-loop upgrade [project-root] [--force]
forge-loop uninstall [project-root] [--codex-skill] [--artifacts] [--force] [--json]
forge-loop doctor [--project project-root] [--tier auto|simple|standard|complex] [--workflow] [--slug slug]
forge-loop route "<request>" [--json]
forge-loop scaffold <quick|requirement|feature|design|contract|plan|parallel-plan|result|retrospective|experiment> [--project project-root] --slug slug [--request "..."] [--mode quick|fix|spike] [--force]
forge-loop gate <H1|H2|H3|H4> [--project project-root] --slug slug [--json]
forge-loop approve <H1|H2|H3|H4> [--project project-root] --slug slug [--json]
forge-loop next [--project project-root] [--slug slug] [--json]
forge-loop status [--project project-root] [--slug slug] [--json]
forge-loop eval [--project project-root] [--slug slug] [--summary] [--propose] [--json]
forge-loop validate [artifact-path] [--project project-root] [--slug slug] [--json]
forge-loop install-codex-skill [--force]
forge-loop version

• init：安装项目本地 core 缓存和指定 profile 的薄适配层；默认写入 .gitignore 忽略 .agent-workflow/、.forge-loop/、.claude/skills/，并始终忽略 .forge-loop/state/。
• upgrade：升级 .agent-workflow/forge-loop/core，保留本地上下文和 overrides。
• uninstall：移除项目内 Forge Loop core 缓存、命令适配层、Claude Code forge skills、生成的入口文件和 .gitignore 规则；默认保留 specs/、tasks/、docs/、.out-of-scope/ 里的工作流产物，也默认保留全局 ~/.codex/skills/forge-loop，需要分别用 --artifacts 和 --codex-skill 显式删除。
• doctor：检查本地入口、core 路径、skills/templates/adapters 数量；按 --tier auto|simple|standard|complex 调整长期知识骨架严格度，simple/standard 缺失给 warning，complex 缺失失败；加 --workflow 后同时检查当前工作流门禁状态。
• route：把一句需求稳定路由到 Quick Lane、Issue Intake 或 Feature Iteration，并输出 mode、risk、slug、scope、contractImpact、confidence、spikeType、升级原因，以及 agentEnvironment、modelTier、recommendedModel、reasoningEffort、modelReason 等模型建议；同时返回 neededFiles 和基于文件字符数估算的 contextEstimate，供 Agent 按需读取上下文。
• scaffold：按模板分阶段生成 Quick、Requirement、Design、Contract、Plan、Parallel Plan、Result、Retrospective 或 Workflow Experiment 产物；Quick 产物会按 --mode quick|fix|spike 条件展开；feature 是 H1 初始产物的兼容别名。
• gate：脚本化检查 H1/H2/H3/H4，未满足条件时返回非 0 exit code。
• approve：在 gate 检查通过后记录人类确认，写入 tasks/gates/<slug>/<gate>.md；status/next/doctor --workflow 不会把未批准 gate 视为可跨越。
• next：基于当前产物给出下一步动作、要读写的文件、应运行的检查命令和停止门禁；未传 --slug 时优先使用 .forge-loop/state/active.json。
• status：扫描当前 Quick 或 Feature 产物，给出当前门禁、缺失项和下一步；未传 --slug 时优先使用 .forge-loop/state/active.json。
• eval：聚合 .forge-loop/state/evals/events.jsonl 中的本地工作流事件，输出 summary、按任务 slug 聚合的估算 token、上下文估算趋势或改进候选；它不是门禁，原始事件不提交。
• validate / fill-check：检查单个产物或某个 slug 的产物是否仍有占位符、阻塞字段或未完成结构化状态。
• install-codex-skill：只安装或更新 ~/.codex/skills/forge-loop。
• version：输出 npm 包版本。

常用示例：

# 初始化 Codex 项目，同时安装 ~/.codex/skills/forge-loop
npx @shawnxie666/forge-loop init --agent codex

# 只写最小可提交上下文
npx @shawnxie666/forge-loop init --profile minimal

# 生成并允许提交全部适配层
npx @shawnxie666/forge-loop init --profile full

# 如果团队明确要提交 workflow core 副本
npx @shawnxie666/forge-loop init --vendor-core

# 初始化 Claude Code 项目，安装 .claude/skills/*
npx @shawnxie666/forge-loop init --agent claude-code

# 检查当前项目 Forge Loop 是否完整
npx @shawnxie666/forge-loop doctor --project .

# 按复杂项目严格度检查长期知识骨架
npx @shawnxie666/forge-loop doctor --project . --tier complex

# 检查安装和当前工作流门禁
npx @shawnxie666/forge-loop doctor --project . --workflow

# 升级项目内 .agent-workflow/forge-loop/core
npx @shawnxie666/forge-loop upgrade

# 卸载项目内 Forge Loop 工作流，保留已生成的 specs/tasks/docs 产物
npx @shawnxie666/forge-loop uninstall

# 同时删除工作流产物骨架和全局 Codex skill
npx @shawnxie666/forge-loop uninstall --artifacts --codex-skill

# 只安装或更新 Codex 用户级 skill
npx @shawnxie666/forge-loop install-codex-skill --force

Scripted Workflow Controls

这些命令是给通用 Agent 使用的“工具适配层”，目的是把容易跑偏的判断固定下来。Agent 可以阅读 Markdown 工作流，但在路由、建档、跨门禁和查状态时应优先调用 CLI。

# 1. 判断一句话需求该走哪条路径
forge-loop route "新增 API 权限控制" --json

# 2. 生成对应产物
forge-loop scaffold quick --slug change-login-copy --request "把登录按钮文案改成 Continue"
forge-loop scaffold feature --slug add-api-auth --request "新增 API 权限控制"
forge-loop scaffold design --slug add-api-auth
forge-loop scaffold contract --slug add-api-auth
forge-loop scaffold plan --slug add-api-auth
forge-loop scaffold parallel-plan --slug add-api-auth

# 3. 检查人工门禁；blocked 时 exit code 为 1
forge-loop gate H1 --slug add-api-auth
forge-loop approve H1 --slug add-api-auth
forge-loop gate H2 --slug add-api-auth
forge-loop approve H2 --slug add-api-auth
forge-loop gate H3 --slug add-api-auth
forge-loop approve H3 --slug add-api-auth
forge-loop gate H4 --slug add-api-auth
forge-loop approve H4 --slug add-api-auth

# 4. 查看当前进度和下一步
forge-loop status --slug add-api-auth
forge-loop next --slug add-api-auth
# scaffold/approve 会写入 .forge-loop/state/active.json，通常也可以省略 --slug
forge-loop status
forge-loop next

# 5. 检查产物填写质量
forge-loop validate --slug add-api-auth
forge-loop validate specs/requirements/add-api-auth.md

# 6. 观察工作流效果并提出实验候选
forge-loop eval --summary
forge-loop eval --propose
forge-loop scaffold experiment --slug reduce-template-noise

门禁检查会同时拦截缺失文件、未填占位符、结构化 status: draft/blocked/pending、blocking: true、阻塞问题、未解决冲突、失败测试和 Must Fix。刚 scaffold 出来的模板不会直接通过门禁，必须由 Agent 根据项目上下文补全并把 frontmatter 更新为可进入下一阶段的状态。gate 通过只代表产物检查通过；跨越 H1/H2/H3/H4 前还必须由人类确认，并用 forge-loop approve <gate> --slug <slug> 写入批准记录。

scaffold 和 approve 会更新 .forge-loop/state/active.json，让 status、next 和 validate 在未传 --slug 时稳定选择当前工作流；如果 active state 缺失或指向不存在的产物，CLI 会回退到最近修改的 Quick/Requirement 产物。路由、建档、门禁、批准和验证会在已初始化项目中追加轻量 eval 事件到 .forge-loop/state/evals/events.jsonl；事件可包含基于文件字符数的上下文估算，用来发现过大的读取计划。forge-loop eval --summary --json 的 summary.tasks 会按 slug 聚合估算 token，便于复盘单个任务的上下文开销。这些事件只用于本地聚合观察，默认不提交、不作为新门禁。

工作流自进化遵循 Proposal -> Experiment -> Adopt。forge-loop eval --propose 只提出候选；需要改变核心规则时，先用 forge-loop scaffold experiment --slug <slug> 生成 docs/workflow-experiments/<slug>.md，记录假设、证据、实验窗口、成功指标和采用/拒绝结论。

核心模板都带有结构化 frontmatter：

---
forge_loop: true
artifact: requirement
slug: add-api-auth
status: draft
gate: H1
blocking: false
---

CLI 会优先读取这些字段，Markdown 正文继续作为人类可读协议和交接文档。

Compatibility Script

如果不想通过 npm 使用，也可以直接运行兼容脚本：

./scripts/init-project.sh /path/to/project --agent codex

这个脚本会生成本地适配层，但默认引用当前仓库的 core/，不会复制 core 到目标项目，也不会安装 Codex 用户级 skill。npm CLI 是推荐路径。

Release

推荐发版命令：

npm run release -- patch
npm run release -- patch --publish

快捷 patch 发布：

npm run release:patch
npm run release:public

release helper 会要求 git 工作区干净，先运行 npm test，再用 npm version <target> -m "Release %s" 创建版本提交和 tag；只有传 --publish 时才执行 npm publish --access public。prepublishOnly 仍会自动运行 npm test，避免跳过打包检查。

Minimal Use

初始化后，在业务项目中直接说：

/forge 把登录按钮文案改成 Continue

可用命令：

/forge <任意请求，自动判断路径>
/forge-quick <小需求>
/forge-fix <小 bug>
/forge-spike <探索问题>
/forge-feature <需求>
/forge-bugfix <问题>
/forge-next [说明]
/forge-implement <Task ID>
/forge-review [范围]

Quick Lane 适合低风险、1 到 3 个文件内的小改动，会生成 tasks/quick/<slug>.md。涉及 API、权限、安全、数据迁移、多模块并行、超过 3 个文件或高风险时，命令会升级到完整 Feature Iteration。

Quick Lane spike 也承载 zoom-out、architecture review、issue triage 和 optimization review。它只记录模块地图、架构候选、triage 建议或 follow-up，不直接重构生产代码。

默认推荐只用 /forge。细分命令用于你想强制指定路径时。

Workflow Model

Forge Loop 提供两条执行路径：Quick Lane 和 Feature Iteration。/forge 会先做路由判断，然后选择合适路径。

整体流程图：

flowchart TD
    A["用户请求<br/>/forge 或普通实现、修复、review、继续"] --> B["Auto Intake<br/>读取 AGENTS、workflow-config、project-context、overrides、Core"]
    B --> C["优先调用 CLI<br/>forge-loop route --json"]
    C --> D{"路由判断"}

    D -->|"低风险小改动<br/>1-3 文件<br/>无契约/权限/数据影响"| Q1["Quick Lane"]
    D -->|"明确小 bug / 测试失败<br/>范围小"| Q2["Quick Fix Mode"]
    D -->|"探索、调研、优化评估<br/>zoom-out / 架构 review / issue triage"| Q3["Quick Spike Mode"]
    D -->|"API、权限、安全、计费<br/>数据迁移、跨模块、并行、高风险"| F1["Feature Iteration"]

    Q1 --> Q4["生成 tasks/quick/slug.md"]
    Q2 --> Q4
    Q3 --> Q4
    Q4 --> Q5{"Quick 类型"}
    Q5 -->|"quick"| Q6["实现最小必要改动"]
    Q5 -->|"fix"| Q7["先复现、收集证据、定位根因<br/>再修复"]
    Q5 -->|"spike"| Q8["只分析，记录 Findings / Follow-ups"]
    Q6 --> Q9["运行局部验证"]
    Q7 --> Q9
    Q8 --> Q10["更新 quick task 结果"]
    Q9 --> Q10
    Q10 --> Q11["Quick 完成或升级 Feature"]

    F1 --> F2["Requirement<br/>specs/requirements/slug.md"]
    F2 --> F3["Product Review<br/>specs/requirements/slug-review.md"]
    F3 --> H1{"H1 需求确认<br/>gate + human approve"}

    H1 -->|"通过"| F4["Design<br/>specs/designs/slug-design.md"]
    H1 -->|"阻塞"| S1["停止并报告缺失项"]

    F4 --> F5{"Contract Required?"}
    F5 -->|"yes"| F6["Contract<br/>specs/contracts/slug-contract.md"]
    F5 -->|"no"| F7["Design 记录跳过原因"]
    F6 --> H2{"H2 设计/契约确认<br/>gate + human approve"}
    F7 --> H2

    H2 -->|"通过"| F8["Task Planning<br/>tasks/plans/slug-plan.md"]
    H2 -->|"阻塞"| S1

    F8 --> F9{"Parallel Execution?"}
    F9 -->|"yes"| F10["Dependency Analysis<br/>+ Execution Plan"]
    F9 -->|"no"| F11["顺序执行计划"]
    F10 --> H3{"H3 执行计划确认<br/>gate + human approve"}
    F11 --> H3

    H3 -->|"通过"| F12["Implementation<br/>每个任务产出 task-result"]
    H3 -->|"阻塞"| S1

    F12 --> F13["Integration / Merge<br/>integration-report"]
    F13 --> F14["Testing<br/>test-report"]
    F14 --> F15["Code Review<br/>review-report"]
    F15 --> H4{"H4 最终 Review<br/>无 Must Fix / 高风险"}
    H4 -->|"通过"| F16["人工 merge / 可选 H5 上线确认"]
    H4 -->|"阻塞"| S1
    F16 --> F17["Retrospective 或记录跳过原因"]
    F17 --> F18["更新长期 docs / follow-ups / done"]

Quick Lane

Quick Lane 面向敏捷小迭代和一句话需求。

适合：

• 低风险小改动。
• 预计修改 1 到 3 个文件。
• 不涉及 API、权限、安全、计费、数据迁移。
• 不需要 subagents 并行。
• 可以用局部测试或简单检查验证。
• 可以是 zoom-out、architecture review、issue triage 或 optimization review，只分析不实现。

流程：

/forge
→ 判断为 Quick Lane
→ 生成 tasks/quick/<slug>.md
→ 实现最小改动、建立 bug feedback loop，或完成 spike 探索
→ 运行局部验证
→ 更新 quick task 结果

产物：

tasks/quick/<slug>.md

Feature Iteration

Feature Iteration 面向中大型功能、并行开发和契约敏感改动。

触发条件：

• 涉及 API、权限、安全、计费、数据删除或数据库迁移。
• 跨模块、跨前后端或预计超过 3 个文件。
• 需要 subagents 并行。
• 需求范围不清或风险较高。
• 需要设计、契约、任务 DAG 或集成门禁。
• 输入是 Issue URL、#123 或本地 issue 文件且需要产品/技术 intake。

流程：

/forge
→ Requirement
→ Product Review
→ H1 需求确认
→ Design
→ Contract（仅共享契约需要时）
→ H2 设计与可选契约确认
→ Task Planning
→ Dependency Analysis / Scheduling（仅 subagents 并行需要时）
→ H3 执行计划确认
→ Implementation
→ Integration
→ Testing
→ Code Review
→ H4 最终 Review
→ Retrospective（条件触发，可记录跳过原因）

核心产物：

specs/requirements/
specs/designs/
specs/contracts/
tasks/plans/
tasks/results/
docs/retrospectives/
docs/agents/
docs/adr/
.out-of-scope/

Feature Iteration 默认读取 CONTEXT.md、CONTEXT-MAP.md、.ai/project-context.md 和 docs/agents/domain.md 来保持领域语言一致。Design 阶段会判断 ADR Required: yes/no 并标注 Fragile Assumption；Task Planning 阶段会优先拆 vertical tracer bullet，并为每个任务标注 Execution Mode: AFK/HITL、Human Touchpoint 和 Verification Surface。Review 阶段按 diff 面积记录 Review Depth，并区分 safe_auto、gated_auto、manual 和 advisory。

Human Gates

门禁是 Forge Loop 的核心能力：Agent 可以推进文档和低风险实现，但关键决策必须停下来让人确认。

| Gate | 位置 | 目的 | 继续方式 | | --- | --- | --- | --- | | H1 | Requirement + Product Review 后 | 确认目标、范围、验收标准 | /forge-next H1 已确认 | | H2 | Design + optional Contract 后 | 确认技术方案、共享契约判断、风险和回滚 | /forge-next H2 已确认 | | H3 | Task Planning + optional Scheduling 后 | 确认执行顺序、并行判断、文件边界 | /forge-next H3 已确认 | | H4 | Integration + Testing + Code Review 后 | 确认无 Must Fix、无高风险未解释问题 | 人工合并或继续复盘 |

关键规则：

• 没有需求，不进入设计。
• 需要共享契约但没有契约，不并行开发。
• 需要 subagents 并行但没有依赖分析，不调度 subagents。
• 没有 task result，不集成。
• 有 unresolved conflicts，不进入 Review。
• 有 Must Fix，不合并。
• 高风险或生产操作只给建议，不自动执行。

Routing Rules

/forge 的默认路由逻辑：

| 判断 | 路由 | | --- | --- | | 小、低风险、1 到 3 个文件 | Quick Lane | | 明确小 bug | Quick Lane fix mode | | 探索、调研、评估优化空间、不确定方案 | Quick Lane spike mode | | zoom-out、模块地图、架构评审 | Quick Lane spike mode | | Issue URL、#123、本地 issue 文件 | Issue Intake，然后 Quick 或 Feature | | issue triage、ready-for-agent 判断 | Quick Lane spike mode | | API、权限、安全、计费、数据迁移 | Feature Iteration | | 跨模块、跨前后端、需要并行 | Feature Iteration | | 用户说“继续” | 从当前门禁进入下一阶段 | | 用户说“实现 T2” | 执行单个任务 | | 用户说“review / 提交前检查 / check before commit” | Code Review |

如果 Agent 无法安全判断，必须选择更保守的路径：先生成分析或需求文档，并停在人工确认点。

Agent Command Behavior

/forge 会自动判断路径：

| 输入类型 | 默认路径 | 产物 | | --- | --- | --- | | 小需求、低风险、1 到 3 个文件 | Quick Lane | tasks/quick/<slug>.md | | 小 bug | Quick Lane fix mode | tasks/quick/<slug>.md | | 探索/调研/zoom-out/架构评审/issue triage | Quick Lane spike mode | tasks/quick/<slug>.md | | Issue URL、#123、本地 issue 文件 | Issue Intake | specs/requirements/* 或 tasks/quick/<slug>.md | | API、权限、安全、数据迁移、多模块、高风险 | Feature Iteration | specs/requirements/* 并停在 H1 | | 继续当前迭代 | Next gate | 推进到 H2/H3/H4 | | 实现 Tn | Implementation Skill | tasks/results/task-result-Tn.md | | Review / 提交前检查 | Code Review Skill | tasks/results/<slug>/review-report.md |

Natural Trigger Phrases

除了 /forge-* 之外，以下自然语义也应该直接唤起对应阶段：

| 用户说法 | 默认阶段 | | --- | --- | | “设计一下 / 技术方案 / 怎么做更稳” | H2 Design | | “拆任务 / 排计划 / 怎么分工” | H3 Task Planning | | “补测试 / 回归一下 / 验证一下” | Testing | | “集成一下 / 合一下这些任务” | Integration / Merge | | “准备提交 / 开 PR / merge 前看一眼 / 提交前检查” | H4 Code Review | | “复盘一下 / 收尾 / 记一下经验教训” | Retrospective |

如果仓库是 git 项目且工作区存在未提交改动，forge-loop status 和 forge-loop next 也会额外提示：如果你正准备提交 commit 或开 PR，先运行 /forge-review 刷新当前 diff 的 review。

Codex 和 Claude Code 的入口不同：

| Agent | 安装位置 | 初始化方式 | | --- | --- | --- | | Codex | ~/.codex/skills/forge-loop/SKILL.md | npx @shawnxie666/forge-loop init --agent codex | | Claude Code | .claude/skills/*/SKILL.md | npx @shawnxie666/forge-loop init --agent claude-code | | 其他 Agent | .forge-loop/commands/*.md + AGENTS.md | npx @shawnxie666/forge-loop init |