mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-11 17:21:03 +08:00
Refactor team collaboration skills and update documentation
- Renamed `team-lifecycle-v5` to `team-lifecycle` across various documentation files for consistency. - Updated references in code examples and usage sections to reflect the new skill name. - Added a new command file for the `monitor` functionality in the `team-iterdev` skill, detailing the coordinator's monitoring events and task management. - Introduced new components for dynamic pipeline visualization and session coordinates display in the frontend. - Implemented utility functions for pipeline stage detection and status derivation based on message history. - Enhanced the team role panel to map members to their respective pipeline roles with status indicators. - Updated Chinese documentation to reflect the changes in skill names and descriptions.
This commit is contained in:
catlog22
@@ -1,355 +0,0 @@
|
||||
# Command: create-plans
|
||||
|
||||
Generate execution plans via action-planning-agent. Produces IMPL_PLAN.md, .task/IMPL-*.json, and TODO_LIST.md — the same artifact format as workflow-plan skill.
|
||||
|
||||
## Purpose
|
||||
|
||||
Transform phase context into structured task JSONs and implementation plan. Delegates to action-planning-agent for document generation. Produces artifacts compatible with workflow-plan's output format, enabling reuse of executor and verifier logic.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of planner execution (after research, before self-validation)
|
||||
- Called once per PLAN-* task
|
||||
|
||||
## Strategy
|
||||
|
||||
Delegate to action-planning-agent with phase context (context.md + roadmap phase section). The agent produces task JSONs with convergence criteria (replacing the old must_haves concept), dependency graph (replacing wave numbering), and implementation steps.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `sessionFolder` | From PLAN-* task description | Session artifact directory |
|
||||
| `phaseNumber` | From PLAN-* task description | Phase number (1-based) |
|
||||
|
||||
## Output Artifact Mapping (vs old plan-NN.md)
|
||||
|
||||
| Old (plan-NN.md) | New (IMPL-*.json) | Notes |
|
||||
|-------------------|--------------------|-------|
|
||||
| `plan: NN` | `id: "IMPL-N"` | Task identifier |
|
||||
| `wave: N` | `depends_on: [...]` | Dependency graph replaces explicit waves |
|
||||
| `files_modified: [...]` | `files: [{path, action, change}]` | Structured file list |
|
||||
| `requirements: [REQ-IDs]` | `description` + `scope` | Requirements embedded in description |
|
||||
| `must_haves.truths` | `convergence.criteria` | Observable behaviors → measurable criteria |
|
||||
| `must_haves.artifacts` | `files` + `convergence.verification` | File checks in verification command |
|
||||
| `must_haves.key_links` | `convergence.verification` | Import wiring in verification command |
|
||||
| Plan body (implementation steps) | `implementation: [...]` | Step-by-step actions |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Load Phase Context
|
||||
|
||||
```javascript
|
||||
const context = Read(`${sessionFolder}/phase-${phaseNumber}/context.md`)
|
||||
const roadmap = Read(`${sessionFolder}/roadmap.md`)
|
||||
const config = JSON.parse(Read(`${sessionFolder}/config.json`))
|
||||
|
||||
// Extract phase section from roadmap
|
||||
const phaseGoal = extractPhaseGoal(roadmap, phaseNumber)
|
||||
const requirements = extractRequirements(roadmap, phaseNumber)
|
||||
const successCriteria = extractSuccessCriteria(roadmap, phaseNumber)
|
||||
|
||||
// Check for gap closure context
|
||||
const isGapClosure = context.includes("Gap Closure Context")
|
||||
|
||||
// Load prior phase summaries for cross-phase context
|
||||
const priorSummaries = []
|
||||
for (let p = 1; p < phaseNumber; p++) {
|
||||
try {
|
||||
const summaryFiles = Glob(`${sessionFolder}/phase-${p}/summary-*.md`)
|
||||
for (const sf of summaryFiles) {
|
||||
priorSummaries.push(Read(sf))
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Prepare Output Directories
|
||||
|
||||
```javascript
|
||||
Bash(`mkdir -p "${sessionFolder}/phase-${phaseNumber}/.task"`)
|
||||
```
|
||||
|
||||
### Step 3: Delegate to action-planning-agent
|
||||
|
||||
```javascript
|
||||
const taskDir = `${sessionFolder}/phase-${phaseNumber}/.task`
|
||||
const implPlanPath = `${sessionFolder}/phase-${phaseNumber}/IMPL_PLAN.md`
|
||||
const todoListPath = `${sessionFolder}/phase-${phaseNumber}/TODO_LIST.md`
|
||||
|
||||
Task({
|
||||
subagent_type: "action-planning-agent",
|
||||
run_in_background: false,
|
||||
description: `Generate phase ${phaseNumber} planning documents`,
|
||||
prompt: `
|
||||
## TASK OBJECTIVE
|
||||
Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for roadmap-dev session phase ${phaseNumber}.
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - generate planning documents, NOT implementing code.
|
||||
|
||||
## PHASE CONTEXT
|
||||
${context}
|
||||
|
||||
## ROADMAP PHASE ${phaseNumber}
|
||||
Goal: ${phaseGoal}
|
||||
|
||||
Requirements:
|
||||
${requirements.map(r => `- ${r.id}: ${r.desc}`).join('\n')}
|
||||
|
||||
Success Criteria:
|
||||
${successCriteria.map(c => `- ${c}`).join('\n')}
|
||||
|
||||
${isGapClosure ? `## GAP CLOSURE
|
||||
This is a gap closure iteration. Only address gaps listed in context — do NOT re-plan completed work.
|
||||
Existing task JSONs in ${taskDir} represent prior work. Create gap-specific tasks starting from next available ID.` : ''}
|
||||
|
||||
${priorSummaries.length > 0 ? `## PRIOR PHASE CONTEXT
|
||||
${priorSummaries.join('\n\n---\n\n')}` : ''}
|
||||
|
||||
## SESSION PATHS
|
||||
Output:
|
||||
- Task Dir: ${taskDir}
|
||||
- IMPL_PLAN: ${implPlanPath}
|
||||
- TODO_LIST: ${todoListPath}
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session: ${sessionFolder}
|
||||
Phase: ${phaseNumber}
|
||||
Depth: ${config.depth || 'standard'}
|
||||
|
||||
## USER CONFIGURATION
|
||||
Execution Method: agent
|
||||
Preferred CLI Tool: gemini
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Task JSON Files (${taskDir}/IMPL-*.json)
|
||||
- Unified flat schema (task-schema.json)
|
||||
- Quantified requirements with explicit counts
|
||||
- focus_paths from context.md relevant files
|
||||
- convergence criteria derived from success criteria (goal-backward)
|
||||
|
||||
2. Implementation Plan (${implPlanPath})
|
||||
- Phase goal and context
|
||||
- Task breakdown and execution strategy
|
||||
- Dependency graph
|
||||
|
||||
3. TODO List (${todoListPath})
|
||||
- Flat structure with [ ] for pending
|
||||
- Links to task JSONs
|
||||
|
||||
## TASK ID FORMAT
|
||||
Use: IMPL-{phaseNumber}{seq} (e.g., IMPL-101, IMPL-102 for phase 1)
|
||||
|
||||
## CONVERGENCE CRITERIA RULES (replacing old must_haves)
|
||||
Each task MUST include convergence:
|
||||
- criteria: Measurable conditions derived from success criteria (goal-backward, not task-forward)
|
||||
- Include file existence checks
|
||||
- Include export/symbol presence checks
|
||||
- Include test passage checks where applicable
|
||||
- verification: Executable command to verify criteria
|
||||
- definition_of_done: Business-language completion definition
|
||||
|
||||
## CLI EXECUTION ID FORMAT
|
||||
Each task: cli_execution.id = "RD-${sessionFolder.split('/').pop()}-{task_id}"
|
||||
|
||||
## QUALITY STANDARDS
|
||||
- Task count <= 10 per phase (hard limit)
|
||||
- All requirements quantified
|
||||
- Acceptance criteria measurable
|
||||
- Dependencies form a valid DAG (no cycles)
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 4: Validate Generated Artifacts
|
||||
|
||||
```javascript
|
||||
// 4a. Verify task JSONs were created
|
||||
const taskFiles = Glob(`${taskDir}/IMPL-*.json`)
|
||||
if (!taskFiles || taskFiles.length === 0) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "error",
|
||||
})
|
||||
return
|
||||
}
|
||||
|
||||
// 4b. Validate each task JSON
|
||||
for (const taskFile of taskFiles) {
|
||||
const taskJson = JSON.parse(Read(taskFile))
|
||||
|
||||
// Required fields check
|
||||
const requiredFields = ['id', 'title', 'description', 'files', 'implementation', 'convergence']
|
||||
for (const field of requiredFields) {
|
||||
if (!taskJson[field]) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// Convergence criteria check
|
||||
if (!taskJson.convergence?.criteria || taskJson.convergence.criteria.length === 0) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
})
|
||||
}
|
||||
|
||||
// Dependency cycle check (simple: task cannot depend on itself)
|
||||
if (taskJson.depends_on?.includes(taskJson.id)) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "error",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 4c. Validate dependency DAG (no cycles)
|
||||
const allTasks = taskFiles.map(f => JSON.parse(Read(f)))
|
||||
const taskIds = new Set(allTasks.map(t => t.id))
|
||||
|
||||
// Check all depends_on references are valid
|
||||
for (const task of allTasks) {
|
||||
for (const dep of (task.depends_on || [])) {
|
||||
if (!taskIds.has(dep)) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 4d. Verify IMPL_PLAN.md exists
|
||||
const implPlanExists = Bash(`test -f "${implPlanPath}" && echo "EXISTS" || echo "NOT_FOUND"`).trim()
|
||||
if (implPlanExists === "NOT_FOUND") {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
})
|
||||
// Create minimal IMPL_PLAN.md from task JSONs
|
||||
generateMinimalImplPlan(allTasks, implPlanPath, phaseGoal, phaseNumber)
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Compute Wave Structure (for reporting)
|
||||
|
||||
```javascript
|
||||
// Derive wave structure from dependency graph (for reporting only — executor uses depends_on directly)
|
||||
function computeWaves(tasks) {
|
||||
const waves = {}
|
||||
const assigned = new Set()
|
||||
let currentWave = 1
|
||||
|
||||
while (assigned.size < tasks.length) {
|
||||
const waveMembers = tasks.filter(t =>
|
||||
!assigned.has(t.id) &&
|
||||
(t.depends_on || []).every(d => assigned.has(d))
|
||||
)
|
||||
|
||||
if (waveMembers.length === 0 && assigned.size < tasks.length) {
|
||||
const unassigned = tasks.find(t => !assigned.has(t.id))
|
||||
waveMembers.push(unassigned)
|
||||
}
|
||||
|
||||
for (const task of waveMembers) {
|
||||
waves[task.id] = currentWave
|
||||
assigned.add(task.id)
|
||||
}
|
||||
currentWave++
|
||||
}
|
||||
return { waves, totalWaves: currentWave - 1 }
|
||||
}
|
||||
|
||||
const { waves, totalWaves } = computeWaves(allTasks)
|
||||
```
|
||||
|
||||
### Step 6: Report Plan Structure
|
||||
|
||||
```javascript
|
||||
const taskCount = allTasks.length
|
||||
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
ref: `${sessionFolder}/phase-${phaseNumber}/`
|
||||
})
|
||||
|
||||
return {
|
||||
taskCount,
|
||||
totalWaves,
|
||||
waves,
|
||||
taskFiles,
|
||||
implPlanPath,
|
||||
todoListPath
|
||||
}
|
||||
```
|
||||
|
||||
## Gap Closure Plans
|
||||
|
||||
When creating plans for gap closure (re-planning after verification found gaps):
|
||||
|
||||
```javascript
|
||||
if (isGapClosure) {
|
||||
// 1. Existing IMPL-*.json files represent completed work
|
||||
// 2. action-planning-agent receives gap context and creates gap-specific tasks
|
||||
// 3. New task IDs start from next available (e.g., IMPL-103 if 101,102 exist)
|
||||
// 4. convergence criteria should directly address gap descriptions from verification.md
|
||||
// 5. Gap tasks may depend on existing completed tasks
|
||||
}
|
||||
```
|
||||
|
||||
## Helper: Minimal IMPL_PLAN.md Generation
|
||||
|
||||
```javascript
|
||||
function generateMinimalImplPlan(tasks, outputPath, phaseGoal, phaseNumber) {
|
||||
const content = `# Implementation Plan: Phase ${phaseNumber}
|
||||
|
||||
## Goal
|
||||
|
||||
${phaseGoal}
|
||||
|
||||
## Tasks
|
||||
|
||||
${tasks.map(t => `### ${t.id}: ${t.title}
|
||||
|
||||
${t.description}
|
||||
|
||||
**Files**: ${(t.files || []).map(f => f.path).join(', ')}
|
||||
**Depends on**: ${(t.depends_on || []).join(', ') || 'None'}
|
||||
|
||||
**Convergence Criteria**:
|
||||
${(t.convergence?.criteria || []).map(c => `- ${c}`).join('\n')}
|
||||
`).join('\n---\n\n')}
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
${'```'}
|
||||
${tasks.map(t => `${t.id} → [${(t.depends_on || []).join(', ')}]`).join('\n')}
|
||||
${'```'}
|
||||
`
|
||||
|
||||
Write(outputPath, content)
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| context.md not found | Error — research phase was skipped or failed |
|
||||
| action-planning-agent fails | Retry once. If still fails, error to coordinator |
|
||||
| No task JSONs generated | Error to coordinator — agent may have misunderstood input |
|
||||
| Dependency cycle detected | Log warning, break cycle at lowest-numbered task |
|
||||
| Too many tasks (>10) | Log warning — agent should self-limit but validate |
|
||||
| Missing convergence criteria | Log warning — every task should have at least one criterion |
|
||||
| IMPL_PLAN.md not generated | Create minimal version from task JSONs |
|
||||
@@ -1,219 +0,0 @@
|
||||
# Command: research
|
||||
|
||||
Gather context for a phase before creating execution plans. Explores the codebase, reads requirements from roadmap, and produces a structured context.md file.
|
||||
|
||||
## Purpose
|
||||
|
||||
Build a comprehensive understanding of the phase's scope by combining roadmap requirements, prior phase outputs, and codebase analysis. The resulting context.md is the sole input for the create-plans command.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 2 of planner execution (after task discovery, before plan creation)
|
||||
- Called once per PLAN-* task (including gap closure iterations)
|
||||
|
||||
## Strategy
|
||||
|
||||
Subagent delegation (cli-explore-agent) for codebase exploration, supplemented by optional Gemini CLI for deep analysis when depth warrants it. Planner does NOT explore the codebase directly -- it delegates.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Source | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `sessionFolder` | From PLAN-* task description | Session artifact directory |
|
||||
| `phaseNumber` | From PLAN-* task description | Phase to research (1-based) |
|
||||
| `depth` | From config.json or task description | "quick" / "standard" / "comprehensive" |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Read Roadmap and Extract Phase Requirements
|
||||
|
||||
```javascript
|
||||
const roadmap = Read(`${sessionFolder}/roadmap.md`)
|
||||
const config = JSON.parse(Read(`${sessionFolder}/config.json`))
|
||||
const depth = config.depth || "standard"
|
||||
|
||||
// Parse phase section from roadmap
|
||||
// Extract: goal, requirements (REQ-IDs), success criteria
|
||||
const phaseSection = extractPhaseSection(roadmap, phaseNumber)
|
||||
const phaseGoal = phaseSection.goal
|
||||
const requirements = phaseSection.requirements // [{id: "REQ-101", desc: "..."}, ...]
|
||||
const successCriteria = phaseSection.successCriteria // ["testable behavior 1", ...]
|
||||
```
|
||||
|
||||
### Step 2: Read Prior Phase Context (if applicable)
|
||||
|
||||
```javascript
|
||||
const priorContext = []
|
||||
|
||||
if (phaseNumber > 1) {
|
||||
// Load summaries from previous phases for dependency context
|
||||
for (let p = 1; p < phaseNumber; p++) {
|
||||
try {
|
||||
const summary = Glob(`${sessionFolder}/phase-${p}/summary-*.md`)
|
||||
for (const summaryFile of summary) {
|
||||
priorContext.push({
|
||||
phase: p,
|
||||
file: summaryFile,
|
||||
content: Read(summaryFile)
|
||||
})
|
||||
}
|
||||
} catch {
|
||||
// Prior phase may not have summaries yet (first phase)
|
||||
}
|
||||
|
||||
// Also load verification results for dependency awareness
|
||||
try {
|
||||
const verification = Read(`${sessionFolder}/phase-${p}/verification.md`)
|
||||
priorContext.push({
|
||||
phase: p,
|
||||
file: `${sessionFolder}/phase-${p}/verification.md`,
|
||||
content: verification
|
||||
})
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
|
||||
// For gap closure: load the verification that triggered re-planning
|
||||
const isGapClosure = planTaskDescription.includes("Gap closure")
|
||||
let gapContext = null
|
||||
if (isGapClosure) {
|
||||
gapContext = Read(`${sessionFolder}/phase-${phaseNumber}/verification.md`)
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Codebase Exploration via cli-explore-agent
|
||||
|
||||
```javascript
|
||||
// Build exploration query from requirements
|
||||
const explorationQuery = requirements.map(r => r.desc).join('; ')
|
||||
|
||||
const exploreResult = Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore codebase for phase ${phaseNumber} requirements`,
|
||||
prompt: `Explore this codebase to gather context for the following requirements:
|
||||
|
||||
## Phase Goal
|
||||
${phaseGoal}
|
||||
|
||||
## Requirements
|
||||
${requirements.map(r => `- ${r.id}: ${r.desc}`).join('\n')}
|
||||
|
||||
## Success Criteria
|
||||
${successCriteria.map(c => `- ${c}`).join('\n')}
|
||||
|
||||
## What to Find
|
||||
1. Files that will need modification to satisfy these requirements
|
||||
2. Existing patterns and conventions relevant to this work
|
||||
3. Dependencies and integration points
|
||||
4. Test patterns used in this project
|
||||
5. Configuration or schema files that may need updates
|
||||
|
||||
## Output Format
|
||||
Provide a structured summary:
|
||||
- **Relevant Files**: List of files with brief description of relevance
|
||||
- **Patterns Found**: Coding patterns, naming conventions, architecture patterns
|
||||
- **Dependencies**: Internal and external dependencies that affect this work
|
||||
- **Test Infrastructure**: Test framework, test file locations, test patterns
|
||||
- **Risks**: Potential issues or complications discovered`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 4: Optional Deep Analysis via Gemini CLI
|
||||
|
||||
```javascript
|
||||
// Only for comprehensive depth or complex phases
|
||||
if (depth === "comprehensive") {
|
||||
const analysisResult = Bash({
|
||||
command: `ccw cli -p "PURPOSE: Deep codebase analysis for implementation planning. Phase goal: ${phaseGoal}
|
||||
TASK: \
|
||||
- Analyze module boundaries and coupling for affected files \
|
||||
- Identify shared utilities and helpers that can be reused \
|
||||
- Map data flow through affected components \
|
||||
- Assess test coverage gaps in affected areas \
|
||||
- Identify backward compatibility concerns
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Requirements: ${requirements.map(r => r.desc).join(', ')}
|
||||
EXPECTED: Structured analysis with: module map, reuse opportunities, data flow diagram, test gaps, compatibility risks
|
||||
CONSTRAINTS: Focus on files relevant to phase ${phaseNumber} requirements" \
|
||||
--tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
|
||||
run_in_background: false,
|
||||
timeout: 300000
|
||||
})
|
||||
|
||||
// Store deep analysis result for context.md
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Write context.md
|
||||
|
||||
```javascript
|
||||
Bash(`mkdir -p "${sessionFolder}/phase-${phaseNumber}"`)
|
||||
|
||||
const contextContent = `# Phase ${phaseNumber} Context
|
||||
|
||||
Generated: ${new Date().toISOString().slice(0, 19)}
|
||||
Session: ${sessionFolder}
|
||||
Depth: ${depth}
|
||||
|
||||
## Phase Goal
|
||||
|
||||
${phaseGoal}
|
||||
|
||||
## Requirements
|
||||
|
||||
${requirements.map(r => `- **${r.id}**: ${r.desc}`).join('\n')}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
${successCriteria.map(c => `- [ ] ${c}`).join('\n')}
|
||||
|
||||
## Prior Phase Dependencies
|
||||
|
||||
${priorContext.length > 0
|
||||
? priorContext.map(p => `### Phase ${p.phase}\n- Source: ${p.file}\n- Key outputs: ${extractKeyOutputs(p.content)}`).join('\n\n')
|
||||
: 'None (this is the first phase)'}
|
||||
|
||||
${isGapClosure ? `## Gap Closure Context\n\nThis is a gap closure iteration. Gaps from previous verification:\n${gapContext}` : ''}
|
||||
|
||||
## Relevant Files
|
||||
|
||||
${exploreResult.relevantFiles.map(f => `- \`${f.path}\`: ${f.description}`).join('\n')}
|
||||
|
||||
## Patterns Identified
|
||||
|
||||
${exploreResult.patterns.map(p => `- **${p.name}**: ${p.description}`).join('\n')}
|
||||
|
||||
## Dependencies
|
||||
|
||||
${exploreResult.dependencies.map(d => `- ${d}`).join('\n')}
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
${exploreResult.testInfo || 'Not analyzed (quick depth)'}
|
||||
|
||||
${depth === "comprehensive" && analysisResult ? `## Deep Analysis\n\n${analysisResult}` : ''}
|
||||
|
||||
## Questions / Risks
|
||||
|
||||
${exploreResult.risks.map(r => `- ${r}`).join('\n')}
|
||||
`
|
||||
|
||||
Write(`${sessionFolder}/phase-${phaseNumber}/context.md`, contextContent)
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
| Artifact | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| context.md | `{sessionFolder}/phase-{N}/context.md` | Structured phase context for plan creation |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| roadmap.md not found | Error to coordinator via message bus |
|
||||
| cli-explore-agent fails | Retry once. Fallback: use ACE search_context directly |
|
||||
| Gemini CLI fails | Skip deep analysis section, proceed with basic context |
|
||||
| Prior phase summaries missing | Log warning, proceed without dependency context |
|
||||
| Phase section not found in roadmap | Error to coordinator -- phase number may be invalid |
|
||||
@@ -1,239 +0,0 @@
|
||||
# Planner Role
|
||||
|
||||
Research and plan creation per phase. Gathers codebase context via cli-explore-agent and Gemini CLI, then generates wave-based execution plans with convergence criteria. Each plan is a self-contained unit of work that an executor can implement autonomously.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `planner` | **Tag**: `[planner]`
|
||||
- **Task Prefix**: `PLAN-*`
|
||||
- **Responsibility**: Orchestration (research + plan generation)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- All outputs must carry `[planner]` prefix
|
||||
- Only process `PLAN-*` prefixed tasks
|
||||
- Only communicate with coordinator (SendMessage)
|
||||
- Delegate research to commands/research.md
|
||||
- Delegate plan creation to commands/create-plans.md
|
||||
- Reference real files discovered during research (never fabricate paths)
|
||||
- Verify plans have no dependency cycles before reporting
|
||||
- Work strictly within Orchestration responsibility scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Direct code writing or modification
|
||||
- Call code-developer or other implementation subagents
|
||||
- Create tasks for other roles (TaskCreate)
|
||||
- Interact with user (AskUserQuestion)
|
||||
- Process EXEC-* or VERIFY-* tasks
|
||||
- Skip the research phase
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Omit `[planner]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
| `research` | [commands/research.md](commands/research.md) | Phase 2 | Context gathering via codebase exploration |
|
||||
| `create-plans` | [commands/create-plans.md](commands/create-plans.md) | Phase 3 | Wave-based plan file generation |
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `cli-explore-agent` | Subagent | planner | Codebase exploration, pattern analysis |
|
||||
| `action-planning-agent` | Subagent | planner | Task JSON + IMPL_PLAN.md generation |
|
||||
| `gemini` | CLI tool | planner | Deep analysis for complex phases (optional) |
|
||||
| `Read/Write` | File operations | planner | Context and plan file management |
|
||||
| `Glob/Grep` | Search | planner | File discovery and pattern matching |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `plan_ready` | planner -> coordinator | Plans created | Plan files written with wave structure |
|
||||
| `plan_progress` | planner -> coordinator | Research complete | Context gathered, starting plan creation |
|
||||
| `error` | planner -> coordinator | Failure | Research or planning failed |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "planner",
|
||||
type: <message-type>,
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from planner --type <type> --ref <artifact-path> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `PLAN-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
**Resume Artifact Check**: Check whether this task's output artifact already exists:
|
||||
- `<session>/phase-N/context.md` exists -> skip to Phase 3
|
||||
- Artifact incomplete or missing -> normal Phase 2-4 execution
|
||||
|
||||
### Phase 2: Research (via command)
|
||||
|
||||
**Objective**: Gather codebase context for plan generation.
|
||||
|
||||
**Loading steps**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| roadmap.md | <session-folder>/roadmap.md | Yes |
|
||||
| Prior phase summaries | <session-folder>/phase-*/summary-*.md | No |
|
||||
| Wisdom | <session-folder>/wisdom/ | No |
|
||||
|
||||
Delegate to `commands/research.md`:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Read roadmap.md for phase goal and requirements |
|
||||
| 2 | Read prior phase summaries (if any) |
|
||||
| 3 | Launch cli-explore-agent for codebase exploration |
|
||||
| 4 | Optional: Gemini CLI for deeper analysis (if depth=comprehensive) |
|
||||
| 5 | Write context.md to {sessionFolder}/phase-{N}/context.md |
|
||||
|
||||
**Produces**: `{sessionFolder}/phase-{N}/context.md`
|
||||
|
||||
**Command**: [commands/research.md](commands/research.md)
|
||||
|
||||
**Report progress via team_msg**:
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId,
|
||||
from: "planner",
|
||||
type: "plan_progress",
|
||||
ref: "<session>/phase-<N>/context.md"
|
||||
})
|
||||
```
|
||||
|
||||
### Phase 3: Create Plans (via command)
|
||||
|
||||
**Objective**: Generate wave-based execution plans.
|
||||
|
||||
Delegate to `commands/create-plans.md`:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Load context.md for phase |
|
||||
| 2 | Prepare output directories (.task/) |
|
||||
| 3 | Delegate to action-planning-agent |
|
||||
| 4 | Agent produces IMPL_PLAN.md + .task/IMPL-*.json + TODO_LIST.md |
|
||||
| 5 | Validate generated artifacts |
|
||||
| 6 | Return task count and dependency structure |
|
||||
|
||||
**Produces**:
|
||||
- `{sessionFolder}/phase-{N}/IMPL_PLAN.md`
|
||||
- `{sessionFolder}/phase-{N}/.task/IMPL-*.json`
|
||||
- `{sessionFolder}/phase-{N}/TODO_LIST.md`
|
||||
|
||||
**Command**: [commands/create-plans.md](commands/create-plans.md)
|
||||
|
||||
### Phase 4: Self-Validation
|
||||
|
||||
**Objective**: Verify task JSONs before reporting.
|
||||
|
||||
**Validation checks**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Referenced files exist | `test -f <path>` for modify actions | All files found or warning logged |
|
||||
| Self-dependency | Check if depends_on includes own ID | No self-dependencies |
|
||||
| Convergence criteria | Check convergence.criteria exists | Each task has criteria |
|
||||
| Cross-dependency | Verify all depends_on IDs exist | All dependencies valid |
|
||||
|
||||
**Validation steps**:
|
||||
|
||||
1. **File existence check** (for modify actions):
|
||||
- For each task file with action="modify"
|
||||
- Check file exists
|
||||
- Log warning if not found
|
||||
|
||||
2. **Self-dependency check**:
|
||||
- For each task, verify task.id not in task.depends_on
|
||||
- Log error if self-dependency detected
|
||||
|
||||
3. **Convergence criteria check**:
|
||||
- Verify each task has convergence.criteria array
|
||||
- Log warning if missing
|
||||
|
||||
4. **Cross-dependency validation**:
|
||||
- Collect all task IDs
|
||||
- Verify each depends_on reference exists
|
||||
- Log warning if unknown dependency
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[planner]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Wave count computation**:
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Start with wave=1, assigned=set() |
|
||||
| 2 | Find tasks with all dependencies in assigned |
|
||||
| 3 | Assign those tasks to current wave, add to assigned |
|
||||
| 4 | Increment wave, repeat until all tasks assigned |
|
||||
| 5 | Return wave count |
|
||||
|
||||
**Report message**:
|
||||
```
|
||||
SendMessage({
|
||||
message: "[planner] Phase <N> planning complete.
|
||||
- Tasks: <count>
|
||||
- Waves: <wave-count>
|
||||
- IMPL_PLAN: <session>/phase-<N>/IMPL_PLAN.md
|
||||
- Task JSONs: <file-list>
|
||||
|
||||
All tasks validated. Ready for execution."
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No PLAN-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Context/Plan file not found | Notify coordinator, request location |
|
||||
| Command file not found | Fall back to inline execution |
|
||||
| roadmap.md not found | Error to coordinator -- dispatch may have failed |
|
||||
| cli-explore-agent fails | Retry once. If still fails, use direct ACE search as fallback |
|
||||
| Gemini CLI fails | Skip deep analysis, proceed with basic context |
|
||||
| action-planning-agent fails | Retry once. If still fails, error to coordinator |
|
||||
| No task JSONs generated | Error to coordinator -- agent may have misunderstood input |
|
||||
| No requirements found for phase | Error to coordinator -- roadmap may be malformed |
|
||||
| Dependency cycle detected | Log warning, break cycle |
|
||||
| Referenced file not found | Log warning. If file is from prior wave, acceptable |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
| Unexpected error | Log error via team_msg, report to coordinator |
|
||||
Reference in New Issue
Block a user