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` |
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse plan-and-execute input -> detect input type -> determine execution method -> assess scope.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
| Input Pattern | Type | Action |
|
||||
|--------------|------|--------|
|
||||
| `ISS-\d{8}-\d{6}` pattern | Issue IDs | Use directly |
|
||||
| `--text '...'` flag | Text requirement | Create issues via CLI |
|
||||
| `--plan <path>` flag | Plan file | Read file, parse phases |
|
||||
|
||||
## Execution Method Selection
|
||||
|
||||
| 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 |
|
||||
|
||||
## Scope Assessment
|
||||
|
||||
| Factor | Complexity |
|
||||
|--------|------------|
|
||||
| Issue count 1-3 | Low |
|
||||
| Issue count 4-10 | Medium |
|
||||
| Issue count > 10 | High |
|
||||
| Cross-cutting concern | +1 level |
|
||||
|
||||
## Output
|
||||
|
||||
Write <session>/task-analysis.json:
|
||||
```json
|
||||
{
|
||||
"task_description": "<original>",
|
||||
"input_type": "<issues|text|plan>",
|
||||
"raw_input": "<original input>",
|
||||
"execution_method": "<codex|gemini>",
|
||||
"issue_count_estimate": 0,
|
||||
"complexity": { "score": 0, "level": "Low|Medium|High" },
|
||||
"pipeline_type": "plan-execute",
|
||||
"roles": [
|
||||
{ "name": "planner", "prefix": "PLAN", "inner_loop": true },
|
||||
{ "name": "executor", "prefix": "EXEC", "inner_loop": true }
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -118,14 +118,14 @@ Collect task states from TaskList()
|
||||
| +- EXEC-* -> executor
|
||||
+- Spawn team-worker:
|
||||
Agent({
|
||||
agent_type: "team-worker",
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: <team-name>,
|
||||
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>
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
# Coordinator Role
|
||||
|
||||
Orchestrate the team-planex pipeline: parse input, create team, dispatch tasks, monitor progress via Spawn-and-Stop beats. Uses **team-worker agent** for all worker spawns.
|
||||
Orchestrate team-planex: analyze -> dispatch -> spawn -> monitor -> report.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report
|
||||
- Name: coordinator | Tag: [coordinator]
|
||||
- Responsibility: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -22,29 +21,22 @@ Orchestrate the team-planex pipeline: parse input, create team, dispatch tasks,
|
||||
- Call implementation CLI tools (code-developer, etc.) directly
|
||||
- Skip dependency validation when creating task chains
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
3. **Commands are inline execution guides** - NOT separate agents
|
||||
4. **Execute synchronously** - complete the command workflow before proceeding
|
||||
|
||||
---
|
||||
When coordinator needs to execute a command:
|
||||
1. Read `commands/<command>.md`
|
||||
2. Follow the workflow defined in the command
|
||||
3. Commands are inline execution guides, NOT separate agents
|
||||
4. Execute synchronously, complete before proceeding
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, detect invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains `[planner]` or `[executor]` tag | -> handleCallback (monitor.md) |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Add tasks | Arguments contain "add" | -> handleAdd |
|
||||
| Worker callback | Message contains [planner] or [executor] tag | -> handleCallback (monitor.md) |
|
||||
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Add tasks | Args contain "add" | -> handleAdd |
|
||||
| Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
@@ -58,13 +50,11 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
4. If planner already sent `all_planned` (check team_msg) -> `SendMessage` to planner to re-enter loop
|
||||
5. STOP
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. Scan `.workflow/.team/PEX-*/.msg/meta.json` for sessions with status "active" or "paused"
|
||||
2. No sessions found -> proceed to Phase 1
|
||||
3. Single session found -> resume (Session Reconciliation)
|
||||
2. No sessions -> Phase 1
|
||||
3. Single session -> resume (Session Reconciliation)
|
||||
4. Multiple sessions -> AskUserQuestion for selection
|
||||
|
||||
**Session Reconciliation**:
|
||||
@@ -73,20 +63,18 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
3. Rebuild team if needed (TeamCreate + spawn needed workers)
|
||||
4. Kick first executable task -> Phase 4
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Input Parsing + Execution Method
|
||||
|
||||
1. **Parse arguments**: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
|
||||
TEXT-LEVEL ONLY. No source code reading.
|
||||
|
||||
2. **Determine execution method** (see SKILL.md Selection Decision Table):
|
||||
1. Delegate to commands/analyze.md -> produces task-analysis.json
|
||||
2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
|
||||
3. Determine execution method (see specs/pipelines.md Selection Decision Table):
|
||||
- Explicit `--exec` flag -> use specified method
|
||||
- `-y` / `--yes` flag -> Auto mode
|
||||
- No flags -> AskUserQuestion for method choice
|
||||
|
||||
3. **Store requirements**: input_type, raw_input, execution_method
|
||||
|
||||
---
|
||||
4. Store requirements: input_type, raw_input, execution_method
|
||||
5. CRITICAL: Always proceed to Phase 2, never skip team workflow
|
||||
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
@@ -97,57 +85,46 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
5. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
|
||||
6. Initialize meta.json with pipeline metadata:
|
||||
```typescript
|
||||
// Use team_msg to write pipeline metadata to .msg/meta.json
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session-id>",
|
||||
from: "coordinator",
|
||||
type: "state_update",
|
||||
summary: "Session initialized",
|
||||
operation: "log", session_id: "<id>", from: "coordinator",
|
||||
type: "state_update", summary: "Session initialized",
|
||||
data: {
|
||||
pipeline_mode: "plan-execute",
|
||||
pipeline_stages: ["planner", "executor"],
|
||||
roles: ["coordinator", "planner", "executor"],
|
||||
team_name: "planex",
|
||||
input_type: "<issues|text|plan>",
|
||||
execution_method: "<agent|codex|gemini>"
|
||||
execution_method: "<codex|gemini>"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
Delegate to `commands/dispatch.md`:
|
||||
|
||||
1. Read `roles/coordinator/commands/dispatch.md`
|
||||
2. Execute its workflow to create PLAN-001 task
|
||||
3. PLAN-001 contains input info + execution method in description
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
1. Load `commands/monitor.md`
|
||||
2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
|
||||
3. Output status summary
|
||||
4. **STOP** (idle, wait for worker callback)
|
||||
4. STOP (idle, wait for worker callback)
|
||||
|
||||
**ONE_STEP_PER_INVOCATION**: true — coordinator does one operation per wake-up, then STOPS.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
When all tasks are complete (monitor.md detects PIPELINE_COMPLETE):
|
||||
|
||||
1. Load session state -> count completed tasks, duration
|
||||
2. List deliverables with output paths
|
||||
3. Update session status -> "completed"
|
||||
4. Execute Completion Action (see SKILL.md)
|
||||
|
||||
---
|
||||
4. Execute Completion Action per session.completion_action:
|
||||
- interactive -> AskUserQuestion (Archive/Keep/Export)
|
||||
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
|
||||
- auto_keep -> Keep Active (status=paused)
|
||||
- auto_yes -> Archive & Clean without prompting
|
||||
|
||||
## Error Handling
|
||||
|
||||
|
||||
91
.claude/skills/team-planex/roles/executor/role.md
Normal file
91
.claude/skills/team-planex/roles/executor/role.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
role: executor
|
||||
prefix: EXEC
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: impl_complete
|
||||
error: impl_failed
|
||||
---
|
||||
|
||||
# Executor
|
||||
|
||||
Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.
|
||||
|
||||
## Phase 2: Task & Solution Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Issue ID | Task description `Issue ID:` field | Yes |
|
||||
| Solution file | Task description `Solution file:` field | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Execution method | Task description `Execution method:` field | Yes |
|
||||
| Wisdom | `<session>/wisdom/` | No |
|
||||
|
||||
1. Extract issue ID, solution file path, session folder, execution method
|
||||
2. Load solution JSON from file (file-first)
|
||||
3. If file not found -> fallback: `ccw issue solution <issueId> --json`
|
||||
4. Load wisdom files for conventions and patterns
|
||||
5. Verify solution has required fields: title, tasks
|
||||
|
||||
## Phase 3: Implementation
|
||||
|
||||
### Backend Selection
|
||||
|
||||
| Method | Backend | CLI Tool |
|
||||
|--------|---------|----------|
|
||||
| `codex` | `ccw cli --tool codex --mode write` | Background CLI |
|
||||
| `gemini` | `ccw cli --tool gemini --mode write` | Background CLI |
|
||||
|
||||
### CLI Backend (Codex/Gemini)
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
|
||||
TASK: <solution.tasks as bullet points>
|
||||
MODE: write
|
||||
CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
|
||||
EXPECTED: Working implementation with: code changes, test updates, no syntax errors
|
||||
CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
|
||||
Issue: <issueId>
|
||||
Title: <solution.title>
|
||||
Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
|
||||
```
|
||||
|
||||
Wait for CLI completion before proceeding to verification.
|
||||
|
||||
## Phase 4: Verification + Commit
|
||||
|
||||
### Test Verification
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Tests | Detect and run project test command | All pass |
|
||||
| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
|
||||
|
||||
If tests fail: retry implementation once, then report `impl_failed`.
|
||||
|
||||
### Commit
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat(<issueId>): <solution.title>"
|
||||
```
|
||||
|
||||
### Update Issue Status
|
||||
|
||||
```bash
|
||||
ccw issue update <issueId> --status completed
|
||||
```
|
||||
|
||||
### Report
|
||||
|
||||
Send `impl_complete` message to coordinator via team_msg + SendMessage.
|
||||
|
||||
## Boundaries
|
||||
|
||||
| Allowed | Prohibited |
|
||||
|---------|-----------|
|
||||
| Load solution from file | Create or modify issues |
|
||||
| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
|
||||
| Run tests | Spawn additional agents (use CLI tools instead) |
|
||||
| git commit | Direct user interaction |
|
||||
| Update issue status | Create tasks for other roles |
|
||||
111
.claude/skills/team-planex/roles/planner/role.md
Normal file
111
.claude/skills/team-planex/roles/planner/role.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
role: planner
|
||||
prefix: PLAN
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: issue_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# Planner
|
||||
|
||||
Requirement decomposition -> issue creation -> solution design -> EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Input type + raw input | Task description | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Execution method | Task description `Execution method:` field | Yes |
|
||||
| Wisdom | `<session>/wisdom/` | No |
|
||||
|
||||
1. Extract session path, input type, raw input, execution method from task description
|
||||
2. Load wisdom files if available
|
||||
3. Parse input to determine issue list:
|
||||
|
||||
| Detection | Condition | Action |
|
||||
|-----------|-----------|--------|
|
||||
| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly |
|
||||
| `--text '...'` | Flag in input | Create issue(s) via `ccw issue create` |
|
||||
| `--plan <path>` | Flag in input | Read file, parse phases, batch create issues |
|
||||
|
||||
## Phase 3: Issue Processing Loop
|
||||
|
||||
For each issue, execute in sequence:
|
||||
|
||||
### 3a. Generate Solution
|
||||
|
||||
Use CLI tool for issue planning:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths
|
||||
TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Session context from <session>/wisdom/
|
||||
EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity
|
||||
CONSTRAINTS: Follow project patterns | Reference existing implementations
|
||||
" --tool gemini --mode analysis --rule planning-breakdown-task-steps
|
||||
```
|
||||
|
||||
Parse CLI output to extract solution JSON. If CLI fails, fallback to `ccw issue solution <issueId> --json`.
|
||||
|
||||
### 3b. Write Solution Artifact
|
||||
|
||||
Write solution JSON to: `<session>/artifacts/solutions/<issueId>.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "<session-id>",
|
||||
"issue_id": "<issueId>",
|
||||
"solution": "<solution-from-agent>",
|
||||
"planned_at": "<ISO timestamp>"
|
||||
}
|
||||
```
|
||||
|
||||
### 3c. Check Conflicts
|
||||
|
||||
Extract `files_touched` from solution. Compare against prior solutions in session.
|
||||
Overlapping files -> log warning to `wisdom/issues.md`, continue.
|
||||
|
||||
### 3d. Create EXEC-* Task
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "EXEC-00N: Implement <issue-title>",
|
||||
description: `Implement solution for issue <issueId>.
|
||||
|
||||
Issue ID: <issueId>
|
||||
Solution file: <session>/artifacts/solutions/<issueId>.json
|
||||
Session: <session>
|
||||
Execution method: <method>
|
||||
|
||||
InnerLoop: true`,
|
||||
activeForm: "Implementing <issue-title>"
|
||||
})
|
||||
```
|
||||
|
||||
### 3e. Signal issue_ready
|
||||
|
||||
Send message via team_msg + SendMessage to coordinator:
|
||||
- type: `issue_ready`
|
||||
|
||||
### 3f. Continue Loop
|
||||
|
||||
Process next issue. Do NOT wait for executor.
|
||||
|
||||
## Phase 4: Completion Signal
|
||||
|
||||
After all issues processed:
|
||||
1. Send `all_planned` message to coordinator via team_msg + SendMessage
|
||||
2. Summary: total issues planned, EXEC-* tasks created
|
||||
|
||||
## Boundaries
|
||||
|
||||
| Allowed | Prohibited |
|
||||
|---------|-----------|
|
||||
| Parse input, create issues | Write/modify business code |
|
||||
| Generate solutions (CLI) | Run tests |
|
||||
| Write solution artifacts | git commit |
|
||||
| Create EXEC-* tasks | Call code-developer |
|
||||
| Conflict checking | Direct user interaction |
|
||||
93
.claude/skills/team-planex/specs/pipelines.md
Normal file
93
.claude/skills/team-planex/specs/pipelines.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# PlanEx Pipeline Definitions
|
||||
|
||||
## Pipeline Diagram
|
||||
|
||||
Issue-based beat pipeline — planner creates EXEC-* tasks at runtime as solutions are completed.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Beat Cycle
|
||||
|
||||
Event-driven Spawn-and-Stop. Each beat = coordinator wake -> process callback -> spawn next -> STOP.
|
||||
|
||||
```
|
||||
Event Coordinator Workers
|
||||
----------------------------------------------------------------------
|
||||
User invokes -------> Phase 1-3:
|
||||
Parse input
|
||||
TeamCreate
|
||||
Create PLAN-001
|
||||
Phase 4:
|
||||
spawn planner ---------> [planner] Phase 1-5
|
||||
STOP (idle) |
|
||||
|
|
||||
callback <-- planner issue_ready -(per issue)-----------+
|
||||
handleCallback:
|
||||
detect new EXEC-* tasks
|
||||
spawn executor ---------------------> [executor] Phase 1-5
|
||||
STOP (idle) |
|
||||
|
|
||||
callback <-- executor impl_complete ---------------------+
|
||||
handleCallback:
|
||||
mark issue done
|
||||
check next ready EXEC-*
|
||||
spawn next executor / STOP
|
||||
```
|
||||
|
||||
## Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| PLAN-001 | planner | (none) | Requirement decomposition: parse input, create issues, generate solutions, create EXEC-* tasks |
|
||||
| EXEC-001 | executor | PLAN-001 (created at runtime by planner) | Implement solution for issue #1 |
|
||||
| EXEC-002 | executor | PLAN-001 (created at runtime by planner) | Implement solution for issue #2 |
|
||||
| EXEC-00N | executor | PLAN-001 (created at runtime by planner) | Implement solution for issue #N |
|
||||
|
||||
> EXEC-* tasks are created by planner at runtime (per-issue beat), not predefined in the task chain.
|
||||
|
||||
## Execution Method Selection
|
||||
|
||||
| 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 |
|
||||
|
||||
## Input Type Detection
|
||||
|
||||
| Input Pattern | Type | Action |
|
||||
|--------------|------|--------|
|
||||
| `ISS-\d{8}-\d{6}` pattern | Issue IDs | Use directly |
|
||||
| `--text '...'` flag | Text requirement | Create issues via `ccw issue create` |
|
||||
| `--plan <path>` flag | Plan file | Read file, parse phases, batch create issues |
|
||||
|
||||
## Checkpoints
|
||||
|
||||
| Trigger | Condition | Action |
|
||||
|---------|-----------|--------|
|
||||
| Planner complete | all_planned signal received | Wait for remaining EXEC-* executors to finish |
|
||||
| Pipeline stall | No ready tasks + no running tasks + has pending | Coordinator checks blockedBy chains, escalates to user |
|
||||
| Executor blocked | blocked > 2 tasks | Coordinator escalates to user |
|
||||
|
||||
## Scope Assessment
|
||||
|
||||
| Factor | Complexity |
|
||||
|--------|------------|
|
||||
| Issue count 1-3 | Low |
|
||||
| Issue count 4-10 | Medium |
|
||||
| Issue count > 10 | High |
|
||||
| Cross-cutting concern | +1 level |
|
||||
Reference in New Issue
Block a user