feat: Add templates for epics, product brief, and requirements PRD

- Introduced a comprehensive template for generating epics and stories, including an index and individual epic files. - Created a product brief template to outline product vision, problem statements, and target users. - Developed a requirements PRD template to structure functional and non-functional requirements, including traceability and prioritization. - Implemented ast-grep processors for JavaScript and TypeScript to extract relationships such as imports and inheritance. - Added corresponding patterns for JavaScript and TypeScript to support relationship extraction. - Established comparison tests to validate the accuracy of relationship extraction between tree-sitter and ast-grep methods.
2026-02-28 09:23:08 +08:00 · 2026-02-18 12:02:02 +08:00
parent 9ebcc43055
commit f0dda075f0
37 changed files with 10324 additions and 30 deletions
--- a/.claude/skills/team-lifecycle-v2/roles/planner/role.md
+++ b/.claude/skills/team-lifecycle-v2/roles/planner/role.md
@@ -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 |