claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/code-review.md

@@ -0,0 +1,163 @@
+# Command: code-review
+
+## Purpose
+
+4-dimension code review analyzing quality, security, architecture, and requirements compliance. Produces a verdict (BLOCK/CONDITIONAL/APPROVE) with categorized findings.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Plan file | `<session_folder>/plan/plan.json` | Yes |
+| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes |
+| Modified files | From git diff --name-only | Yes |
+| Test results | Tester output (if available) | No |
+| Wisdom | `<session_folder>/wisdom/` | No |
+
+## Phase 3: 4-Dimension Review
+
+### Dimension Overview
+
+| Dimension | Focus | Weight |
+|-----------|-------|--------|
+| Quality | Code correctness, type safety, clean code | Equal |
+| Security | Vulnerability patterns, secret exposure | Equal |
+| Architecture | Module structure, coupling, file size | Equal |
+| Requirements | Acceptance criteria coverage, completeness | Equal |
+
+---
+
+### Dimension 1: Quality
+
+Scan each modified file for quality anti-patterns.
+
+| Severity | Pattern | What to Detect |
+|----------|---------|----------------|
+| Critical | Empty catch blocks | `catch(e) {}` with no handling |
+| High | @ts-ignore without justification | Suppression comment < 10 chars explanation |
+| High | `any` type in public APIs | `any` outside comments and generic definitions |
+| High | console.log in production | `console.(log\|debug\|info)` outside test files |
+| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment |
+| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times |
+
+**Detection example** (Grep for console statements):
+
+```bash
+Grep(pattern="console\\.(log|debug|info)", path="<file_path>", output_mode="content", "-n"=true)
+```
+
+---
+
+### Dimension 2: Security
+
+Scan for vulnerability patterns across all modified files.
+
+| Severity | Pattern | What to Detect |
+|----------|---------|----------------|
+| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) |
+| Critical | SQL injection | String concatenation in `query()`/`execute()` calls |
+| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` |
+| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` |
+| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) |
+| Low | Missing input validation | Functions with parameters but no validation in first 5 lines |
+
+---
+
+### Dimension 3: Architecture
+
+Assess structural health of modified files.
+
+| Severity | Pattern | What to Detect |
+|----------|---------|----------------|
+| Critical | Circular dependencies | File A imports B, B imports A |
+| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) |
+| Medium | Large files | Files exceeding 500 lines |
+| Medium | Tight coupling | >5 imports from same base module |
+| Medium | Long functions | Functions exceeding 50 lines |
+| Medium | Module boundary changes | Modifications to index.ts/index.js files |
+
+**Detection example** (check for deep parent imports):
+
+```bash
+Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="<file_path>", output_mode="content", "-n"=true)
+```
+
+---
+
+### Dimension 4: Requirements
+
+Verify implementation against plan acceptance criteria.
+
+| Severity | Check | Method |
+|----------|-------|--------|
+| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) |
+| High | Missing error handling | Plan mentions "error handling" but no try/catch in code |
+| Medium | Partially met criteria | Keyword overlap 40-69% |
+| Medium | Missing tests | Plan mentions "test" but no test files in modified set |
+
+**Verification flow**:
+1. Read plan file → extract acceptance criteria section
+2. For each criterion → extract keywords (4+ char meaningful words)
+3. Search modified files for keyword matches
+4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet
+
+---
+
+### Verdict Routing
+
+| Verdict | Criteria | Action |
+|---------|----------|--------|
+| BLOCK | Any critical-severity issues found | Must fix before merge |
+| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking |
+| APPROVE | Only low issues or none | Ready to merge |
+
+## Phase 4: Validation
+
+### Report Format
+
+The review report follows this structure:
+
+```
+# Code Review Report
+
+**Verdict**: <BLOCK|CONDITIONAL|APPROVE>
+
+## Blocking Issues (if BLOCK)
+- **<type>** (<file>:<line>): <message>
+
+## Review Dimensions
+
+### Quality Issues
+**CRITICAL** (<count>)
+- <message> (<file>:<line>)
+
+### Security Issues
+(same format per severity)
+
+### Architecture Issues
+(same format per severity)
+
+### Requirements Issues
+(same format per severity)
+
+## Recommendations
+1. <actionable recommendation>
+```
+
+### Summary Counts
+
+| Field | Description |
+|-------|-------------|
+| Total issues | Sum across all dimensions and severities |
+| Critical count | Must be 0 for APPROVE |
+| Blocking issues | Listed explicitly in report header |
+| Dimensions covered | Must be 4/4 |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Plan file not found | Skip requirements dimension, note in report |
+| Git diff empty | Report no changes to review |
+| File read fails | Skip file, note in report |
+| No modified files | Report empty review |

package/.claude/skills/team-lifecycle-v3/roles/reviewer/commands/spec-quality.md

@@ -0,0 +1,202 @@
+# Command: spec-quality
+
+## Purpose
+
+5-dimension spec quality check with weighted scoring, quality gate determination, and readiness report generation.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Spec documents | `<session_folder>/spec/` (all .md files) | Yes |
+| Original requirements | Product brief objectives section | Yes |
+| Quality gate config | specs/quality-gates.md | No |
+| Session folder | Task description `Session:` field | Yes |
+
+**Spec document phases** (matched by filename/directory):
+
+| Phase | Expected Path | Required |
+|-------|--------------|---------|
+| product-brief | spec/product-brief.md | Yes |
+| prd | spec/requirements/*.md | Yes |
+| architecture | spec/architecture/_index.md + ADR-*.md | Yes |
+| user-stories | spec/epics/*.md | Yes |
+| implementation-plan | plan/plan.json | No (impl-only/full-lifecycle) |
+| test-strategy | spec/test-strategy.md | No (optional, not generated by pipeline) |
+
+## Phase 3: 5-Dimension Scoring
+
+### Dimension Weights
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Completeness | 25% | All required sections present with substance |
+| Consistency | 20% | Terminology, format, references, naming |
+| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain |
+| Depth | 20% | AC testable, ADRs justified, stories estimable |
+| Coverage | 10% | Original requirements mapped to spec |
+
+---
+
+### Dimension 1: Completeness (25%)
+
+Check each spec document for required sections.
+
+**Required sections by phase**:
+
+| Phase | Required Sections |
+|-------|------------------|
+| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints |
+| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements |
+| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack |
+| user-stories | Story List, Acceptance Criteria, Priority, Estimation |
+| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation |
+
+> **Note**: `test-strategy` is optional — skip scoring if `spec/test-strategy.md` is absent. Do not penalize completeness score for missing optional phases.
+
+**Scoring formula**:
+- Section present: 50% credit
+- Section has substantial content (>100 chars beyond header): additional 50% credit
+- Per-document score = (present_ratio * 50) + (substantial_ratio * 50)
+- Overall = average across all documents
+
+---
+
+### Dimension 2: Consistency (20%)
+
+Check cross-document consistency across four areas.
+
+| Area | What to Check | Severity |
+|------|--------------|----------|
+| Terminology | Same concept with different casing/spelling across docs | Medium |
+| Format | Mixed header styles at same level across docs | Low |
+| References | Broken links (`./` or `../` paths that don't resolve) | High |
+| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low |
+
+**Scoring**:
+- Penalty weights: High = 10, Medium = 5, Low = 2
+- Score = max(0, 100 - (total_penalty / 100) * 100)
+
+---
+
+### Dimension 3: Traceability (25%)
+
+Build and validate traceability chains: Goals -> Requirements -> Components -> Stories.
+
+**Chain building flow**:
+1. Extract goals from product-brief (pattern: `- Goal: <text>`)
+2. Extract requirements from PRD (pattern: `- REQ-NNN: <text>`)
+3. Extract components from architecture (pattern: `- Component: <text>`)
+4. Extract stories from user-stories (pattern: `- US-NNN: <text>`)
+5. Link by keyword overlap (threshold: 30% keyword match)
+
+**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story.
+
+**Scoring**: (complete chains / total chains) * 100
+
+**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories).
+
+---
+
+### Dimension 4: Depth (20%)
+
+Assess the analytical depth of spec content across four sub-dimensions.
+
+| Sub-dimension | Source | Testable Criteria |
+|---------------|--------|-------------------|
+| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers |
+| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs |
+| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate |
+| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms |
+
+**Scoring**: Average of sub-dimension scores (each 0-100%)
+
+---
+
+### Dimension 5: Coverage (10%)
+
+Map original requirements to spec requirements.
+
+**Flow**:
+1. Extract original requirements from product-brief objectives section
+2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`)
+3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%)
+4. Score = (covered_count / total_original) * 100
+
+---
+
+### Quality Gate Decision Table
+
+| Gate | Criteria | Message |
+|------|----------|---------|
+| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation |
+| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required |
+| REVIEW | All other cases | Improvements needed, may proceed with caution |
+
+## Phase 4: Validation
+
+### Readiness Report Format
+
+Write to `<session_folder>/spec/readiness-report.md`:
+
+```
+# Specification Readiness Report
+
+**Generated**: <timestamp>
+**Overall Score**: <score>%
+**Quality Gate**: <PASS|REVIEW|FAIL> - <message>
+**Recommended Action**: <action>
+
+## Dimension Scores
+
+| Dimension | Score | Weight | Weighted Score |
+|-----------|-------|--------|----------------|
+| Completeness | <n>% | 25% | <n>% |
+| Consistency | <n>% | 20% | <n>% |
+| Traceability | <n>% | 25% | <n>% |
+| Depth | <n>% | 20% | <n>% |
+| Coverage | <n>% | 10% | <n>% |
+
+## Completeness Analysis
+(per-phase breakdown: sections present/expected, missing sections)
+
+## Consistency Analysis
+(issues by area: terminology, format, references, naming)
+
+## Traceability Analysis
+(complete chains / total, weak links)
+
+## Depth Analysis
+(per sub-dimension scores)
+
+## Requirement Coverage
+(covered / total, uncovered requirements list)
+```
+
+### Spec Summary Format
+
+Write to `<session_folder>/spec/spec-summary.md`:
+
+```
+# Specification Summary
+
+**Overall Quality Score**: <score>%
+**Quality Gate**: <gate>
+
+## Documents Reviewed
+(per document: phase, path, size, section list)
+
+## Key Findings
+### Strengths (dimensions scoring >= 80%)
+### Areas for Improvement (dimensions scoring < 70%)
+### Recommendations
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Spec folder empty | FAIL gate, report no documents found |
+| Missing phase document | Score 0 for that phase in completeness, note in report |
+| No original requirements found | Score coverage at 100% (nothing to cover) |
+| Broken references | Flag in consistency, do not fail entire review |

package/.claude/skills/team-lifecycle-v3/roles/reviewer/role.md

@@ -0,0 +1,104 @@
+# Role: reviewer
+
+Dual-mode review: code review (REVIEW-*) and spec quality validation (QUALITY-*). Auto-switches by task prefix.
+
+## Identity
+
+- **Name**: `reviewer` | **Prefix**: `REVIEW-*` + `QUALITY-*` | **Tag**: `[reviewer]`
+- **Responsibility**: Branch by Prefix → Review/Score → Report
+
+## Boundaries
+
+### MUST
+- Process REVIEW-* and QUALITY-* tasks
+- Generate readiness-report.md for QUALITY tasks
+- Cover all required dimensions per mode
+
+### MUST NOT
+- Create tasks
+- Modify source code
+- Skip quality dimensions
+- Approve without verification
+
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| review_result | → coordinator | Code review complete |
+| quality_result | → coordinator | Spec quality complete |
+| fix_required | → coordinator | Critical issues found |
+
+## Toolbox
+
+| Tool | Purpose |
+|------|---------|
+| commands/code-review.md | 4-dimension code review |
+| commands/spec-quality.md | 5-dimension spec quality |
+
+---
+
+## Mode Detection
+
+| Task Prefix | Mode | Dimensions |
+|-------------|------|-----------|
+| REVIEW-* | Code Review | quality, security, architecture, requirements |
+| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage |
+
+---
+
+## Code Review (REVIEW-*)
+
+**Inputs**: Plan file, git diff, modified files, test results (if available)
+
+**4 dimensions** (delegate to commands/code-review.md):
+
+| Dimension | Critical Issues |
+|-----------|----------------|
+| Quality | Empty catch, any in public APIs, @ts-ignore, console.log |
+| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
+| Architecture | Circular deps, parent imports >2 levels, files >500 lines |
+| Requirements | Missing core functionality, incomplete acceptance criteria |
+
+**Verdict**:
+
+| Verdict | Criteria |
+|---------|----------|
+| BLOCK | Critical issues present |
+| CONDITIONAL | High/medium only |
+| APPROVE | Low or none |
+
+---
+
+## Spec Quality (QUALITY-*)
+
+**Inputs**: All spec docs in session folder, quality gate config
+
+**5 dimensions** (delegate to commands/spec-quality.md):
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Completeness | 25% | All sections present with substance |
+| Consistency | 20% | Terminology, format, references |
+| Traceability | 25% | Goals → Reqs → Arch → Stories chain |
+| Depth | 20% | AC testable, ADRs justified, stories estimable |
+| Coverage | 10% | Original requirements mapped |
+
+**Quality gate**:
+
+| Gate | Criteria |
+|------|----------|
+| PASS | Score ≥ 80% AND coverage ≥ 70% |
+| REVIEW | Score 60-79% OR coverage 50-69% |
+| FAIL | Score < 60% OR coverage < 50% |
+
+**Artifacts**: readiness-report.md + spec-summary.md
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Missing context | Request from coordinator |
+| Invalid mode | Abort with error |
+| Analysis failure | Retry, then fallback template |

package/.claude/skills/team-lifecycle-v3/roles/tester/commands/validate.md

@@ -0,0 +1,152 @@
+# Command: validate
+
+## Purpose
+
+Test-fix cycle with strategy engine: detect framework, run tests, classify failures, select fix strategy, iterate until pass rate target is met or max iterations exhausted.
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts |
+| PASS_RATE_TARGET | 95% | Minimum pass rate to succeed |
+| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite |
+
+## Phase 2: Context Loading
+
+Load from task description and executor output:
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Framework | Auto-detected (see below) | Yes |
+| Modified files | Executor task output / git diff | Yes |
+| Affected tests | Derived from modified files | No |
+| Session folder | Task description `Session:` field | Yes |
+| Wisdom | `<session_folder>/wisdom/` | No |
+
+**Framework detection** (priority order):
+
+| Priority | Method | Check |
+|----------|--------|-------|
+| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
+| 2 | package.json scripts.test | Command contains framework name |
+| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini |
+
+**Affected test discovery** from modified files:
+- For each modified file `<name>.<ext>`, search:
+  `<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
+
+## Phase 3: Test-Fix Cycle
+
+### Test Command Table
+
+| Framework | Affected Tests | Full Suite |
+|-----------|---------------|------------|
+| vitest | `vitest run <files> --reporter=verbose` | `vitest run --reporter=verbose` |
+| jest | `jest <files> --no-coverage --verbose` | `jest --no-coverage --verbose` |
+| mocha | `mocha <files> --reporter spec` | `mocha --reporter spec` |
+| pytest | `pytest <files> -v --tb=short` | `pytest -v --tb=short` |
+
+### Iteration Flow
+
+```
+Iteration 1
+  ├─ Run affected tests (or full suite if none)
+  ├─ Parse results → pass rate
+  ├─ Pass rate >= 95%?
+  │   ├─ YES + affected-only → run full suite to confirm
+  │   │   ├─ Full suite passes → SUCCESS
+  │   │   └─ Full suite fails → continue with full results
+  │   └─ YES + full suite → SUCCESS
+  └─ NO → classify failures → select strategy → apply fixes
+
+Iteration 2..10
+  ├─ Re-run tests
+  ├─ Track best pass rate across iterations
+  ├─ Pass rate >= 95% → SUCCESS
+  ├─ No failures to fix → STOP (anomaly)
+  └─ Failures remain → classify → select strategy → apply fixes
+
+After iteration 10
+  └─ FAIL: max iterations reached, report best pass rate
+```
+
+**Progress update**: When iteration > 5, send progress to coordinator with current pass rate and iteration count.
+
+### Strategy Selection Matrix
+
+| Condition | Strategy | Behavior |
+|-----------|----------|----------|
+| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first |
+| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences |
+| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high failures in batch |
+| Default (no other match) | Conservative | Safe fallback |
+
+### Failure Classification Table
+
+| Severity | Error Patterns |
+|----------|---------------|
+| Critical | SyntaxError, cannot find module, is not defined |
+| High | Assertion mismatch (expected/received), toBe/toEqual failures |
+| Medium | Timeout, async errors |
+| Low | Warnings, deprecation notices |
+
+### Fix Approach by Error Type
+
+| Error Type | Pattern | Fix Approach |
+|------------|---------|-------------|
+| missing_import | "Cannot find module '<module>'" | Add import statement, resolve relative path from modified files |
+| undefined_variable | "<name> is not defined" | Check source for renamed/moved exports, update reference |
+| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line, update expected value if behavior change is intentional |
+| timeout | "Timeout" | Increase timeout or add async/await |
+| syntax_error | "SyntaxError" | Read source at error line, fix syntax |
+
+### Tool Call Example
+
+Run tests with framework-appropriate command:
+
+```bash
+Bash(command="vitest run src/utils/__tests__/parser.test.ts --reporter=verbose", timeout=120000)
+```
+
+Read test file to analyze failure:
+
+```bash
+Read(file_path="<test_file_path>")
+```
+
+Apply fix via Edit:
+
+```bash
+Edit(file_path="<file>", old_string="<old>", new_string="<new>")
+```
+
+## Phase 4: Validation
+
+### Success Criteria
+
+| Check | Criteria | Required |
+|-------|----------|----------|
+| Pass rate | >= 95% | Yes |
+| Full suite run | At least one full suite pass | Yes |
+| No critical failures | Zero critical-severity failures remaining | Yes |
+| Best pass rate tracked | Reported in final result | Yes |
+
+### Result Routing
+
+| Outcome | Message Type | Content |
+|---------|-------------|---------|
+| Pass rate >= target | test_result | Success, iterations count, full suite confirmed |
+| Max iterations, pass rate < target | fix_required | Best pass rate, remaining failures, iteration count |
+| No tests found | error | Framework detected but no test files |
+| Framework not detected | error | Detection methods exhausted |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Framework not detected | Report error to coordinator, list detection attempts |
+| No test files found | Report to coordinator, suggest manual test path |
+| Test command fails (exit code != 0/1) | Check stderr for environment issues, retry once |
+| Fix application fails | Skip fix, try next iteration with different strategy |
+| Infinite loop (same failures repeat) | Abort after 3 identical result sets |