moai

执行前上下文

!git status --porcelain 2>/dev/null || true !git branch --show-current 2>/dev/null || true

必要文件

.moai/config/sections/*.yaml

---

权威参考

所有工作流的规则和约束始终从以下来源加载。请勿在此处重复其内容：

• 核心身份、编排原则、Agent 目录：CLAUDE.md
• 质量门禁、安全边界：.claude/rules/moai/core/moai-constitution.md
• SPEC 工作流阶段、令牌预算：.claude/rules/moai/workflow/spec-workflow.md
• 开发方法（DDD/TDD）：.claude/rules/moai/workflow/spec-workflow.md（Run Phase 部分）
• Agent 定义：参见 CLAUDE.md 第 4 节。创建 Agent 时，使用 builder-harness 子 Agent（artifact_type=agent）。
• @MX 标签规则和协议：.claude/rules/moai/workflow/mx-tag-protocol.md

---

路由观察账本

分派子命令或工作流时，编排器会在分派时通过 moai harness ledger record 将路由决策记录到仅追加的路由账本（.moai/state/routing-ledger.jsonl）中——请求文本通过 stdin 传入，且仅存储保护隐私的摘要，绝不存储用户原文。当路由的管线到达门禁点时，会通过 moai harness ledger evidence 追加机器证据（门禁退出状态、审计判定、验证日志路径）。结果不会作为输入提供；仅根据机器证据确定最终结果。此观察功能为选择启用且故障开放——绝不会阻止路由。注意：记录取决于编排器是否在分派时实际调用 moai harness ledger record；当可观察性选择启用为 ON，但未发出该记录调用时，账本会保持为空——这表示分派未被记录，而不是选择启用关闭后的空操作。不要将空路由账本解读为“选择启用已禁用”。

---

意图路由器

原始用户输入

$ARGUMENTS

路由说明

[HARD] 按照以下严格优先级顺序路由上方的原始用户输入。提取输入的第一个词用于子命令匹配。子命令关键字之后的所有文本均为要传递给匹配工作流的上下文，不是路由信号，且绝不得影响所选工作流。

执行模式标志（互斥）

• --team：强制采用 Phase 4 的 4 种模式目录中的 Agent 团队模式（.claude/rules/moai/workflow/orchestration-mode-selection.md §A），并受其能力门禁约束
• --solo：强制采用串行模式（子 Agent——每个阶段使用单个顺序执行的 Agent）
• 无标志：编排器在 Phase 4 从完整的 4 种模式目录中自动选择；复杂度自动选择阈值仅在 orchestration-mode-selection.md §B.1 中说明一次（机器来源：workflow.yaml auto_selection），此处不再重述

--team / --solo 标志会强制覆盖目录中的选择；未指定标志时，默认行为会根据目录决策树（§B）及其能力门禁确定。--mode 分派轴是独立的轴——参见 orchestration-mode-selection.md §G.1 中的对照表（对应关系，而非合并）。

优先级 1：显式子命令匹配

[HARD] 从上方的 Raw User Input 部分提取第一个词。如果它与下方任一子命令（或其别名）匹配，立即路由到相应工作流。不要分析剩余文本以进行路由——剩余文本是匹配工作流的上下文：

[HARD] 混合语言保护：仅当 (a) 输入为纯 ASCII/拉丁文，或 (b) 消息以字面形式的 /moai 斜杠命令开头时，才按第一个词匹配子命令。如果消息在第一个词之后包含非拉丁文字（韩文／日文／中文等），不要根据开头的英文词立即路由——它可能是嵌入的外来词，应转到优先级 3，对整条消息进行语义分类。原因：CJK 技术写作会在句首嵌入英文外来词，例如 'goal'、'run'、'fix'、'plan'；按第一个词立即路由会导致误判。

• plan（别名：spec）：SPEC 文档创建工作流
• run（别名：impl）：DDD/TDD 实现工作流（遵循 quality.yaml 中的 constitution.development_mode）
• sync（别名：docs、pr）：文档同步与 PR 创建
• project（别名：init）：项目文档生成
• feedback（别名：fb）：GitHub issue 创建
• fix：一次性自动修复错误
• loop：迭代自动修复，直到满足完成条件
• mx：扫描代码库中的 MX 标签并添加注释
• review（别名：code-review）：代码审查，检查安全性和 MX 标签合规性
• clean（别名：dead-code）：识别并安全移除死代码
• codemaps：在 .moai/project/codemaps/ 中生成架构文档
• gate（别名：check、pre-commit）：轻量级提交前质量门禁（lint+format+type-check+test）
• e2e（别名：e2e-test、end-to-end）：跨平台端到端测试（web/mobile/desktop），自动检测项目类型并优先选择 CLI 工具链
• harness（别名：hrn）：harness 生命周期管理——学习生命周期动词（status / apply / rollback <date> / disable）和 v4 生命周期动词（list / edit / remove / doctor）均通过统一的 moai harness Go 二进制 Cobra 子命令树进行分发；斜杠命令是文档中面向用户的入口
• goal：由条件声明的通用 Agent 循环——设置完成条件（/moai goal "<condition>"）、检查状态、清除或恢复；每轮结束时由 stop-goal Stop hook 进行评估
• todo（别名：backlog）：待办队列——斜杠命令提供两种操作：添加事项（/moai todo "<description>"）和列出队列（不带参数的 /moai todo）。选择下一张任务卡和移除任务仅支持通过 CLI 操作，命令为 moai todo next [<n>] 和 moai todo done <n>；这是操作人员进入看板的入口

优先级 2：SPEC-ID 检测

仅当优先级 1 未匹配时：检查 Raw User Input 是否包含匹配 SPEC-XXX 的模式（例如 SPEC-AUTH-001）。如果找到，则自动路由到 run 工作流。SPEC-ID 将作为 DDD/TDD 实现的目标。

优先级 3：自然语言分类

仅当优先级 1 和优先级 2 均不匹配时，才将整条原始用户输入作为自然语言进行意图分类。如果首词匹配已知子命令，则永远不会到达此优先级。

[HARD] 以下列出的提示词是英文示例，并非字面匹配要求。对于任何 conversation_language，都应根据语义进行分类——表达相同意图的韩语、日语、中文或其他语言请求，路由方式都相同。无需求英文原词出现在输入中。

• 规划和设计类语言（设计、架构、计划、规范、需求、功能请求）路由到 plan
• 质量门禁类语言（格式化、检查、pre-commit、质量门禁）路由到 gate
• E2E 和用户旅程测试类语言（e2e、端到端测试、浏览器测试、移动应用测试、桌面应用测试、用户旅程）路由到 e2e ——这些是语义示例；任何 conversation_language 中表达 E2E 测试意图的请求，路由方式都相同
• 安全类语言（安全、审计、owasp、漏洞、注入、xss、csrf）路由到 review（使用 --security 范围）
• 代码审查类语言（审查我的代码、代码审查、检查我的 PR、查看我的更改）路由到 review
• 错误和修复类语言（修复、错误、bug、损坏、失败、lint）路由到 fix
• 迭代和重复类语言（持续修复、直到完成、重复、迭代、所有错误）路由到 loop
• 死代码和清理类语言（死代码、未使用的代码、安全移除、清理、孤立代码）路由到 clean
• 文档类语言（编写文档、同步、docs、readme、changelog、PR）路由到 sync 或 project
• 架构图类语言（架构图、代码地图、依赖关系图、结构文档）路由到 codemaps
• 反馈和 bug 报告类语言（报告、反馈、建议、问题）路由到 feedback
• MX 标记类语言（mx 标记、注释、代码上下文、旧式注释）路由到 mx
• 待办列表类语言（添加到待办列表、记下来以后处理、接下来该做什么、提醒我）路由到 todo ——这些是语义示例；任何 conversation_language 中表达“将此排入队列，现在不要开始”的请求，路由方式都相同
• 具有明确范围的实现类语言（实现、构建、创建、添加、开发）路由到 moai（默认自主执行）

优先级 4：默认行为

如果经过所有优先级检查后，意图仍不明确，则使用 AskUserQuestion 展示最匹配的 2-3 个工作流，并让用户选择。

如果明确是开发任务，但没有特定的路由信号，则默认使用 moai 工作流（plan -> run -> sync 流程），以实现完全自主执行。

---

工作流快速参考

plan - SPEC 文档创建

用途：使用 GEARS 格式，通过 Research-Plan-Annotate 循环创建完整的规范文档。 阶段：深入研究（research.md）-> SPEC 规划 -> 注释循环（1-6 次迭代）-> SPEC 创建 -> 独立审查（plan-auditor） Agent：manager-spec（主要）、Explore（研究）、plan-auditor（质量门禁）、manager-git（按需） 技能：moai-workflow-spec、moai-foundation-thinking（根据 delegation.yaml） 标志：--branch、--resume SPEC-XXX、--issue（可选启用；根据延迟创建分支的可选策略，默认跳过 GitHub Issue 创建） 详细编排说明：阅读 ${CLAUDE_SKILL_DIR}/workflows/plan.md

run - DDD/TDD 实现

用途：通过配置的开发方法实现 SPEC 需求。 Agent：manager-develop（根据 quality.yaml 中的 cycle_type=ddd|tdd 设置主要类型）、manager-git 技能：moai-workflow-tdd、moai-workflow-ddd（根据 delegation.yaml，按 cycle_type 选择）+ 根据任务注入领域 moai-ref-* 标志：--resume SPEC-XXX、--team（实验性——重新允许 Agent Teams；参见 Execution Mode Flags） 详细编排说明：阅读 ${CLAUDE_SKILL_DIR}/workflows/run.md

sync - 文档同步与 PR

用途：使文档与代码变更保持同步，并准备拉取请求。 Agent：manager-docs（主要）、sync-auditor（质量门禁）、manager-git 技能：moai-workflow-project（根据 delegation.yaml） 模式：auto、force、status、project。标志：--merge、--skip-mx 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/sync.md

gate - 提交前质量门禁

用途：轻量级提交前质量检查，并行运行 lint、格式检查、类型检查和测试。也集成到 run（阶段 15）和 sync（阶段 1）工作流中，作为自动预检查。 Agent：直接执行（不委派 Agent） 标志：--fix、--staged、--file PATH 集成：run 工作流（阶段 15）和 sync 工作流（阶段 1）会自动调用，并启用 --fix 行为。 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/gate.md

e2e - 多平台端到端测试

用途：为 Web、移动端和桌面应用创建并运行 E2E 测试，支持自动检测项目类型、优先选择 CLI 工具链（Playwright、Maestro、Playwright-Electron、WebdriverIO + tauri-service），并尽量减少令牌用量。 Agent：e2e-tester（主要 — 检测、旅程映射、脚本创建、执行、录制） 技能：moai-foundation-quality、moai-ref-testing-pyramid（根据 delegation.yaml） 标志：--tool、--platform、--record、--url、--journey、--headless、--browser、--timeout、--retry 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/e2e.md

goal - 条件声明式 Agent 循环

用途：设置完成条件（机械命令 + 模型声明）；stop-goal Stop-hook 评估器会阻止每轮结束，直到条件满足或达到轮次上限（默认 30）。 动词：/moai goal "<condition>"（注册并启动）、status [--all]、clear、resume。 推进模式：自主（默认）或半自主 — 在实现启动审批时选择；两种模式下门禁都必须执行。 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/goal.md

todo - 待办队列

用途：收纳操作员接下来想处理的事项。backlog 没有所属会话，因此加入看板始终由操作员执行 — 这就是对应入口。 动词 — 斜杠命令入口：/moai todo "<description>"（追加）、单独使用 /moai todo（列出）。仅 CLI：moai todo next（打印排队卡片；moai todo next <n> [--spec <SPEC-ID>] 标记一项为已选 — 选择操作通过 AskUserQuestion 呈现），moai todo done <n>（移除）。 状态：.moai/state/kanban/backlog.json — 项目本地文件，不提交，采用原子写入。 由操作员选择：绝不预选，绝不按推断的优先级重新排序，绝不从 TODO 注释或 issue 自动填充。 启用：当 .moai/config/sections/workflow.yaml 中的 workflow.todo.enabled 为 false 时，不要通过推断将请求路由到此工作流 — 如果操作员没有指定子命令，就应直接回答类似待办事项的表述，而不是将其加入队列。此门禁仅约束自动路由：显式调用 /moai todo 或 /moai todo "<description>" 仍照常运行，与缺少该键或键值为 true 时完全相同。此标志抑制的是引导，而非功能 — moai todo 仍会注册，所有动词也继续有效，因此拒绝或静默忽略明确指定的调用属于缺陷，并非预期行为。 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/todo.md

fix - 自动修复错误

用途：自主检测并修复 LSP 错误、lint 问题和类型错误。 Agent：manager-develop（cycle_type=autofix）、Agent(general-purpose)，并使用领域白名单（修复） 技能：moai-workflow-ddd（根据 delegation.yaml）+ 按任务注入领域 moai-ref-* 标志：--dry、--sequential、--level N、--resume、--team（实验性 — 再次允许 Agent Teams；参见执行模式标志） 详细编排：读取 ${CLAUDE_SKILL_DIR}/workflows/fix.md

loop - 迭代式自动修复

用途：反复修复问题，直至满足完成条件或达到最大迭代次数。 Agent：manager-develop（cycle_type=autofix）、具有领域白名单的 Agent（general-purpose） 技能：moai-workflow-loop（根据 delegation.yaml）+ 根据任务注入领域 moai-ref-* 标志：--max N、--auto-fix、--seq 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/loop.md

mx - MX 标签扫描与注释

用途：扫描代码库并添加 @MX 代码级注释，为 AI Agent 提供上下文。 Agent：Explore（扫描）、具有后端范围（注释）权限的 Agent（general-purpose） 标志：--all、--dry、--priority P1-P4、--force、--team（实验性 — Agent Teams 已重新允许；参见 Execution Mode Flags） 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/mx.md

review - 代码审查

用途：从多个角度进行代码审查，分析安全性、性能、质量和 UX。 Agent：sync-auditor（审查）、具有安全范围权限的 Agent（general-purpose） 技能：moai-foundation-quality、moai-ref-owasp-checklist（根据 delegation.yaml；按审查角度注入对应的参考技能） 标志：--staged、--branch、--security、--team（实验性 — Agent Teams 已重新允许；参见 Execution Mode Flags） 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/review.md

clean - 移除死代码

用途：识别并安全移除未使用的代码，并通过测试验证。 Agent：manager-develop、具有重构范围权限的 Agent（general-purpose） 技能：moai-workflow-ddd（根据 delegation.yaml） 标志：--dry、--safe-only、--file PATH 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/clean.md

codemaps - 架构文档

用途：扫描代码库并生成架构文档。 Agent：Explore、manager-docs 标志：--force、--area AREA 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/codemaps.md

(默认) - MoAI 自主工作流

用途：完整的自主研究 -> 计划 -> 注释 -> 执行 -> 同步流程。 阶段：并行探索（research.md）-> SPEC 生成 -> 注释周期 -> 实现 -> 同步 Agent：Explore、manager-spec、plan-auditor（质量关卡）、manager-develop、manager-docs、manager-git、sync-auditor（质量关卡） 技能：moai-workflow-spec、moai-workflow-tdd（根据 delegation.yaml）+ 根据任务注入领域 moai-ref-* 标志：--loop、--max N、--branch、--pr、--resume SPEC-XXX、--team（实验性 — Agent Teams 已重新允许；参见 Execution Mode Flags）、--solo、--issue（可选启用；根据延迟分支可选启用政策，默认跳过创建 GitHub Issue） 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/moai.md

project - 项目文档

用途：通过分析现有代码库生成项目文档。 Agent：Explore、manager-docs、具有 DevOps 范围权限的 Agent（general-purpose）（可选） 技能：moai-workflow-project（根据 delegation.yaml） 输出：.moai/project/ 中的 product.md、structure.md、tech.md 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/project.md

feedback - 创建 GitHub Issue

用途：收集用户反馈并创建 GitHub Issue。 Agent：orchestrator-direct（通过 gh CLI 记录反馈） 编排详情：读取 ${CLAUDE_SKILL_DIR}/workflows/feedback.md

harness - Harness 生命周期 + 自然语言构建（参数分支）

此 harness 子命令根据 $ARGUMENTS 的第一个词元分派到两个工作流之一（基于参数的路由——不引入第二个命令）。在执行任何特定工作流的逻辑之前，先应用路由规则：

• 保留动词（status / apply / rollback / disable）→ 路由到现有的 harness 学习生命周期 工作流（下方分支 A）。此路径保持不变。
• 保留动词（list / edit / remove / doctor）→ 路由到 harness-v4 生命周期处理程序（下方分支 A.1）。这些动词通过 moai harness <verb> Go 二进制子命令枚举、编辑或原子删除 harness-v4 条目，并运行引用完整性冒烟测试门禁（doctor）。
• 其他任何内容（自然语言的 harness 创建请求，例如“为 CLI 模板开发构建一个 harness”）→ 路由到 harness 构建入口工作流（下方分支 B）。

分支 A — harness 学习生命周期（保留动词：status / apply / rollback / disable）

用途：通过斜杠命令路径，向用户展示 harness 学习子系统（观察器、4 层提案阶梯、5 层安全流水线）。生命周期动词（status / apply / rollback / disable）通过统一的 moai harness Go 二进制 Cobra 子命令树进行分派，由其执行文件系统操作。Tier-4 应用需经编排器发出的 AskUserQuestion 门禁批准。 技能：moai-harness-learner（用于展示 Tier-4 的配套技能）。项目专属 harness 生成由 v4 Builder（builder-harness Agent，分支 B）负责。 动词：status（层级分布 + 遥测）| apply（下一个 Tier-4 提案 → AskUserQuestion → 5 层流水线 → 快照 + 写入）| rollback <YYYY-MM-DD>（恢复快照）| disable（设置 learning.enabled: false） 产物：.moai/harness/usage-log.jsonl、.moai/harness/proposals/、.moai/harness/learning-history/snapshots/、.moai/harness/learning-history/applied/、.moai/harness/learning-history/frozen-guard-violations.jsonl 权威 SPEC：harness 基础策略（取代 V3R3-HARNESS-001、V3R3-HARNESS-LEARNING-001、V3R3-PROJECT-HARNESS-001） 详细编排说明：读取 ${CLAUDE_SKILL_DIR}/workflows/harness.md

分支 A.1 — harness-v4 生命周期（保留动词：list / edit / remove / doctor）

用途：管理 harness-v4 条目——枚举已构建的 harness，定位其清单文件及专用文件以供编辑，原子化移除 harness 及其所有构件，或运行引用完整性冒烟检查门禁。这四个动词会分派至 moai harness <verb> Go 二进制子命令，由其执行文件系统操作（扫描 .claude/commands/harness/*.md 并与 manifest.json 关联；原子化移除并防止遗留孤立文件；doctor 会交叉检查清单文件、专用文件和技能文件是否存在）。 动词：list（枚举所有 harness：名称 + 领域 + 入口命令；若清单声明了计划，还会显示该计划——间隔 + 机制；未声明计划的 harness 显示方式与计划功能引入前的基线完全相同）| edit <name>（显示清单文件、专用文件和技能路径以供编辑——清单文件是 SSOT）| remove <name>（原子化移除命令、工作流、专用文件、技能和清单文件；若任一构件缺失，则安全失败；若清单声明了计划，则打印注销提示并注明所声明的机制——cron 对应 CronDelete，loop 对应会话范围内的循环取消；该提示在删除前根据清单计算）| doctor（引用完整性冒烟检查门禁：验证每个已构建 harness 的清单文件、专用文件和技能文件均存在且相互引用正确；计划声明的架构无效时，会生成 ERROR 级别的问题） CLI：moai harness list [--json]、moai harness edit <name> [--json]、moai harness remove <name>、moai harness doctor（均支持 --project-root） 构件：.claude/commands/harness/<name>.md（轻量封装命令）、.claude/commands/harness/<name>/manifest.json（SSOT）、.claude/workflows/hns-<name>-run.js（Runner）、.claude/agents/harness/hns-<name>*-specialist.md（专用 Agent）、.claude/skills/hns-<name>*/（配套技能） 命名空间：.claude/commands/harness/、.claude/workflows/hns-*.js、.claude/agents/harness/ 和 .claude/skills/hns-*/ 均由用户拥有——moai update 会保留这些内容（必要时备份，绝不覆盖）。带有 harness- 或 my-harness- 前缀的旧版代际内容也会得到同等保留（基于识别的向后兼容）；Builder 仅生成 hns- 名称。

分支 B — harness 构建入口（自然语言请求）

用途：通过 Context-First Discovery（提取领域 / 目标 / 约束 / 范围），根据 harness <name> 推导名称（名称根据请求推导——由用户静态提供的情况除外），并由编排器明确发出批准，然后交由编排器直接调用 Builder（4 个由信号驱动的阶段：ANALYZE / PLAN / GENERATE / ACTIVATE），将自然语言创建 harness 的请求转化为具体的 harness。当意图清晰度低于 100% 时，编排器必须进行 AskUserQuestion 苏格拉底式提问轮次（每轮最多 4 个问题）。 Agent：builder-harness（v4 Builder——针对项目生成 harness） Builder：由编排器直接处理（不是动态工作流脚本）——入口的阶段 0-3 会交由 ${CLAUDE_SKILL_DIR}/workflows/harness-builder.md 执行 4 阶段创建逻辑。编排器直接控制 PLAN→GENERATE 的 AskUserQuestion 批准门禁；该轮提问也会询问是否需要周期性运行（可选的清单 schedule，仅用于发现的计划运行），而 ACTIVATE 会在冒烟检查门禁通过后注册已声明的计划。若请求提及某个现有 harness 并包含计划安排意图，则会路由至入口工作流的 Schedule Retrofit 分支（在处理名称冲突之前评估），而不是进入创建流程。 编排详情：阅读 ${CLAUDE_SKILL_DIR}/workflows/harness-build-entry.md

---

执行指令

激活此技能时，请按顺序执行以下步骤： 步骤 1 - 解析参数： 从原始用户输入中提取子命令关键词和标志。可识别的全局标志：--resume [ID]、--seq、--team、--solo。同时检测输入文本中的 ultrathink 关键词。

关键：深度分析模式：

• 检测到 ultrathink 关键词 → 激活 Claude 原生扩展推理（xhigh 努力度模式）。这是 Claude 的原生行为，不依赖 MCP。

步骤 1.5 - 标志与子命令兼容性验证： [HARD] 解析子命令和标志后（步骤 1），在路由之前验证标志与子命令的兼容性。如果检测到禁止的组合，立即停止所有后续处理，并使用用户的 conversation_language 输出错误。不要继续执行步骤 2。

禁止的标志与子命令组合：

标志	允许的子命令	禁止的子命令
--branch	plan、默认（自主）	run、sync

原因：--branch 会在 SPEC 初始化时创建功能分支，因此 /moai run 和 /moai sync 必须在 plan 已建立的分支上运行——在生命周期中途重新创建分支会破坏 SPEC 生命周期，因此路由器会拒绝此操作。

已退役的 --worktree 标志单独处理：携带此标志的请求不属于禁止组合错误，而是使用了已退役标志。告知用户，plan 不再创建工作区，替代方案是先进入工作区。

错误消息模板（韩语 conversation_language；替换为实际标志和子命令）：

에러: --branch 플래그는 /moai plan 전용입니다.
/moai run 과 /moai sync 는 plan 단계에서 만든 브랜치를 그대로 씁니다.

올바른 사용법:
  /moai plan SPEC-XXX --branch    (브랜치 생성)
  /moai run SPEC-XXX              (기존 브랜치 재사용)
  /moai sync SPEC-XXX             (기존 브랜치 재사용)

--branch 플래그를 뺀 형태로 다시 실행하세요.

已退役标志消息（--worktree）：

안내: --worktree 플래그는 폐기됐습니다. plan 은 더 이상 작업 공간을 만들지 않습니다.

격리된 공간에서 작업하려면 먼저 들어간 뒤 plan 을 실행하세요:
  moai cc -w <이름>              (그 자리에서 진입)
  moai cg -w <이름> --spawn      (새 tmux 창, 현재 세션 유지)
  /moai plan "<설명>"

对于英语（en conversation_language），请翻译该消息；结构保持不变。

步骤 2 - 路由到工作流： 应用意图路由器（优先级 1 到优先级 4）以确定目标工作流。如果存在歧义，使用 AskUserQuestion 向用户澄清。

步骤 2.2 - 记录路由决策： 路由解析完成后（步骤 2），立即将路由决策记录到只追加的路由日志（.moai/state/routing-ledger.jsonl），以便观察自动调用情况。运行：

echo "<raw request text>" | moai harness ledger record --subcommand <matched> --mode <phase-4-mode> --tier <tier> --level <harness-level> --session <session-id>

请求文本通过 stdin 传入，只存储保护隐私的摘要，绝不存储用户原文（政策来源：上文的 § 路由观察日志）。此步骤为可选且采用故障开放策略：如果 moai CLI 不在 PATH 中，或命令以非零状态退出，则不记录任何内容并继续——它绝不会阻止路由、限制工作流或触发重试循环。未记录的分派属于观察缺口，而非错误。

步骤 2.5 - 项目文档检查： 在执行 plan、run、sync、fix、loop 或默认工作流之前，通过检查 .moai/project/product.md 确认项目文档是否存在。如果 product.md 不存在，则使用 AskUserQuestion 以用户的 conversation_language 询问用户：

问题：未找到项目文档。是否要先创建？ 选项：

• 创建项目文档（推荐）：通过引导式访谈生成 product.md、structure.md 和 tech.md。这有助于 MoAI 了解项目背景，从而在后续所有工作流中提供更好的结果。
• 跳过并继续：在没有项目文档的情况下继续。MoAI 对项目的了解会较少。

此检查不适用于：project、feedback 子命令。

[HARD] 面向初学者的选项设计： MoAI 工作流中的所有 AskUserQuestion 调用都必须遵循以下规则：

• 第一个选项必须始终是推荐选项，并明确标记“（推荐）”后缀
• 每个选项都必须包含详细说明，解释其作用及影响

步骤 2.8 - 需求分析与完成条件： 在加载工作流正文之前（步骤 3），为路由后的请求生成一条需求分析记录：

1. 需求摘要（1-3 句话）：用编排器自己的话重述用户的请求。
2. 完成条件：表示“完成”的最终状态。如果条件可通过机器验证（测试退出码、lint 无错误状态、grep 计数、有界轮数），请按照 .claude/rules/moai/workflow/goal-directive.md 中与 /moai goal 兼容的格式表达（一个可衡量的最终状态 + 明确的检查方式 + 边界条款）。不要另行发明评估机制：在目标引擎可用时（已启用 hooks），通过 /moai goal 设置条件（评估器是 stop-goal Stop hook）；否则，编排器在每轮按相同条件文本进行评估（优雅降级——不引入新机制）。
3. 流水线契约：full-pipeline（默认的自然语言路由——阶段运行完成后自动衔接到同步）或 single-phase（显式的 run/sync 子命令——后续衔接只作为“（推荐）”的下一步选项提供，绝不静默触发）。
4. 编排形态预信号：作为 Phase 4 四模式选择（orchestration-mode-selection.md §A）的早期输入——在此处记录，在 Phase 4 决定。

琐碎范围豁免：对于 feedback、gate、codemaps、sync 状态模式，以及 askuser-protocol.md § Ambiguity Triggers and Exceptions 中的任何 Stage-1-Clarify 例外，完全跳过此步骤。 苏格拉底式优先顺序：意图清晰度未达到 100% 时，先运行苏格拉底式访谈（遵循 askuser-protocol.md），再推导完成条件——完成条件应体现已厘清的意图，绝不能是猜测。 推导出的完成条件绝不授权自动进入 run 阶段——在 plan→run 边界处，实施启动审批仍为必需。

Step 3 - 加载工作流详情： 读取目标子命令对应的 workflows/<name>.md。（Agent Teams 静态层已弃用；--team 标志会根据 .claude/rules/moai/workflow/orchestration-mode-selection.md 回退到子 Agent 模式——不存在单独的 team/<name>.md 工作流文件。）

Step 4 - 读取配置： 按需从 .moai/config/sections/*.yaml 配置文件加载相关配置。

Step 5 - 初始化任务跟踪： 使用 TaskCreate 注册已发现的工作项，并将状态设为 pending。

Step 6 - 执行工作流阶段： 遵循工作流专属的阶段说明。通过 Agent() 将所有实施工作委派给适当的 Agent。通过 AskUserQuestion 在指定检查点收集用户审批。每次启动实施/审查 Agent() 之前，应用 .claude/rules/moai/workflow/skill-routing.md §1：根据委派映射（.moai/config/sections/delegation.yaml）注入 0-3 行 At start, invoke Skill("<name>") for <reason>。

Step 7 - 跟踪进度： 随着工作推进，使用 TaskUpdate 更新任务状态（从 pending 到 in_progress，再到 completed）。

Step 8 - 呈现结果： 使用 Markdown 格式，以用户的 conversation_language 向用户展示结果。

Step 9 - 宣告完成： 所有工作流阶段成功完成后，在完成报告（横幅/正文）中说明工作流已完成，确保结果明确无误。

Step 10 - 指引后续步骤： 使用 AskUserQuestion，根据已完成的工作流向用户提供合理的后续操作。

---

版本：2.8.0 最后更新：2026-07-07