mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
@@ -1,304 +1,123 @@
|
||||
---
|
||||
name: team-planex
|
||||
description: Unified team skill for plan-and-execute pipeline. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team planex".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
||||
description: Unified team skill for plan-and-execute pipeline. Pure router — coordinator always. Beat model is coordinator-only in monitor.md. Triggers on "team planex".
|
||||
allowed-tools: Agent(*), TaskCreate(*), TaskList(*), TaskGet(*), TaskUpdate(*), TeamCreate(*), TeamDelete(*), SendMessage(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*)
|
||||
---
|
||||
|
||||
# Team PlanEx
|
||||
|
||||
Unified team skill: plan-and-execute pipeline for issue-based development. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.
|
||||
|
||||
> **Note**: This skill has its own coordinator implementation (`roles/coordinator/role.md`), independent of `team-lifecycle`. It follows the same v5 architectural patterns (team-worker agents, role-specs, Spawn-and-Stop) but with a simplified 2-role pipeline (planner + executor) tailored for plan-and-execute workflows.
|
||||
Unified team skill: plan-and-execute pipeline for issue-based development. Built on **team-worker agent architecture** — coordinator orchestrates, workers are team-worker agents loading role-specific instructions from `roles/<role>/role.md`.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Skill(skill="team-planex", args="需求描述") │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
│ Always → coordinator
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ coordinator │ Phase 1-5 + dispatch/monitor commands
|
||||
└───┬──────┬───┘
|
||||
│ │
|
||||
↓ ↓
|
||||
┌──────────┐ ┌──────────┐
|
||||
│ planner │ │ executor │ team-worker agents
|
||||
│ PLAN-* │ │ EXEC-* │ with role-spec injection
|
||||
└──────────┘ └──────────┘
|
||||
Skill(skill="team-planex", args="task description")
|
||||
|
|
||||
SKILL.md (this file) = Router
|
||||
|
|
||||
+--------------+--------------+
|
||||
| |
|
||||
no --role flag --role <name>
|
||||
| |
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/role.md
|
||||
|
|
||||
+-- analyze -> dispatch -> spawn workers -> STOP
|
||||
|
|
||||
+---------------+---------------+
|
||||
v v
|
||||
[planner] [executor]
|
||||
(team-worker agent, (team-worker agent,
|
||||
loads roles/planner/role.md) loads roles/executor/role.md)
|
||||
```
|
||||
|
||||
## Role Registry
|
||||
|
||||
| Role | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | true |
|
||||
| executor | [roles/executor/role.md](roles/executor/role.md) | EXEC-* | true |
|
||||
|
||||
## Role Router
|
||||
|
||||
This skill is **coordinator-only**. Workers do NOT invoke this skill — they are spawned as `team-worker` agents directly.
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
### Input Parsing
|
||||
## Shared Constants
|
||||
|
||||
Parse `$ARGUMENTS`. No `--role` needed — always routes to coordinator.
|
||||
- **Session prefix**: `PEX`
|
||||
- **Session path**: `.workflow/.team/PEX-<slug>-<date>/`
|
||||
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
|
||||
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
|
||||
|
||||
Optional flags: `--exec` (execution method), `-y`/`--yes` (auto mode).
|
||||
## Worker Spawn Template
|
||||
|
||||
### Role Registry
|
||||
|
||||
| Role | Spec | Task Prefix | Type | Inner Loop |
|
||||
|------|------|-------------|------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
|
||||
| planner | [role-specs/planner.md](role-specs/planner.md) | PLAN-* | pipeline | true |
|
||||
| executor | [role-specs/executor.md](role-specs/executor.md) | EXEC-* | pipeline | true |
|
||||
|
||||
### Dispatch
|
||||
|
||||
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
User provides task description.
|
||||
|
||||
**Invocation**: `Skill(skill="team-planex", args="<task-description>")`
|
||||
|
||||
**Lifecycle**:
|
||||
```
|
||||
User provides task description
|
||||
-> coordinator Phase 1-3: Parse input -> TeamCreate -> Create task chain (dispatch)
|
||||
-> coordinator Phase 4: spawn planner worker (background) -> STOP
|
||||
-> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
|
||||
-> Loop until pipeline complete -> Phase 5 report + completion action
|
||||
```
|
||||
|
||||
**User Commands** (wake paused coordinator):
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status graph, no advancement |
|
||||
| `resume` / `continue` | Check worker states, advance next step |
|
||||
| `add <issue-ids or --text '...' or --plan path>` | Append new tasks to planner queue |
|
||||
|
||||
---
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
|
||||
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** - complete the command workflow before proceeding
|
||||
|
||||
---
|
||||
|
||||
## Input Types
|
||||
|
||||
支持 3 种输入方式:
|
||||
|
||||
| 输入类型 | 格式 | 示例 |
|
||||
|----------|------|------|
|
||||
| Issue IDs | 直接传入 ID | `ISS-20260215-001 ISS-20260215-002` |
|
||||
| 需求文本 | `--text '...'` | `--text '实现用户认证模块'` |
|
||||
| Plan 文件 | `--plan path` | `--plan plan/2026-02-15-auth.md` |
|
||||
|
||||
## Execution Method Selection
|
||||
|
||||
支持 2 种执行后端：
|
||||
|
||||
| Executor | 后端 | 适用场景 |
|
||||
|----------|------|----------|
|
||||
| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 |
|
||||
| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 |
|
||||
|
||||
### Selection Decision Table
|
||||
|
||||
| Condition | Execution Method |
|
||||
|-----------|-----------------|
|
||||
| `--exec=codex` specified | Codex |
|
||||
| `--exec=gemini` specified | Gemini |
|
||||
| `-y` or `--yes` flag present | Auto (default Gemini) |
|
||||
| No flags (interactive) | AskUserQuestion -> user choice |
|
||||
| Auto + task_count <= 3 | Gemini |
|
||||
| Auto + task_count > 3 | Codex |
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
### v5 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path:
|
||||
Coordinator spawns workers using this template:
|
||||
|
||||
```
|
||||
Agent({
|
||||
agent_type: "team-worker",
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker",
|
||||
team_name: <team-name>,
|
||||
team_name: "planex",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-planex/role-specs/<role>.md
|
||||
role_spec: .claude/skills/team-planex/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: <team-name>
|
||||
team_name: planex
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
execution_method: <agent|codex|gemini>
|
||||
execution_method: <codex|gemini>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
|
||||
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
**Inner Loop roles** (planner, executor): Set `inner_loop: true`. The team-worker agent handles the loop internally.
|
||||
## User Commands
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Definitions
|
||||
|
||||
### Pipeline Diagram
|
||||
|
||||
```
|
||||
Issue-based beat pipeline (逐 Issue 节拍)
|
||||
═══════════════════════════════════════════════════
|
||||
PLAN-001 ──> [planner] issue-1 solution → EXEC-001
|
||||
issue-2 solution → EXEC-002
|
||||
...
|
||||
issue-N solution → EXEC-00N
|
||||
all_planned signal
|
||||
|
||||
EXEC-001 ──> [executor] implement issue-1
|
||||
EXEC-002 ──> [executor] implement issue-2
|
||||
...
|
||||
EXEC-00N ──> [executor] implement issue-N
|
||||
═══════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### Cadence Control
|
||||
|
||||
**Beat model**: Event-driven Spawn-and-Stop. Each beat = coordinator wake -> process callback -> spawn next -> STOP.
|
||||
|
||||
```
|
||||
Beat Cycle (Coordinator Spawn-and-Stop)
|
||||
======================================================================
|
||||
Event Coordinator Workers
|
||||
----------------------------------------------------------------------
|
||||
用户调用 ----------> ┌─ Phase 1-3 ──────────┐
|
||||
│ 解析输入 │
|
||||
│ TeamCreate │
|
||||
│ 创建 PLAN-001 │
|
||||
├─ Phase 4 ─────────────┤
|
||||
│ spawn planner ────────┼──> [planner] Phase 1-5
|
||||
└─ STOP (idle) ──────────┘ │
|
||||
│
|
||||
callback <─ planner issue_ready ────────────────────────┘
|
||||
┌─ monitor.handleCallback ─┐
|
||||
│ 检查新 EXEC-* 任务 │
|
||||
│ spawn executor ─────────┼──> [executor] Phase 1-5
|
||||
└─ STOP (idle) ───────────┘ │
|
||||
│
|
||||
callback <─ executor impl_complete ────────┘
|
||||
┌─ monitor.handleCallback ─┐
|
||||
│ 标记完成 │
|
||||
│ 检查下一个 ready task │
|
||||
└─ spawn/STOP ────────────┘
|
||||
======================================================================
|
||||
```
|
||||
|
||||
**Checkpoints**:
|
||||
|
||||
| 触发条件 | 位置 | 行为 |
|
||||
|----------|------|------|
|
||||
| Planner 全部完成 | all_planned 信号 | Executor 完成剩余 EXEC-* 后结束 |
|
||||
| Pipeline 停滞 | 无 ready + 无 running | Coordinator escalate to user |
|
||||
| Executor 阻塞 | blocked > 2 tasks | Coordinator escalate to user |
|
||||
|
||||
### Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Phase | Dependencies | Description |
|
||||
|---------|------|-------|-------------|-------------|
|
||||
| PLAN-001 | planner | planning | (none) | 初始规划：需求拆解、issue 创建、方案设计 |
|
||||
| EXEC-001 | executor | execution | (created by planner at runtime) | 第一个 issue 的代码实现 |
|
||||
| EXEC-N | executor | execution | (created by planner at runtime) | 第 N 个 issue 的代码实现 |
|
||||
|
||||
> 注: EXEC-* 任务由 planner 在运行时逐个创建（逐 Issue 节拍），不预先定义完整任务链。
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
When the pipeline completes (all tasks done, coordinator Phase 5):
|
||||
|
||||
```javascript
|
||||
if (autoYes) {
|
||||
// Auto mode: Archive & Clean without prompting
|
||||
completionAction = "Archive & Clean";
|
||||
} else {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Team pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
|
||||
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
|
||||
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
| Choice | Action |
|
||||
|--------|--------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions |
|
||||
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
|
||||
|
||||
---
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View execution status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
| `add <issue-ids or --text '...' or --plan path>` | Append new tasks to planner queue |
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/PEX-{slug}-{date}/
|
||||
├── .msg/meta.json # Session state
|
||||
.workflow/.team/PEX-<slug>-<YYYY-MM-DD>/
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Message bus log
|
||||
│ └── meta.json # Session state
|
||||
├── task-analysis.json # Coordinator analyze output
|
||||
├── artifacts/
|
||||
│ └── solutions/ # Planner solution output per issue
|
||||
│ ├── {issueId-1}.json
|
||||
│ └── {issueId-N}.json
|
||||
├── wisdom/ # Cross-task knowledge
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── .msg/messages.jsonl # Team message bus
|
||||
└── .msg/meta.json # Session metadata
|
||||
│ ├── <issueId-1>.json
|
||||
│ └── <issueId-N>.json
|
||||
└── wisdom/ # Cross-task knowledge
|
||||
├── learnings.md
|
||||
├── decisions.md
|
||||
├── conventions.md
|
||||
└── issues.md
|
||||
```
|
||||
|
||||
---
|
||||
## Specs Reference
|
||||
|
||||
## Message Bus
|
||||
|
||||
每次 SendMessage 前，先调用 `mcp__ccw-tools__team_msg` 记录：
|
||||
|
||||
- 参数: operation="log", session_id=`<session-id>`, from=`<role>`, type=`<type>`, data={ref: "`<artifact-path>`"}
|
||||
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
|
||||
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
|
||||
|
||||
**Message types by role**:
|
||||
|
||||
| Role | Types |
|
||||
|------|-------|
|
||||
| planner | `issue_ready`, `all_planned`, `error` |
|
||||
| executor | `impl_complete`, `impl_failed`, `error` |
|
||||
|
||||
---
|
||||
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task metadata registry, execution method selection
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Role spec file not found | Error with expected path (role-specs/<name>.md) |
|
||||
| Command file not found | Fallback to inline execution in coordinator role.md |
|
||||
| Unknown command | Error with available command list |
|
||||
| Role not found | Error with role registry |
|
||||
| Role spec file not found | Error with expected path (roles/<name>/role.md) |
|
||||
| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
|
||||
| Planner issue planning failure | Retry once, then skip to next issue |
|
||||
| Executor impl failure | Report to coordinator, continue with next EXEC-* task |
|
||||
| Pipeline stall | Coordinator monitors, escalate to user |
|
||||
| Completion action timeout | Default to Keep Active |
|
||||
| Worker no response | Report waiting task, suggest user `resume` |
|
||||
|
||||
Reference in New Issue
Block a user