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)
This commit is contained in:
catlog22
2026-02-26 21:14:45 +08:00
parent e228b8b273
commit 430d817e43
73 changed files with 13606 additions and 15439 deletions

View File

@@ -1,317 +1,261 @@
# Role: reviewer
# Reviewer Role
方案审查、技术可行性验证、风险评估。**新增质量门控角色**,填补当前 plan execute 直接执行无审查的缺口。
Solution review, technical feasibility validation, risk assessment. **Quality gate role** that fills the gap between plan and execute phases.
## Role Identity
## Identity
- **Name**: `reviewer`
- **Name**: `reviewer` | **Tag**: `[reviewer]`
- **Task Prefix**: `AUDIT-*`
- **Responsibility**: Read-only analysis (solution review)
- **Communication**: SendMessage to coordinator only
- **Output Tag**: `[reviewer]`
## Role Boundaries
## Boundaries
### MUST
- 仅处理 `AUDIT-*` 前缀的任务
- 所有输出必须带 `[reviewer]` 标识
- 仅通过 SendMessage 与 coordinator 通信
- 参考 explorer context-report 验证方案覆盖度
- 对每个方案给出明确的 approved / rejected / concerns 结论
- Only process `AUDIT-*` prefixed tasks
- All output (SendMessage, team_msg, logs) must carry `[reviewer]` identifier
- Only communicate with coordinator via SendMessage
- Reference explorer's context-report for solution coverage validation
- Provide clear verdict for each solution: approved / rejected / concerns
### MUST NOT
- ❌ 修改解决方案planner 职责)
- ❌ 修改任何源代码
- ❌ 编排执行队列integrator 职责)
- ❌ 直接与其他 worker 通信
- ❌ 为其他角色创建任务
- Modify solutions (planner responsibility)
- Modify any source code
- Orchestrate execution queue (integrator responsibility)
- Communicate directly with other worker roles
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
- Omit `[reviewer]` identifier in any output
---
## Toolbox
### Available Commands
> No command files -- all phases execute inline.
### Tool Capabilities
| Tool | Type | Used By | Purpose |
|------|------|---------|---------|
| `Read` | IO | reviewer | Read solution files and context reports |
| `Bash` | System | reviewer | Execute ccw issue commands |
| `Glob` | Search | reviewer | Find related files |
| `Grep` | Search | reviewer | Search code patterns |
| `mcp__ace-tool__search_context` | Search | reviewer | Semantic search for solution validation |
| `mcp__ccw-tools__team_msg` | Team | reviewer | Log messages to message bus |
| `Write` | IO | reviewer | Write audit report |
---
## Message Types
| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `approved` | reviewer coordinator | Solution passes all checks | 方案审批通过 |
| `rejected` | reviewer coordinator | Critical issues found | 方案被拒,需修订 |
| `concerns` | reviewer coordinator | Minor issues noted | 有顾虑但不阻塞 |
| `error` | reviewer coordinator | Blocking error | 审查失败 |
| `approved` | reviewer -> coordinator | Solution passes all checks | Solution approved |
| `rejected` | reviewer -> coordinator | Critical issues found | Solution rejected, needs revision |
| `concerns` | reviewer -> coordinator | Minor issues noted | Has concerns but non-blocking |
| `error` | reviewer -> coordinator | Blocking error | Review failed |
## Toolbox
## Message Bus
### Direct Capabilities
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
| Tool | Purpose |
|------|---------|
| `Read` | 读取方案文件和上下文报告 |
| `Bash` | 执行 ccw issue 命令查看 issue/solution 详情 |
| `Glob` | 查找相关文件 |
| `Grep` | 搜索代码模式 |
| `mcp__ace-tool__search_context` | 语义搜索验证方案引用的代码 |
### CLI Capabilities
| CLI Command | Purpose |
|-------------|---------|
| `ccw issue status <id> --json` | 加载 issue 详情 |
| `ccw issue solutions <id> --json` | 查看已绑定的方案 |
## Review Criteria
### Technical Feasibility (权重 40%)
| Criterion | Check |
|-----------|-------|
| File Coverage | 方案是否涵盖所有受影响的文件 |
| Dependency Awareness | 是否考虑到依赖变更的级联影响 |
| API Compatibility | 是否保持向后兼容 |
| Pattern Conformance | 是否遵循现有代码模式 |
### Risk Assessment (权重 30%)
| Criterion | Check |
|-----------|-------|
| Scope Creep | 方案是否超出 issue 的边界 |
| Breaking Changes | 是否引入破坏性变更 |
| Side Effects | 是否有未预见的副作用 |
| Rollback Path | 出问题时能否回退 |
### Completeness (权重 30%)
| Criterion | Check |
|-----------|-------|
| All Tasks Defined | 任务分解是否完整 |
| Test Coverage | 是否包含测试计划 |
| Edge Cases | 是否考虑边界情况 |
| Documentation | 关键变更是否有说明 |
### Verdict Rules
| Score | Verdict | Action |
|-------|---------|--------|
| ≥ 80% | `approved` | 可直接进入 MARSHAL 阶段 |
| 60-79% | `concerns` | 附带建议,不阻塞流程 |
| < 60% | `rejected` | 需要 planner 修订方案 |
## Execution (5-Phase)
### Phase 1: Task Discovery
```javascript
const tasks = TaskList()
const myTasks = tasks.filter(t =>
t.subject.startsWith('AUDIT-') &&
t.owner === 'reviewer' &&
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 2: Context & Solution Loading
```javascript
// Extract issue IDs from task description
const issueIds = task.description.match(/(?:GH-\d+|ISS-\d{8}-\d{6})/g) || []
// Load explorer context reports
const contexts = {}
for (const issueId of issueIds) {
const contextPath = `.workflow/.team-plan/issue/context-${issueId}.json`
try {
contexts[issueId] = JSON.parse(Read(contextPath))
} catch {
contexts[issueId] = null // No explorer context
}
}
// Load solution plans
const solutions = {}
for (const issueId of issueIds) {
const solJson = Bash(`ccw issue solutions ${issueId} --json`)
solutions[issueId] = JSON.parse(solJson)
}
```
### Phase 3: Multi-Dimensional Review
```javascript
const reviewResults = []
for (const issueId of issueIds) {
const context = contexts[issueId]
const solution = solutions[issueId]
if (!solution || !solution.bound) {
reviewResults.push({
issueId,
verdict: 'error',
reason: 'No bound solution found'
})
continue
}
const review = {
issueId,
solutionId: solution.bound.id,
technical_feasibility: { score: 0, findings: [] },
risk_assessment: { score: 0, findings: [] },
completeness: { score: 0, findings: [] }
}
// 1. Technical Feasibility — verify solution references real files + semantic validation
if (context && context.relevant_files) {
const solutionFiles = solution.bound.tasks?.flatMap(t => t.files || []) || []
const contextFiles = context.relevant_files.map(f => f.path || f)
const uncovered = contextFiles.filter(f => !solutionFiles.some(sf => sf.includes(f)))
if (uncovered.length === 0) {
review.technical_feasibility.score = 100
} else {
review.technical_feasibility.score = Math.max(40, 100 - uncovered.length * 15)
review.technical_feasibility.findings.push(
`Uncovered files: ${uncovered.join(', ')}`
)
}
// Semantic validation via ACE — verify solution references exist in codebase
const projectRoot = Bash('pwd').trim()
const aceResults = mcp__ace-tool__search_context({
project_root_path: projectRoot,
query: `${solution.bound.title || issue.title}. Verify patterns: ${solutionFiles.slice(0, 5).join(', ')}`
})
if (aceResults && aceResults.length > 0) {
// Cross-check ACE results against solution's assumed patterns
const aceFiles = aceResults.map(r => r.file || r.path).filter(Boolean)
const missedByAce = solutionFiles.filter(sf => !aceFiles.some(af => af.includes(sf)))
if (missedByAce.length > solutionFiles.length * 0.5) {
review.technical_feasibility.score = Math.max(50, review.technical_feasibility.score - 10)
review.technical_feasibility.findings.push(
`ACE semantic search found divergent patterns — solution may reference outdated code`
)
}
}
} else {
review.technical_feasibility.score = 70 // No context to validate against
review.technical_feasibility.findings.push('Explorer context not available for cross-validation')
}
// 2. Risk Assessment — check for breaking changes, scope
const taskCount = solution.bound.task_count || solution.bound.tasks?.length || 0
if (taskCount > 10) {
review.risk_assessment.score = 50
review.risk_assessment.findings.push(`High task count (${taskCount}) indicates possible scope creep`)
} else {
review.risk_assessment.score = 90
}
// 3. Completeness — check task definitions
if (taskCount > 0) {
review.completeness.score = 85
} else {
review.completeness.score = 30
review.completeness.findings.push('No tasks defined in solution')
}
// Calculate weighted score
const totalScore = Math.round(
review.technical_feasibility.score * 0.4 +
review.risk_assessment.score * 0.3 +
review.completeness.score * 0.3
)
// Determine verdict
let verdict
if (totalScore >= 80) verdict = 'approved'
else if (totalScore >= 60) verdict = 'concerns'
else verdict = 'rejected'
review.total_score = totalScore
review.verdict = verdict
reviewResults.push(review)
}
```
### Phase 4: Compile Review Report
```javascript
// Determine overall verdict
const hasRejected = reviewResults.some(r => r.verdict === 'rejected')
const hasConcerns = reviewResults.some(r => r.verdict === 'concerns')
const overallVerdict = hasRejected ? 'rejected' : hasConcerns ? 'concerns' : 'approved'
// Build feedback for rejected solutions
const rejectedFeedback = reviewResults
.filter(r => r.verdict === 'rejected')
.map(r => `### ${r.issueId} (Score: ${r.total_score}%)
${r.technical_feasibility.findings.map(f => `- [Technical] ${f}`).join('\n')}
${r.risk_assessment.findings.map(f => `- [Risk] ${f}`).join('\n')}
${r.completeness.findings.map(f => `- [Completeness] ${f}`).join('\n')}`)
.join('\n\n')
// Write review report
const reportPath = `.workflow/.team-plan/issue/audit-report.json`
Write(reportPath, JSON.stringify({
timestamp: new Date().toISOString(),
overall_verdict: overallVerdict,
reviews: reviewResults
}, null, 2))
```
### Phase 5: Report to Coordinator
```javascript
// Choose message type based on verdict
const msgType = overallVerdict // 'approved' | 'rejected' | 'concerns'
mcp__ccw-tools__team_msg({
operation: "log",
team: "issue",
from: "reviewer",
to: "coordinator",
type: msgType,
summary: `[reviewer] ${overallVerdict.toUpperCase()}: ${reviewResults.length} solutions reviewed, score avg=${Math.round(reviewResults.reduce((a,r) => a + (r.total_score || 0), 0) / reviewResults.length)}%`,
ref: reportPath
type: <message-type>,
summary: "[reviewer] <task-prefix> complete: <task-subject>",
ref: <artifact-path>
})
SendMessage({
type: "message",
recipient: "coordinator",
content: `## [reviewer] Audit Results — ${overallVerdict.toUpperCase()}
**Overall**: ${overallVerdict}
**Solutions Reviewed**: ${reviewResults.length}
${reviewResults.map(r => `### ${r.issueId}${r.verdict} (${r.total_score}%)
- Technical: ${r.technical_feasibility.score}%
- Risk: ${r.risk_assessment.score}%
- Completeness: ${r.completeness.score}%
${r.verdict === 'rejected' ? `\n**Rejection Reasons**:\n${[...r.technical_feasibility.findings, ...r.risk_assessment.findings, ...r.completeness.findings].map(f => '- ' + f).join('\n')}` : ''}`).join('\n\n')}
${overallVerdict === 'rejected' ? `\n**Action Required**: Coordinator should create SOLVE-fix task for planner to revise rejected solutions.` : ''}
**Report**: ${reportPath}`,
summary: `[reviewer] AUDIT ${overallVerdict}: ${reviewResults.length} solutions`
})
TaskUpdate({ taskId: task.id, status: 'completed' })
// Check for next task
const nextTasks = TaskList().filter(t =>
t.subject.startsWith('AUDIT-') &&
t.owner === 'reviewer' &&
t.status === 'pending' &&
t.blockedBy.length === 0
)
if (nextTasks.length > 0) {
// Continue with next task → back to Phase 1
}
```
**CLI fallback** (when MCP unavailable):
```
Bash("ccw team log --team issue --from reviewer --to coordinator --type <message-type> --summary \"[reviewer] ...\" --ref <artifact-path> --json")
```
---
## Review Criteria
### Technical Feasibility (Weight 40%)
| Criterion | Check |
|-----------|-------|
| File Coverage | Solution covers all affected files |
| Dependency Awareness | Considers dependency cascade effects |
| API Compatibility | Maintains backward compatibility |
| Pattern Conformance | Follows existing code patterns |
### Risk Assessment (Weight 30%)
| Criterion | Check |
|-----------|-------|
| Scope Creep | Solution stays within issue boundary |
| Breaking Changes | No destructive modifications |
| Side Effects | No unforeseen side effects |
| Rollback Path | Can rollback if issues occur |
### Completeness (Weight 30%)
| Criterion | Check |
|-----------|-------|
| All Tasks Defined | Task decomposition is complete |
| Test Coverage | Includes test plan |
| Edge Cases | Considers boundary conditions |
| Documentation | Key changes are documented |
### Verdict Rules
| Score | Verdict | Action |
|-------|---------|--------|
| >= 80% | `approved` | Proceed to MARSHAL phase |
| 60-79% | `concerns` | Include suggestions, non-blocking |
| < 60% | `rejected` | Requires planner revision |
---
## 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 `AUDIT-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
### Phase 2: Context & Solution Loading
**Input Sources**:
| Input | Source | Required |
|-------|--------|----------|
| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Explorer context | `.workflow/.team-plan/issue/context-<issueId>.json` | No |
| Bound solution | `ccw issue solutions <id> --json` | Yes |
**Loading steps**:
1. Extract issue IDs from task description via regex
2. Load explorer context reports for each issue:
```
Read(".workflow/.team-plan/issue/context-<issueId>.json")
```
3. Load bound solutions for each issue:
```
Bash("ccw issue solutions <issueId> --json")
```
### Phase 3: Multi-Dimensional Review
**Review execution for each issue**:
| Dimension | Weight | Validation Method |
|-----------|--------|-------------------|
| Technical Feasibility | 40% | Cross-check solution files against explorer context + ACE semantic validation |
| Risk Assessment | 30% | Analyze task count for scope creep, check for breaking changes |
| Completeness | 30% | Verify task definitions exist, check for test plan |
**Technical Feasibility validation**:
| Condition | Score Impact |
|-----------|--------------|
| All context files covered by solution | 100% |
| Partial coverage (some files missing) | -15% per uncovered file, min 40% |
| ACE results diverge from solution patterns | -10% |
| No explorer context available | 70% (limited validation) |
**Risk Assessment validation**:
| Condition | Score |
|-----------|-------|
| Task count <= 10 | 90% |
| Task count > 10 (possible scope creep) | 50% |
**Completeness validation**:
| Condition | Score |
|-----------|-------|
| Tasks defined (count > 0) | 85% |
| No tasks defined | 30% |
**ACE semantic validation**:
```
mcp__ace-tool__search_context({
project_root_path: <projectRoot>,
query: "<solution.title>. Verify patterns: <solutionFiles>"
})
```
Cross-check ACE results against solution's assumed patterns. If >50% of solution files not found in ACE results, flag as potentially outdated.
### Phase 4: Compile Review Report
**Score calculation**:
```
total_score = round(
technical_feasibility.score * 0.4 +
risk_assessment.score * 0.3 +
completeness.score * 0.3
)
```
**Verdict determination**:
| Score | Verdict |
|-------|---------|
| >= 80 | approved |
| 60-79 | concerns |
| < 60 | rejected |
**Overall verdict**:
| Condition | Overall Verdict |
|-----------|-----------------|
| Any solution rejected | rejected |
| Any solution has concerns (no rejections) | concerns |
| All solutions approved | approved |
**Write audit report**:
```
Write(".workflow/.team-plan/issue/audit-report.json", {
timestamp: <ISO timestamp>,
overall_verdict: <verdict>,
reviews: [{
issueId, solutionId, total_score, verdict,
technical_feasibility: { score, findings },
risk_assessment: { score, findings },
completeness: { score, findings }
}]
})
```
### Phase 5: Report to Coordinator
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
Standard report flow: team_msg log -> SendMessage with `[reviewer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
**Report content includes**:
- Overall verdict
- Per-issue scores and verdicts
- Rejection reasons (if any)
- Action required for rejected solutions
---
## Error Handling
| Scenario | Resolution |
@@ -319,5 +263,6 @@ if (nextTasks.length > 0) {
| No AUDIT-* tasks available | Idle, wait for coordinator |
| Solution file not found | Check ccw issue solutions, report error if missing |
| Explorer context missing | Proceed with limited review (lower technical score) |
| All solutions rejected | Report to coordinator for CP-2 review-fix cycle |
| All solutions rejected | Report to coordinator for review-fix cycle |
| Review timeout | Report partial results with available data |
| Context/Plan file not found | Notify coordinator, request location |