@andyqiu/codeforge 0.3.5 → 0.3.8

package/commands/parallel-status.md

@@ -0,0 +1,56 @@
+---
+description: 查询当前 inflight 子任务（subagent）的运行状态
+subtask: false
+adr: 0054
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: parallel-status
+  version: 1.0.0
+  allowed_tools: (无 — 纯查询)
+  说明：subtask: false 让命令在主 session 执行（拿 parent context），
+        plugins/parallel-status.ts 在 command.execute.before 拦截并回写 markdown。
+-->
+
+# /parallel-status — 查询子任务进度
+
+随时查询当前正在跑的 `/parallel` 子任务（subagent）状态，复用 subtask-heartbeat 内存 inflight Map。
+
+## 用法
+
+```
+/parallel-status
+```
+
+## 输出示例
+
+如果有 inflight：
+
+```
+📊 当前 3 个 subagent 在跑：
+
+| # | child id | parent id | agent | 已跑 | 最近工具 |
+|---|----------|-----------|-------|------|----------|
+| 1 | `ses_xxx1`     | `ses_p`         | coder    | 1m20s | edit     |
+| 2 | `ses_xxx2`     | `ses_p`         | coder    | 45s   | bash     |
+| 3 | `ses_xxx3`     | `ses_p`         | reviewer | 30s   | grep     |
+```
+
+如果无：
+
+```
+✅ 当前无 inflight subagent
+```
+
+## 行为
+
+1. `plugins/parallel-status.ts` 注册 `command.execute.before` hook
+2. 拦截 `command === "parallel-status"`，调 `getInflightSnapshot()` 拿快照
+3. 调纯函数 `formatInflightMarkdown(snapshot)` 生成 markdown
+4. 回写到 `output.parts`，覆盖 .md template 默认内容
+
+## 元数据
+
+- `subtask`: `false` —— 强制走主 session，避免被 opencode 当 subagent 派发
+- `allowed_tools`: 无（plugin hook 直接接管输出）

package/commands/parallel.md

@@ -10,7 +10,7 @@ codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）
   trigger_workflow: parallel-explore
   allowed_tools: smart_search, repo-map
   说明：subtask: true 强制走 opencode 子代理通道，不污染主上下文；agent 由 workflow 控制
-  ADR-0008（gstack 单 markdown skill）/ ADR-0011（Roo Boomerang Tasks）
+  ADR-0008（gstack 单 markdown skill）/ ADR-0011（Roo Boomerang Tasks）/ ADR-0054（父 session 反馈通道）
 -->
 
 
@@ -85,3 +85,40 @@ planner 会先出 3 路子任务方案，subtasks 并发执行，reviewer 汇总
 - `agent`: 不指定 —— 由 parallel-explore.yaml 控制 agent 切换
 - `subtask`: `true` —— opencode 原生字段，强制走子代理通道
 - `trigger_workflow`: `parallel-explore`
+
+## 反馈通道（ADR-0054）
+
+`/parallel` 执行期间，父 session 会看到 4 类结构化文字反馈：
+
+1. **派出**：`🚀 /parallel 已派出 N 个子任务（并发=K）...` + 子任务清单
+2. **启动**：每个子任务跑起来时 `▶ 子任务 i/N 启动: <id> — <description>`
+3. **完成**：每个子任务结束时 `<emoji> 子任务 i/N 完成 [status] <id> (Xms, files=Y)`
+   - ✅ success / ⚠ need_review / ⏱ timeout / 🗑 cancelled / ❌ failed
+4. **总结**：所有子任务完成后吐既有的 digest（成功/失败/冲突）
+
+这些文字用 `synthetic+ignored+noReply` 三件套追加到 `session.messages`，
+**用户可见但 LLM 不读**（不污染父 session 上下文）。
+
+### 随时查进度
+
+跑 `/parallel-status` 立刻看当前 inflight subagent：
+
+```
+/parallel-status
+
+📊 当前 2 个 subagent 在跑：
+| # | child id | parent id | agent | 已跑 | 最近工具 |
+|---|----------|-----------|-------|------|----------|
+| 1 | `ses_xxx1...` | `ses_yyy...` | coder | 1m20s | edit |
+```
+
+或没有时：
+
+```
+✅ 当前无 inflight subagent
+```
+
+### 失败降级
+
+如果 opencode SDK 太老（< v1.15）或 `promptAsync` 不可用，notice 会静默 noop（log warn）——
+此时退化到原有行为（只有最终 digest）。`/parallel-status` 不受影响（纯内存查询）。

package/commands/refactor.md

@@ -0,0 +1,79 @@
+---
+description: 安全重构工作流，先补特征测试再重构，保证行为不变
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: refactor
+  version: 1.0.0
+  trigger_workflow: refactor
+  requires_human_approval: true
+  allowed_tools: smart_search, save_chat_insight, pending-changes, repo-map, nav-find, nav-goto, bash
+  说明：workflow-engine 看到 trigger_workflow=refactor 拦截 /refactor 触发对应 YAML
+-->
+
+
+# /refactor — 安全重构工作流
+
+触发 `workflows/refactor.yaml`。核心原则：**先补 characterization test 锁定现状行为，再重构**（参考 Working Effectively with Legacy Code）。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/refactor lib/foo.ts 里的 doBar 函数
+/refactor 把 user-service 缓存层抽出来
+/refactor #234 提到的 N+1 query
+```
+
+## 流程（7 步，由 refactor.yaml 编排）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 规划 | planner | 出重构方案 + smart_search 历史经验 | 否 |
+| 2. 补特征测试 | coder | 先写 characterization tests（锁定现状） | 否，auto_feedback 自纠 |
+| 3. 确认覆盖 | reviewer | 确认测试覆盖待重构代码路径 | 否 |
+| 4. 重构 | coder | 实施重构，每步保证测试仍绿 | 否，auto_feedback 自纠 |
+| 5. 审阅 | reviewer | 确认行为不变 + 代码更清晰 | 否 |
+| 6. 落地 | coder | `pending-changes apply_all` | **必审批**（YAML 写死） |
+| 7. 沉淀 | reviewer | `save_chat_insight` 把经验回写 KH | 否（写失败 skip） |
+
+## 与 /tdd 的区别
+
+| 维度 | /refactor | /tdd |
+|---|---|---|
+| 起点 | 已有可工作代码（可能很烂） | 新功能从零开始 |
+| 测试角色 | 锁定现状（characterization test） | 驱动设计（先红再绿） |
+| 终极目标 | 行为不变 + 代码更清晰 | 实现新功能 + 测试覆盖 |
+
+## 自主度（AGENTS.md C18）
+
+`/refactor` 默认 `semi`：风险动作（apply / bash）弹审批，但 `auto_feedback` 在测试反复失败时**自动 escalate 给 reviewer**（避免 coder 死循环）。
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (规划)        | abort |
+| step 2 (补测试)      | auto_feedback 3 轮重试，仍败 escalate reviewer |
+| step 3 (覆盖不足)    | REQUEST_CHANGES → 回 step 2 重补，max_loops=3 兜底 |
+| step 4 (重构)        | auto_feedback 5 轮重试，仍败 escalate reviewer |
+| step 5 (审阅 REQUEST_CHANGES) | 回 step 4 重做 |
+| step 6 (apply)       | hash 漂移则拒（防脏覆盖） |
+| step 7 (沉淀)        | skip |
+
+## 元数据
+
+- `agent`: `planner` —— 起手让 planner 出方案
+- `trigger_workflow`: `refactor`
+- `requires_human_approval`: `true` —— 高影响命令，CLI/UI 额外确认

package/commands/review.md

@@ -0,0 +1,66 @@
+---
+description: 审阅 PR / diff / 本地未提交改动，输出 APPROVE/REQUEST_CHANGES/BLOCK
+agent: reviewer
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: review
+  version: 1.0.0
+  trigger_workflow: code-review
+  allowed_tools: smart_search, save_chat_insight, pending-changes, bash, repo-map, nav-find
+  说明：workflow-engine 看到 trigger_workflow=code-review 拦截 /review 触发对应 YAML
+-->
+
+
+# /review — 代码审阅工作流
+
+触发 `workflows/code-review.yaml`。**只读流程**：不 stage 任何改动，不 apply 任何 pending。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/review                    # 审本地未提交改动（默认）
+/review <PR URL>           # 审指定 PR
+/review --base main        # 审当前分支与 main 的 diff
+```
+
+## 流程（4 步，由 code-review.yaml 编排）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 准备 diff | reviewer | 取 diff 上下文 + smart_search 历史经验 | 否 |
+| 2. 出审阅维度 | planner | 列出本次必查维度（安全/性能/可维护性/测试/风格） | 否 |
+| 3. 审阅 | reviewer | 按维度逐项审 + 跑测试 + 给 APPROVE/REQUEST_CHANGES/BLOCK | 否 |
+| 4. 沉淀 | reviewer | 把发现的 gotcha 沉淀回 KH | 否（写失败 skip） |
+
+## 与 /plan / /ship 的关系
+
+- `/plan` = 规划（不写代码）
+- `/ship` = 全套（规划 → coder → review → apply → 沉淀）
+- `/review` = **只审，不动手**：用于 PR review、code review 例会、入职新人代码巡检
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (准备 diff) | abort：取不到 diff 后续无意义 |
+| step 2 (出维度)   | abort：planner 出不来维度则无可执行清单 |
+| step 3 (审阅 BLOCK) | abort：严重问题，用户决定是否继续 |
+| step 4 (沉淀)     | skip：KH 写失败不能让审阅结果"看起来失败" |
+
+## 元数据
+
+- `agent`: `reviewer` —— 起手就切到 reviewer
+- `trigger_workflow`: `code-review`
+- 不像 `/ship`，本命令**不需要 human_approval**（因为只读，无副作用）

package/commands/tdd.md

@@ -0,0 +1,91 @@
+---
+description: TDD 严格流程 RED → GREEN → REFACTOR，测试驱动新功能
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: tdd
+  version: 1.0.0
+  trigger_workflow: tdd
+  requires_human_approval: true
+  allowed_tools: smart_search, save_chat_insight, pending-changes, repo-map, nav-find, nav-goto, bash
+  说明：workflow-engine 看到 trigger_workflow=tdd 拦截 /tdd 触发对应 YAML
+-->
+
+
+# /tdd — Test-Driven Development 工作流
+
+触发 `workflows/tdd.yaml`。严格 **RED → GREEN → REFACTOR** 三步循环，避免"先写实现再补测试"反 TDD。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/tdd 给 lib/utils 加一个 deepMerge 函数
+/tdd 实现 #345：用户登录 24h 内失败 5 次自动锁定
+/tdd 给 Channel 加 LarkChannel 子类型
+```
+
+## 流程（7 步，由 tdd.yaml 编排，max_loops=5）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 拆需求 | planner | 把需求拆成可测的小步骤清单 | 否 |
+| 2. 写测试-RED | coder | 先写测试（不写实现） | 否 |
+| 3. 验证 RED | reviewer | 跑 npm test 确认测试**确实红了**（绿则 BLOCK） | 否 |
+| 4. 最小实现-GREEN | coder | 写最小实现让测试变绿（不超出需要） | 否，auto_feedback 自纠 |
+| 5. 重构-REFACTOR | coder | 可选 refactor，测试必须仍绿 | 否，可 skip |
+| 6. 审阅 | reviewer | 确认三步全做 + 测试覆盖核心 | 否 |
+| 7. 落地 | coder | `pending-changes apply_all` | **必审批**（YAML 写死） |
+
+## TDD 三色循环
+
+```
+┌─────────────────────────────────────────────────────┐
+│  RED    →  写一个失败的测试（描述期望行为）            │
+│  GREEN  →  写最简实现让测试通过（不超出测试需要）       │
+│  REFACT →  在测试保护下重构（可选；测试仍绿才能进下一轮） │
+└─────────────────────────────────────────────────────┘
+```
+
+`max_loops=5` 表示 reviewer REQUEST_CHANGES 时最多回到 step 2 重做 5 轮，防止死循环。
+
+## 与 /ship / /refactor 的区别
+
+| 维度 | /ship | /refactor | /tdd |
+|---|---|---|---|
+| 起点 | 任何需求 | 已有代码（改善结构） | 新功能（从零） |
+| 测试态度 | 写完后测 | 改前先锁定 | **先红再绿** |
+| 适用 | 大部分日常 | 技术债清理 | 新功能 + 高质量要求 |
+
+## 自主度
+
+`/tdd` 默认 `semi`：apply 必审批；其余步骤 auto_feedback 自纠。
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (拆需求) | abort |
+| step 2 (写测试) | retry 1 次 |
+| step 3 (验证 RED 失败，测试是绿的) | BLOCK：测试无效，必须重写 |
+| step 4 (最小实现) | auto_feedback 5 轮 |
+| step 5 (REFACTOR 失败) | skip：refactor 是可选 |
+| step 6 (审阅 REQUEST_CHANGES) | 回 step 2，max_loops=5 |
+| step 7 (apply) | hash 漂移则拒 |
+
+## 元数据
+
+- `agent`: `planner` —— 起手让 planner 拆需求
+- `trigger_workflow`: `tdd`
+- `requires_human_approval`: `true`