claude-code-workflow 6.3.54 → 7.0.0

package/.claude/skills/team-lifecycle-v4/roles/planner/commands/explore.md

@@ -0,0 +1,172 @@
+# Command: explore
+
+## Purpose
+
+Complexity-driven codebase exploration using shared explore subagent with centralized cache. v4 optimized: checks cache before exploring, avoids duplicate work across roles.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | PLAN-* task subject/description | Yes |
+| Session folder | Task description `Session:` field | Yes |
+| Spec context | `<session-folder>/spec/` (if exists) | No |
+| Plan directory | `<session-folder>/plan/` | Yes (create if missing) |
+| Project tech | `.workflow/project-tech.json` | No |
+| Cache index | `<session-folder>/explorations/cache-index.json` | No (create if missing) |
+
+## Phase 3: Exploration
+
+### Complexity Assessment
+
+Score the task description against keyword indicators:
+
+| Indicator | Keywords | Score |
+|-----------|----------|-------|
+| Structural change | refactor, architect, restructure, modular | +2 |
+| Multi-scope | multiple, across, cross-cutting | +2 |
+| Integration | integrate, api, database | +1 |
+| Non-functional | security, performance, auth | +1 |
+
+**Complexity routing**:
+
+| Score | Level | Strategy | Angle Count |
+|-------|-------|----------|-------------|
+| 0-1 | Low | ACE semantic search only | 1 |
+| 2-3 | Medium | Explore subagent per angle | 2-3 |
+| 4+ | High | Explore subagent per angle | 3-5 |
+
+### Angle Presets
+
+Select preset by dominant keyword match, then take first N angles per complexity:
+
+| Preset | Trigger Keywords | Angles (priority order) |
+|--------|-----------------|------------------------|
+| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points |
+| security | security, auth, permission, access | security, auth-patterns, dataflow, validation |
+| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access |
+| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases |
+| feature | (default) | patterns, integration-points, testing, dependencies |
+
+### Cache-First Strategy (v4 new)
+
+Before launching any exploration, check the shared cache:
+
+```
+1. Read <session-folder>/explorations/cache-index.json
+2. For each selected angle:
+   a. If angle exists in cache -> SKIP (reuse cached result)
+   b. If angle not in cache -> explore via subagent
+3. Only explore uncached angles
+```
+
+This avoids duplicating work done by analyst's `general` exploration or any prior role.
+
+### Low Complexity: Direct Search
+
+```bash
+mcp__ace-tool__search_context(project_root_path="<project-root>", query="<task-description>")
+```
+
+Transform results into exploration JSON and write to `<session-folder>/explorations/explore-general.json`.
+Update cache-index.json.
+
+**ACE failure fallback**:
+
+```bash
+Bash(command="rg -l '<keywords>' --type ts", timeout=30000)
+```
+
+### Medium/High Complexity: Explore Subagent per Angle
+
+For each uncached angle, call the shared explore subagent:
+
+```
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  description: "Explore: <angle>",
+  prompt: "Explore codebase for: <task-description>
+Focus angle: <angle>
+Keywords: <relevant-keywords>
+Session folder: <session-folder>
+
+## Cache Check
+1. Read <session-folder>/explorations/cache-index.json (if exists)
+2. Look for entry with matching angle
+3. If found AND file exists -> read cached result, return summary
+4. If not found -> proceed to exploration
+
+## Exploration Focus
+<angle-focus-from-table-below>
+
+## Output
+Write JSON to: <session-folder>/explorations/explore-<angle>.json
+Update cache-index.json with new entry
+Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols"
+})
+```
+
+### Angle Focus Guide
+
+| Angle | Focus Points |
+|-------|-------------|
+| architecture | Layer boundaries, design patterns, component responsibilities, ADRs |
+| dependencies | Import chains, external libraries, circular dependencies, shared utilities |
+| modularity | Module interfaces, separation of concerns, extraction opportunities |
+| integration-points | API endpoints, data flow between modules, event systems, service integrations |
+| security | Auth/authz logic, input validation, sensitive data handling, middleware |
+| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions |
+| dataflow | Data transformations, state propagation, validation points, mutation paths |
+| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity |
+| error-handling | Try-catch blocks, error propagation, recovery strategies, logging |
+| patterns | Code conventions, design patterns, naming conventions, best practices |
+| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking |
+
+### Explorations Manifest
+
+After all explorations complete (both cached and new), write manifest to `<session-folder>/plan/explorations-manifest.json`:
+
+```json
+{
+  "task_description": "<description>",
+  "complexity": "<Low|Medium|High>",
+  "exploration_count": "<N>",
+  "cached_count": "<M>",
+  "explorations": [
+    { "angle": "<angle>", "file": "../explorations/explore-<angle>.json", "source": "cached|new" }
+  ]
+}
+```
+
+## Phase 4: Validation
+
+### Output Files
+
+```
+<session-folder>/explorations/           (shared cache)
+  +- cache-index.json                    (updated)
+  +- explore-<angle>.json                (per angle)
+
+<session-folder>/plan/
+  +- explorations-manifest.json          (summary referencing shared cache)
+```
+
+### Success Criteria
+
+| Check | Criteria | Required |
+|-------|----------|----------|
+| At least 1 exploration | Non-empty exploration file exists | Yes |
+| Manifest written | explorations-manifest.json exists | Yes |
+| File roles assigned | Every relevant_file has role + rationale | Yes |
+| Cache updated | cache-index.json reflects all explorations | Yes |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Single exploration agent fails | Skip angle, remove from manifest, continue |
+| All explorations fail | Proceed to plan generation with task description only |
+| ACE search fails (Low) | Fallback to ripgrep keyword search |
+| Schema file not found | Use inline schema from Output section |
+| Cache index corrupt | Reset cache-index.json to empty, re-explore all |

package/.claude/skills/team-lifecycle-v4/roles/planner/role.md

@@ -0,0 +1,139 @@
+# Role: planner
+
+Multi-angle code exploration and structured implementation planning.
+Uses **Inner Loop** pattern for consistency (currently single PLAN-* task, extensible).
+
+## Identity
+
+- **Name**: `planner` | **Prefix**: `PLAN-*` | **Tag**: `[planner]`
+- **Mode**: Inner Loop
+- **Responsibility**: Complexity assessment -> Code exploration (shared cache) -> Plan generation -> Approval
+
+## Boundaries
+
+### MUST
+- Only process PLAN-* tasks
+- Assess complexity before planning
+- Use shared explore subagent for codebase exploration (cache-aware)
+- Generate plan.json + .task/TASK-*.json
+- Load spec context in full-lifecycle mode
+- Submit plan for coordinator approval
+
+### MUST NOT
+- Create tasks for other roles
+- Implement code
+- Modify spec documents
+- Skip complexity assessment
+
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| plan_ready | -> coordinator | Plan complete |
+| plan_revision | -> coordinator | Plan revised per feedback |
+| error | -> coordinator | Exploration or planning failure |
+
+## Toolbox
+
+| Tool | Purpose |
+|------|---------|
+| commands/explore.md | Complexity-driven exploration via shared explore subagent |
+| Explore subagent | Per-angle exploration (shared cache) |
+| cli-lite-planning-agent | Plan generation |
+
+---
+
+## Phase 1.5: Load Spec Context (Full-Lifecycle)
+
+If `<session-folder>/spec/` exists -> load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise -> impl-only mode.
+
+**Check shared explorations**: Read `<session-folder>/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore.
+
+---
+
+## Phase 2: Multi-Angle Exploration
+
+**Objective**: Explore codebase to inform planning.
+
+**Complexity routing**:
+
+| Complexity | Criteria | Strategy |
+|------------|----------|----------|
+| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
+| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent |
+| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent |
+
+Delegate to `commands/explore.md` for angle selection and execution.
+
+**Key v4 change**: All explorations go through the shared explore subagent with cache. Before launching an exploration for an angle, check cache-index.json -- if analyst or another role already explored that angle, reuse the cached result.
+
+---
+
+## Phase 3: Plan Generation
+
+**Objective**: Generate structured implementation plan.
+
+| Complexity | Strategy |
+|------------|----------|
+| Low | Direct planning -> single TASK-001 with plan.json |
+| Medium/High | cli-lite-planning-agent with exploration results |
+
+**Agent call** (Medium/High):
+
+```
+Task({
+  subagent_type: "cli-lite-planning-agent",
+  run_in_background: false,
+  description: "Generate implementation plan",
+  prompt: "Generate plan.
+Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
+Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
+Task: <task-description>
+Explorations: <explorations-manifest>
+Complexity: <complexity>
+Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on"
+})
+```
+
+**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
+
+---
+
+## Phase 4: Submit for Approval
+
+1. Read plan.json and TASK-*.json
+2. Report to coordinator: complexity, task count, task list, approach, plan location
+3. Wait for response: approved -> complete; revision -> update and resubmit
+
+**Session files**:
+```
+<session-folder>/explorations/          (shared cache, written by explore subagent)
++-- cache-index.json
++-- explore-<angle>.json
+
+<session-folder>/plan/
++-- explorations-manifest.json          (summary, references ../explorations/)
++-- plan.json
++-- .task/TASK-*.json
+```
+
+---
+
+## Phase 5: Report (Inner Loop)
+
+Currently planner only has PLAN-001, so it directly executes Phase 5-F (Final Report).
+If future extensions add multiple PLAN-* tasks, Phase 5-L loop activates automatically:
+- Phase 5-L: Mark task completed, accumulate summary, loop back to Phase 1
+- Phase 5-F: All PLAN-* done, send final report to coordinator with full summary
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Exploration agent failure | Plan from description only |
+| Planning agent failure | Fallback to direct planning |
+| Plan rejected 3+ times | Notify coordinator, suggest alternative |
+| Schema not found | Use basic structure |
+| Cache index corrupt | Clear cache, re-explore all angles |

package/.claude/skills/team-lifecycle-v4/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-v4/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 |