mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add templates for architecture documents, epics, product briefs, and requirements PRD
- Introduced architecture document template for Phase 4, including structure and individual ADR records. - Added epics & stories template for Phase 5, detailing epic breakdown and dependencies. - Created product brief template for Phase 2, summarizing product vision, problem statement, and target users. - Developed requirements PRD template for Phase 3, outlining functional and non-functional requirements with traceability. - Implemented spec command for project spec management with subcommands for loading, listing, rebuilding, and initializing specs.
This commit is contained in:
catlog22
@@ -0,0 +1,466 @@
|
||||
# Command: Multi-Angle Exploration
|
||||
|
||||
Phase 2 of planner execution - assess complexity, select exploration angles, and execute parallel exploration.
|
||||
|
||||
## Overview
|
||||
|
||||
This command performs multi-angle codebase exploration based on task complexity. Low complexity uses direct semantic search, while Medium/High complexity launches parallel cli-explore-agent subagents for comprehensive analysis.
|
||||
|
||||
## Complexity Assessment
|
||||
|
||||
### assessComplexity Function
|
||||
|
||||
```javascript
|
||||
function assessComplexity(desc) {
|
||||
let score = 0
|
||||
if (/refactor|architect|restructure|模块|系统/.test(desc)) score += 2
|
||||
if (/multiple|多个|across|跨/.test(desc)) score += 2
|
||||
if (/integrate|集成|api|database/.test(desc)) score += 1
|
||||
if (/security|安全|performance|性能/.test(desc)) score += 1
|
||||
return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low'
|
||||
}
|
||||
|
||||
const complexity = assessComplexity(task.description)
|
||||
```
|
||||
|
||||
### Complexity Levels
|
||||
|
||||
| Level | Score | Characteristics | Angle Count |
|
||||
|-------|-------|----------------|-------------|
|
||||
| **Low** | 0-1 | Simple feature, single module, clear scope | 1 |
|
||||
| **Medium** | 2-3 | Multiple modules, integration points, moderate scope | 3 |
|
||||
| **High** | 4+ | Architecture changes, cross-cutting concerns, complex scope | 4 |
|
||||
|
||||
## Angle Selection
|
||||
|
||||
### ANGLE_PRESETS
|
||||
|
||||
```javascript
|
||||
const ANGLE_PRESETS = {
|
||||
architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
|
||||
security: ['security', 'auth-patterns', 'dataflow', 'validation'],
|
||||
performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
|
||||
bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
|
||||
feature: ['patterns', 'integration-points', 'testing', 'dependencies']
|
||||
}
|
||||
```
|
||||
|
||||
### selectAngles Function
|
||||
|
||||
```javascript
|
||||
function selectAngles(desc, count) {
|
||||
const text = desc.toLowerCase()
|
||||
let preset = 'feature'
|
||||
if (/refactor|architect|restructure|modular/.test(text)) preset = 'architecture'
|
||||
else if (/security|auth|permission|access/.test(text)) preset = 'security'
|
||||
else if (/performance|slow|optimi|cache/.test(text)) preset = 'performance'
|
||||
else if (/fix|bug|error|issue|broken/.test(text)) preset = 'bugfix'
|
||||
return ANGLE_PRESETS[preset].slice(0, count)
|
||||
}
|
||||
|
||||
const angleCount = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1)
|
||||
const selectedAngles = selectAngles(task.description, angleCount)
|
||||
```
|
||||
|
||||
### Angle Definitions
|
||||
|
||||
| Angle | Focus | Use Case |
|
||||
|-------|-------|----------|
|
||||
| **architecture** | System structure, layer boundaries, design patterns | Refactoring, restructuring |
|
||||
| **dependencies** | Module dependencies, coupling, external libraries | Integration, modularity |
|
||||
| **modularity** | Component boundaries, separation of concerns | Architecture changes |
|
||||
| **integration-points** | API boundaries, data flow between modules | Feature development |
|
||||
| **security** | Auth/authz, input validation, data protection | Security features |
|
||||
| **auth-patterns** | Authentication flows, session management | Auth implementation |
|
||||
| **dataflow** | Data transformation, state propagation | Bug fixes, features |
|
||||
| **validation** | Input validation, error handling | Security, quality |
|
||||
| **performance** | Bottlenecks, optimization opportunities | Performance tuning |
|
||||
| **bottlenecks** | Slow operations, resource contention | Performance issues |
|
||||
| **caching** | Cache strategies, invalidation patterns | Performance optimization |
|
||||
| **data-access** | Database queries, data fetching patterns | Performance, features |
|
||||
| **error-handling** | Error propagation, recovery strategies | Bug fixes |
|
||||
| **state-management** | State updates, consistency | Bug fixes, features |
|
||||
| **edge-cases** | Boundary conditions, error scenarios | Bug fixes, testing |
|
||||
| **patterns** | Code patterns, conventions, best practices | Feature development |
|
||||
| **testing** | Test coverage, test strategies | Feature development |
|
||||
|
||||
## Exploration Execution
|
||||
|
||||
### Low Complexity: Direct Semantic Search
|
||||
|
||||
```javascript
|
||||
if (complexity === 'Low') {
|
||||
// Direct exploration via semantic search
|
||||
const results = mcp__ace-tool__search_context({
|
||||
project_root_path: projectRoot,
|
||||
query: task.description
|
||||
})
|
||||
|
||||
// Transform ACE results to exploration JSON
|
||||
const exploration = {
|
||||
project_structure: "Analyzed via ACE semantic search",
|
||||
relevant_files: results.files.map(f => ({
|
||||
path: f.path,
|
||||
rationale: f.relevance_reason || "Semantic match to task description",
|
||||
role: "modify_target",
|
||||
discovery_source: "ace-search",
|
||||
key_symbols: f.symbols || []
|
||||
})),
|
||||
patterns: results.patterns || [],
|
||||
dependencies: results.dependencies || [],
|
||||
integration_points: results.integration_points || [],
|
||||
constraints: [],
|
||||
clarification_needs: [],
|
||||
_metadata: {
|
||||
exploration_angle: selectedAngles[0],
|
||||
complexity: 'Low',
|
||||
discovery_method: 'ace-semantic-search'
|
||||
}
|
||||
}
|
||||
|
||||
Write(`${planDir}/exploration-${selectedAngles[0]}.json`, JSON.stringify(exploration, null, 2))
|
||||
}
|
||||
```
|
||||
|
||||
### Medium/High Complexity: Parallel cli-explore-agent
|
||||
|
||||
```javascript
|
||||
else {
|
||||
// Launch parallel cli-explore-agent for each angle
|
||||
selectedAngles.forEach((angle, index) => {
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore: ${angle}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Execute **${angle}** exploration for task planning context.
|
||||
|
||||
## Output Location
|
||||
**Session Folder**: ${sessionFolder}
|
||||
**Output File**: ${planDir}/exploration-${angle}.json
|
||||
|
||||
## Assigned Context
|
||||
- **Exploration Angle**: ${angle}
|
||||
- **Task Description**: ${task.description}
|
||||
- **Spec Context**: ${specContext ? 'Available — use spec/requirements, spec/architecture, spec/epics for informed exploration' : 'Not available (impl-only mode)'}
|
||||
- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Run: rg -l "{relevant_keyword}" --type ts (locate relevant files)
|
||||
2. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema)
|
||||
3. Read: .workflow/project-tech.json (if exists - technology stack)
|
||||
|
||||
## Expected Output
|
||||
Write JSON to: ${planDir}/exploration-${angle}.json
|
||||
Follow explore-json-schema.json structure with ${angle}-focused findings.
|
||||
|
||||
**MANDATORY**: Every file in relevant_files MUST have:
|
||||
- **rationale** (required): Specific selection basis tied to ${angle} topic (>10 chars, not generic)
|
||||
- **role** (required): modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only
|
||||
- **discovery_source** (recommended): bash-scan|cli-analysis|ace-search|dependency-trace|manual
|
||||
- **key_symbols** (recommended): Key functions/classes/types relevant to task
|
||||
|
||||
## Exploration Focus by Angle
|
||||
|
||||
${getAngleFocusGuide(angle)}
|
||||
|
||||
## Output Schema Structure
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"project_structure": "string - high-level architecture overview",
|
||||
"relevant_files": [
|
||||
{
|
||||
"path": "string - relative file path",
|
||||
"rationale": "string - WHY this file matters for ${angle} (>10 chars, specific)",
|
||||
"role": "modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only",
|
||||
"discovery_source": "bash-scan|cli-analysis|ace-search|dependency-trace|manual",
|
||||
"key_symbols": ["function/class/type names"]
|
||||
}
|
||||
],
|
||||
"patterns": ["string - code patterns relevant to ${angle}"],
|
||||
"dependencies": ["string - module/library dependencies"],
|
||||
"integration_points": ["string - API/interface boundaries"],
|
||||
"constraints": ["string - technical constraints"],
|
||||
"clarification_needs": ["string - questions needing user input"],
|
||||
"_metadata": {
|
||||
"exploration_angle": "${angle}",
|
||||
"complexity": "${complexity}",
|
||||
"discovery_method": "cli-explore-agent"
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Angle Focus Guide
|
||||
|
||||
```javascript
|
||||
function getAngleFocusGuide(angle) {
|
||||
const guides = {
|
||||
architecture: `
|
||||
**Architecture Focus**:
|
||||
- Identify layer boundaries (presentation, business, data)
|
||||
- Map module dependencies and coupling
|
||||
- Locate design patterns (factory, strategy, observer, etc.)
|
||||
- Find architectural decision records (ADRs)
|
||||
- Analyze component responsibilities`,
|
||||
|
||||
dependencies: `
|
||||
**Dependencies Focus**:
|
||||
- Map internal module dependencies (import/require statements)
|
||||
- Identify external library usage (package.json, requirements.txt)
|
||||
- Trace dependency chains and circular dependencies
|
||||
- Locate shared utilities and common modules
|
||||
- Analyze coupling strength between modules`,
|
||||
|
||||
modularity: `
|
||||
**Modularity Focus**:
|
||||
- Identify module boundaries and interfaces
|
||||
- Analyze separation of concerns
|
||||
- Locate tightly coupled code
|
||||
- Find opportunities for extraction/refactoring
|
||||
- Map public vs private APIs`,
|
||||
|
||||
'integration-points': `
|
||||
**Integration Points Focus**:
|
||||
- Locate API endpoints and routes
|
||||
- Identify data flow between modules
|
||||
- Find event emitters/listeners
|
||||
- Map external service integrations
|
||||
- Analyze interface contracts`,
|
||||
|
||||
security: `
|
||||
**Security Focus**:
|
||||
- Locate authentication/authorization logic
|
||||
- Identify input validation points
|
||||
- Find sensitive data handling
|
||||
- Analyze access control mechanisms
|
||||
- Locate security-related middleware`,
|
||||
|
||||
'auth-patterns': `
|
||||
**Auth Patterns Focus**:
|
||||
- Identify authentication flows (login, logout, refresh)
|
||||
- Locate session management code
|
||||
- Find token generation/validation
|
||||
- Map user permission checks
|
||||
- Analyze auth middleware`,
|
||||
|
||||
dataflow: `
|
||||
**Dataflow Focus**:
|
||||
- Trace data transformations
|
||||
- Identify state propagation paths
|
||||
- Locate data validation points
|
||||
- Map data sources and sinks
|
||||
- Analyze data mutation points`,
|
||||
|
||||
validation: `
|
||||
**Validation Focus**:
|
||||
- Locate input validation logic
|
||||
- Identify schema definitions
|
||||
- Find error handling for invalid data
|
||||
- Map validation middleware
|
||||
- Analyze sanitization functions`,
|
||||
|
||||
performance: `
|
||||
**Performance Focus**:
|
||||
- Identify computational bottlenecks
|
||||
- Locate database queries (N+1 problems)
|
||||
- Find synchronous blocking operations
|
||||
- Map resource-intensive operations
|
||||
- Analyze algorithm complexity`,
|
||||
|
||||
bottlenecks: `
|
||||
**Bottlenecks Focus**:
|
||||
- Locate slow operations (profiling data)
|
||||
- Identify resource contention points
|
||||
- Find inefficient algorithms
|
||||
- Map hot paths in code
|
||||
- Analyze concurrency issues`,
|
||||
|
||||
caching: `
|
||||
**Caching Focus**:
|
||||
- Locate existing cache implementations
|
||||
- Identify cacheable operations
|
||||
- Find cache invalidation logic
|
||||
- Map cache key strategies
|
||||
- Analyze cache hit/miss patterns`,
|
||||
|
||||
'data-access': `
|
||||
**Data Access Focus**:
|
||||
- Locate database query patterns
|
||||
- Identify ORM/query builder usage
|
||||
- Find data fetching strategies
|
||||
- Map data access layers
|
||||
- Analyze query optimization opportunities`,
|
||||
|
||||
'error-handling': `
|
||||
**Error Handling Focus**:
|
||||
- Locate try-catch blocks
|
||||
- Identify error propagation paths
|
||||
- Find error recovery strategies
|
||||
- Map error logging points
|
||||
- Analyze error types and handling`,
|
||||
|
||||
'state-management': `
|
||||
**State Management Focus**:
|
||||
- Locate state containers (Redux, Vuex, etc.)
|
||||
- Identify state update patterns
|
||||
- Find state synchronization logic
|
||||
- Map state dependencies
|
||||
- Analyze state consistency mechanisms`,
|
||||
|
||||
'edge-cases': `
|
||||
**Edge Cases Focus**:
|
||||
- Identify boundary conditions
|
||||
- Locate null/undefined handling
|
||||
- Find empty array/object handling
|
||||
- Map error scenarios
|
||||
- Analyze exceptional flows`,
|
||||
|
||||
patterns: `
|
||||
**Patterns Focus**:
|
||||
- Identify code patterns and conventions
|
||||
- Locate design pattern implementations
|
||||
- Find naming conventions
|
||||
- Map code organization patterns
|
||||
- Analyze best practices usage`,
|
||||
|
||||
testing: `
|
||||
**Testing Focus**:
|
||||
- Locate test files and test utilities
|
||||
- Identify test coverage gaps
|
||||
- Find test patterns (unit, integration, e2e)
|
||||
- Map mocking/stubbing strategies
|
||||
- Analyze test organization`
|
||||
}
|
||||
|
||||
return guides[angle] || `**${angle} Focus**: Analyze codebase from ${angle} perspective`
|
||||
}
|
||||
```
|
||||
|
||||
## Explorations Manifest
|
||||
|
||||
```javascript
|
||||
// Build explorations manifest
|
||||
const explorationManifest = {
|
||||
session_id: `${taskSlug}-${dateStr}`,
|
||||
task_description: task.description,
|
||||
complexity: complexity,
|
||||
exploration_count: selectedAngles.length,
|
||||
explorations: selectedAngles.map(angle => ({
|
||||
angle: angle,
|
||||
file: `exploration-${angle}.json`,
|
||||
path: `${planDir}/exploration-${angle}.json`
|
||||
}))
|
||||
}
|
||||
Write(`${planDir}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2))
|
||||
```
|
||||
|
||||
## Output Schema
|
||||
|
||||
### explore-json-schema.json Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"project_structure": "string - high-level architecture overview",
|
||||
"relevant_files": [
|
||||
{
|
||||
"path": "string - relative file path",
|
||||
"rationale": "string - specific selection basis (>10 chars)",
|
||||
"role": "modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only",
|
||||
"discovery_source": "bash-scan|cli-analysis|ace-search|dependency-trace|manual",
|
||||
"key_symbols": ["string - function/class/type names"]
|
||||
}
|
||||
],
|
||||
"patterns": ["string - code patterns relevant to angle"],
|
||||
"dependencies": ["string - module/library dependencies"],
|
||||
"integration_points": ["string - API/interface boundaries"],
|
||||
"constraints": ["string - technical constraints"],
|
||||
"clarification_needs": ["string - questions needing user input"],
|
||||
"_metadata": {
|
||||
"exploration_angle": "string - angle name",
|
||||
"complexity": "Low|Medium|High",
|
||||
"discovery_method": "ace-semantic-search|cli-explore-agent"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Phase 3
|
||||
|
||||
Phase 3 (Plan Generation) consumes:
|
||||
1. `explorations-manifest.json` - list of exploration files
|
||||
2. `exploration-{angle}.json` - per-angle exploration results
|
||||
3. `specContext` (if available) - requirements, architecture, epics
|
||||
|
||||
These inputs are passed to cli-lite-planning-agent for plan generation.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Exploration Agent Failure
|
||||
|
||||
```javascript
|
||||
try {
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore: ${angle}`,
|
||||
prompt: `...`
|
||||
})
|
||||
} catch (error) {
|
||||
// Skip exploration, continue with available explorations
|
||||
console.error(`[planner] Exploration failed for angle: ${angle}`, error)
|
||||
// Remove failed angle from manifest
|
||||
explorationManifest.explorations = explorationManifest.explorations.filter(e => e.angle !== angle)
|
||||
explorationManifest.exploration_count = explorationManifest.explorations.length
|
||||
}
|
||||
```
|
||||
|
||||
### All Explorations Fail
|
||||
|
||||
```javascript
|
||||
if (explorationManifest.exploration_count === 0) {
|
||||
// Fallback: Plan from task description only
|
||||
console.warn(`[planner] All explorations failed, planning from task description only`)
|
||||
// Proceed to Phase 3 with empty explorations
|
||||
}
|
||||
```
|
||||
|
||||
### ACE Search Failure (Low Complexity)
|
||||
|
||||
```javascript
|
||||
try {
|
||||
const results = mcp__ace-tool__search_context({
|
||||
project_root_path: projectRoot,
|
||||
query: task.description
|
||||
})
|
||||
} catch (error) {
|
||||
// Fallback: Use ripgrep for basic file discovery
|
||||
const rgResults = Bash(`rg -l "${task.description}" --type ts`)
|
||||
const exploration = {
|
||||
project_structure: "Basic file discovery via ripgrep",
|
||||
relevant_files: rgResults.split('\n').map(path => ({
|
||||
path: path.trim(),
|
||||
rationale: "Matched task description keywords",
|
||||
role: "modify_target",
|
||||
discovery_source: "bash-scan",
|
||||
key_symbols: []
|
||||
})),
|
||||
patterns: [],
|
||||
dependencies: [],
|
||||
integration_points: [],
|
||||
constraints: [],
|
||||
clarification_needs: [],
|
||||
_metadata: {
|
||||
exploration_angle: selectedAngles[0],
|
||||
complexity: 'Low',
|
||||
discovery_method: 'ripgrep-fallback'
|
||||
}
|
||||
}
|
||||
Write(`${planDir}/exploration-${selectedAngles[0]}.json`, JSON.stringify(exploration, null, 2))
|
||||
}
|
||||
```
|
||||
253
.claude/skills_lib/team-lifecycle-v2/roles/planner/role.md
Normal file
253
.claude/skills_lib/team-lifecycle-v2/roles/planner/role.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Role: planner
|
||||
|
||||
Multi-angle code exploration and structured implementation planning. Submits plans to the coordinator for approval.
|
||||
|
||||
## Role Identity
|
||||
|
||||
- **Name**: `planner`
|
||||
- **Task Prefix**: `PLAN-*`
|
||||
- **Output Tag**: `[planner]`
|
||||
- **Responsibility**: Code exploration → Implementation planning → Coordinator approval
|
||||
- **Communication**: SendMessage to coordinator only
|
||||
|
||||
## Role Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process PLAN-* tasks
|
||||
- Communicate only with coordinator
|
||||
- Write plan artifacts to `plan/` folder
|
||||
- Tag all SendMessage and team_msg calls with `[planner]`
|
||||
- Assess complexity (Low/Medium/High)
|
||||
- Execute multi-angle exploration based on complexity
|
||||
- Generate plan.json + .task/TASK-*.json following schemas
|
||||
- Submit plan for coordinator approval
|
||||
- Load spec context in full-lifecycle mode
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Contact other workers directly
|
||||
- Implement code
|
||||
- Modify spec documents
|
||||
- Skip complexity assessment
|
||||
- Proceed without exploration (Medium/High complexity)
|
||||
- Generate plan without schema validation
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `plan_ready` | planner → coordinator | Plan generation complete | With plan.json path and task count summary |
|
||||
| `plan_revision` | planner → coordinator | Plan revised and resubmitted | Describes changes made |
|
||||
| `impl_progress` | planner → coordinator | Exploration phase progress | Optional, for long explorations |
|
||||
| `error` | planner → coordinator | Unrecoverable error | Exploration failure, schema missing, etc. |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every `SendMessage`, MUST call `mcp__ccw-tools__team_msg` to log:
|
||||
|
||||
```javascript
|
||||
// Plan ready
|
||||
mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "planner", to: "coordinator", type: "plan_ready", summary: "[planner] Plan ready: 3 tasks, Medium complexity", ref: `${sessionFolder}/plan/plan.json` })
|
||||
|
||||
// Plan revision
|
||||
mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "planner", to: "coordinator", type: "plan_revision", summary: "[planner] Split task-2 into two subtasks per feedback" })
|
||||
|
||||
// Error report
|
||||
mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "planner", to: "coordinator", type: "error", summary: "[planner] plan-overview-base-schema.json not found, using default structure" })
|
||||
```
|
||||
|
||||
### CLI Fallback
|
||||
|
||||
When `mcp__ccw-tools__team_msg` MCP is unavailable:
|
||||
|
||||
```javascript
|
||||
Bash(`ccw team log --team "${teamName}" --from "planner" --to "coordinator" --type "plan_ready" --summary "[planner] Plan ready: 3 tasks" --ref "${sessionFolder}/plan/plan.json" --json`)
|
||||
```
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
- `commands/explore.md` - Multi-angle codebase exploration (Phase 2)
|
||||
|
||||
### Subagent Capabilities
|
||||
- **cli-explore-agent**: Per-angle exploration (Medium/High complexity)
|
||||
- **cli-lite-planning-agent**: Plan generation (Medium/High complexity)
|
||||
|
||||
### CLI Capabilities
|
||||
None directly (delegates to subagents)
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
```javascript
|
||||
const tasks = TaskList()
|
||||
const myTasks = tasks.filter(t =>
|
||||
t.subject.startsWith('PLAN-') &&
|
||||
t.owner === 'planner' &&
|
||||
t.status === 'pending' &&
|
||||
t.blockedBy.length === 0
|
||||
)
|
||||
|
||||
if (myTasks.length === 0) return // idle
|
||||
|
||||
const task = TaskGet({ taskId: myTasks[0].id })
|
||||
TaskUpdate({ taskId: task.id, status: 'in_progress' })
|
||||
```
|
||||
|
||||
### Phase 1.5: Load Spec Context (Full-Lifecycle Mode)
|
||||
|
||||
```javascript
|
||||
// Extract session folder from task description (set by coordinator)
|
||||
const sessionMatch = task.description.match(/Session:\s*(.+)/)
|
||||
const sessionFolder = sessionMatch ? sessionMatch[1].trim() : `.workflow/.team/default`
|
||||
const planDir = `${sessionFolder}/plan`
|
||||
Bash(`mkdir -p ${planDir}`)
|
||||
|
||||
// Check if spec directory exists (full-lifecycle mode)
|
||||
const specDir = `${sessionFolder}/spec`
|
||||
let specContext = null
|
||||
try {
|
||||
const reqIndex = Read(`${specDir}/requirements/_index.md`)
|
||||
const archIndex = Read(`${specDir}/architecture/_index.md`)
|
||||
const epicsIndex = Read(`${specDir}/epics/_index.md`)
|
||||
const specConfig = JSON.parse(Read(`${specDir}/spec-config.json`))
|
||||
specContext = { reqIndex, archIndex, epicsIndex, specConfig }
|
||||
} catch { /* impl-only mode has no spec */ }
|
||||
```
|
||||
|
||||
### Phase 2: Multi-Angle Exploration
|
||||
|
||||
**Delegate to**: `Read("commands/explore.md")`
|
||||
|
||||
Execute complexity assessment, angle selection, and parallel exploration. See `commands/explore.md` for full implementation.
|
||||
|
||||
### Phase 3: Plan Generation
|
||||
|
||||
```javascript
|
||||
// Read schema reference
|
||||
const schema = Bash(`cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json`)
|
||||
|
||||
if (complexity === 'Low') {
|
||||
// Direct Claude planning
|
||||
Bash(`mkdir -p ${planDir}/.task`)
|
||||
// Generate plan.json + .task/TASK-*.json following schemas
|
||||
|
||||
const plan = {
|
||||
session_id: `${taskSlug}-${dateStr}`,
|
||||
task_description: task.description,
|
||||
complexity: 'Low',
|
||||
approach: "Direct implementation based on semantic search",
|
||||
task_count: 1,
|
||||
task_ids: ['TASK-001'],
|
||||
exploration_refs: [`${planDir}/exploration-patterns.json`]
|
||||
}
|
||||
Write(`${planDir}/plan.json`, JSON.stringify(plan, null, 2))
|
||||
|
||||
const taskDetail = {
|
||||
id: 'TASK-001',
|
||||
title: task.subject,
|
||||
description: task.description,
|
||||
files: [],
|
||||
convergence: { criteria: ["Implementation complete", "Tests pass"] },
|
||||
depends_on: []
|
||||
}
|
||||
Write(`${planDir}/.task/TASK-001.json`, JSON.stringify(taskDetail, null, 2))
|
||||
|
||||
} else {
|
||||
// Use cli-lite-planning-agent for Medium/High
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: "Generate detailed implementation plan",
|
||||
prompt: `Generate implementation plan.
|
||||
Output: ${planDir}/plan.json + ${planDir}/.task/TASK-*.json
|
||||
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
|
||||
Task Description: ${task.description}
|
||||
Explorations: ${explorationManifest}
|
||||
Complexity: ${complexity}
|
||||
${specContext ? `Spec Context:
|
||||
- Requirements: ${specContext.reqIndex.substring(0, 500)}
|
||||
- Architecture: ${specContext.archIndex.substring(0, 500)}
|
||||
- Epics: ${specContext.epicsIndex.substring(0, 500)}
|
||||
Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.` : ''}
|
||||
Requirements: 2-7 tasks, each with id, title, files[].change, convergence.criteria, depends_on`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Submit for Approval
|
||||
|
||||
```javascript
|
||||
const plan = JSON.parse(Read(`${planDir}/plan.json`))
|
||||
const planTasks = plan.task_ids.map(id => JSON.parse(Read(`${planDir}/.task/${id}.json`)))
|
||||
const taskCount = plan.task_count || plan.task_ids.length
|
||||
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", team: teamName,
|
||||
from: "planner", to: "coordinator",
|
||||
type: "plan_ready",
|
||||
summary: `[planner] Plan就绪: ${taskCount}个task, ${complexity}复杂度`,
|
||||
ref: `${planDir}/plan.json`
|
||||
})
|
||||
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "coordinator",
|
||||
content: `[planner] ## Plan Ready for Review
|
||||
|
||||
**Task**: ${task.subject}
|
||||
**Complexity**: ${complexity}
|
||||
**Tasks**: ${taskCount}
|
||||
|
||||
### Task Summary
|
||||
${planTasks.map((t, i) => (i+1) + '. ' + t.title).join('\n')}
|
||||
|
||||
### Approach
|
||||
${plan.approach}
|
||||
|
||||
### Plan Location
|
||||
${planDir}/plan.json
|
||||
Task Files: ${planDir}/.task/
|
||||
|
||||
Please review and approve or request revisions.`,
|
||||
summary: `[planner] Plan ready: ${taskCount} tasks`
|
||||
})
|
||||
|
||||
// Wait for coordinator response (approve → mark completed, revision → update and resubmit)
|
||||
```
|
||||
|
||||
### Phase 5: After Approval
|
||||
|
||||
```javascript
|
||||
TaskUpdate({ taskId: task.id, status: 'completed' })
|
||||
|
||||
// Check for next PLAN task → back to Phase 1
|
||||
```
|
||||
|
||||
## Session Files
|
||||
|
||||
```
|
||||
{sessionFolder}/plan/
|
||||
├── exploration-{angle}.json
|
||||
├── explorations-manifest.json
|
||||
├── planning-context.md
|
||||
├── plan.json
|
||||
└── .task/
|
||||
└── TASK-*.json
|
||||
```
|
||||
|
||||
> **Note**: `sessionFolder` is extracted from task description (`Session: .workflow/.team/TLS-xxx`). Plan outputs go to `plan/` subdirectory. In full-lifecycle mode, spec products are available at `../spec/`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No PLAN-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Exploration agent failure | Skip exploration, plan from task description only |
|
||||
| Planning agent failure | Fallback to direct Claude planning |
|
||||
| Plan rejected 3+ times | Notify coordinator with `[planner]` tag, suggest alternative approach |
|
||||
| Schema file not found | Use basic plan structure without schema validation, log error with `[planner]` tag |
|
||||
| Spec context load failure | Continue in impl-only mode (no spec context) |
|
||||
| Session folder not found | Notify coordinator with `[planner]` tag, request session path |
|
||||
| Unexpected error | Log error via team_msg with `[planner]` tag, report to coordinator |
|
||||
Reference in New Issue
Block a user