feat(idaw): add run-coordinate command for external CLI execution with hook callbacks

2026-03-02 15:23:19 +08:00 · 2026-03-01 20:58:26 +08:00
parent b1e321267e
commit 8c953b287d
5 changed files with 776 additions and 1 deletions
--- a/docs/commands/claude/idaw.md
+++ b/docs/commands/claude/idaw.md
@@ -29,6 +29,7 @@
 |---------|----------|--------|
 | [`add`](#add) | Create tasks manually or import from issue | `/idaw:add [-y] [--from-issue <id>] "description" [--type <type>] [--priority 1-5]` |
 | [`run`](#run) | Execute task queue with git checkpoints | `/idaw:run [-y] [--task <id,...>] [--dry-run]` |
+| [`run-coordinate`](#run-coordinate) | Execute via external CLI with hook callbacks | `/idaw:run-coordinate [-y] [--task <id,...>] [--tool <tool>]` |
 | [`status`](#status) | View task and session progress | `/idaw:status [session-id]` |
 | [`resume`](#resume) | Resume interrupted session | `/idaw:resume [-y] [session-id]` |

@@ -135,6 +136,66 @@ Phase 6: Report

 ---

+### run-coordinate
+
+**Function**: Coordinator variant of `/idaw:run` — executes via external CLI with hook callbacks instead of blocking Skill() calls.
+
+**Syntax**:
+```bash
+/idaw:run-coordinate [-y|--yes] [--task <id>[,<id>,...]] [--dry-run] [--tool <tool>]
+```
+
+**Options**:
+- `--tool <tool>`: CLI tool to use (`claude`, `gemini`, `qwen`, default: `claude`)
+- `--task <id,...>`: Execute specific tasks
+- `--dry-run`: Preview plan without executing
+- `-y`: Auto mode
+
+**Execution Model**:
+
+```
+Launch skill via ccw cli --tool <tool> --mode write (background)
+    ↓
+★ STOP — wait for hook callback
+    ↓
+Hook fires → handleStepCompletion()
+    ├─ More skills in chain → launch next → STOP
+    ├─ Chain complete → git checkpoint → next task → STOP
+    └─ All done → Report
+```
+
+**When to Use**:
+
+| Scenario | Command |
+|----------|---------|
+| Standard execution (main process, blocking) | `/idaw:run` |
+| External CLI, isolated context per skill | `/idaw:run-coordinate` |
+| Long-running tasks, avoid context pressure | `/idaw:run-coordinate` |
+| Need specific CLI tool (claude/gemini) | `/idaw:run-coordinate --tool gemini` |
+
+**Differences from `/idaw:run`**:
+
+| Aspect | `/idaw:run` | `/idaw:run-coordinate` |
+|--------|-------------|----------------------|
+| Execution | `Skill()` blocking | `ccw cli` background + hook |
+| Context | Shared main context | Isolated per CLI call |
+| Tool selection | N/A | `--tool claude\|gemini\|qwen` |
+| State | session.json | session.json + prompts_used |
+
+**Examples**:
+```bash
+# Execute via claude CLI (default)
+/idaw:run-coordinate -y
+
+# Use gemini as execution tool
+/idaw:run-coordinate -y --tool gemini
+
+# Specific tasks
+/idaw:run-coordinate --task IDAW-001,IDAW-003 --tool claude
+```
+
+---
+
 ### status

 **Function**: Read-only view of IDAW task queue and session progress.
--- a/docs/commands/claude/index.md
+++ b/docs/commands/claude/index.md
@@ -12,7 +12,7 @@
 | **Workflow** | 20+ | Planning, execution, review, TDD, testing workflows |
 | **Session Management** | 6 | Session creation, listing, resuming, completion |
 | **Issue Workflow** | 8 | Issue discovery, planning, queue, execution |
-| **IDAW** | 4 | Batch autonomous task execution with git checkpoints |
+| **IDAW** | 5 | Batch autonomous task execution with git checkpoints |
 | **Memory** | 8 | Memory capture, update, document generation |
 | **CLI Tools** | 2 | CLI initialization, Codex review |
 | **UI Design** | 10 | UI design prototype generation, style extraction |
@@ -76,6 +76,7 @@
 |---------|----------|------------|
 | [`/idaw:add`](./idaw.md#add) | Create tasks manually or import from ccw issue | Beginner |
 | [`/idaw:run`](./idaw.md#run) | Execute task queue with skill chains and git checkpoints | Intermediate |
+| [`/idaw:run-coordinate`](./idaw.md#run-coordinate) | Execute via external CLI with hook callbacks | Intermediate |
 | [`/idaw:status`](./idaw.md#status) | View task and session progress | Beginner |
 | [`/idaw:resume`](./idaw.md#resume) | Resume interrupted session from last checkpoint | Intermediate |

--- a/docs/zh/commands/claude/idaw.md
+++ b/docs/zh/commands/claude/idaw.md
@@ -29,6 +29,7 @@
 |------|------|------|
 | [`add`](#add) | 手动创建或从 issue 导入任务 | `/idaw:add [-y] [--from-issue <id>] "描述" [--type <类型>] [--priority 1-5]` |
 | [`run`](#run) | 串行执行任务队列并 git checkpoint | `/idaw:run [-y] [--task <id,...>] [--dry-run]` |
+| [`run-coordinate`](#run-coordinate) | 通过外部 CLI 和 hook 回调执行 | `/idaw:run-coordinate [-y] [--task <id,...>] [--tool <tool>]` |
 | [`status`](#status) | 查看任务和会话进度 | `/idaw:status [session-id]` |
 | [`resume`](#resume) | 从断点恢复中断的会话 | `/idaw:resume [-y] [session-id]` |

@@ -128,6 +129,69 @@ Phase 6: 报告

 ---

+### run-coordinate
+
+**功能**：`/idaw:run` 的协调器变体 — 通过外部 CLI 后台执行，使用 hook 回调驱动流程推进。
+
+**语法**：
+```bash
+/idaw:run-coordinate [-y|--yes] [--task <id>[,<id>,...]] [--dry-run] [--tool <tool>]
+```
+
+**参数**：
+- `--tool <tool>`：使用的 CLI 工具（`claude`、`gemini`、`qwen`，默认：`claude`）
+- `--task <id,...>`：执行特定任务
+- `--dry-run`：预览计划，不实际执行
+- `-y`：自动模式
+
+**执行模型**：
+
+```
+通过 ccw cli --tool <tool> --mode write 后台启动 Skill
+    ↓
+★ 暂停 — 等待 hook 回调
+    ↓
+Hook 触发 → handleStepCompletion()
+    ├─ 链中还有 Skill → 启动下一个 → 暂停
+    ├─ 链完成 → git checkpoint → 下一个任务 → 暂停
+    └─ 全部完成 → 生成报告
+```
+
+**适用场景**：
+
+| 场景 | 命令 |
+|------|------|
+| 标准执行（主进程，阻塞） | `/idaw:run` |
+| 外部 CLI，每个 Skill 独立上下文 | `/idaw:run-coordinate` |
+| 长时间任务，避免上下文压力 | `/idaw:run-coordinate` |
+| 需要指定 CLI 工具 | `/idaw:run-coordinate --tool gemini` |
+
+**与 `/idaw:run` 的区别**：
+
+| 对比维度 | `/idaw:run` | `/idaw:run-coordinate` |
+|----------|-------------|----------------------|
+| 执行方式 | `Skill()` 阻塞调用 | `ccw cli` 后台 + hook |
+| 上下文 | 共享主进程上下文 | 每次 CLI 调用独立上下文 |
+| 工具选择 | N/A | `--tool claude\|gemini\|qwen` |
+| 状态追踪 | session.json | session.json + prompts_used |
+
+**示例**：
+```bash
+# 通过 claude CLI 执行（默认）
+/idaw:run-coordinate -y
+
+# 使用 gemini 作为执行工具
+/idaw:run-coordinate -y --tool gemini
+
+# 执行特定任务
+/idaw:run-coordinate --task IDAW-001,IDAW-003 --tool claude
+
+# 预览计划
+/idaw:run-coordinate --dry-run
+```
+
+---
+
 ### status

 **功能**：只读查看 IDAW 任务队列和会话进度。
--- a/docs/zh/commands/claude/index.md
+++ b/docs/zh/commands/claude/index.md
@@ -74,6 +74,7 @@
 | --- | --- | --- |
 | [`/idaw:add`](./idaw.md#add) | 手动创建或从 issue 导入任务 | Beginner |
 | [`/idaw:run`](./idaw.md#run) | 串行执行任务 Skill 链并 git checkpoint | Intermediate |
+| [`/idaw:run-coordinate`](./idaw.md#run-coordinate) | 通过外部 CLI 和 hook 回调执行任务 | Intermediate |
 | [`/idaw:status`](./idaw.md#status) | 查看任务和会话进度 | Beginner |
 | [`/idaw:resume`](./idaw.md#resume) | 从断点恢复中断的会话 | Intermediate |