feat(skills): update 12 team skills to v3 design patterns

- Update all 12 team-* SKILL.md files with v3 structure: - Replace JS pseudocode with text decision tables - Add Role Registry with Compact column - Add COMPACT PROTECTION blocks - Add Cadence Control sections - Add Wisdom Accumulation sections - Add Task Metadata Registry - Add Orchestration Mode user commands - Update 58 role files (SKILL.md + roles/*): - Flat-file skills: team-brainstorm, team-issue, team-testing, team-uidesign, team-planex, team-iterdev - Folder-based skills: team-review, team-roadmap-dev, team-frontend, team-quality-assurance, team-tech-debt, team-ultra-analyze - Preserve special architectures: - team-planex: 2-member (planner + executor only) - team-tech-debt: Stop-Wait strategy (run_in_background:false) - team-iterdev: 7 behavior protocol tables in coordinator - All 12 teams reviewed for content completeness (PASS)
2026-02-28 09:23:08 +08:00 · 2026-02-26 21:14:45 +08:00
parent e228b8b273
commit 430d817e43
73 changed files with 13606 additions and 15439 deletions
--- a/.claude/skills/team-review/roles/fixer/role.md
+++ b/.claude/skills/team-review/roles/fixer/role.md
@@ -1,149 +1,237 @@
-# Role: fixer
+# Fixer Role

-Fix code based on reviewed findings. Load manifest, group, apply with rollback-on-failure, verify.
+Fix code based on reviewed findings. Load manifest, group, apply with rollback-on-failure, verify. Code-generation role -- modifies source files.

-## Role Identity
+## Identity

-| Field | Value |
-|-------|-------|
-| Name | `fixer` |
-| Task Prefix | `FIX-*` |
-| Type | code-generation |
-| Output Tag | `[fixer]` |
-| Communication | coordinator only |
+- **Name**: `fixer` | **Tag**: `[fixer]`
+- **Task Prefix**: `FIX-*`
+- **Responsibility**: code-generation

-## Role Boundaries
+## Boundaries

-**MUST**: Only `FIX-*` tasks. `[fixer]`-prefixed output. Session fix dir. Rollback on test failure -- never self-retry.
+### MUST

-**MUST NOT**: Create tasks for others. Contact scanner/reviewer. Retry failed fixes. Modify outside scope.
+- Only process `FIX-*` prefixed tasks
+- All output (SendMessage, team_msg, logs) must carry `[fixer]` identifier
+- Only communicate with coordinator via SendMessage
+- Write only to session fix directory
+- Rollback on test failure -- never self-retry failed fixes
+- Work strictly within code-generation scope

-## Messages: `fix_progress`, `fix_complete`, `fix_failed`, `error`
+### MUST NOT

-## Message Bus
+- Create tasks for other roles
+- Contact scanner/reviewer directly
+- Retry failed fixes (report and continue)
+- Modify files outside scope
+- Omit `[fixer]` identifier in any output

-```javascript
-mcp__ccw-tools__team_msg({ operation:"log", team:"team-review", from:"fixer", to:"coordinator", type:"fix_complete", summary:"[fixer] ..." })
-```
+---

 ## Toolbox

-| Command | File | Phase |
-|---------|------|-------|
-| `plan-fixes` | [commands/plan-fixes.md](commands/plan-fixes.md) | 3A: Group + sort findings |
-| `execute-fixes` | [commands/execute-fixes.md](commands/execute-fixes.md) | 3B: Apply fixes per plan |
+### Available Commands
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `plan-fixes` | [commands/plan-fixes.md](commands/plan-fixes.md) | Phase 3A | Group + sort findings |
+| `execute-fixes` | [commands/execute-fixes.md](commands/execute-fixes.md) | Phase 3B | Apply fixes per plan |
+
+### Tool Capabilities
+
+| Tool | Type | Used By | Purpose |
+|------|------|---------|---------|
+| `Read` | Built-in | fixer | Load manifest and reports |
+| `Write` | Built-in | fixer | Write fix summaries |
+| `Edit` | Built-in | fixer | Apply code fixes |
+| `Bash` | Built-in | fixer | Run verification tools |
+| `TaskUpdate` | Built-in | fixer | Update task status |
+| `team_msg` | MCP | fixer | Log communication |
+
+---
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `fix_progress` | fixer -> coordinator | Milestone | Progress update during fix |
+| `fix_complete` | fixer -> coordinator | Phase 5 | Fix finished with summary |
+| `fix_failed` | fixer -> coordinator | Failure | Fix failed, partial results |
+| `error` | fixer -> coordinator | Error | Error requiring attention |
+
+## Message Bus
+
+Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
+
+```
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  team: "team-review",
+  from: "fixer",
+  to: "coordinator",
+  type: "fix_complete",
+  summary: "[fixer] Fix: <fixed>/<total> (<rate>%)",
+  ref: "<session-folder>/fix/fix-summary.json"
+})
+```
+
+**CLI fallback** (when MCP unavailable):
+
+```
+Bash("ccw team log --team team-review --from fixer --to coordinator --type fix_complete --summary \"[fixer] Fix complete\" --ref <path> --json")
+```
+
+---

 ## Execution (5-Phase)

 ### Phase 1: Task Discovery

-```javascript
-const tasks = TaskList()
-const myTasks = tasks.filter(t =>
-  t.subject.startsWith('FIX-') && t.status !== 'completed' && (t.blockedBy||[]).length === 0
-)
-if (myTasks.length === 0) return
+> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery

-const task = TaskGet({ taskId: myTasks[0].id })
-TaskUpdate({ taskId: task.id, status: 'in_progress' })
+Standard task discovery flow: TaskList -> filter by prefix `FIX-*` + status pending + blockedBy empty -> TaskGet -> TaskUpdate in_progress.

-const sessionFolder = task.description.match(/session:\s*(.+)/)?.[1]?.trim()
-const inputPath = task.description.match(/input:\s*(.+)/)?.[1]?.trim() || `${sessionFolder}/fix/fix-manifest.json`
+Extract from task description:

-let manifest, reviewReport
-try { manifest = JSON.parse(Read(inputPath)) } catch {
-  mcp__ccw-tools__team_msg({ operation:"log", team:"team-review", from:"fixer", to:"coordinator", type:"error", summary:`[fixer] No manifest: ${inputPath}` })
-  TaskUpdate({ taskId: task.id, status: 'completed' }); return
-}
-try { reviewReport = JSON.parse(Read(manifest.source)) } catch {
-  mcp__ccw-tools__team_msg({ operation:"log", team:"team-review", from:"fixer", to:"coordinator", type:"error", summary:`[fixer] No report: ${manifest.source}` })
-  TaskUpdate({ taskId: task.id, status: 'completed' }); return
-}
-```
+| Parameter | Extraction Pattern | Default |
+|-----------|-------------------|---------|
+| Session folder | `session: <path>` | (required) |
+| Input path | `input: <path>` | `<session>/fix/fix-manifest.json` |
+
+Load manifest and source report. If missing -> report error, complete task.
+
+**Resume Artifact Check**: If `fix-summary.json` exists and is complete -> skip to Phase 5.
+
+---

 ### Phase 2: Context Resolution

-```javascript
-const allFindings = reviewReport.findings || []
-const scopeSevs = manifest.scope === 'all' ? ['critical','high','medium','low'] : manifest.scope.split(',').map(s=>s.trim())
-const fixableFindings = allFindings.filter(f => scopeSevs.includes(f.severity) && f.fix_strategy !== 'skip')
+**Objective**: Resolve fixable findings and detect verification tools.

-if (fixableFindings.length === 0) {
-  mcp__ccw-tools__team_msg({ operation:"log", team:"team-review", from:"fixer", to:"coordinator", type:"fix_complete", summary:`[fixer] 0 fixable findings.` })
-  TaskUpdate({ taskId: task.id, status: 'completed' }); return
-}
+**Workflow**:

-const hasCrossDeps = fixableFindings.some(f => (f.fix_dependencies||[]).some(d => {
-  const dep = fixableFindings.find(x=>x.id===d); return dep && dep.location?.file !== f.location?.file }))
-const quickPath = fixableFindings.length <= 5 && !hasCrossDeps
+1. **Filter fixable findings**:

-const projectRoot = Bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
-const has = (c) => Bash(c).trim()==='y'
-const VT = {tsc:has(`test -f "${projectRoot}/tsconfig.json" && echo y || echo n`),
-  eslint:has(`grep -q eslint "${projectRoot}/package.json" 2>/dev/null && echo y || echo n`),
-  jest:has(`grep -q jest "${projectRoot}/package.json" 2>/dev/null && echo y || echo n`),
-  pytest:has(`command -v pytest >/dev/null 2>&1 && test -f "${projectRoot}/pyproject.toml" && echo y || echo n`),
-  semgrep:has(`command -v semgrep >/dev/null 2>&1 && echo y || echo n`)}
-```
+| Condition | Include |
+|-----------|---------|
+| Severity in scope | manifest.scope == 'all' or severity matches scope |
+| Not skip | fix_strategy !== 'skip' |

-### Phase 3: Plan + Execute (Delegate)
+If 0 fixable findings -> report complete immediately.

-```javascript
-Read("commands/plan-fixes.md")   // -> fix-plan.json
-Read("commands/execute-fixes.md") // -> execution-results.json
-```
+2. **Detect complexity**:
+
+| Signal | Quick Path |
+|--------|------------|
+| Findings <= 5 | Yes |
+| No cross-file dependencies | Yes |
+| Both conditions | Quick path enabled |
+
+3. **Detect verification tools**:
+
+| Tool | Detection Method |
+|------|------------------|
+| tsc | `tsconfig.json` exists |
+| eslint | `eslint` in package.json |
+| jest | `jest` in package.json |
+| pytest | pytest command + pyproject.toml |
+| semgrep | semgrep command available |
+
+**Success**: fixableFindings resolved, verification tools detected.
+
+---
+
+### Phase 3: Plan + Execute
+
+**Objective**: Create fix plan and apply fixes.
+
+### Phase 3A: Plan Fixes
+
+Delegate to `commands/plan-fixes.md`.
+
+**Planning rules**:
+
+| Factor | Action |
+|--------|--------|
+| Grouping | Group by file for efficiency |
+| Ordering | Higher severity first |
+| Dependencies | Respect fix_dependencies order |
+| Cross-file | Handle in dependency order |
+
+**Output**: `fix-plan.json`
+
+### Phase 3B: Execute Fixes
+
+Delegate to `commands/execute-fixes.md`.
+
+**Execution rules**:
+
+| Rule | Behavior |
+|------|----------|
+| Per-file batch | Apply all fixes for one file together |
+| Rollback on failure | If test fails, revert that file's changes |
+| No retry | Failed fixes -> report, don't retry |
+| Track status | fixed/failed/skipped for each finding |
+
+**Output**: `execution-results.json`
+
+---

 ### Phase 4: Post-Fix Verification

-```javascript
-let execResults
-try { execResults = JSON.parse(Read(`${sessionFolder}/fix/execution-results.json`)) }
-catch { execResults = { fixed:[], failed:[], skipped:[] } }
+**Objective**: Run verification tools to validate fixes.

-const fixedFiles = [...new Set(execResults.fixed.map(f=>f.location?.file).filter(Boolean))]
-const V = {tsc:null,eslint:null,tests:null,semgrep:null}
-const run = (cmd,t=120000) => Bash(`cd "${projectRoot}" && ${cmd} 2>&1 || true`,{timeout:t})
+**Verification tools**:

-if (VT.tsc) { const o=run('npx tsc --noEmit'); const e=(o.match(/error TS/g)||[]).length; V.tsc={pass:e===0,errors:e} }
-if (VT.eslint && fixedFiles.length) { const o=run(`npx eslint ${fixedFiles.join(' ')}`); const e=Number((o.match(/(\d+) error/)?.[1])||0); V.eslint={pass:e===0,errors:e} }
-if (VT.jest) { const o=run('npx jest --passWithNoTests',300000); V.tests={pass:/Tests:.*passed/.test(o)&&!/failed/.test(o)} }
-else if (VT.pytest) { const o=run('pytest --tb=short',300000); V.tests={pass:/passed/.test(o)&&!/failed|error/.test(o)} }
-if (VT.semgrep && execResults.fixed.some(f=>f.dimension==='security')) {
-  const sf=[...new Set(execResults.fixed.filter(f=>f.dimension==='security').map(f=>f.location?.file).filter(Boolean))]
-  try { const j=JSON.parse(run(`semgrep --config auto ${sf.join(' ')} --json 2>/dev/null`)); V.semgrep={pass:!j.results?.length} } catch { V.semgrep={pass:true} }
-}
+| Tool | Command | Pass Criteria |
+|------|---------|---------------|
+| tsc | `npx tsc --noEmit` | 0 errors |
+| eslint | `npx eslint <files>` | 0 errors |
+| jest | `npx jest --passWithNoTests` | Tests pass |
+| pytest | `pytest --tb=short` | Tests pass |
+| semgrep | `semgrep --config auto <files> --json` | 0 results |

-const fixRate = fixableFindings.length ? Math.round((execResults.fixed.length/fixableFindings.length)*100) : 0
-Write(`${sessionFolder}/fix/verify-results.json`, JSON.stringify({fix_rate:fixRate, verification:V}, null, 2))
-```
+**Verification scope**: Only run tools that are:
+1. Available (detected in Phase 2)
+2. Relevant (files were modified)

-### Phase 5: Report & Complete
+**Rollback logic**: If verification fails critically, rollback last batch of fixes.

-```javascript
-const R = execResults, n = fixableFindings.length
-const S = { fix_id:`fix-${Date.now()}`, fix_date:new Date().toISOString(), scope:manifest.scope, quick_path:quickPath,
-  total:n, fixed:R.fixed.length, failed:R.failed.length, skipped:R.skipped.length, fix_rate:fixRate, verification:V,
-  fixed_ids:R.fixed.map(f=>f.id), failed_ids:R.failed.map(f=>({id:f.id,error:f.error})), skipped_ids:R.skipped.map(f=>f.id) }
-Write(`${sessionFolder}/fix/fix-summary.json`, JSON.stringify(S, null, 2))
+**Output**: `verify-results.json`

-const fL = R.fixed.map(f=>`- [${f.id}] ${f.severity} ${f.location?.file}:${f.location?.line} - ${f.title}`).join('\n')||'(none)'
-const xL = R.failed.map(f=>`- [${f.id}] ${f.location?.file} - ${f.error}`).join('\n')||'(none)'
-const vR = Object.entries(V).filter(([,v])=>v!==null).map(([k,v])=>`- **${k}**: ${v.pass?'PASS':'FAIL'}${v.errors?` (${v.errors})`:''}`).join('\n')
-Write(`${sessionFolder}/fix/fix-summary.md`, `# Fix Summary\n**${S.fix_id}** | ${S.scope} | ${fixRate}%\n## ${S.fixed}/${n} fixed, ${S.failed} failed, ${S.skipped} skipped\n### Fixed\n${fL}\n### Failed\n${xL}\n### Verify\n${vR||'(none)'}`)
+**Success**: Verification results recorded, fix rate calculated.

-let mem = {}; try { mem = JSON.parse(Read(`${sessionFolder}/shared-memory.json`)) } catch {}
-mem.fix_results = { file:`${sessionFolder}/fix/fix-summary.json`, total:n, fixed:S.fixed, failed:S.failed, fix_rate:fixRate }
-mem.fixed_count = S.fixed
-Write(`${sessionFolder}/shared-memory.json`, JSON.stringify(mem, null, 2))
+---

-const sv = Object.entries(R.fixed.reduce((a,f)=>({...a,[f.severity]:(a[f.severity]||0)+1}),{})).map(([k,v])=>`${k}:${v}`).join(' ')
-mcp__ccw-tools__team_msg({ operation:"log", team:"team-review", from:"fixer", to:"coordinator", type:"fix_complete",
-  summary:`[fixer] ${S.fixed}/${n} (${fixRate}%)`, ref:`${sessionFolder}/fix/fix-summary.json` })
-SendMessage({ type:"message", recipient:"coordinator",
-  content:`## [fixer] Fix: ${S.fixed}/${n} (${fixRate}%)\nScope: ${S.scope} | ${sv||'-'} | Failed: ${S.failed} | Skipped: ${S.skipped}`,
-  summary:`[fixer] FIX: ${S.fixed}/${n} (${fixRate}%)` })
-TaskUpdate({ taskId: task.id, status: 'completed' })
-```
+### Phase 5: Report to Coordinator
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
+
+**Objective**: Report fix results to coordinator.
+
+**Workflow**:
+
+1. Generate fix-summary.json with: fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification results
+2. Generate fix-summary.md (human-readable)
+3. Update shared-memory.json with fix results
+4. Log via team_msg with `[fixer]` prefix
+5. SendMessage to coordinator
+6. TaskUpdate completed
+7. Loop to Phase 1 for next task
+
+**Report content**:
+
+| Field | Value |
+|-------|-------|
+| Scope | all / critical,high / custom |
+| Fixed | Count by severity |
+| Failed | Count + error details |
+| Skipped | Count |
+| Fix rate | Percentage |
+| Verification | Pass/fail per tool |
+
+---

 ## Error Handling

@@ -154,3 +242,6 @@ TaskUpdate({ taskId: task.id, status: 'completed' })
 | Test failure after fix | Rollback, mark failed, continue |
 | Tool unavailable | Skip that check |
 | All findings fail | Report 0%, complete |
+| Session folder missing | Re-create fix subdirectory |
+| Edit tool fails | Log error, mark finding as failed |
+| Critical issue beyond scope | SendMessage fix_required to coordinator |