mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: Enhance team lifecycle roles with checkpoint handling and inner loop execution
- Added checkpoint gate handling to the coordinator role, defining behavior based on quality gate results. - Updated planner role to utilize inner loop pattern for structured implementation planning and reporting. - Revised writer role to implement inner loop for document generation, delegating CLI execution to a subagent. - Introduced a new doc-generation subagent for isolated CLI calls and document generation strategies. - Enhanced UI components in the frontend to display job statuses, last run times, and improved error handling. - Updated localization files to include new strings for job details and status banners. - Improved CSS styles for markdown previews to enhance readability and presentation.
This commit is contained in:
catlog22
@@ -77,6 +77,7 @@ Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto ro
|
||||
|----------|------|-------------|---------|
|
||||
| discuss | [subagents/discuss-subagent.md](subagents/discuss-subagent.md) | analyst, writer, reviewer | Multi-perspective critique |
|
||||
| explore | [subagents/explore-subagent.md](subagents/explore-subagent.md) | analyst, planner, any role | Codebase exploration with cache |
|
||||
| doc-generation | [subagents/doc-generation-subagent.md](subagents/doc-generation-subagent.md) | writer | Document generation (CLI execution) |
|
||||
|
||||
### Dispatch
|
||||
|
||||
@@ -105,6 +106,10 @@ User provides task description
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status graph, no advancement |
|
||||
| `resume` / `continue` | Check worker states, advance next step |
|
||||
| `revise <TASK-ID> [feedback]` | Create revision task for specified document + cascade downstream |
|
||||
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
|
||||
| `recheck` | Re-run QUALITY-001 quality check (after manual edits) |
|
||||
| `improve [dimension]` | Auto-improve weakest dimension from readiness-report |
|
||||
|
||||
---
|
||||
|
||||
@@ -144,7 +149,8 @@ Task completion with optional fast-advance to skip coordinator round-trip:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| 1 ready task, simple linear successor | Spawn directly via Task(run_in_background: true) |
|
||||
| 同前缀后续任务 (Inner Loop 角色) | 不 spawn，主 agent 内循环 (Phase 5-L) |
|
||||
| 1 ready task, simple linear successor, 不同前缀 | Spawn directly via Task(run_in_background: true) |
|
||||
| Multiple ready tasks (parallel window) | SendMessage to coordinator (needs orchestration) |
|
||||
| No ready tasks + others running | SendMessage to coordinator (status update) |
|
||||
| No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) |
|
||||
@@ -152,6 +158,92 @@ Task completion with optional fast-advance to skip coordinator round-trip:
|
||||
|
||||
**Fast-advance failure recovery**: If a fast-advanced task fails (worker exits without completing), the coordinator detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing, no manual intervention required. See [monitor.md](roles/coordinator/commands/monitor.md) Fast-Advance Failure Recovery.
|
||||
|
||||
### Worker Inner Loop (同前缀多任务角色)
|
||||
|
||||
适用角色：writer (DRAFT-*)、planner (PLAN-*)、executor (IMPL-*)
|
||||
|
||||
当一个角色拥有**同前缀的多个串行任务**时，不再每完成一个就 spawn 新 agent，而是在同一 agent 内循环处理：
|
||||
|
||||
**Inner Loop 流程**：
|
||||
|
||||
```
|
||||
Phase 1: 发现任务 (首次)
|
||||
│
|
||||
├─ 找到任务 → Phase 2-3: 加载上下文 + Subagent 执行
|
||||
│ │
|
||||
│ v
|
||||
│ Phase 4: 验证 (+ Inline Discuss if applicable)
|
||||
│ │
|
||||
│ v
|
||||
│ Phase 5-L: 轻量完成 (Loop variant)
|
||||
│ │
|
||||
│ ├─ TaskUpdate 标完成
|
||||
│ ├─ team_msg 记录
|
||||
│ ├─ 累积摘要到 context_accumulator
|
||||
│ │
|
||||
│ ├─ 检查：还有同前缀待处理任务？
|
||||
│ │ ├─ YES → 回到 Phase 1 (内循环)
|
||||
│ │ └─ NO → Phase 5-F: 最终报告
|
||||
│ │
|
||||
│ └─ 异常中断条件？
|
||||
│ ├─ consensus_blocked HIGH → SendMessage → STOP
|
||||
│ └─ 错误累计 ≥ 3 → SendMessage → STOP
|
||||
│
|
||||
└─ Phase 5-F: 最终报告 (Final)
|
||||
├─ SendMessage (含全部任务摘要)
|
||||
└─ STOP
|
||||
```
|
||||
|
||||
**context_accumulator** (主 agent 上下文中维护，不写文件):
|
||||
|
||||
每个 subagent 返回后，主 agent 将结果压缩为摘要追加到 accumulator：
|
||||
|
||||
```
|
||||
context_accumulator = []
|
||||
|
||||
# DRAFT-001 subagent 返回后
|
||||
context_accumulator.append({
|
||||
task: "DRAFT-001",
|
||||
artifact: "spec/product-brief.md",
|
||||
key_decisions: ["聚焦 B2B 场景", "MVP 不含移动端"],
|
||||
discuss_verdict: "consensus_reached",
|
||||
discuss_rating: 4.2
|
||||
})
|
||||
|
||||
# DRAFT-002 subagent 返回后
|
||||
context_accumulator.append({
|
||||
task: "DRAFT-002",
|
||||
artifact: "spec/requirements/_index.md",
|
||||
key_decisions: ["REQ-003 降级为 P2", "NFR-perf 新增 SLA"],
|
||||
discuss_verdict: "consensus_reached",
|
||||
discuss_rating: 3.8
|
||||
})
|
||||
```
|
||||
|
||||
后续 subagent 调用时，将 accumulator 摘要作为 CONTEXT 传入，实现知识传递。
|
||||
|
||||
**Phase 5-L vs Phase 5-F 区别**：
|
||||
|
||||
| 步骤 | Phase 5-L (循环中) | Phase 5-F (最终) |
|
||||
|------|-------------------|-----------------|
|
||||
| TaskUpdate completed | YES | YES |
|
||||
| team_msg log | YES | YES |
|
||||
| 累积摘要 | YES | - |
|
||||
| SendMessage to coordinator | NO | YES (含所有任务汇总) |
|
||||
| Fast-Advance 到下一前缀 | - | YES (检查跨前缀后续) |
|
||||
|
||||
**中断恢复**：
|
||||
|
||||
如果 Inner Loop agent 在 DRAFT-003 崩溃：
|
||||
1. DRAFT-001, DRAFT-002 已落盘 + 已标完成 → 安全
|
||||
2. DRAFT-003 状态为 in_progress → coordinator resume 时检测到无 active_worker → 重置为 pending
|
||||
3. 重新 spawn writer → Phase 1 找到 DRAFT-003 → Resume Artifact Check:
|
||||
- DRAFT-003 产物不存在 → 正常执行
|
||||
- DRAFT-003 产物已写但未标完成 → 验证后标完成
|
||||
4. 新 writer 从 DRAFT-003 开始循环，丢失的只是 001+002 的隐性摘要（可从磁盘重建基础信息）
|
||||
|
||||
**恢复增强** (可选)：在每个 Phase 5-L 后将 context_accumulator 写入 `<session>/shared-memory.json` 的 `context_accumulator` 字段，crash 后可读回。
|
||||
|
||||
### Inline Discuss Protocol (produce roles: analyst, writer, reviewer)
|
||||
|
||||
After completing their primary output, produce roles call the discuss subagent inline:
|
||||
@@ -354,10 +446,41 @@ Beat 1 2 3 4
|
||||
|
||||
| Trigger | Position | Behavior |
|
||||
|---------|----------|----------|
|
||||
| Spec->Impl transition | QUALITY-001 completed | Pause, wait for user `resume` |
|
||||
| Spec->Impl transition | QUALITY-001 completed | Read readiness-report.md, extract gate + scores, display Checkpoint Output Template, pause for user action |
|
||||
| GC loop max | QA-FE max 2 rounds | Stop iteration, report current state |
|
||||
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
|
||||
|
||||
**Checkpoint Output Template** (QUALITY-001 completion):
|
||||
|
||||
Coordinator reads `<session>/spec/readiness-report.md`, extracts gate + dimension scores, displays:
|
||||
|
||||
```
|
||||
[coordinator] ══════════════════════════════════════════
|
||||
[coordinator] SPEC PHASE COMPLETE
|
||||
[coordinator] Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
|
||||
[coordinator]
|
||||
[coordinator] Dimension Scores:
|
||||
[coordinator] Completeness: <bar> <n>%
|
||||
[coordinator] Consistency: <bar> <n>%
|
||||
[coordinator] Traceability: <bar> <n>%
|
||||
[coordinator] Depth: <bar> <n>%
|
||||
[coordinator] Coverage: <bar> <n>%
|
||||
[coordinator]
|
||||
[coordinator] Available Actions:
|
||||
[coordinator] resume → Proceed to implementation
|
||||
[coordinator] improve → Auto-improve weakest dimension
|
||||
[coordinator] improve <dimension> → Improve specific dimension
|
||||
[coordinator] revise <TASK-ID> → Revise specific document
|
||||
[coordinator] recheck → Re-run quality check
|
||||
[coordinator] feedback <text> → Inject feedback, create revision
|
||||
[coordinator] ══════════════════════════════════════════
|
||||
```
|
||||
|
||||
Gate-specific guidance:
|
||||
- PASS: All actions available, resume is primary suggestion
|
||||
- REVIEW: Recommend improve/revise before resume, warn on resume
|
||||
- FAIL: Recommend improve/revise, do not suggest resume (user can force)
|
||||
|
||||
**Stall detection** (coordinator `handleCheck`):
|
||||
|
||||
| Check | Condition | Resolution |
|
||||
@@ -385,6 +508,8 @@ Beat 1 2 3 4
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
### 标准 Worker (单任务角色: analyst, tester, reviewer, architect)
|
||||
|
||||
When coordinator spawns workers, use background mode (Spawn-and-Stop):
|
||||
|
||||
```
|
||||
@@ -419,6 +544,42 @@ Session: <session-folder>
|
||||
})
|
||||
```
|
||||
|
||||
### Inner Loop Worker (多任务角色: writer, planner, executor)
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: "Spawn <role> worker (inner loop)",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `You are team "<team-name>" <ROLE>.
|
||||
|
||||
## Primary Instruction
|
||||
All your work MUST be executed by calling Skill to get role definition:
|
||||
Skill(skill="team-lifecycle-v4", args="--role=<role>")
|
||||
|
||||
Current requirement: <task-description>
|
||||
Session: <session-folder>
|
||||
|
||||
## Inner Loop Mode
|
||||
You will handle ALL <PREFIX>-* tasks in this session, not just the first one.
|
||||
After completing each task, loop back to find the next <PREFIX>-* task.
|
||||
Only SendMessage to coordinator when:
|
||||
- All <PREFIX>-* tasks are done
|
||||
- A consensus_blocked HIGH occurs
|
||||
- Errors accumulate (≥ 3)
|
||||
|
||||
## Role Guidelines
|
||||
- Only process <PREFIX>-* tasks, do not execute other role work
|
||||
- All output prefixed with [<role>] tag
|
||||
- Only communicate with coordinator
|
||||
- Do not use TaskCreate to create tasks for other roles
|
||||
- Before each SendMessage, call mcp__ccw-tools__team_msg to log
|
||||
- Use subagent calls for heavy work, retain summaries in context`
|
||||
})
|
||||
```
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user