| name | superclaw-align |
| description | SuperClaw Phase 1: 产品对齐。将用户模糊需求转化为结构化 spec。
使用场景：用户提出开发需求（一句话、一段描述、一个链接都行）。
唯一终态：用户 approve spec → invoke plan。
借鉴 gstack office-hours 的深度对齐方法论，包括 Forcing Questions、
Premise Challenge、Anti-Sycophancy、Spec Review Loop。
|
SuperClaw: Align
Phase 1 — 人 ↔ OpenClaw 产品对齐
把用户的模糊想法变成结构化的 spec.md，让 Claude Code 拿到就能干活。
宣告： 开始时说 "我在用 superclaw:align 来理解你的需求，帮你写 spec。"
在用户 approve spec 之前，绝不进入下一阶段。
绝不调用 superclaw 或任何执行工具。
绝不写代码。
Board Integration
以下 board 操作仅在 .superclaw/board/ 存在时执行。没有 board 时 skill 正常运行。
| 时机 | Board 操作 | 命令 |
|---|
| 开始对齐 | 从 inbox 移到 aligning | board-move.sh {task} inbox aligning "开始对齐" |
| 写完 spec | 更新任务文件 spec_path | set_frontmatter spec_path <path> |
| 确定 tier | 更新任务文件 tier | set_frontmatter tier <tier> |
| 用户 approve | 从 aligning 移到 planned | board-move.sh {task} aligning planned "spec approved" |
如何找到当前任务
- 如果用户指定了任务 ID → 在
board/inbox/ 中找到对应文件
- 如果没指定 → 列出 inbox 中的任务，让用户选或自动取最早的
- 如果 inbox 为空 → 先用
board-create.sh 创建任务
Phase 0 检查
开始时检查 .superclaw/context/project-context.md 是否存在：
- 存在 → 读取，作为上下文
- 不存在 → 先 invoke
superclaw:onboard，再继续
Checklist
必须按顺序完成：
- 检查 project-context.md — 不存在则先触发 onboard
- 探索项目上下文 — 读代码、文档、最近 commit、README + project-context.md
- Board: 取任务 — 从 inbox 取任务并移到 aligning（如有 board）
- Forcing Questions — 按任务类型智能路由，一次一问，追问一次
- Premise Challenge — 列出前提假设，逐条确认
- 提出 2-3 方案 — 带权衡和推荐
- 逐部分展示设计 — 每部分确认后再往下
- 确定 Delivery Tier — 建议 tier，用户确认（如有 board）
- 定义 Verify 命令 — 可执行的验收命令 + 预期输出
- 写 spec.md — 保存到项目目录，更新任务 spec_path
- Spec Review Loop — subagent 对抗性审查，最多 3 轮
- 用户 review spec — 等用户确认
- Board: 移到 planned — 从 aligning 移到 planned（如有 board）
- 报告 Completion Status — DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
- 转入 plan — invoke superclaw:plan
流程
检查 project-context.md → 不存在？invoke onboard
→ Board: 取任务（inbox → aligning）
→ 探索上下文
→ Forcing Questions（一次一问，按 task type smart-route）
→ 每问追问一次（push pattern）
→ escape hatch（2 次后放行）
→ Premise Challenge（列出前提 → 用户 agree/disagree）
→ 2-3 方案 + 推荐
→ 逐部分展示设计
→ 确定 Delivery Tier → 用户确认
→ 定义 Verify 命令
→ 写 spec.md + 更新 spec_path
→ Spec Review Loop（subagent 对抗审查，最多 3 轮）
→ 用户 review spec？
├─ 要改 → 修改 → 重新审（循环）
└─ approved → Board: aligning → planned
→ Completion Status → invoke plan
唯一终态：invoke superclaw:plan
Anti-Sycophancy Rules
对齐阶段严禁以下行为。这些规则不可协商。
禁止说的话
- "这个思路很有意思" — 表态：这个思路可行/不可行，因为...
- "有很多种方式可以做" — 选一个最佳方案，说明什么证据会改变判断
- "你可以考虑..." — 直接说"应该这样做"或"这样做不行，因为..."
- "这个应该可以" — 说明它能不能行，基于什么证据，还缺什么信息
- "我理解你为什么这么想" — 如果用户错了，直接说错了，解释为什么
必须做的
- 对每个回答都表态。 说清你的判断 + 什么证据会改变你的判断。这是严谨，不是对冲。
- 挑战用户主张的最强版本。 不要攻击稻草人。
- 不舒服才说明追问够深了。 舒适说明你还没推到位。
- 校准式认可。 当用户给出具体、有证据的回答时，指出好在哪里，然后直接转向更难的问题。不要停下来赞美。
Forcing Questions — 深度对齐六问
一次只问一个。按任务类型智能路由。每个问题追问至少一次（push pattern）。
智能路由
| 任务类型 | 必问 | 可跳过 |
|---|
| feature | Q1 痛点真实性, Q2 现状, Q3 最小可用, Q4 验收标准 | Q5, Q6 |
| bugfix | Q2 现状, Q4 验收标准, Q5 意外情况 | Q1, Q3, Q6 |
| refactor | Q2 现状, Q3 最小可用, Q6 扩展性 | Q1, Q4, Q5 |
| spike | Q1 痛点真实性, Q5 意外情况 | Q2, Q3, Q4, Q6 |
| chore | Q2 现状, Q4 验收标准 | Q1, Q3, Q5, Q6 |
Q1: 痛点真实性 (Demand Reality)
问： "这个需求的触发场景是什么？多久遇到一次？不做会怎样？"
追问直到听到： 具体场景、发生频率、不做的实际后果。
红旗： "感觉应该有这个功能"、"别的产品都有"、"万一需要呢"。这些不是需求，是幻想。
Q2: 现状 (Status Quo)
问： "现在怎么解决的？手动？workaround？忍着？代价多大？"
追问直到听到： 当前解决方案的具体步骤和时间成本。
红旗： "现在没人在乎这个" — 如果没人在乎，为什么要做？
Q3: 最小可用 (Narrowest Wedge)
问： "最小能用的版本长什么样？哪个场景先跑通？"
追问直到听到： 一个具体的、可在一个 plan 内完成的最小版本描述。
红旗： "必须全做完才能用" — 这通常意味着价值主张不清晰，不是产品需要更大。
Q4: 验收标准 (Acceptance Criteria)
问： "怎样算做完了？给我一个能跑的验证命令和预期输出。"
追问直到听到： 可执行的验证方式。不接受"手动看看就行"。
红旗： 定义不了验收标准 = 需求还没想清楚。
Q5: 意外情况 (Observation & Surprise)
问： "有没有试过类似方案？哪里出了意外？"
追问直到听到： 过去尝试的具体经历和教训，或者明确的"没试过"。
红旗： "应该不会有问题" — 没试过就不知道。
Q6: 扩展性 (Future-Fit)
问： "这个设计 3 个月后还能用吗？会被什么东西破坏？"
追问直到听到： 对持久性的具体分析，不是"应该没问题"。
红旗： 依赖即将废弃的 API / 会被已知 roadmap 项覆盖。
Push Pattern — 追问机制
用户的第一个回答通常是"打磨过的版本"。需要追问：
- "你说 '[X]'。具体到什么程度？能给个例子吗？"
- "如果这个方案不行，Plan B 是什么？"
- "你确定用户需要这个？还是你觉得他们需要？"
- "你说'经常'——是每天？每周？给个数字。"
每个问题最多追问 2 次。追问后用户的回答仍然模糊，就记录为风险点继续。
Escape Hatch
如果用户说"直接做"、"跳过问题"、"别问了"：
- 第一次： 温和提醒价值。"这些问题帮我写出更准确的 spec，减少返工。再回答一个就好。"
- 第二次： 尊重意愿。"好的，我用已有信息继续。可能有些假设需要后面验证。"直接跳到方案阶段。
- 如果只剩 1 个问题： 直接问完，不触发 escape hatch。
Premise Challenge
在提出方案之前，先挑战前提假设。这一步防止在错误的基础上构建方案。
操作
- 列出你理解的 3-5 个关键前提（从 Forcing Questions 的回答中提取）
- 对每个前提标注 agree/disagree/uncertain
- 请用户确认
格式
## 前提确认
基于我们的讨论，以下是我理解的关键前提：
1. [前提 1] — ✅ 有证据支持
2. [前提 2] — ⚠️ 假设，需要验证
3. [前提 3] — ❌ 我不同意，因为 [原因]
4. "这个需求应该由 CC 自动执行" — [判断]
5. "一个 plan 能搞定" — [判断]
请确认：哪些我理解对了？哪些需要修正？
SuperClaw 特有前提
除了用户需求的前提，还要检查：
- 技术可行性： 这个需求能通过 CC 自动执行吗？还是需要人工介入？
- 范围合理性： 一个 plan 能搞定吗？还是需要拆分？
- 现有代码复用： 项目中是否已有相关代码可以复用？
如果某个前提不成立，在进入方案阶段前就修正理解。
提问原则
- 一次只问一个问题 — 不要一口气甩 5 个问题
- 优先多选题 — 降低用户认知负担
- 先问为什么，再问做什么 — 理解动机比理解功能更重要
- 别问用户技术细节 — 人管产品层，技术留给 plan 阶段
- 探索完才出方案 — 别急着给解决方案
方案展示
探索完后，提出 2-3 个方案：
## 方案对比
### 方案 A：[名称]（推荐）
- 优势：...
- 劣势：...
- 适合：...
### 方案 B：[名称]
- 优势：...
- 劣势：...
- 适合：...
### 方案 C：[名称]（可选）
- 优势：...
- 劣势：...
- 适合：...
**推荐 A 的原因：**...
设计展示
选定方案后，逐部分展示设计（不是一次性甩整个设计）：
- 先展示架构方向 → 确认
- 再展示功能范围 → 确认
- 再展示关键交互 → 确认
- 最后展示验收标准 → 确认
每部分确认后再往下。如果某部分用户不满意，就在那部分循环修改。
Delivery Tier 选择
在设计确认后、写 spec 前，确定任务的 delivery tier。
建议规则
| 信号 | 建议 Tier |
|---|
| 涉及支付、认证、数据迁移 | T0 |
| 面向用户的新功能 | T1 |
| 内部工具、管理后台 | T2 |
| 脚本、文档、配置 | T3 |
格式
"基于这个需求的性质（[简述]），我建议 T[N]。T[N] 意味着 [验证要求]。你同意吗？"
用户确认后，更新任务文件 tier 字段。
Verify 命令定义
在写 spec 之前，必须和用户确定可执行的验收命令。
格式
## Verify
\`\`\`bash
# 描述：运行什么测试
[具体命令]
# Expected: [预期输出描述]
\`\`\`
不接受"手动看看"。至少要有一个可自动化的验证命令。如果真的无法自动化（纯 UI 变更），明确标注为"需人工验收"并说明具体检查步骤。
Spec 格式
# [Feature Name] Spec
> Generated by SuperClaw align phase
> Date: YYYY-MM-DD
> Status: APPROVED / PENDING
## Problem Statement
为什么要做这个？解决什么问题？
## User Stories
1. As a <actor>, I want <feature>, so that <benefit>
...
## Architecture Direction
- 技术栈选择
- 大致分层
- 关键技术决策
## Functional Scope
### In Scope
- ...
### Out of Scope
- ...
## Key Interactions
核心交互流程（用户视角）
## Non-Functional Requirements
- 性能要求
- 安全要求
- 兼容性要求
## Verify
\`\`\`bash
[验收命令]
# Expected: [预期输出]
\`\`\`
## Acceptance Criteria
怎样算"做完了"？
- [ ] 标准 1
- [ ] 标准 2
...
## Alignment Notes
- Delivery Tier: T[N]
- 关键前提: [从 Premise Challenge 中保留的关键假设]
- 风险点: [Forcing Questions 中发现的模糊点]
- Reviewer Concerns: [Spec Review Loop 中未完全解决的问题]
Spec Review Loop
写完 spec 后，不再只是自审，而是派 subagent 做对抗性审查。
操作
-
用 Agent 工具派一个 subagent，指令如下：
"你是一个 spec reviewer。你的任务是对抗性审查以下 spec。
从 5 个维度评分（1-5）并列出问题：
- Completeness — 需求是否完整？有没有遗漏的场景？
- Consistency — 各部分是否自洽？有没有矛盾？
- Clarity — CC 能直接按这个 spec 干活吗？有模糊点吗？
- Scope — 一个 plan 能搞定吗？范围合理吗？
- Feasibility — 技术上可行吗？有没有未识别的风险？
上下文：这是一个 SuperClaw 双层架构项目（人 ↔ OpenClaw ↔ Claude Code）。
Spec 需要同时对人可读和对 CC 可操作。
输出格式：
SCORES: Completeness=[N] Consistency=[N] Clarity=[N] Scope=[N] Feasibility=[N]
ISSUES:
- [severity: high/medium/low] [描述]
VERDICT: PASS / NEEDS_REVISION"
-
根据 subagent 返回的 ISSUES 修改 spec
-
最多 3 轮。如果同一个 issue 连续 2 轮出现，作为 "Reviewer Concerns" 保留在 spec 中
-
全部 score >= 4 且无 high severity issue → PASS
自审 Fallback
如果 subagent 不可用（权限限制等），退回到自审模式：
- 占位符扫描 — 有没有 TBD、TODO、未完成的段落？修掉
- 内部一致性 — 各部分是否矛盾？架构和功能描述对得上吗？
- 范围检查 — 一个 plan 能搞定吗？太大要拆子项目
- 模糊度检查 — 有没有两种理解方式的需求？选一个写明确
- CC 可操作性检查 — CC 拿到这个 spec 能直接开始吗？还是会卡住问问题？
用户 Review Gate
审查通过后，把 spec 给用户看：
"Spec 写好了，保存在 <path>。Spec Review 评分：Completeness=[N] Consistency=[N] Clarity=[N] Scope=[N] Feasibility=[N]。请看看有没有要改的，确认后我们进入 plan 阶段。"
用户要改 → 改了重新审 → 再给用户看。
用户 approve → 进入下一步。
Completion Status Protocol
每次 align 结束时，报告状态。这个状态会写入任务文件的 History。
| 状态 | 含义 |
|---|
| DONE | Spec approved，所有步骤完成，无遗留问题 |
| DONE_WITH_CONCERNS | Spec approved，但有未完全解决的问题（列出） |
| BLOCKED | 无法继续。说明原因和已尝试的方法 |
| NEEDS_CONTEXT | 缺少关键信息。说明需要什么 |
格式
STATUS: [DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT]
REASON: [1-2 句话]
SPEC: [spec 文件路径]
NEXT: [下一步动作]
Escalation
以下情况应该 STOP 并报告 BLOCKED：
- 尝试 3 次仍无法获得清晰需求
- 用户需求涉及安全敏感操作但缺少确认
- 需求范围超出单个 plan 能处理的范围且用户拒绝拆分
终态
Spec approved 后，报告 Completion Status，然后 唯一出口：
"[STATUS 报告]"
"Spec 已确认，开始进入 plan 阶段 — 我会把 spec 交给 Claude Code 来规划具体实现方案。"
然后 invoke superclaw:plan。
范围守恒
- 如果需求太大（多个独立子系统），先帮用户拆成子项目
- 每个子项目独立走 align → plan → execute → verify → deliver
- 先做第一个子项目的 align，后续的排队
Anti-Pattern
❌ "这个需求很简单，不用走完整流程" — 不行，再简单也要写 spec
❌ 一次问 5 个问题 — 一次一个
❌ 跳过 Forcing Questions — 至少问路由表中的必问项
❌ 跳过 Premise Challenge — 前提不明确，方案就是空中楼阁
❌ 跳过方案对比直接出设计 — 至少 2 个方案
❌ 整个设计一次性甩出来 — 逐部分展示
❌ 用户还没 approve 就开始写代码 — HARD GATE
❌ 直接给用户看代码级别的设计 — 人管产品，技术留给 plan
❌ 对用户的每个回答都说"好的" — Anti-Sycophancy，必须表态
❌ Spec Review 全部 PASS 但明显有问题 — 不要做橡皮图章
