diff --git a/.claude/agents/team-worker.md b/.claude/agents/team-worker.md index 3213acf5..91c026ae 100644 --- a/.claude/agents/team-worker.md +++ b/.claude/agents/team-worker.md @@ -99,8 +99,8 @@ Execute on every loop iteration: - Subject starts with this role's `prefix` + `-` (e.g., `DRAFT-`, `IMPL-`) - Status is `pending` - `blockedBy` list is empty (all dependencies resolved) - - **Owner matches** `agent_name` from prompt (e.g., task owner "explorer-1" matches agent_name "explorer-1"). This prevents parallel workers from claiming each other's tasks. - If role has `additional_prefixes` (e.g., reviewer handles REVIEW-* + QUALITY-* + IMPROVE-*), check all prefixes + - **NOTE**: Do NOT filter by owner name. The system appends numeric suffixes to agent names (e.g., `profiler` → `profiler-4`), making exact owner matching unreliable. Prefix-based filtering is sufficient to prevent cross-role task claiming. 3. **No matching tasks?** - If first iteration → report idle, SendMessage "No tasks found for [role]", STOP - If inner loop continuation → proceed to Phase 5-F (all done) diff --git a/.claude/skills/team-arch-opt/role-specs/analyzer.md b/.claude/skills/team-arch-opt/role-specs/analyzer.md deleted file mode 100644 index e5a72062..00000000 --- a/.claude/skills/team-arch-opt/role-specs/analyzer.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -prefix: ANALYZE -inner_loop: false -cli_tools: [explore] -message_types: - success: analyze_complete - error: error ---- - -# Architecture Analyzer - -Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report. - -## Phase 2: Context & Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | /wisdom/.msg/meta.json | No | - -1. Extract session path and target scope from task description -2. Detect project type by scanning for framework markers: - -| Signal File | Project Type | Analysis Focus | -|-------------|-------------|----------------| -| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports | -| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns | -| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection | -| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts | -| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering | -| No detection | Generic | All architecture dimensions | - -3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope -4. Detect available analysis tools (linters, dependency analyzers, build tools) - -## Phase 3: Architecture Analysis - -Execute analysis based on detected project type: - -**Dependency analysis**: -- Build import/require graph across modules -- Detect circular dependencies (direct and transitive cycles) -- Identify layering violations (e.g., UI importing from data layer, utils importing from domain) -- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled) - -**Structural analysis**: -- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities) -- Calculate coupling metrics (afferent/efferent coupling per module) -- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods) -- Detect code duplication (repeated logic blocks, copy-paste patterns) -- Identify missing abstractions (repeated conditionals, switch-on-type patterns) - -**API surface analysis**: -- Count exported symbols per module (export bloat detection) -- Identify dead exports (exported but never imported elsewhere) -- Detect dead code (unreachable functions, unused variables, orphan files) -- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling) - -**All project types**: -- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution) -- Rank top 3-7 architecture issues by severity (Critical / High / Medium) -- Record evidence: file paths, line numbers, measured values - -## Phase 4: Report Generation - -1. Write architecture baseline to `/artifacts/architecture-baseline.json`: - - Module count, dependency count, cycle count, average coupling, average cohesion - - God Class candidates with LOC and method count - - Dead code file count, dead export count - - Timestamp and project type details - -2. Write architecture report to `/artifacts/architecture-report.md`: - - Ranked list of architecture issues with severity, location (file:line or module), measured impact - - Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT - - Evidence summary per issue - - Detected project type and analysis methods used - -3. Update `/wisdom/.msg/meta.json` under `analyzer` namespace: - - Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back diff --git a/.claude/skills/team-arch-opt/role-specs/designer.md b/.claude/skills/team-arch-opt/role-specs/designer.md deleted file mode 100644 index d82596d6..00000000 --- a/.claude/skills/team-arch-opt/role-specs/designer.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -prefix: DESIGN -inner_loop: false -discuss_rounds: [DISCUSS-REFACTOR] -cli_tools: [discuss] -message_types: - success: design_complete - error: error ---- - -# Refactoring Designer - -Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments. - -## Phase 2: Analysis Loading - -| Input | Source | Required | -|-------|--------|----------| -| Architecture report | /artifacts/architecture-report.md | Yes | -| Architecture baseline | /artifacts/architecture-baseline.json | Yes | -| .msg/meta.json | /wisdom/.msg/meta.json | Yes | -| Wisdom files | /wisdom/patterns.md | No | - -1. Extract session path from task description -2. Read architecture report -- extract ranked issue list with severities and categories -3. Read architecture baseline -- extract current structural metrics -4. Load .msg/meta.json for analyzer findings (project_type, scope) -5. Assess overall refactoring complexity: - -| Issue Count | Severity Mix | Complexity | -|-------------|-------------|------------| -| 1-2 | All Medium | Low | -| 2-3 | Mix of High/Medium | Medium | -| 3+ or any Critical | Any Critical present | High | - -## Phase 3: Strategy Formulation - -For each architecture issue, select refactoring approach by type: - -| Issue Type | Strategies | Risk Level | -|------------|-----------|------------| -| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High | -| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High | -| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium | -| Code duplication | Extract shared utility/base class, template method pattern | Low | -| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium | -| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low | -| Dead code | Safe removal with reference verification | Low | -| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium | - -Prioritize refactorings by impact/effort ratio: - -| Priority | Criteria | -|----------|----------| -| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) | -| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) | -| P2 (Medium) | Medium impact + Low effort (duplication extraction) | -| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) | - -If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan. - -Define measurable success criteria per refactoring (target metric improvement or structural change). - -## Phase 4: Plan Output - -1. Write refactoring plan to `/artifacts/refactoring-plan.md`: - - Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block: - - ```markdown - ### REFACTOR-001: - - Priority: P0 - - Target issue: <issue from report> - - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT> - - Target files: <file-list> - - Strategy: <selected approach> - - Expected improvement: <metric> by <description> - - Risk level: <Low/Medium/High> - - Success criteria: <specific structural change to verify> - - Implementation guidance: - 1. <step 1> - 2. <step 2> - 3. <step 3> - - ### REFACTOR-002: <title> - ... - ``` - - Requirements: - - Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...) - - Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution) - - Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others - -2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace: - - Read existing -> merge -> write back: - ```json - { - "designer": { - "complexity": "<Low|Medium|High>", - "refactoring_count": 4, - "priorities": ["P0", "P0", "P1", "P2"], - "discuss_used": false, - "refactorings": [ - { - "id": "REFACTOR-001", - "title": "<title>", - "issue_type": "<CYCLE|COUPLING|...>", - "priority": "P0", - "target_files": ["src/a.ts", "src/b.ts"], - "expected_improvement": "<metric> by <description>", - "success_criteria": "<threshold>" - } - ] - } - } - ``` - -3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md` diff --git a/.claude/skills/team-arch-opt/role-specs/refactorer.md b/.claude/skills/team-arch-opt/role-specs/refactorer.md deleted file mode 100644 index ca6e8fa8..00000000 --- a/.claude/skills/team-arch-opt/role-specs/refactorer.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -prefix: REFACTOR -inner_loop: true -additional_prefixes: [FIX] -cli_tools: [explore] -message_types: - success: refactor_complete - error: error - fix: fix_required ---- - -# Code Refactorer - -Implement architecture refactoring changes following the design plan. For FIX tasks, apply targeted corrections based on review/validation feedback. - -## Modes - -| Mode | Task Prefix | Trigger | Focus | -|------|-------------|---------|-------| -| Refactor | REFACTOR | Design plan ready | Apply refactorings per plan priority | -| Fix | FIX | Review/validation feedback | Targeted fixes for identified issues | - -## Phase 2: Plan & Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Refactoring plan | <session>/artifacts/refactoring-plan.md | Yes (REFACTOR, no branch) | -| Branch refactoring detail | <session>/artifacts/branches/B{NN}/refactoring-detail.md | Yes (REFACTOR with branch) | -| Pipeline refactoring plan | <session>/artifacts/pipelines/{P}/refactoring-plan.md | Yes (REFACTOR with pipeline) | -| Review/validation feedback | From task description | Yes (FIX) | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Wisdom files | <session>/wisdom/patterns.md | No | -| Context accumulator | From prior REFACTOR/FIX tasks | Yes (inner loop) | - -1. Extract session path and task mode (REFACTOR or FIX) from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|--------- -| `BranchId: B{NN}` | Present | Fan-out branch -- load single refactoring detail | -| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan | -| Neither present | - | Single mode -- load full refactoring plan | - -3. **Load refactoring context by mode**: - - **Single mode (no branch)**: Read `<session>/artifacts/refactoring-plan.md` -- extract ALL priority-ordered changes - - **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- extract ONLY this branch's refactoring (single REFACTOR-ID) - - **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` -- extract this pipeline's plan - -4. For FIX: parse review/validation feedback for specific issues to address -5. Use `explore` CLI tool to load implementation context for target files -6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks - -**Meta.json namespace**: -- Single: write to `refactorer` namespace -- Fan-out: write to `refactorer.B{NN}` namespace -- Independent: write to `refactorer.{P}` namespace - -## Phase 3: Code Implementation - -Implementation backend selection: - -| Backend | Condition | Method | -|---------|-----------|--------| -| CLI | Multi-file refactoring with clear plan | ccw cli --tool gemini --mode write | -| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools | - -For REFACTOR tasks: -- **Single mode**: Apply refactorings in plan priority order (P0 first, then P1, etc.) -- **Fan-out branch**: Apply ONLY this branch's single refactoring (from refactoring-detail.md) -- **Independent pipeline**: Apply this pipeline's refactorings in priority order -- Follow implementation guidance from plan (target files, patterns) -- **Preserve existing behavior -- refactoring must not change functionality** -- **Update ALL import references** when moving/renaming modules -- **Update ALL test files** that reference moved/renamed symbols - -For FIX tasks: -- Read specific issues from review/validation feedback -- Apply targeted corrections to flagged code locations -- Verify the fix addresses the exact concern raised - -General rules: -- Make minimal, focused changes per refactoring -- Add comments only where refactoring logic is non-obvious -- Preserve existing code style and conventions -- Verify no dangling imports after module moves - -## Phase 4: Self-Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Syntax | IDE diagnostics or build check | No new errors | -| File integrity | Verify all planned files exist and are modified | All present | -| Import integrity | Verify no broken imports after moves | All imports resolve | -| Acceptance | Match refactoring plan success criteria | All structural changes applied | -| No regression | Run existing tests if available | No new failures | - -If validation fails, attempt auto-fix (max 2 attempts) before reporting error. - -Append to context_accumulator for next REFACTOR/FIX task (single/inner-loop mode only): -- Files modified, refactorings applied, validation results -- Any discovered patterns or caveats for subsequent iterations - -**Branch output paths**: -- Single: write artifacts to `<session>/artifacts/` -- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/` -- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/` diff --git a/.claude/skills/team-arch-opt/role-specs/reviewer.md b/.claude/skills/team-arch-opt/role-specs/reviewer.md deleted file mode 100644 index 631a2988..00000000 --- a/.claude/skills/team-arch-opt/role-specs/reviewer.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -prefix: REVIEW -inner_loop: false -additional_prefixes: [QUALITY] -discuss_rounds: [DISCUSS-REVIEW] -cli_tools: [discuss] -message_types: - success: review_complete - error: error - fix: fix_required ---- - -# Architecture Reviewer - -Review refactoring code changes for correctness, pattern consistency, completeness, migration safety, and adherence to best practices. Provide structured verdicts with actionable feedback. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Refactoring code changes | From REFACTOR task artifacts / git diff | Yes | -| Refactoring plan / detail | Varies by mode (see below) | Yes | -| Validation results | Varies by mode (see below) | No | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | - -1. Extract session path from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|--------- -| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes | -| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes | -| Neither present | - | Single mode -- review all refactoring changes | - -3. **Load refactoring context by mode**: - - Single: Read `<session>/artifacts/refactoring-plan.md` - - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` - - Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` - -4. Load .msg/meta.json for scoped refactorer namespace: - - Single: `refactorer` namespace - - Fan-out: `refactorer.B{NN}` namespace - - Independent: `refactorer.{P}` namespace - -5. Identify changed files from refactorer context -- read ONLY files modified by this branch/pipeline -6. If validation results available, read from scoped path: - - Single: `<session>/artifacts/validation-results.json` - - Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json` - - Independent: `<session>/artifacts/pipelines/{P}/validation-results.json` - -## Phase 3: Multi-Dimension Review - -Analyze refactoring changes across five dimensions: - -| Dimension | Focus | Severity | -|-----------|-------|----------| -| Correctness | No behavior changes, all references updated, no dangling imports | Critical | -| Pattern consistency | Follows existing patterns, naming consistent, language-idiomatic | High | -| Completeness | All related code updated (imports, tests, config, documentation) | High | -| Migration safety | No dangling references, backward compatible, public API preserved | Critical | -| Best practices | Clean Architecture / SOLID principles, appropriate abstraction level | Medium | - -Per-dimension review process: -- Scan modified files for patterns matching each dimension -- Record findings with severity (Critical / High / Medium / Low) -- Include specific file:line references and suggested fixes - -**Correctness checks**: -- Verify moved code preserves original behavior (no logic changes mixed with structural changes) -- Check all import/require statements updated to new paths -- Verify no orphaned files left behind after moves - -**Pattern consistency checks**: -- New module names follow existing naming conventions -- Extracted interfaces/classes use consistent patterns with existing codebase -- File organization matches project conventions (e.g., index files, barrel exports) - -**Completeness checks**: -- All test files updated for moved/renamed modules -- Configuration files updated if needed (e.g., path aliases, build configs) -- Type definitions updated for extracted interfaces - -**Migration safety checks**: -- Public API surface unchanged (same exports available to consumers) -- No circular dependencies introduced by the refactoring -- Re-exports in place if module paths changed for backward compatibility - -**Best practices checks**: -- Extracted modules have clear single responsibility -- Dependency direction follows layer conventions (dependencies flow inward) -- Appropriate abstraction level (not over-engineered, not under-abstracted) - -If any Critical findings detected, invoke `discuss` CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. - -## Phase 4: Verdict & Feedback - -Classify overall verdict based on findings: - -| Verdict | Condition | Action | -|---------|-----------|--------| -| APPROVE | No Critical or High findings | Send review_complete | -| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback | -| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for designer escalation | - -1. Write review report to scoped output path: - - Single: `<session>/artifacts/review-report.md` - - Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md` - - Independent: `<session>/artifacts/pipelines/{P}/review-report.md` - - Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts - -2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace: - - Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }` - - Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }` - - Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }` - -3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions) diff --git a/.claude/skills/team-arch-opt/role-specs/validator.md b/.claude/skills/team-arch-opt/role-specs/validator.md deleted file mode 100644 index c22949d0..00000000 --- a/.claude/skills/team-arch-opt/role-specs/validator.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -prefix: VALIDATE -inner_loop: false -message_types: - success: validate_complete - error: error - fix: fix_required ---- - -# Architecture Validator - -Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality. - -## Phase 2: Environment & Baseline Loading - -| Input | Source | Required | -|-------|--------|----------| -| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes | -| Refactoring plan / detail | Varies by mode (see below) | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | - -1. Extract session path from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|--------- -| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes | -| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline | -| Neither present | - | Single mode -- full validation | - -3. **Load architecture baseline**: - - Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline) - - Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json` - -4. **Load refactoring context**: - - Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria - - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria - - Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md` - -5. Load .msg/meta.json for project type and refactoring scope -6. Detect available validation tools from project: - -| Signal | Validation Tool | Method | -|--------|----------------|--------| -| package.json + tsc | TypeScript compiler | Type-check entire project | -| package.json + vitest/jest | Test runner | Run existing test suite | -| package.json + eslint | Linter | Run lint checks for import/export issues | -| Cargo.toml | Rust compiler | cargo check + cargo test | -| go.mod | Go tools | go build + go test | -| Makefile with test target | Custom tests | make test | -| No tooling detected | Manual validation | File existence + import grep checks | - -7. Get changed files scope from .msg/meta.json: - - Single: `refactorer` namespace - - Fan-out: `refactorer.B{NN}` namespace - - Independent: `refactorer.{P}` namespace - -## Phase 3: Validation Execution - -Run validations across four dimensions: - -**Build validation**: -- Compile/type-check the project -- zero new errors allowed -- Verify all moved/renamed files are correctly referenced -- Check for missing imports or unresolved modules - -**Test validation**: -- Run existing test suite -- all previously passing tests must still pass -- Identify any tests that need updating due to module moves (update, don't skip) -- Check for test file imports that reference old paths - -**Dependency metric validation**: -- Recalculate architecture metrics post-refactoring -- Compare coupling scores against baseline (must improve or stay neutral) -- Verify no new circular dependencies introduced -- Check cohesion metrics for affected modules - -**API compatibility validation**: -- Verify public API signatures are preserved (exported function/class/type names) -- Check for dangling references (imports pointing to removed/moved files) -- Verify no new dead exports introduced by the refactoring -- Check that re-exports maintain backward compatibility where needed - -**Branch-scoped validation** (fan-out mode): -- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md) -- Still check for regressions across all metrics (not just branch-specific ones) - -## Phase 4: Result Analysis - -Compare against baseline and plan criteria: - -| Metric | Threshold | Verdict | -|--------|-----------|---------| -| Build passes | Zero compilation errors | PASS | -| All tests pass | No new test failures | PASS | -| Coupling improved or neutral | No metric degradation > 5% | PASS | -| No new cycles introduced | Cycle count <= baseline | PASS | -| All plan success criteria met | Every criterion satisfied | PASS | -| Partial improvement | Some metrics improved, none degraded | WARN | -| Build fails | Compilation errors detected | FAIL -> fix_required | -| Test failures | Previously passing tests now fail | FAIL -> fix_required | -| New cycles introduced | Cycle count > baseline | FAIL -> fix_required | -| Dangling references | Unresolved imports detected | FAIL -> fix_required | - -1. Write validation results to output path: - - Single: `<session>/artifacts/validation-results.json` - - Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json` - - Independent: `<session>/artifacts/pipelines/{P}/validation-results.json` - - Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any) - -2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace: - - Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }` - - Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }` - - Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }` - -3. If verdict is FAIL, include detailed feedback in message for FIX task creation: - - Which validations failed, specific errors, suggested investigation areas diff --git a/.claude/skills/team-arch-opt/specs/team-config.json b/.claude/skills/team-arch-opt/specs/team-config.json index b29e16d1..4763c836 100644 --- a/.claude/skills/team-arch-opt/specs/team-config.json +++ b/.claude/skills/team-arch-opt/specs/team-config.json @@ -23,7 +23,7 @@ "name": "analyzer", "type": "orchestration", "description": "Analyzes architecture: dependency graphs, coupling/cohesion, layering violations, God Classes, dead code", - "role_spec": "role-specs/analyzer.md", + "role_spec": "roles/analyzer/role.md", "inner_loop": false, "frontmatter": { "prefix": "ANALYZE", @@ -43,7 +43,7 @@ "name": "designer", "type": "orchestration", "description": "Designs refactoring strategies from architecture analysis, produces prioritized refactoring plan with discrete REFACTOR-IDs", - "role_spec": "role-specs/designer.md", + "role_spec": "roles/designer/role.md", "inner_loop": false, "frontmatter": { "prefix": "DESIGN", @@ -63,7 +63,7 @@ "name": "refactorer", "type": "code_generation", "description": "Implements architecture refactoring changes following the design plan", - "role_spec": "role-specs/refactorer.md", + "role_spec": "roles/refactorer/role.md", "inner_loop": true, "frontmatter": { "prefix": "REFACTOR", @@ -84,7 +84,7 @@ "name": "validator", "type": "validation", "description": "Validates refactoring: build checks, test suites, dependency metrics, API compatibility", - "role_spec": "role-specs/validator.md", + "role_spec": "roles/validator/role.md", "inner_loop": false, "frontmatter": { "prefix": "VALIDATE", @@ -105,7 +105,7 @@ "name": "reviewer", "type": "read_only_analysis", "description": "Reviews refactoring code for correctness, pattern consistency, completeness, migration safety, and best practices", - "role_spec": "role-specs/reviewer.md", + "role_spec": "roles/reviewer/role.md", "inner_loop": false, "frontmatter": { "prefix": "REVIEW", diff --git a/.claude/skills/team-brainstorm/role-specs/challenger.md b/.claude/skills/team-brainstorm/role-specs/challenger.md deleted file mode 100644 index e63137bb..00000000 --- a/.claude/skills/team-brainstorm/role-specs/challenger.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -prefix: CHALLENGE -inner_loop: false -delegates_to: [] -message_types: - success: critique_ready - error: error ---- - -# Challenger - -Devil's advocate role. Assumption challenging, feasibility questioning, risk identification. Acts as the Critic in the Generator-Critic loop. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description (Session: line) | Yes | -| Ideas | <session>/ideas/*.md files | Yes | -| Previous critiques | <session>/.msg/meta.json critique_insights | No | - -1. Extract session path from task description (match "Session: <path>") -2. Glob idea files from <session>/ideas/ -3. Read all idea files for analysis -4. Read .msg/meta.json critique_insights to avoid repeating past challenges - -## Phase 3: Critical Analysis - -**Challenge Dimensions** (apply to each idea): - -| Dimension | Focus | -|-----------|-------| -| Assumption Validity | Does the core assumption hold? Counter-examples? | -| Feasibility | Technical/resource/time feasibility? | -| Risk Assessment | Worst case scenario? Hidden risks? | -| Competitive Analysis | Better alternatives already exist? | - -**Severity Classification**: - -| Severity | Criteria | -|----------|----------| -| CRITICAL | Fundamental issue, idea may need replacement | -| HIGH | Significant flaw, requires revision | -| MEDIUM | Notable weakness, needs consideration | -| LOW | Minor concern, does not invalidate the idea | - -**Generator-Critic Signal**: - -| Condition | Signal | -|-----------|--------| -| Any CRITICAL or HIGH severity | REVISION_NEEDED | -| All MEDIUM or lower | CONVERGED | - -**Output**: Write to `<session>/critiques/critique-<num>.md` -- Sections: Ideas Reviewed, Per-idea challenges with severity, Summary table with counts, GC Signal - -## Phase 4: Severity Summary - -1. Count challenges by severity level -2. Determine signal: REVISION_NEEDED if critical+high > 0, else CONVERGED -3. Update shared state: - - Append challenges to .msg/meta.json critique_insights - - Each entry: idea, severity, key_challenge, round diff --git a/.claude/skills/team-brainstorm/role-specs/evaluator.md b/.claude/skills/team-brainstorm/role-specs/evaluator.md deleted file mode 100644 index 83382c5d..00000000 --- a/.claude/skills/team-brainstorm/role-specs/evaluator.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -prefix: EVAL -inner_loop: false -delegates_to: [] -message_types: - success: evaluation_ready - error: error ---- - -# Evaluator - -Scoring, ranking, and final selection. Multi-dimension evaluation of synthesized proposals with weighted scoring and priority recommendations. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description (Session: line) | Yes | -| Synthesis results | <session>/synthesis/*.md files | Yes | -| All ideas | <session>/ideas/*.md files | No (for context) | -| All critiques | <session>/critiques/*.md files | No (for context) | - -1. Extract session path from task description (match "Session: <path>") -2. Glob synthesis files from <session>/synthesis/ -3. Read all synthesis files for evaluation -4. Optionally read ideas and critiques for full context - -## Phase 3: Evaluation and Scoring - -**Scoring Dimensions**: - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Feasibility | 30% | Technical feasibility, resource needs, timeline | -| Innovation | 25% | Novelty, differentiation, breakthrough potential | -| Impact | 25% | Scope of impact, value creation, problem resolution | -| Cost Efficiency | 20% | Implementation cost, risk cost, opportunity cost | - -**Weighted Score**: `(Feasibility * 0.30) + (Innovation * 0.25) + (Impact * 0.25) + (Cost * 0.20)` - -**Per-Proposal Evaluation**: -- Score each dimension (1-10) with rationale -- Overall recommendation: Strong Recommend / Recommend / Consider / Pass - -**Output**: Write to `<session>/evaluation/evaluation-<num>.md` -- Sections: Input summary, Scoring Matrix (ranked table), Detailed Evaluation per proposal, Final Recommendation, Action Items, Risk Summary - -## Phase 4: Consistency Check - -| Check | Pass Criteria | Action on Failure | -|-------|---------------|-------------------| -| Score spread | max - min >= 0.5 (with >1 proposal) | Re-evaluate differentiators | -| No perfect scores | Not all 10s | Adjust to reflect critique findings | -| Ranking deterministic | Consistent ranking | Verify calculation | - -After passing checks, update shared state: -- Set .msg/meta.json evaluation_scores -- Each entry: title, weighted_score, rank, recommendation diff --git a/.claude/skills/team-brainstorm/role-specs/ideator.md b/.claude/skills/team-brainstorm/role-specs/ideator.md deleted file mode 100644 index d6366106..00000000 --- a/.claude/skills/team-brainstorm/role-specs/ideator.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -prefix: IDEA -inner_loop: false -delegates_to: [] -message_types: - success: ideas_ready - error: error ---- - -# Ideator - -Multi-angle idea generator. Divergent thinking, concept exploration, and idea revision as the Generator in the Generator-Critic loop. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description (Session: line) | Yes | -| Topic | <session>/.msg/meta.json | Yes | -| Angles | <session>/.msg/meta.json | Yes | -| GC Round | <session>/.msg/meta.json | Yes | -| Previous critique | <session>/critiques/*.md | For revision tasks only | -| Previous ideas | <session>/.msg/meta.json generated_ideas | No | - -1. Extract session path from task description (match "Session: <path>") -2. Read .msg/meta.json for topic, angles, gc_round -3. Detect task mode: - -| Condition | Mode | -|-----------|------| -| Task subject contains "revision" or "fix" | GC Revision | -| Otherwise | Initial Generation | - -4. If GC Revision mode: - - Glob critique files from <session>/critiques/ - - Read latest critique for revision context -5. Read previous ideas from .msg/meta.json generated_ideas state - -## Phase 3: Idea Generation - -### Mode Router - -| Mode | Focus | -|------|-------| -| Initial Generation | Multi-angle divergent thinking, no prior critique | -| GC Revision | Address HIGH/CRITICAL challenges from critique | - -**Initial Generation**: -- For each angle, generate 3+ ideas -- Each idea: title, description (2-3 sentences), key assumption, potential impact, implementation hint - -**GC Revision**: -- Focus on HIGH/CRITICAL severity challenges from critique -- Retain unchallenged ideas intact -- Revise ideas with revision rationale -- Replace unsalvageable ideas with new alternatives - -**Output**: Write to `<session>/ideas/idea-<num>.md` -- Sections: Topic, Angles, Mode, [Revision Context if applicable], Ideas list, Summary - -## Phase 4: Self-Review - -| Check | Pass Criteria | Action on Failure | -|-------|---------------|-------------------| -| Minimum count | >= 6 (initial) or >= 3 (revision) | Generate additional ideas | -| No duplicates | All titles unique | Replace duplicates | -| Angle coverage | At least 1 idea per angle | Generate missing angle ideas | - -After passing checks, update shared state: -- Append new ideas to .msg/meta.json generated_ideas -- Each entry: id, title, round, revised flag diff --git a/.claude/skills/team-brainstorm/role-specs/synthesizer.md b/.claude/skills/team-brainstorm/role-specs/synthesizer.md deleted file mode 100644 index 8b6714cb..00000000 --- a/.claude/skills/team-brainstorm/role-specs/synthesizer.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -prefix: SYNTH -inner_loop: false -delegates_to: [] -message_types: - success: synthesis_ready - error: error ---- - -# Synthesizer - -Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Session folder | Task description (Session: line) | Yes | -| All ideas | <session>/ideas/*.md files | Yes | -| All critiques | <session>/critiques/*.md files | Yes | -| GC rounds completed | <session>/.msg/meta.json gc_round | Yes | - -1. Extract session path from task description (match "Session: <path>") -2. Glob all idea files from <session>/ideas/ -3. Glob all critique files from <session>/critiques/ -4. Read all idea and critique files for synthesis -5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights) - -## Phase 3: Synthesis Execution - -| Step | Action | -|------|--------| -| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas | -| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale | -| 3. Complementary Grouping | Group complementary ideas together | -| 4. Gap Identification | Discover uncovered perspectives | -| 5. Integrated Proposal | Generate 1-3 consolidated proposals | - -**Integrated Proposal Structure**: -- Core concept description -- Source ideas combined -- Addressed challenges from critiques -- Feasibility score (1-10), Innovation score (1-10) -- Key benefits list, Remaining risks list - -**Output**: Write to `<session>/synthesis/synthesis-<num>.md` -- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis - -## Phase 4: Quality Check - -| Check | Pass Criteria | Action on Failure | -|-------|---------------|-------------------| -| Proposal count | >= 1 proposal | Generate at least one proposal | -| Theme count | >= 2 themes | Look for more patterns | -| Conflict resolution | All conflicts documented | Address unresolved conflicts | - -After passing checks, update shared state: -- Set .msg/meta.json synthesis_themes -- Each entry: name, strength, supporting_ideas diff --git a/.claude/skills/team-frontend/role-specs/analyst.md b/.claude/skills/team-frontend/role-specs/analyst.md deleted file mode 100644 index 639ff85e..00000000 --- a/.claude/skills/team-frontend/role-specs/analyst.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -prefix: ANALYZE -inner_loop: false -message_types: - success: analyze_ready - error: error ---- - -# Requirements Analyst - -Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Industry context | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path, industry type, and tech stack from task description -2. Detect existing design system: - -| Signal | Detection Method | -|--------|-----------------| -| Token files | Glob `**/*token*.*` | -| CSS files | Glob `**/*.css` | -| Package.json | Read for framework dependencies | - -3. Detect tech stack from package.json: - -| Dependency | Stack | -|------------|-------| -| `next` | nextjs | -| `react` | react | -| `vue` | vue | -| `svelte` | svelte | -| `@shadcn/ui` | shadcn | -| (none) | html-tailwind | - -4. Load .msg/meta.json for shared state - -## Phase 3: Design Intelligence Retrieval - -Retrieve design intelligence via ui-ux-pro-max skill integration. - -**Step 1: Invoke ui-ux-pro-max** (primary path): - -| Action | Invocation | -|--------|------------| -| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` | -| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` | -| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` | - -**Step 2: Fallback** (if skill unavailable): -- Generate design recommendations from LLM general knowledge -- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill` - -**Step 3: Analyze existing codebase** (if token/CSS files found): -- Explore existing design patterns (color palette, typography scale, spacing, component patterns) - -**Step 4: Competitive reference** (optional, if industry is not "Other"): -- `WebSearch({ query: "<industry> web design trends best practices" })` - -**Step 5: Compile design-intelligence.json**: - -| Field | Source | -|-------|--------| -| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" | -| `industry` | Task description | -| `detected_stack` | Phase 2 detection | -| `design_system` | Skill output (colors, typography, effects) | -| `ux_guidelines` | Skill UX domain output | -| `stack_guidelines` | Skill stack output | -| `recommendations` | Synthesized: style, anti-patterns, must-have | - -**Output files**: -- `<session>/analysis/design-intelligence.json` -- `<session>/analysis/requirements.md` - -## Phase 4: Self-Review - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| JSON validity | Parse design-intelligence.json | No parse errors | -| Required fields | Check _source, industry, design_system | All present | -| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array | -| Requirements doc exists | File check | requirements.md written | - -Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys. diff --git a/.claude/skills/team-frontend/role-specs/architect.md b/.claude/skills/team-frontend/role-specs/architect.md deleted file mode 100644 index b3038989..00000000 --- a/.claude/skills/team-frontend/role-specs/architect.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -prefix: ARCH -inner_loop: false -message_types: - success: arch_ready - error: error ---- - -# Frontend Architect - -Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Scope | Extracted from task description (tokens/components/full) | No (default: full) | -| Design intelligence | <session>/analysis/design-intelligence.json | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path and scope from task description -2. Load design intelligence from analyst output -3. Load .msg/meta.json for shared state (industry_context, design_intelligence) -4. Detect existing project structure via Glob `src/**/*` - -**Fail-safe**: If design-intelligence.json not found, use default token values and log warning. - -## Phase 3: Architecture Design - -**Scope selection**: - -| Scope | Output | -|-------|--------| -| `tokens` | Design token system only | -| `components` | Component specs only | -| `full` | Both tokens and components + project structure | - -**Step 1: Design Token System** (scope: tokens or full): - -Generate `<session>/architecture/design-tokens.json` with categories: - -| Category | Content | Source | -|----------|---------|--------| -| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max | -| `typography` | Font families, font sizes (scale) | ui-ux-pro-max | -| `spacing` | xs through 2xl | Standard scale | -| `border-radius` | sm, md, lg, full | Standard scale | -| `shadow` | sm, md, lg | Standard elevation | -| `transition` | fast, normal, slow | Standard durations | - -Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values. - -**Step 2: Component Architecture** (scope: components or full): - -Generate component specs in `<session>/architecture/component-specs/`: -- Design reference (style, stack) -- Props table (name, type, default, description) -- Variants table -- Accessibility requirements (role, keyboard, ARIA, contrast) -- Anti-patterns to avoid (from design intelligence) - -**Step 3: Project Structure** (scope: full): - -Generate `<session>/architecture/project-structure.md` with stack-specific layout: - -| Stack | Key Directories | -|-------|----------------| -| react | src/components/, src/pages/, src/hooks/, src/styles/ | -| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ | -| vue | src/components/, src/views/, src/composables/, src/styles/ | -| html-tailwind | src/components/, src/pages/, src/styles/ | - -## Phase 4: Self-Review - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| JSON validity | Parse design-tokens.json | No errors | -| Required categories | Check color, typography, spacing | All present | -| Anti-pattern compliance | Token values vs anti-patterns | No violations | -| Component specs complete | Each has props + accessibility | All complete | -| File existence | Verify all planned files | All present | - -Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys. diff --git a/.claude/skills/team-frontend/role-specs/developer.md b/.claude/skills/team-frontend/role-specs/developer.md deleted file mode 100644 index 16486f36..00000000 --- a/.claude/skills/team-frontend/role-specs/developer.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -prefix: DEV -inner_loop: true -message_types: - success: dev_complete - error: error ---- - -# Frontend Developer - -Consume architecture artifacts (design tokens, component specs, project structure) to implement frontend code. Reference design-intelligence.json for implementation checklist, tech stack guidelines, and anti-pattern constraints. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Scope | Extracted from task description (tokens/components/full) | No (default: full) | -| Design intelligence | <session>/analysis/design-intelligence.json | No | -| Design tokens | <session>/architecture/design-tokens.json | Yes | -| Component specs | <session>/architecture/component-specs/*.md | No | -| Project structure | <session>/architecture/project-structure.md | No | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path and scope from task description -2. Load design tokens (required -- if missing, report to coordinator) -3. Load design intelligence for anti-patterns and guidelines -4. Load component specs and project structure -5. Detect tech stack from design intelligence `detected_stack` -6. Load .msg/meta.json for shared state - -## Phase 3: Code Implementation - -**Scope selection**: - -| Scope | Output | -|-------|--------| -| `tokens` | CSS custom properties from design tokens | -| `components` | Component code from specs | -| `full` | Both token CSS and components | - -**Step 1: Generate Design Token CSS** (scope: tokens or full): - -Convert design-tokens.json to `src/styles/tokens.css`: - -| JSON Category | CSS Variable Prefix | -|---------------|---------------------| -| color | `--color-` | -| typography.font-family | `--font-` | -| typography.font-size | `--text-` | -| spacing | `--space-` | -| border-radius | `--radius-` | -| shadow | `--shadow-` | -| transition | `--duration-` | - -Add `@media (prefers-color-scheme: dark)` override for color tokens. - -**Step 2: Implement Components** (scope: components or full): - -Implementation strategy by complexity: - -| Condition | Strategy | -|-----------|----------| -| <= 2 components | Direct inline Edit/Write | -| 3-5 components | Single batch implementation | -| > 5 components | Group by module, implement per batch | - -**Coding standards** (mandatory): -- Use design token CSS variables -- never hardcode colors/spacing -- All interactive elements: `cursor: pointer` -- Transitions: 150-300ms via `var(--duration-normal)` -- Text contrast: minimum 4.5:1 ratio -- Include `focus-visible` styles for keyboard navigation -- Support `prefers-reduced-motion` -- Responsive: mobile-first with md/lg breakpoints -- No emoji as functional icons - -## Phase 4: Self-Review - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Hardcoded colors | Scan for hex codes outside tokens.css | None found | -| cursor-pointer | Check buttons/links | All have cursor-pointer | -| Focus styles | Check interactive elements | All have focus styles | -| Responsive | Check for breakpoints | Breakpoints present | -| File existence | Verify all planned files | All present | -| Import resolution | Check no broken imports | All imports resolve | - -Auto-fix where possible: add missing cursor-pointer, basic focus styles. - -Update .msg/meta.json: merge `component_inventory` key with implemented file list. diff --git a/.claude/skills/team-frontend/role-specs/qa.md b/.claude/skills/team-frontend/role-specs/qa.md deleted file mode 100644 index 8b124c8e..00000000 --- a/.claude/skills/team-frontend/role-specs/qa.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -prefix: QA -inner_loop: false -message_types: - success: qa_passed - error: error ---- - -# QA Engineer - -Execute 5-dimension quality audit integrating ux-guidelines Do/Don't rules, pre-delivery checklist, and industry anti-pattern library. Perform CSS-level precise review on architecture artifacts and implementation code. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Review type | Extracted from task description | No (default: code-review) | -| Design intelligence | <session>/analysis/design-intelligence.json | No | -| Design tokens | <session>/architecture/design-tokens.json | No | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path and review type from task description -2. Load design intelligence (for anti-patterns, must-have rules) -3. Load design tokens (for compliance checks) -4. Load .msg/meta.json (for industry context, strictness level) -5. Collect files to review based on review type: - -| Type | Files to Review | -|------|-----------------| -| architecture-review | `<session>/architecture/**/*` | -| token-review | `<session>/architecture/**/*` | -| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` | -| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` | - -## Phase 3: 5-Dimension Audit - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Code Quality | 0.20 | Structure, naming, maintainability | -| Accessibility | 0.25 | WCAG compliance, keyboard nav, screen reader | -| Design Compliance | 0.20 | Anti-pattern check, design token usage | -| UX Best Practices | 0.20 | Interaction patterns, responsive, animations | -| Pre-Delivery | 0.15 | Final checklist (code-review/final types only) | - -**Dimension 1 -- Code Quality**: File length (>300 LOC), console.log, empty catch, unused imports. - -**Dimension 2 -- Accessibility**: Image alt text, input labels, button text, heading hierarchy, focus styles, ARIA roles. Strict mode (medical/financial): prefers-reduced-motion required. - -**Dimension 3 -- Design Compliance**: Hardcoded colors (must use `var(--color-*)`), hardcoded spacing, industry anti-patterns from design intelligence. - -**Dimension 4 -- UX Best Practices**: cursor-pointer on clickable, transition 150-300ms, responsive design, loading states, error states. - -**Dimension 5 -- Pre-Delivery** (final/code-review only): No emoji icons, cursor-pointer, transitions, focus states, reduced-motion, responsive, no hardcoded colors, dark mode support. - -**Score calculation**: `score = sum(dimension_score * weight)` - -**Verdict**: - -| Condition | Verdict | Message Type | -|-----------|---------|-------------| -| score >= 8 AND critical == 0 | PASSED | `qa_passed` | -| score >= 6 AND critical == 0 | PASSED_WITH_WARNINGS | `qa_result` | -| score < 6 OR critical > 0 | FIX_REQUIRED | `fix_required` | - -## Phase 4: Self-Review - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| All dimensions scored | Check 5 dimension scores | All present | -| Audit report written | File check | audit-NNN.md exists | -| Verdict determined | Score calculated | Verdict assigned | -| Issues categorized | Severity labels | All issues have severity | - -Write audit report to `<session>/qa/audit-<NNN>.md` with: summary, dimension scores, issues by severity, passed dimensions. - -Update .msg/meta.json: append to `qa_history` array. diff --git a/.claude/skills/team-issue/role-specs/explorer.md b/.claude/skills/team-issue/role-specs/explorer.md deleted file mode 100644 index 21e13fd2..00000000 --- a/.claude/skills/team-issue/role-specs/explorer.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -prefix: EXPLORE -inner_loop: false -message_types: - success: context_ready - error: error ---- - -# Issue Explorer - -Analyze issue context, explore codebase for relevant files, map dependencies and impact scope. Produce a shared context report for planner, reviewer, and implementer. - -## Phase 2: Issue Loading & Context Setup - -| Input | Source | Required | -|-------|--------|----------| -| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes | -| Issue details | `ccw issue status <id> --json` | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})` -2. If no issue ID found -> report error, STOP -3. Load issue details: - -``` -Bash("ccw issue status <issueId> --json") -``` - -4. Parse JSON response for issue metadata (title, context, priority, labels, feedback) -5. Load wisdom files from `<session>/wisdom/` if available - -## Phase 3: Codebase Exploration & Impact Analysis - -**Complexity assessment determines exploration depth**: - -| Signal | Weight | Keywords | -|--------|--------|----------| -| Structural change | +2 | refactor, architect, restructure, module, system | -| Cross-cutting | +2 | multiple, across, cross | -| Integration | +1 | integrate, api, database | -| High priority | +1 | priority >= 4 | - -| Score | Complexity | Strategy | -|-------|------------|----------| -| >= 4 | High | Deep exploration via CLI tool | -| 2-3 | Medium | Hybrid: ACE search + selective CLI | -| 0-1 | Low | Direct ACE search only | - -**Exploration execution**: - -| Complexity | Execution | -|------------|-----------| -| Low | Direct ACE search: `mcp__ace-tool__search_context(project_root_path, query)` | -| Medium/High | CLI exploration: `Bash("ccw cli -p \"<exploration_prompt>\" --tool gemini --mode analysis", { run_in_background: false })` | - -**CLI exploration prompt template**: - -``` -PURPOSE: Explore codebase for issue <issueId> to identify relevant files, dependencies, and impact scope; success = comprehensive context report written to <session>/explorations/context-<issueId>.json - -TASK: • Run ccw tool exec get_modules_by_depth '{}' • Execute ACE searches for issue keywords • Map file dependencies and integration points • Assess impact scope • Find existing patterns • Check git log for related changes - -MODE: analysis - -CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>) - -EXPECTED: JSON report with: relevant_files (path + relevance), dependencies, impact_scope (low/medium/high), existing_patterns, related_changes, key_findings, complexity_assessment - -CONSTRAINTS: Focus on issue context | Write output to <session>/explorations/context-<issueId>.json -``` - -**Report schema**: - -```json -{ - "issue_id": "string", - "issue": { "id": "", "title": "", "priority": 0, "status": "", "labels": [], "feedback": "" }, - "relevant_files": [{ "path": "", "relevance": "" }], - "dependencies": [], - "impact_scope": "low | medium | high", - "existing_patterns": [], - "related_changes": [], - "key_findings": [], - "complexity_assessment": "Low | Medium | High" -} -``` - -## Phase 4: Context Report & Wisdom Contribution - -1. Write context report to `<session>/explorations/context-<issueId>.json` -2. If file not found from agent, build minimal report from ACE results -3. Update `<session>/wisdom/.msg/meta.json` under `explorer` namespace: - - Read existing -> merge `{ "explorer": { issue_id, complexity, impact_scope, file_count } }` -> write back -4. Contribute discoveries to `<session>/wisdom/learnings.md` if new patterns found diff --git a/.claude/skills/team-issue/role-specs/implementer.md b/.claude/skills/team-issue/role-specs/implementer.md deleted file mode 100644 index a5a06c7c..00000000 --- a/.claude/skills/team-issue/role-specs/implementer.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -prefix: BUILD -inner_loop: false -message_types: - success: impl_complete - failed: impl_failed - error: error ---- - -# Issue Implementer - -Load solution plan, route to execution backend (Agent/Codex/Gemini), run tests, and commit. Execution method determined by coordinator during task creation. Supports parallel instances for batch mode. - -## Modes - -| Backend | Condition | Method | -|---------|-----------|--------| -| codex | task_count > 3 or explicit | `ccw cli --tool codex --mode write --id issue-<issueId>` | -| gemini | task_count <= 3 or explicit | `ccw cli --tool gemini --mode write --id issue-<issueId>` | -| qwen | explicit | `ccw cli --tool qwen --mode write --id issue-<issueId>` | - -## Phase 2: Load Solution & Resolve Executor - -| Input | Source | Required | -|-------|--------|----------| -| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes | -| Bound solution | `ccw issue solutions <id> --json` | Yes | -| Explorer context | `<session>/explorations/context-<issueId>.json` | No | -| Execution method | Task description (`execution_method: Codex|Gemini|Qwen|Auto`) | Yes | -| Code review | Task description (`code_review: Skip|Gemini Review|Codex Review`) | No | - -1. Extract issue ID from task description -2. If no issue ID -> report error, STOP -3. Load bound solution: `Bash("ccw issue solutions <issueId> --json")` -4. If no bound solution -> report error, STOP -5. Load explorer context (if available) -6. Resolve execution method (Auto: task_count <= 3 -> gemini, else codex) -7. Update issue status: `Bash("ccw issue update <issueId> --status in-progress")` - -## Phase 3: Implementation (Multi-Backend Routing) - -**Execution prompt template** (all backends): - -``` -## Issue -ID: <issueId> -Title: <solution.bound.title> - -## Solution Plan -<solution.bound JSON> - -## Codebase Context (from explorer) -Relevant files: <explorerContext.relevant_files> -Existing patterns: <explorerContext.existing_patterns> -Dependencies: <explorerContext.dependencies> - -## Implementation Requirements -1. Follow the solution plan tasks in order -2. Write clean, minimal code following existing patterns -3. Run tests after each significant change -4. Ensure all existing tests still pass -5. Do NOT over-engineer - -## Quality Checklist -- All solution tasks implemented -- No TypeScript/linting errors -- Existing tests pass -- New tests added where appropriate -``` - -Route by executor: -- **codex**: `Bash("ccw cli -p \"<prompt>\" --tool codex --mode write --id issue-<issueId>", { run_in_background: false })` -- **gemini**: `Bash("ccw cli -p \"<prompt>\" --tool gemini --mode write --id issue-<issueId>", { run_in_background: false })` -- **qwen**: `Bash("ccw cli -p \"<prompt>\" --tool qwen --mode write --id issue-<issueId>", { run_in_background: false })` - -On CLI failure, resume: `ccw cli -p "Continue" --resume issue-<issueId> --tool <tool> --mode write` - -## Phase 4: Verify & Commit - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Tests pass | Detect and run test command | No new failures | -| Code review | Optional, per task config | Review output logged | - -- Tests pass -> optional code review -> `ccw issue update <issueId> --status resolved` -> report `impl_complete` -- Tests fail -> report `impl_failed` with truncated test output - -Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace: -- Read existing -> merge `{ "implementer": { issue_id, executor, test_status, review_status } }` -> write back diff --git a/.claude/skills/team-issue/role-specs/integrator.md b/.claude/skills/team-issue/role-specs/integrator.md deleted file mode 100644 index e0e20b24..00000000 --- a/.claude/skills/team-issue/role-specs/integrator.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -prefix: MARSHAL -inner_loop: false -message_types: - success: queue_ready - conflict: conflict_found - error: error ---- - -# Issue Integrator - -Queue orchestration, conflict detection, and execution order optimization. Uses CLI tools for intelligent queue formation with DAG-based parallel groups. - -## Phase 2: Collect Bound Solutions - -| Input | Source | Required | -|-------|--------|----------| -| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes | -| Bound solutions | `ccw issue solutions <id> --json` | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract issue IDs from task description via regex -2. Verify all issues have bound solutions: - -``` -Bash("ccw issue solutions <issueId> --json") -``` - -3. Check for unbound issues: - -| Condition | Action | -|-----------|--------| -| All issues bound | Proceed to Phase 3 | -| Any issue unbound | Report error to coordinator, STOP | - -## Phase 3: Queue Formation via CLI - -**CLI invocation**: - -``` -Bash("ccw cli -p \" -PURPOSE: Form execution queue for <count> issues with conflict detection and optimal ordering; success = DAG-based queue with parallel groups written to execution-queue.json - -TASK: • Load all bound solutions from .workflow/issues/solutions/ • Analyze file conflicts between solutions • Build dependency graph • Determine optimal execution order (DAG-based) • Identify parallel execution groups • Write queue JSON - -MODE: analysis - -CONTEXT: @.workflow/issues/solutions/**/*.json | Memory: Issues to queue: <issueIds> - -EXPECTED: Queue JSON with: ordered issue list, conflict analysis, parallel_groups (issues that can run concurrently), depends_on relationships -Write to: .workflow/issues/queue/execution-queue.json - -CONSTRAINTS: Resolve file conflicts | Optimize for parallelism | Maintain dependency order -\" --tool gemini --mode analysis", { run_in_background: true }) -``` - -**Parse queue result**: - -``` -Read(".workflow/issues/queue/execution-queue.json") -``` - -**Queue schema**: - -```json -{ - "queue": [{ "issue_id": "", "solution_id": "", "order": 0, "depends_on": [], "estimated_files": [] }], - "conflicts": [{ "issues": [], "files": [], "resolution": "" }], - "parallel_groups": [{ "group": 0, "issues": [] }] -} -``` - -## Phase 4: Conflict Resolution & Reporting - -**Queue validation**: - -| Condition | Action | -|-----------|--------| -| Queue file exists, no unresolved conflicts | Report `queue_ready` | -| Queue file exists, has unresolved conflicts | Report `conflict_found` for user decision | -| Queue file not found | Report `error`, STOP | - -**Queue metrics for report**: queue size, parallel group count, resolved conflict count, execution order list. - -Update `<session>/wisdom/.msg/meta.json` under `integrator` namespace: -- Read existing -> merge `{ "integrator": { queue_size, parallel_groups, conflict_count } }` -> write back diff --git a/.claude/skills/team-issue/role-specs/planner.md b/.claude/skills/team-issue/role-specs/planner.md deleted file mode 100644 index a51bdc15..00000000 --- a/.claude/skills/team-issue/role-specs/planner.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -prefix: SOLVE -inner_loop: false -additional_prefixes: [SOLVE-fix] -message_types: - success: solution_ready - multi: multi_solution - error: error ---- - -# Issue Planner - -Design solutions and decompose into implementation tasks. Uses CLI tools for ACE exploration and solution generation. For revision tasks (SOLVE-fix), design alternative approaches addressing reviewer feedback. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes | -| Explorer context | `<session>/explorations/context-<issueId>.json` | No | -| Review feedback | Task description (for SOLVE-fix tasks) | No | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})` -2. If no issue ID found -> report error, STOP -3. Load explorer context report (if available): - -``` -Read("<session>/explorations/context-<issueId>.json") -``` - -4. Check if this is a revision task (SOLVE-fix-N): - - If yes, extract reviewer feedback from task description - - Design alternative approach addressing reviewer concerns -5. Load wisdom files for accumulated codebase knowledge - -## Phase 3: Solution Generation via CLI - -**CLI invocation**: - -``` -Bash("ccw cli -p \" -PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution bound to issue with task breakdown - -TASK: • Load issue details from ccw issue status • Analyze explorer context • Design solution approach • Break down into implementation tasks • Generate solution JSON • Bind solution to issue - -MODE: analysis - -CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>) -Explorer findings: <explorerContext.key_findings> -Relevant files: <explorerContext.relevant_files> -Complexity: <explorerContext.complexity_assessment> - -EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks (ordered list with descriptions), estimated_files, dependencies -Write to: <session>/solutions/solution-<issueId>.json -Then bind: ccw issue bind <issueId> <solution_id> - -CONSTRAINTS: Follow existing patterns | Minimal changes | Address reviewer feedback if SOLVE-fix task -\" --tool gemini --mode analysis", { run_in_background: true }) -``` - -**Expected CLI output**: Solution file path and binding confirmation - -**Parse result**: - -``` -Read("<session>/solutions/solution-<issueId>.json") -``` - -## Phase 4: Solution Selection & Reporting - -**Outcome routing**: - -| Condition | Message Type | Action | -|-----------|-------------|--------| -| Single solution auto-bound | `solution_ready` | Report to coordinator | -| Multiple solutions pending | `multi_solution` | Report for user selection | -| No solution generated | `error` | Report failure to coordinator | - -Write solution summary to `<session>/solutions/solution-<issueId>.json`. - -Update `<session>/wisdom/.msg/meta.json` under `planner` namespace: -- Read existing -> merge `{ "planner": { issue_id, solution_id, task_count, is_revision } }` -> write back diff --git a/.claude/skills/team-issue/role-specs/reviewer.md b/.claude/skills/team-issue/role-specs/reviewer.md deleted file mode 100644 index aadbfdf8..00000000 --- a/.claude/skills/team-issue/role-specs/reviewer.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -prefix: AUDIT -inner_loop: false -message_types: - success: approved - concerns: concerns - rejected: rejected - error: error ---- - -# Issue Reviewer - -Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns. - -## Phase 2: Context & Solution Loading - -| Input | Source | Required | -|-------|--------|----------| -| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes | -| Explorer context | `<session>/explorations/context-<issueId>.json` | No | -| Bound solution | `ccw issue solutions <id> --json` | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract issue IDs from task description via regex -2. Load explorer context reports for each issue -3. Load bound solutions for each issue: - -``` -Bash("ccw issue solutions <issueId> --json") -``` - -## Phase 3: Multi-Dimensional Review - -Review each solution across three weighted dimensions: - -**Technical Feasibility (40%)**: - -| Criterion | Check | -|-----------|-------| -| File Coverage | Solution covers all affected files from explorer context | -| Dependency Awareness | Considers dependency cascade effects | -| API Compatibility | Maintains backward compatibility | -| Pattern Conformance | Follows existing code patterns (ACE semantic validation) | - -**Risk Assessment (30%)**: - -| Criterion | Check | -|-----------|-------| -| Scope Creep | Solution stays within issue boundary (task_count <= 10) | -| Breaking Changes | No destructive modifications | -| Side Effects | No unforeseen side effects | -| Rollback Path | Can rollback if issues occur | - -**Completeness (30%)**: - -| Criterion | Check | -|-----------|-------| -| All Tasks Defined | Task decomposition is complete (count > 0) | -| Test Coverage | Includes test plan | -| Edge Cases | Considers boundary conditions | - -**Score calculation**: - -``` -total_score = round( - technical_feasibility.score * 0.4 + - risk_assessment.score * 0.3 + - completeness.score * 0.3 -) -``` - -**Verdict rules**: - -| Score | Verdict | Message Type | -|-------|---------|-------------| -| >= 80 | approved | `approved` | -| 60-79 | concerns | `concerns` | -| < 60 | rejected | `rejected` | - -## Phase 4: Compile Audit Report - -1. Write audit report to `<session>/audits/audit-report.json`: - - Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings - - Overall verdict (any rejected -> overall rejected) - -2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace: - - Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back - -3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation diff --git a/.claude/skills/team-iterdev/role-specs/architect.md b/.claude/skills/team-iterdev/role-specs/architect.md deleted file mode 100644 index 652a64b1..00000000 --- a/.claude/skills/team-iterdev/role-specs/architect.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -prefix: DESIGN -inner_loop: false -message_types: - success: design_ready - revision: design_revision - error: error ---- - -# Architect - -Technical design, task decomposition, and architecture decision records for iterative development. - -## Phase 2: Context Loading + Codebase Exploration - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | -| Wisdom files | <session>/wisdom/ | No | - -1. Extract session path and requirement from task description -2. Read .msg/meta.json for shared context (architecture_decisions, implementation_context) -3. Read wisdom files if available (learnings.md, decisions.md, conventions.md) -4. Explore codebase for existing patterns, module structure, dependencies: - - Use mcp__ace-tool__search_context for semantic discovery - - Identify similar implementations and integration points - -## Phase 3: Technical Design + Task Decomposition - -**Design strategy selection**: - -| Condition | Strategy | -|-----------|----------| -| Single module change | Direct inline design | -| Cross-module change | Multi-component design with integration points | -| Large refactoring | Phased approach with milestones | - -**Outputs**: - -1. **Design Document** (`<session>/design/design-<num>.md`): - - Architecture decision: approach, rationale, alternatives - - Component design: responsibility, dependencies, files, complexity - - Task breakdown: files, estimated complexity, dependencies, acceptance criteria - - Integration points and risks with mitigations - -2. **Task Breakdown JSON** (`<session>/design/task-breakdown.json`): - - Array of tasks with id, title, files, complexity, dependencies, acceptance_criteria - - Execution order for developer to follow - -## Phase 4: Design Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Components defined | Verify component list | At least 1 component | -| Task breakdown exists | Verify task list | At least 1 task | -| Dependencies mapped | All components have dependencies field | All present (can be empty) | -| Integration points | Verify integration section | Key integrations documented | - -1. Run validation checks above -2. Write architecture_decisions entry to .msg/meta.json: - - design_id, approach, rationale, components, task_count -3. Write discoveries to wisdom/decisions.md and wisdom/conventions.md diff --git a/.claude/skills/team-iterdev/role-specs/developer.md b/.claude/skills/team-iterdev/role-specs/developer.md deleted file mode 100644 index 8cbd2a1b..00000000 --- a/.claude/skills/team-iterdev/role-specs/developer.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -prefix: DEV -inner_loop: true -message_types: - success: dev_complete - progress: dev_progress - error: error ---- - -# Developer - -Code implementer. Implements code according to design, incremental delivery. Acts as Generator in Generator-Critic loop (paired with reviewer). - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Design document | <session>/design/design-001.md | For non-fix tasks | -| Task breakdown | <session>/design/task-breakdown.json | For non-fix tasks | -| Review feedback | <session>/review/*.md | For fix tasks | -| Wisdom files | <session>/wisdom/ | No | - -1. Extract session path from task description -2. Read .msg/meta.json for shared context -3. Detect task type: - -| Task Type | Detection | Loading | -|-----------|-----------|---------| -| Fix task | Subject contains "fix" | Read latest review file for feedback | -| Normal task | No "fix" in subject | Read design document + task breakdown | - -4. Load previous implementation_context from .msg/meta.json -5. Read wisdom files for conventions and known issues - -## Phase 3: Code Implementation - -**Implementation strategy selection**: - -| Task Count | Complexity | Strategy | -|------------|------------|----------| -| <= 2 tasks | Low | Direct: inline Edit/Write | -| 3-5 tasks | Medium | Single agent: one code-developer for all | -| > 5 tasks | High | Batch agent: group by module, one agent per batch | - -**Fix Task Mode** (GC Loop): -- Focus on review feedback items only -- Fix critical issues first, then high, then medium -- Do NOT change code that was not flagged -- Maintain existing code style and patterns - -**Normal Task Mode**: -- Read target files, apply changes using Edit or Write -- Follow execution order from task breakdown -- Validate syntax after each major change - -## Phase 4: Self-Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Syntax | tsc --noEmit or equivalent | No errors | -| File existence | Verify all planned files exist | All files present | -| Import resolution | Check no broken imports | All imports resolve | - -1. Run syntax check: `tsc --noEmit` / `python -m py_compile` / equivalent -2. Auto-fix if validation fails (max 2 attempts) -3. Write dev log to `<session>/code/dev-log.md`: - - Changed files count, syntax status, fix task flag, file list -4. Update implementation_context in .msg/meta.json: - - task, changed_files, is_fix, syntax_clean -5. Write discoveries to wisdom/learnings.md diff --git a/.claude/skills/team-iterdev/role-specs/reviewer.md b/.claude/skills/team-iterdev/role-specs/reviewer.md deleted file mode 100644 index 026b1988..00000000 --- a/.claude/skills/team-iterdev/role-specs/reviewer.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -prefix: REVIEW -inner_loop: false -message_types: - success: review_passed - revision: review_revision - critical: review_critical - error: error ---- - -# Reviewer - -Code reviewer. Multi-dimensional review, quality scoring, improvement suggestions. Acts as Critic in Generator-Critic loop (paired with developer). - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Design document | <session>/design/design-001.md | For requirements alignment | -| Changed files | Git diff | Yes | - -1. Extract session path from task description -2. Read .msg/meta.json for shared context and previous review_feedback_trends -3. Read design document for requirements alignment -4. Get changed files via git diff, read file contents (limit 20 files) - -## Phase 3: Multi-Dimensional Review - -**Review dimensions**: - -| Dimension | Weight | Focus Areas | -|-----------|--------|-------------| -| Correctness | 30% | Logic correctness, boundary handling | -| Completeness | 25% | Coverage of design requirements | -| Maintainability | 25% | Readability, code style, DRY | -| Security | 20% | Vulnerabilities, input validation | - -Per-dimension: scan modified files, record findings with severity (CRITICAL/HIGH/MEDIUM/LOW), include file:line references and suggestions. - -**Scoring**: Weighted average of dimension scores (1-10 each). - -**Output review report** (`<session>/review/review-<num>.md`): -- Files reviewed count, quality score, issue counts by severity -- Per-finding: severity, file:line, dimension, description, suggestion -- Scoring breakdown by dimension -- Signal: CRITICAL / REVISION_NEEDED / APPROVED -- Design alignment notes - -## Phase 4: Trend Analysis + Verdict - -1. Compare with previous review_feedback_trends from .msg/meta.json -2. Identify recurring issues, improvement areas, new issues - -| Verdict Condition | Message Type | -|-------------------|--------------| -| criticalCount > 0 | review_critical | -| score < 7 | review_revision | -| else | review_passed | - -3. Update review_feedback_trends in .msg/meta.json: - - review_id, score, critical count, high count, dimensions, gc_round -4. Write discoveries to wisdom/learnings.md diff --git a/.claude/skills/team-iterdev/role-specs/tester.md b/.claude/skills/team-iterdev/role-specs/tester.md deleted file mode 100644 index cccd94b9..00000000 --- a/.claude/skills/team-iterdev/role-specs/tester.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -prefix: VERIFY -inner_loop: false -message_types: - success: verify_passed - failure: verify_failed - fix: fix_required - error: error ---- - -# Tester - -Test validator. Test execution, fix cycles, and regression detection. - -## Phase 2: Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Changed files | Git diff | Yes | - -1. Extract session path from task description -2. Read .msg/meta.json for shared context -3. Get changed files via git diff -4. Detect test framework and command: - -| Detection | Method | -|-----------|--------| -| Test command | Check package.json scripts, pytest.ini, Makefile | -| Coverage tool | Check for nyc, coverage.py, jest --coverage config | - -Common commands: npm test, pytest, go test ./..., cargo test - -## Phase 3: Execution + Fix Cycle - -**Iterative test-fix cycle** (max 5 iterations): - -| Step | Action | -|------|--------| -| 1 | Run test command | -| 2 | Parse results, check pass rate | -| 3 | Pass rate >= 95% -> exit loop (success) | -| 4 | Extract failing test details | -| 5 | Apply fix using CLI tool | -| 6 | Increment iteration counter | -| 7 | iteration >= MAX (5) -> exit loop (report failures) | -| 8 | Go to Step 1 | - -**Fix delegation**: Use CLI tool to fix failing tests: - -```bash -ccw cli -p "PURPOSE: Fix failing tests; success = all listed tests pass -TASK: • Analyze test failure output • Identify root cause in changed files • Apply minimal fix -MODE: write -CONTEXT: @<changed-files> | Memory: Test output from current iteration -EXPECTED: Code fixes that make failing tests pass without breaking other tests -CONSTRAINTS: Only modify files in changed list | Minimal changes -Test output: <test-failure-details> -Changed files: <file-list>" --tool gemini --mode write --rule development-debug-runtime-issues -``` - -Wait for CLI completion before re-running tests. - -## Phase 4: Regression Check + Report - -1. Run full test suite for regression: `<test-command> --all` - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Regression | Run full test suite | No FAIL in output | -| Coverage | Run coverage tool | >= 80% (if configured) | - -2. Write verification results to `<session>/verify/verify-<num>.json`: - - verify_id, pass_rate, iterations, passed, timestamp, regression_passed - -3. Determine message type: - -| Condition | Message Type | -|-----------|--------------| -| passRate >= 0.95 | verify_passed | -| passRate < 0.95 && iterations >= MAX | fix_required | -| passRate < 0.95 | verify_failed | - -4. Update .msg/meta.json with test_patterns entry -5. Write discoveries to wisdom/issues.md diff --git a/.claude/skills/team-perf-opt/role-specs/benchmarker.md b/.claude/skills/team-perf-opt/role-specs/benchmarker.md deleted file mode 100644 index 172333ac..00000000 --- a/.claude/skills/team-perf-opt/role-specs/benchmarker.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -prefix: BENCH -inner_loop: false -message_types: - success: bench_complete - error: error - fix: fix_required ---- - -# Performance Benchmarker - -Run benchmarks comparing before/after optimization metrics. Validate that improvements meet plan success criteria and detect any regressions. - -## Phase 2: Environment & Baseline Loading - -| Input | Source | Required | -|-------|--------|----------| -| Baseline metrics | <session>/artifacts/baseline-metrics.json (shared) | Yes | -| Optimization plan / detail | Varies by mode (see below) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | - -1. Extract session path from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|---------| -| `BranchId: B{NN}` | Present | Fan-out branch -- benchmark only this branch's metrics | -| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline | -| Neither present | - | Single mode -- full benchmark | - -3. **Load baseline metrics**: - - Single / Fan-out: Read `<session>/artifacts/baseline-metrics.json` (shared baseline) - - Independent: Read `<session>/artifacts/pipelines/{P}/baseline-metrics.json` - -4. **Load optimization context**: - - Single: Read `<session>/artifacts/optimization-plan.md` -- all success criteria - - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` -- only this branch's criteria - - Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md` - -5. Load .msg/meta.json for project type and optimization scope -6. Detect available benchmark tools from project: - -| Signal | Benchmark Tool | Method | -|--------|---------------|--------| -| package.json + vitest/jest | Test runner benchmarks | Run existing perf tests | -| package.json + webpack/vite | Bundle analysis | Compare build output sizes | -| Cargo.toml + criterion | Rust benchmarks | cargo bench | -| go.mod | Go benchmarks | go test -bench | -| Makefile with bench target | Custom benchmarks | make bench | -| No tooling detected | Manual measurement | Timed execution via Bash | - -7. Get changed files scope from shared-memory: - - Single: `optimizer` namespace - - Fan-out: `optimizer.B{NN}` namespace - - Independent: `optimizer.{P}` namespace - -## Phase 3: Benchmark Execution - -Run benchmarks matching detected project type: - -**Frontend benchmarks**: -- Compare bundle size before/after (build output analysis) -- Measure render performance for affected components -- Check for dependency weight changes - -**Backend benchmarks**: -- Measure endpoint response times for affected routes -- Profile memory usage under simulated load -- Verify database query performance improvements - -**CLI / Library benchmarks**: -- Measure execution time for representative workloads -- Compare memory peak usage -- Test throughput under sustained load - -**All project types**: -- Run existing test suite to verify no regressions -- Collect post-optimization metrics matching baseline format -- Calculate improvement percentages per metric - -**Branch-scoped benchmarking** (fan-out mode): -- Only benchmark metrics relevant to this branch's optimization (from optimization-detail.md) -- Still check for regressions across all metrics (not just branch-specific ones) - -## Phase 4: Result Analysis - -Compare against baseline and plan criteria: - -| Metric | Threshold | Verdict | -|--------|-----------|---------| -| Target improvement vs baseline | Meets plan success criteria | PASS | -| No regression in unrelated metrics | < 5% degradation allowed | PASS | -| All plan success criteria met | Every criterion satisfied | PASS | -| Improvement below target | > 50% of target achieved | WARN | -| Regression detected | Any unrelated metric degrades > 5% | FAIL -> fix_required | -| Plan criteria not met | Any criterion not satisfied | FAIL -> fix_required | - -1. Write benchmark results to output path: - - Single: `<session>/artifacts/benchmark-results.json` - - Fan-out: `<session>/artifacts/branches/B{NN}/benchmark-results.json` - - Independent: `<session>/artifacts/pipelines/{P}/benchmark-results.json` - - Content: Per-metric: name, baseline value, current value, improvement %, verdict; Overall verdict: PASS / WARN / FAIL; Regression details (if any) - -2. Update `<session>/.msg/meta.json` under scoped namespace: - - Single: merge `{ "benchmarker": { verdict, improvements, regressions } }` - - Fan-out: merge `{ "benchmarker.B{NN}": { verdict, improvements, regressions } }` - - Independent: merge `{ "benchmarker.{P}": { verdict, improvements, regressions } }` - -3. If verdict is FAIL, include detailed feedback in message for FIX task creation: - - Which metrics failed, by how much, suggested investigation areas diff --git a/.claude/skills/team-perf-opt/role-specs/optimizer.md b/.claude/skills/team-perf-opt/role-specs/optimizer.md deleted file mode 100644 index b7df525a..00000000 --- a/.claude/skills/team-perf-opt/role-specs/optimizer.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -prefix: IMPL -inner_loop: true -additional_prefixes: [FIX] -delegates_to: [] -message_types: - success: impl_complete - error: error - fix: fix_required ---- - -# Code Optimizer - -Implement optimization changes following the strategy plan. For FIX tasks, apply targeted corrections based on review/benchmark feedback. - -## Modes - -| Mode | Task Prefix | Trigger | Focus | -|------|-------------|---------|-------| -| Implement | IMPL | Strategy plan ready | Apply optimizations per plan priority | -| Fix | FIX | Review/bench feedback | Targeted fixes for identified issues | - -## Phase 2: Plan & Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Optimization plan | <session>/artifacts/optimization-plan.md | Yes (IMPL, no branch) | -| Branch optimization detail | <session>/artifacts/branches/B{NN}/optimization-detail.md | Yes (IMPL with branch) | -| Pipeline optimization plan | <session>/artifacts/pipelines/{P}/optimization-plan.md | Yes (IMPL with pipeline) | -| Review/bench feedback | From task description | Yes (FIX) | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Wisdom files | <session>/wisdom/patterns.md | No | -| Context accumulator | From prior IMPL/FIX tasks | Yes (inner loop) | - -1. Extract session path and task mode (IMPL or FIX) from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|---------| -| `BranchId: B{NN}` | Present | Fan-out branch -- load single optimization detail | -| `PipelineId: {P}` | Present | Independent pipeline -- load pipeline-scoped plan | -| Neither present | - | Single mode -- load full optimization plan | - -3. **Load optimization context by mode**: - - **Single mode (no branch)**: Read `<session>/artifacts/optimization-plan.md` -- extract ALL priority-ordered changes - - **Fan-out branch**: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` -- extract ONLY this branch's optimization (single OPT-ID) - - **Independent pipeline**: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md` -- extract this pipeline's plan - -4. For FIX: parse review/benchmark feedback for specific issues to address -5. Use ACE search or CLI tools to load implementation context for target files -6. For inner loop (single mode only): load context_accumulator from prior IMPL/FIX tasks - -**Shared-memory namespace**: -- Single: write to `optimizer` namespace -- Fan-out: write to `optimizer.B{NN}` namespace -- Independent: write to `optimizer.{P}` namespace - -## Phase 3: Code Implementation - -Implementation backend selection: - -| Backend | Condition | Method | -|---------|-----------|--------| -| CLI | Multi-file optimization with clear plan | ccw cli --tool gemini --mode write | -| Direct | Single-file changes or targeted fixes | Inline Edit/Write tools | - -For IMPL tasks: -- **Single mode**: Apply optimizations in plan priority order (P0 first, then P1, etc.) -- **Fan-out branch**: Apply ONLY this branch's single optimization (from optimization-detail.md) -- **Independent pipeline**: Apply this pipeline's optimizations in priority order -- Follow implementation guidance from plan (target files, patterns) -- Preserve existing behavior -- optimization must not break functionality - -For FIX tasks: -- Read specific issues from review/benchmark feedback -- Apply targeted corrections to flagged code locations -- Verify the fix addresses the exact concern raised - -General rules: -- Make minimal, focused changes per optimization -- Add comments only where optimization logic is non-obvious -- Preserve existing code style and conventions - -## Phase 4: Self-Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Syntax | IDE diagnostics or build check | No new errors | -| File integrity | Verify all planned files exist and are modified | All present | -| Acceptance | Match optimization plan success criteria | All target metrics addressed | -| No regression | Run existing tests if available | No new failures | - -If validation fails, attempt auto-fix (max 2 attempts) before reporting error. - -Append to context_accumulator for next IMPL/FIX task (single/inner-loop mode only): -- Files modified, optimizations applied, validation results -- Any discovered patterns or caveats for subsequent iterations - -**Branch output paths**: -- Single: write artifacts to `<session>/artifacts/` -- Fan-out: write artifacts to `<session>/artifacts/branches/B{NN}/` -- Independent: write artifacts to `<session>/artifacts/pipelines/{P}/` diff --git a/.claude/skills/team-perf-opt/role-specs/profiler.md b/.claude/skills/team-perf-opt/role-specs/profiler.md deleted file mode 100644 index 5046ec59..00000000 --- a/.claude/skills/team-perf-opt/role-specs/profiler.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -prefix: PROFILE -inner_loop: false -delegates_to: [] -message_types: - success: profile_complete - error: error ---- - -# Performance Profiler - -Profile application performance to identify CPU, memory, I/O, network, and rendering bottlenecks. Produce quantified baseline metrics and a ranked bottleneck report. - -## Phase 2: Context & Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path and target scope from task description -2. Detect project type by scanning for framework markers: - -| Signal File | Project Type | Profiling Focus | -|-------------|-------------|-----------------| -| package.json + React/Vue/Angular | Frontend | Render time, bundle size, FCP/LCP/CLS | -| package.json + Express/Fastify/NestJS | Backend Node | CPU hotspots, memory, DB queries | -| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | CPU, memory, GC tuning | -| Mixed framework markers | Full-stack | Split into FE + BE profiling passes | -| CLI entry / bin/ directory | CLI Tool | Startup time, throughput, memory peak | -| No detection | Generic | All profiling dimensions | - -3. Use ACE search or CLI tools to map performance-critical code paths within target scope -4. Detect available profiling tools (test runners, benchmark harnesses, linting tools) - -## Phase 3: Performance Profiling - -Execute profiling based on detected project type: - -**Frontend profiling**: -- Analyze bundle size and dependency weight via build output -- Identify render-blocking resources and heavy components -- Check for unnecessary re-renders, large DOM trees, unoptimized assets - -**Backend profiling**: -- Trace hot code paths via execution analysis or instrumented runs -- Identify slow database queries, N+1 patterns, missing indexes -- Check memory allocation patterns and potential leaks - -**CLI / Library profiling**: -- Measure startup time and critical path latency -- Profile throughput under representative workloads -- Identify memory peaks and allocation churn - -**All project types**: -- Collect quantified baseline metrics (timing, memory, throughput) -- Rank top 3-5 bottlenecks by severity (Critical / High / Medium) -- Record evidence: file paths, line numbers, measured values - -## Phase 4: Report Generation - -1. Write baseline metrics to `<session>/artifacts/baseline-metrics.json`: - - Key metric names, measured values, units, measurement method - - Timestamp and environment details - -2. Write bottleneck report to `<session>/artifacts/bottleneck-report.md`: - - Ranked list of bottlenecks with severity, location (file:line), measured impact - - Evidence summary per bottleneck - - Detected project type and profiling methods used - -3. Update `<session>/.msg/meta.json` under `profiler` namespace: - - Read existing -> merge `{ "profiler": { project_type, bottleneck_count, top_bottleneck, scope } }` -> write back diff --git a/.claude/skills/team-perf-opt/role-specs/reviewer.md b/.claude/skills/team-perf-opt/role-specs/reviewer.md deleted file mode 100644 index 7de0b459..00000000 --- a/.claude/skills/team-perf-opt/role-specs/reviewer.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -prefix: REVIEW -inner_loop: false -additional_prefixes: [QUALITY] -discuss_rounds: [DISCUSS-REVIEW] -delegates_to: [] -message_types: - success: review_complete - error: error - fix: fix_required ---- - -# Optimization Reviewer - -Review optimization code changes for correctness, side effects, regression risks, and adherence to best practices. Provide structured verdicts with actionable feedback. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Optimization code changes | From IMPL task artifacts / git diff | Yes | -| Optimization plan / detail | Varies by mode (see below) | Yes | -| Benchmark results | Varies by mode (see below) | No | -| .msg/meta.json | <session>/.msg/meta.json | Yes | - -1. Extract session path from task description -2. **Detect branch/pipeline context** from task description: - -| Task Description Field | Value | Context | -|----------------------|-------|---------| -| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes | -| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes | -| Neither present | - | Single mode -- review all optimization changes | - -3. **Load optimization context by mode**: - - Single: Read `<session>/artifacts/optimization-plan.md` - - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md` - - Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md` - -4. Load .msg/meta.json for scoped optimizer namespace: - - Single: `optimizer` namespace - - Fan-out: `optimizer.B{NN}` namespace - - Independent: `optimizer.{P}` namespace - -5. Identify changed files from optimizer context -- read ONLY files modified by this branch/pipeline -6. If benchmark results available, read from scoped path: - - Single: `<session>/artifacts/benchmark-results.json` - - Fan-out: `<session>/artifacts/branches/B{NN}/benchmark-results.json` - - Independent: `<session>/artifacts/pipelines/{P}/benchmark-results.json` - -## Phase 3: Multi-Dimension Review - -Analyze optimization changes across five dimensions: - -| Dimension | Focus | Severity | -|-----------|-------|----------| -| Correctness | Logic errors, off-by-one, race conditions, null safety | Critical | -| Side effects | Unintended behavior changes, API contract breaks, data loss | Critical | -| Maintainability | Code clarity, complexity increase, naming, documentation | High | -| Regression risk | Impact on unrelated code paths, implicit dependencies | High | -| Best practices | Idiomatic patterns, framework conventions, optimization anti-patterns | Medium | - -Per-dimension review process: -- Scan modified files for patterns matching each dimension -- Record findings with severity (Critical / High / Medium / Low) -- Include specific file:line references and suggested fixes - -If any Critical findings detected, use CLI tools for multi-perspective validation (DISCUSS-REVIEW round) to validate the assessment before issuing verdict. - -## Phase 4: Verdict & Feedback - -Classify overall verdict based on findings: - -| Verdict | Condition | Action | -|---------|-----------|--------| -| APPROVE | No Critical or High findings | Send review_complete | -| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback | -| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for strategist escalation | - -1. Write review report to scoped output path: - - Single: `<session>/artifacts/review-report.md` - - Fan-out: `<session>/artifacts/branches/B{NN}/review-report.md` - - Independent: `<session>/artifacts/pipelines/{P}/review-report.md` - - Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts - -2. Update `<session>/.msg/meta.json` under scoped namespace: - - Single: merge `{ "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }` - - Fan-out: merge `{ "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }` - - Independent: merge `{ "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }` - -3. If DISCUSS-REVIEW was triggered, record discussion summary in `<session>/discussions/DISCUSS-REVIEW.md` (or `DISCUSS-REVIEW-B{NN}.md` for branch-scoped discussions) diff --git a/.claude/skills/team-perf-opt/role-specs/strategist.md b/.claude/skills/team-perf-opt/role-specs/strategist.md deleted file mode 100644 index 67b60a6c..00000000 --- a/.claude/skills/team-perf-opt/role-specs/strategist.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -prefix: STRATEGY -inner_loop: false -discuss_rounds: [DISCUSS-OPT] -delegates_to: [] -message_types: - success: strategy_complete - error: error ---- - -# Optimization Strategist - -Analyze bottleneck reports and baseline metrics to design a prioritized optimization plan with concrete strategies, expected improvements, and risk assessments. - -## Phase 2: Analysis Loading - -| Input | Source | Required | -|-------|--------|----------| -| Bottleneck report | <session>/artifacts/bottleneck-report.md | Yes | -| Baseline metrics | <session>/artifacts/baseline-metrics.json | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Wisdom files | <session>/wisdom/patterns.md | No | - -1. Extract session path from task description -2. Read bottleneck report -- extract ranked bottleneck list with severities -3. Read baseline metrics -- extract current performance numbers -4. Load .msg/meta.json for profiler findings (project_type, scope) -5. Assess overall optimization complexity: - -| Bottleneck Count | Severity Mix | Complexity | -|-----------------|-------------|------------| -| 1-2 | All Medium | Low | -| 2-3 | Mix of High/Medium | Medium | -| 3+ or any Critical | Any Critical present | High | - -## Phase 3: Strategy Formulation - -For each bottleneck, select optimization approach by type: - -| Bottleneck Type | Strategies | Risk Level | -|----------------|-----------|------------| -| CPU hotspot | Algorithm optimization, memoization, caching, worker threads | Medium | -| Memory leak/bloat | Pool reuse, lazy initialization, WeakRef, scope cleanup | High | -| I/O bound | Batching, async pipelines, streaming, connection pooling | Medium | -| Network latency | Request coalescing, compression, CDN, prefetching | Low | -| Rendering | Virtualization, memoization, CSS containment, code splitting | Medium | -| Database | Index optimization, query rewriting, caching layer, denormalization | High | - -Prioritize optimizations by impact/effort ratio: - -| Priority | Criteria | -|----------|----------| -| P0 (Critical) | High impact + Low effort -- quick wins | -| P1 (High) | High impact + Medium effort | -| P2 (Medium) | Medium impact + Low effort | -| P3 (Low) | Low impact or High effort -- defer | - -If complexity is High, use CLI tools for multi-perspective analysis (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan. - -Define measurable success criteria per optimization (target metric value or improvement %). - -## Phase 4: Plan Output - -1. Write optimization plan to `<session>/artifacts/optimization-plan.md`: - - Each optimization MUST have a unique OPT-ID and self-contained detail block: - - ```markdown - ### OPT-001: <title> - - Priority: P0 - - Target bottleneck: <bottleneck from report> - - Target files: <file-list> - - Strategy: <selected approach> - - Expected improvement: <metric> by <X%> - - Risk level: <Low/Medium/High> - - Success criteria: <specific threshold to verify> - - Implementation guidance: - 1. <step 1> - 2. <step 2> - 3. <step 3> - - ### OPT-002: <title> - ... - ``` - - Requirements: - - Each OPT-ID is sequentially numbered (OPT-001, OPT-002, ...) - - Each optimization must be **non-overlapping** in target files (no two OPT-IDs modify the same file unless explicitly noted with conflict resolution) - - Implementation guidance must be self-contained -- a branch optimizer should be able to work from a single OPT block without reading others - -2. Update `<session>/.msg/meta.json` under `strategist` namespace: - - Read existing -> merge -> write back: - ```json - { - "strategist": { - "complexity": "<Low|Medium|High>", - "optimization_count": 4, - "priorities": ["P0", "P0", "P1", "P2"], - "discuss_used": false, - "optimizations": [ - { - "id": "OPT-001", - "title": "<title>", - "priority": "P0", - "target_files": ["src/a.ts", "src/b.ts"], - "expected_improvement": "<metric> by <X%>", - "success_criteria": "<threshold>" - } - ] - } - } - ``` - -3. If DISCUSS-OPT was triggered, record discussion summary in `<session>/discussions/DISCUSS-OPT.md` diff --git a/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md b/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md index a4f198fe..a3a29b29 100644 --- a/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md @@ -73,7 +73,7 @@ Agent({ run_in_background: true, prompt: `## Role Assignment role: <role> -role_spec: ~ or <project>/.claude/skills/team-perf-opt/role-specs/<role>.md +role_spec: ~ or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md session: <session-folder> session_id: <session-id> team_name: perf-opt diff --git a/.claude/skills/team-perf-opt/specs/team-config.json b/.claude/skills/team-perf-opt/specs/team-config.json index 9352e30f..12f37a3f 100644 --- a/.claude/skills/team-perf-opt/specs/team-config.json +++ b/.claude/skills/team-perf-opt/specs/team-config.json @@ -24,7 +24,7 @@ "name": "profiler", "type": "orchestration", "description": "Profiles application performance, identifies CPU/memory/IO/network/rendering bottlenecks", - "role_spec": "role-specs/profiler.md", + "role_spec": "roles/profiler/role.md", "inner_loop": false, "frontmatter": { "prefix": "PROFILE", @@ -44,7 +44,7 @@ "name": "strategist", "type": "orchestration", "description": "Analyzes bottleneck reports, designs prioritized optimization plans with concrete strategies", - "role_spec": "role-specs/strategist.md", + "role_spec": "roles/strategist/role.md", "inner_loop": false, "frontmatter": { "prefix": "STRATEGY", @@ -64,7 +64,7 @@ "name": "optimizer", "type": "code_generation", "description": "Implements optimization changes following the strategy plan", - "role_spec": "role-specs/optimizer.md", + "role_spec": "roles/optimizer/role.md", "inner_loop": true, "frontmatter": { "prefix": "IMPL", @@ -85,7 +85,7 @@ "name": "benchmarker", "type": "validation", "description": "Runs benchmarks, compares before/after metrics, validates performance improvements", - "role_spec": "role-specs/benchmarker.md", + "role_spec": "roles/benchmarker/role.md", "inner_loop": false, "frontmatter": { "prefix": "BENCH", @@ -106,7 +106,7 @@ "name": "reviewer", "type": "read_only_analysis", "description": "Reviews optimization code for correctness, side effects, and regression risks", - "role_spec": "role-specs/reviewer.md", + "role_spec": "roles/reviewer/role.md", "inner_loop": false, "frontmatter": { "prefix": "REVIEW", diff --git a/.claude/skills/team-planex/role-specs/executor.md b/.claude/skills/team-planex/role-specs/executor.md deleted file mode 100644 index 90be7b5f..00000000 --- a/.claude/skills/team-planex/role-specs/executor.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -prefix: EXEC -inner_loop: true -message_types: - success: impl_complete - error: impl_failed ---- - -# Executor - -Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Agent/Codex/Gemini), verifies with tests, commits, and reports completion. - -## Phase 2: Task & Solution Loading - -| Input | Source | Required | -|-------|--------|----------| -| Issue ID | Task description `Issue ID:` field | Yes | -| Solution file | Task description `Solution file:` field | Yes | -| Session folder | Task description `Session:` field | Yes | -| Execution method | Task description `Execution method:` field | Yes | -| Wisdom | `<session>/wisdom/` | No | - -1. Extract issue ID, solution file path, session folder, execution method -2. Load solution JSON from file (file-first) -3. If file not found -> fallback: `ccw issue solution <issueId> --json` -4. Load wisdom files for conventions and patterns -5. Verify solution has required fields: title, tasks - -## Phase 3: Implementation - -### Backend Selection - -| Method | Backend | CLI Tool | -|--------|---------|----------| -| `codex` | `ccw cli --tool codex --mode write` | Background CLI | -| `gemini` | `ccw cli --tool gemini --mode write` | Background CLI | - -### CLI Backend (Codex/Gemini) - -```bash -ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass -TASK: <solution.tasks as bullet points> -MODE: write -CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/ -EXPECTED: Working implementation with: code changes, test updates, no syntax errors -CONSTRAINTS: Follow existing patterns | Maintain backward compatibility -Issue: <issueId> -Title: <solution.title> -Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature -``` - -Wait for CLI completion before proceeding to verification. - -## Phase 4: Verification + Commit - -### Test Verification - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Tests | Detect and run project test command | All pass | -| Syntax | IDE diagnostics or `tsc --noEmit` | No errors | - -If tests fail: retry implementation once, then report `impl_failed`. - -### Commit - -```bash -git add -A -git commit -m "feat(<issueId>): <solution.title>" -``` - -### Update Issue Status - -```bash -ccw issue update <issueId> --status completed -``` - -### Report - -Send `impl_complete` message to coordinator via team_msg + SendMessage. - -## Boundaries - -| Allowed | Prohibited | -|---------|-----------| -| Load solution from file | Create or modify issues | -| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts | -| Run tests | Spawn additional agents (use CLI tools instead) | -| git commit | Direct user interaction | -| Update issue status | Create tasks for other roles | diff --git a/.claude/skills/team-planex/role-specs/planner.md b/.claude/skills/team-planex/role-specs/planner.md deleted file mode 100644 index efe59ccb..00000000 --- a/.claude/skills/team-planex/role-specs/planner.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -prefix: PLAN -inner_loop: true -message_types: - success: issue_ready - error: error ---- - -# Planner - -Requirement decomposition → issue creation → solution design → EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Input type + raw input | Task description | Yes | -| Session folder | Task description `Session:` field | Yes | -| Execution method | Task description `Execution method:` field | Yes | -| Wisdom | `<session>/wisdom/` | No | - -1. Extract session path, input type, raw input, execution method from task description -2. Load wisdom files if available -3. Parse input to determine issue list: - -| Detection | Condition | Action | -|-----------|-----------|--------| -| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly | -| `--text '...'` | Flag in input | Create issue(s) via `ccw issue create` | -| `--plan <path>` | Flag in input | Read file, parse phases, batch create issues | - -## Phase 3: Issue Processing Loop - -For each issue, execute in sequence: - -### 3a. Generate Solution - -Use CLI tool for issue planning: - -```bash -ccw cli -p "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths -TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create -MODE: analysis -CONTEXT: @**/* | Memory: Session context from <session>/wisdom/ -EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity -CONSTRAINTS: Follow project patterns | Reference existing implementations -" --tool gemini --mode analysis --rule planning-breakdown-task-steps -``` - -Parse CLI output to extract solution JSON. If CLI fails, fallback to `ccw issue solution <issueId> --json`. - -### 3b. Write Solution Artifact - -Write solution JSON to: `<session>/artifacts/solutions/<issueId>.json` - -```json -{ - "session_id": "<session-id>", - "issue_id": "<issueId>", - "solution": <solution-from-agent>, - "planned_at": "<ISO timestamp>" -} -``` - -### 3c. Check Conflicts - -Extract `files_touched` from solution. Compare against prior solutions in session. -Overlapping files -> log warning to `wisdom/issues.md`, continue. - -### 3d. Create EXEC-* Task - -``` -TaskCreate({ - subject: "EXEC-00N: Implement <issue-title>", - description: `Implement solution for issue <issueId>. - -Issue ID: <issueId> -Solution file: <session>/artifacts/solutions/<issueId>.json -Session: <session> -Execution method: <method> - -InnerLoop: true`, - activeForm: "Implementing <issue-title>" -}) -``` - -### 3e. Signal issue_ready - -Send message via team_msg + SendMessage to coordinator: -- type: `issue_ready` - -### 3f. Continue Loop - -Process next issue. Do NOT wait for executor. - -## Phase 4: Completion Signal - -After all issues processed: -1. Send `all_planned` message to coordinator via team_msg + SendMessage -2. Summary: total issues planned, EXEC-* tasks created - -## Boundaries - -| Allowed | Prohibited | -|---------|-----------| -| Parse input, create issues | Write/modify business code | -| Generate solutions (issue-plan-agent) | Run tests | -| Write solution artifacts | git commit | -| Create EXEC-* tasks | Call code-developer | -| Conflict checking | Direct user interaction | diff --git a/.claude/skills/team-quality-assurance/role-specs/analyst.md b/.claude/skills/team-quality-assurance/role-specs/analyst.md deleted file mode 100644 index a0623b96..00000000 --- a/.claude/skills/team-quality-assurance/role-specs/analyst.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -prefix: QAANA -inner_loop: false -message_types: - success: analysis_ready - report: quality_report - error: error ---- - -# Quality Analyst - -Analyze defect patterns, coverage gaps, test effectiveness, and generate comprehensive quality reports. Maintain defect pattern database and provide quality scoring. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Discovered issues | meta.json -> discovered_issues | No | -| Test strategy | meta.json -> test_strategy | No | -| Generated tests | meta.json -> generated_tests | No | -| Execution results | meta.json -> execution_results | No | -| Historical patterns | meta.json -> defect_patterns | No | - -1. Extract session path from task description -2. Read .msg/meta.json for all accumulated QA data -3. Read coverage data from `coverage/coverage-summary.json` if available -4. Read layer execution results from `<session>/results/run-*.json` -5. Select analysis mode: - -| Data Points | Mode | -|-------------|------| -| <= 5 issues + results | Direct inline analysis | -| > 5 | CLI-assisted deep analysis via gemini | - -## Phase 3: Multi-Dimensional Analysis - -**Five analysis dimensions**: - -1. **Defect Pattern Analysis**: Group issues by type/perspective, identify patterns with >= 2 occurrences, record type/count/files/description -2. **Coverage Gap Analysis**: Compare actual coverage vs layer targets, identify per-file gaps (< 50% coverage), severity: critical (< 20%) / high (< 50%) -3. **Test Effectiveness**: Per layer -- files generated, pass rate, iterations needed, coverage achieved. Effective = pass_rate >= 95% AND iterations <= 2 -4. **Quality Trend**: Compare against coverage_history. Trend: improving (delta > 5%), declining (delta < -5%), stable -5. **Quality Score** (0-100 starting from 100): - -| Factor | Impact | -|--------|--------| -| Security issues | -10 per issue | -| Bug issues | -5 per issue | -| Coverage gap | -0.5 per gap percentage | -| Test failures | -(100 - pass_rate) * 0.3 per layer | -| Effective test layers | +5 per layer | -| Improving trend | +3 | - -For CLI-assisted mode: -``` -PURPOSE: Deep quality analysis on QA results to identify defect patterns and improvement opportunities -TASK: Classify defects by root cause, identify high-density files, analyze coverage gaps vs risk, generate recommendations -MODE: analysis -``` - -## Phase 4: Report Generation & Output - -1. Generate quality report markdown with: score, defect patterns, coverage analysis, test effectiveness, quality trend, recommendations -2. Write report to `<session>/analysis/quality-report.md` -3. Update `<session>/wisdom/.msg/meta.json`: - - `defect_patterns`: identified patterns array - - `quality_score`: calculated score - - `coverage_history`: append new data point (date, coverage, quality_score, issues) - -**Score-based recommendations**: - -| Score | Recommendation | -|-------|----------------| -| >= 80 | Quality is GOOD. Maintain current testing practices. | -| 60-79 | Quality needs IMPROVEMENT. Focus on coverage gaps and recurring patterns. | -| < 60 | Quality is CONCERNING. Recommend comprehensive review and testing effort. | diff --git a/.claude/skills/team-quality-assurance/role-specs/executor.md b/.claude/skills/team-quality-assurance/role-specs/executor.md deleted file mode 100644 index 5ada8b15..00000000 --- a/.claude/skills/team-quality-assurance/role-specs/executor.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -prefix: QARUN -inner_loop: true -additional_prefixes: [QARUN-gc] -message_types: - success: tests_passed - failure: tests_failed - coverage: coverage_report - error: error ---- - -# Test Executor - -Run test suites, collect coverage data, and perform automatic fix cycles when tests fail. Implements the execution side of the Generator-Executor (GC) loop. - -## Phase 2: Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Test strategy | meta.json -> test_strategy | Yes | -| Generated tests | meta.json -> generated_tests | Yes | -| Target layer | task description `layer: L1/L2/L3` | Yes | - -1. Extract session path and target layer from task description -2. Read .msg/meta.json for strategy and generated test file list -3. Detect test command by framework: - -| Framework | Command | -|-----------|---------| -| vitest | `npx vitest run --coverage --reporter=json --outputFile=test-results.json` | -| jest | `npx jest --coverage --json --outputFile=test-results.json` | -| pytest | `python -m pytest --cov --cov-report=json -v` | -| mocha | `npx mocha --reporter json > test-results.json` | -| unknown | `npm test -- --coverage` | - -4. Get test files from `generated_tests[targetLayer].files` - -## Phase 3: Iterative Test-Fix Cycle - -**Max iterations**: 5. **Pass threshold**: 95% or all tests pass. - -Per iteration: -1. Run test command, capture output -2. Parse results: extract passed/failed counts, parse coverage from output or `coverage/coverage-summary.json` -3. If all pass (0 failures) -> exit loop (success) -4. If pass rate >= 95% and iteration >= 2 -> exit loop (good enough) -5. If iteration >= MAX -> exit loop (report current state) -6. Extract failure details (error lines, assertion failures) -7. Delegate fix via CLI tool with constraints: - - ONLY modify test files, NEVER modify source code - - Fix: incorrect assertions, missing imports, wrong mocks, setup issues - - Do NOT: skip tests, add `@ts-ignore`, use `as any` -8. Increment iteration, repeat - -## Phase 4: Result Analysis & Output - -1. Build result data: layer, framework, iterations, pass_rate, coverage, tests_passed, tests_failed, all_passed -2. Save results to `<session>/results/run-<layer>.json` -3. Save last test output to `<session>/results/output-<layer>.txt` -4. Update `<session>/wisdom/.msg/meta.json` under `execution_results[layer]` and top-level `execution_results.pass_rate`, `execution_results.coverage` -5. Message type: `tests_passed` if all_passed, else `tests_failed` diff --git a/.claude/skills/team-quality-assurance/role-specs/generator.md b/.claude/skills/team-quality-assurance/role-specs/generator.md deleted file mode 100644 index 4c2ea577..00000000 --- a/.claude/skills/team-quality-assurance/role-specs/generator.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -prefix: QAGEN -inner_loop: false -additional_prefixes: [QAGEN-fix] -message_types: - success: tests_generated - revised: tests_revised - error: error ---- - -# Test Generator - -Generate test code according to strategist's strategy and layers. Support L1 unit tests, L2 integration tests, L3 E2E tests. Follow project's existing test patterns and framework conventions. - -## Phase 2: Strategy & Pattern Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Test strategy | meta.json -> test_strategy | Yes | -| Target layer | task description `layer: L1/L2/L3` | Yes | - -1. Extract session path and target layer from task description -2. Read .msg/meta.json for test strategy (layers, coverage targets) -3. Determine if this is a GC fix task (subject contains "fix") -4. Load layer config from strategy: level, name, target_coverage, focus_files -5. Learn existing test patterns -- find 3 similar test files via Glob(`**/*.{test,spec}.{ts,tsx,js,jsx}`) -6. Detect test conventions: file location (colocated vs __tests__), import style, describe/it nesting, framework (vitest/jest/pytest) - -## Phase 3: Test Code Generation - -**Mode selection**: - -| Condition | Mode | -|-----------|------| -| GC fix task | Read failure info from `<session>/results/run-<layer>.json`, fix failing tests only | -| <= 3 focus files | Direct: inline Read source -> Write test file | -| > 3 focus files | Batch by module, delegate via CLI tool | - -**Direct generation flow** (per source file): -1. Read source file content, extract exports -2. Determine test file path following project conventions -3. If test exists -> analyze missing cases -> append new tests via Edit -4. If no test -> generate full test file via Write -5. Include: happy path, edge cases, error cases per export - -**GC fix flow**: -1. Read execution results and failure output from results directory -2. Read each failing test file -3. Fix assertions, imports, mocks, or test setup -4. Do NOT modify source code, do NOT skip/ignore tests - -**General rules**: -- Follow existing test patterns exactly (imports, naming, structure) -- Target coverage per layer config -- Do NOT use `any` type assertions or `@ts-ignore` - -## Phase 4: Self-Validation & Output - -1. Collect generated/modified test files -2. Run syntax check (TypeScript: `tsc --noEmit`, or framework-specific) -3. Auto-fix syntax errors (max 3 attempts) -4. Write test metadata to `<session>/wisdom/.msg/meta.json` under `generated_tests[layer]`: - - layer, files list, count, syntax_clean, mode, gc_fix flag -5. Message type: `tests_generated` for new, `tests_revised` for GC fix iterations diff --git a/.claude/skills/team-quality-assurance/role-specs/scout.md b/.claude/skills/team-quality-assurance/role-specs/scout.md deleted file mode 100644 index 1449a96e..00000000 --- a/.claude/skills/team-quality-assurance/role-specs/scout.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -prefix: SCOUT -inner_loop: false -message_types: - success: scan_ready - error: error - issues: issues_found ---- - -# Multi-Perspective Scout - -Scan codebase from multiple perspectives (bug, security, test-coverage, code-quality, UX) to discover potential issues. Produce structured scan results with severity-ranked findings. - -## Phase 2: Context & Scope Assessment - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract session path and target scope from task description -2. Determine scan scope: explicit scope from task or `**/*` default -3. Get recent changed files: `git diff --name-only HEAD~5 2>/dev/null || echo ""` -4. Read .msg/meta.json for historical defect patterns (`defect_patterns`) -5. Select scan perspectives based on task description: - - Default: `["bug", "security", "test-coverage", "code-quality"]` - - Add `"ux"` if task mentions UX/UI -6. Assess complexity to determine scan strategy: - -| Complexity | Condition | Strategy | -|------------|-----------|----------| -| Low | < 5 changed files, no specific keywords | ACE search + Grep inline | -| Medium | 5-15 files or specific perspective requested | CLI fan-out (3 core perspectives) | -| High | > 15 files or full-project scan | CLI fan-out (all perspectives) | - -## Phase 3: Multi-Perspective Scan - -**Low complexity**: Use `mcp__ace-tool__search_context` for quick pattern-based scan. - -**Medium/High complexity**: CLI fan-out -- one `ccw cli --mode analysis` per perspective: - -For each active perspective, build prompt: -``` -PURPOSE: Scan code from <perspective> perspective to discover potential issues -TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues -MODE: analysis -CONTEXT: @<scan-scope> -EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description -CONSTRAINTS: Focus on actionable findings only -``` -Execute via: `ccw cli -p "<prompt>" --tool gemini --mode analysis` - -After all perspectives complete: -- Parse CLI outputs into structured findings -- Deduplicate by file:line (merge perspectives for same location) -- Compare against known defect patterns from .msg/meta.json -- Rank by severity: critical > high > medium > low - -## Phase 4: Result Aggregation - -1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description) -2. Write scan results to `<session>/scan/scan-results.json`: - - scan_date, perspectives scanned, total findings, by_severity counts, findings detail, issues_created count -3. Update `<session>/wisdom/.msg/meta.json`: merge `discovered_issues` field -4. Contribute to wisdom/issues.md if new patterns found diff --git a/.claude/skills/team-quality-assurance/role-specs/strategist.md b/.claude/skills/team-quality-assurance/role-specs/strategist.md deleted file mode 100644 index 2203eba0..00000000 --- a/.claude/skills/team-quality-assurance/role-specs/strategist.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -prefix: QASTRAT -inner_loop: false -message_types: - success: strategy_ready - error: error ---- - -# Test Strategist - -Analyze change scope, determine test layers (L1-L3), define coverage targets, and generate test strategy document. Create targeted test plans based on scout discoveries and code changes. - -## Phase 2: Context & Change Analysis - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Discovered issues | meta.json -> discovered_issues | No | -| Defect patterns | meta.json -> defect_patterns | No | - -1. Extract session path from task description -2. Read .msg/meta.json for scout discoveries and historical patterns -3. Analyze change scope: `git diff --name-only HEAD~5` -4. Categorize changed files: - -| Category | Pattern | -|----------|---------| -| Source | `\.(ts|tsx|js|jsx|py|java|go|rs)$` | -| Test | `\.(test|spec)\.(ts|tsx|js|jsx)$` or `test_` | -| Config | `\.(json|yaml|yml|toml|env)$` | - -5. Detect test framework from package.json / project files -6. Check existing coverage baseline from `coverage/coverage-summary.json` -7. Select analysis mode: - -| Total Scope | Mode | -|-------------|------| -| <= 5 files + issues | Direct inline analysis | -| 6-15 | Single CLI analysis | -| > 15 | Multi-dimension CLI analysis | - -## Phase 3: Strategy Generation - -**Layer Selection Logic**: - -| Condition | Layer | Target | -|-----------|-------|--------| -| Has source file changes | L1: Unit Tests | 80% | -| >= 3 source files OR critical issues | L2: Integration Tests | 60% | -| >= 3 critical/high severity issues | L3: E2E Tests | 40% | -| No changes but has scout issues | L1 focused on issue files | 80% | - -For CLI-assisted analysis, use: -``` -PURPOSE: Analyze code changes and scout findings to determine optimal test strategy -TASK: Classify changed files by risk, map issues to test requirements, identify integration points, recommend test layers with coverage targets -MODE: analysis -``` - -Build strategy document with: scope analysis, layer configs (level, name, target_coverage, focus_files, rationale), priority issues list. - -**Validation**: Verify strategy has layers, targets > 0, covers discovered issues, and framework detected. - -## Phase 4: Output & Persistence - -1. Write strategy to `<session>/strategy/test-strategy.md` -2. Update `<session>/wisdom/.msg/meta.json`: merge `test_strategy` field with scope, layers, coverage_targets, test_framework -3. Contribute to wisdom/decisions.md with layer selection rationale diff --git a/.claude/skills/team-review/role-specs/fixer.md b/.claude/skills/team-review/role-specs/fixer.md deleted file mode 100644 index a7c850ba..00000000 --- a/.claude/skills/team-review/role-specs/fixer.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -prefix: FIX -inner_loop: true -message_types: - success: fix_complete - error: fix_failed ---- - -# Code Fixer - -Fix code based on reviewed findings. Load manifest, plan fix groups, apply with rollback-on-failure, verify. Code-generation role -- modifies source files. - -## Phase 2: Context & Scope Resolution - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Fix manifest | <session>/fix/fix-manifest.json | Yes | -| Review report | <session>/review/review-report.json | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path, input path from task description -2. Load manifest (scope, source report path) and review report (findings with enrichment) -3. Filter fixable findings: severity in scope AND fix_strategy !== 'skip' -4. If 0 fixable -> report complete immediately -5. Detect quick path: findings <= 5 AND no cross-file dependencies -6. Detect verification tools: tsc (tsconfig.json), eslint (package.json), jest (package.json), pytest (pyproject.toml), semgrep (semgrep available) -7. Load wisdom files from `<session>/wisdom/` - -## Phase 3: Plan + Execute - -### 3A: Plan Fixes (deterministic, no CLI) -1. Group findings by primary file -2. Merge groups with cross-file dependencies (union-find) -3. Topological sort within each group (respect fix_dependencies, append cycles at end) -4. Sort groups by max severity (critical first) -5. Determine execution path: quick_path (<=5 findings, <=1 group) or standard -6. Write `<session>/fix/fix-plan.json`: `{plan_id, quick_path, groups[{id, files[], findings[], max_severity}], execution_order[], total_findings, total_groups}` - -### 3B: Execute Fixes -**Quick path**: Single code-developer agent for all findings. -**Standard path**: One code-developer agent per group, in execution_order. - -Agent prompt includes: finding list (dependency-sorted), file contents (truncated 8K), critical rules: -1. Apply each fix using Edit tool in order -2. After each fix, run related tests -3. Tests PASS -> finding is "fixed" -4. Tests FAIL -> `git checkout -- {file}` -> mark "failed" -> continue -5. No retry on failure. Rollback and move on -6. If finding depends on previously failed finding -> mark "skipped" - -Agent returns JSON: `{results:[{id, status: fixed|failed|skipped, file, error?}]}` -Fallback: check git diff per file if no structured output. - -Write `<session>/fix/execution-results.json`: `{fixed[], failed[], skipped[]}` - -## Phase 4: Post-Fix Verification - -1. Run available verification tools on modified files: - -| 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 | - -2. If verification fails critically -> rollback last batch -3. Write `<session>/fix/verify-results.json` -4. Generate `<session>/fix/fix-summary.json`: `{fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification}` -5. Generate `<session>/fix/fix-summary.md` (human-readable) -6. Update `<session>/.msg/meta.json` with fix results -7. Contribute discoveries to `<session>/wisdom/` files diff --git a/.claude/skills/team-review/role-specs/reviewer.md b/.claude/skills/team-review/role-specs/reviewer.md deleted file mode 100644 index a175ef4f..00000000 --- a/.claude/skills/team-review/role-specs/reviewer.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -prefix: REV -inner_loop: false -message_types: - success: review_complete - error: error ---- - -# Finding Reviewer - -Deep analysis on scan findings: triage, root cause / impact / optimization enrichment via CLI fan-out, cross-correlation, and structured review report generation. Read-only -- never modifies source code. - -## Phase 2: Context & Triage - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Scan results | <session>/scan/scan-results.json | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path, input path, dimensions from task description -2. Load scan results. If missing or empty -> report clean, complete immediately -3. Load wisdom files from `<session>/wisdom/` -4. Triage findings into two buckets: - -| Bucket | Criteria | Action | -|--------|----------|--------| -| deep_analysis | severity in [critical, high, medium], max 15, sorted critical-first | Enrich with root cause, impact, optimization | -| pass_through | remaining (low, info, or overflow) | Include in report without enrichment | - -If deep_analysis empty -> skip Phase 3, go to Phase 4. - -## Phase 3: Deep Analysis (CLI Fan-out) - -Split deep_analysis into two domain groups, run parallel CLI agents: - -| Group | Dimensions | Focus | -|-------|-----------|-------| -| A | Security + Correctness | Root cause tracing, fix dependencies, blast radius | -| B | Performance + Maintainability | Optimization approaches, refactor tradeoffs | - -If either group empty -> skip that agent. - -Build prompt per group requesting 6 enrichment fields per finding: -- `root_cause`: `{description, related_findings[], is_symptom}` -- `impact`: `{scope: low/medium/high, affected_files[], blast_radius}` -- `optimization`: `{approach, alternative, tradeoff}` -- `fix_strategy`: minimal / refactor / skip -- `fix_complexity`: low / medium / high -- `fix_dependencies`: finding IDs that must be fixed first - -Execute via `ccw cli --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause` (fallback: qwen -> codex). Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`. - -## Phase 4: Report Generation - -1. Combine enriched + pass_through findings -2. Cross-correlate: - - **Critical files**: file appears in >=2 dimensions -> list with finding_count, severities - - **Root cause groups**: cluster findings sharing related_findings -> identify primary - - **Optimization suggestions**: from root cause groups + standalone enriched findings -3. Compute metrics: by_dimension, by_severity, dimension_severity_matrix, fixable_count, auto_fixable_count -4. Write `<session>/review/review-report.json`: `{review_id, review_date, findings[], critical_files[], optimization_suggestions[], root_cause_groups[], summary}` -5. Write `<session>/review/review-report.md`: Executive summary, metrics matrix (dimension x severity), critical/high findings table, critical files list, optimization suggestions, recommended fix scope -6. Update `<session>/.msg/meta.json` with review summary -7. Contribute discoveries to `<session>/wisdom/` files diff --git a/.claude/skills/team-review/role-specs/scanner.md b/.claude/skills/team-review/role-specs/scanner.md deleted file mode 100644 index dcbd889d..00000000 --- a/.claude/skills/team-review/role-specs/scanner.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -prefix: SCAN -inner_loop: false -message_types: - success: scan_complete - error: error ---- - -# Code Scanner - -Toolchain + LLM semantic scan producing structured findings. Static analysis tools in parallel, then LLM for issues tools miss. Read-only -- never modifies source code. 4-dimension system: security (SEC), correctness (COR), performance (PRF), maintainability (MNT). - -## Phase 2: Context & Toolchain Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/.msg/meta.json | No | - -1. Extract session path, target, dimensions, quick flag from task description -2. Resolve target files (glob pattern or directory -> `**/*.{ts,tsx,js,jsx,py,go,java,rs}`) -3. If no source files found -> report empty, complete task cleanly -4. Detect toolchain availability: - -| Tool | Detection | Dimension | -|------|-----------|-----------| -| tsc | `tsconfig.json` exists | COR | -| eslint | `.eslintrc*` or `eslint` in package.json | COR/MNT | -| semgrep | `.semgrep.yml` exists | SEC | -| ruff | `pyproject.toml` + ruff available | SEC/COR/MNT | -| mypy | mypy available + `pyproject.toml` | COR | -| npmAudit | `package-lock.json` exists | SEC | - -5. Load wisdom files from `<session>/wisdom/` if they exist - -## Phase 3: Scan Execution - -**Quick mode**: Single CLI call with analysis mode, max 20 findings, skip toolchain. - -**Standard mode** (sequential): - -### 3A: Toolchain Scan -Run detected tools in parallel via Bash backgrounding. Each tool writes to `<session>/scan/tmp/<tool>.{json|txt}`. After `wait`, parse each output into normalized findings: -- tsc: `file(line,col): error TSxxxx: msg` -> dimension=correctness, source=tool:tsc -- eslint: JSON array -> severity 2=correctness/high, else=maintainability/medium -- semgrep: `{results[]}` -> dimension=security, severity from extra.severity -- ruff: `[{code,message,filename}]` -> S*=security, F*/B*=correctness, else=maintainability -- mypy: `file:line: error: msg [code]` -> dimension=correctness -- npm audit: `{vulnerabilities:{}}` -> dimension=security, category=dependency - -Write `<session>/scan/toolchain-findings.json`. - -### 3B: Semantic Scan (LLM via CLI) -Build prompt with target file patterns, toolchain dedup summary, and per-dimension focus areas: -- SEC: Business logic vulnerabilities, privilege escalation, sensitive data flow, auth bypass -- COR: Logic errors, unhandled exception paths, state management bugs, race conditions -- PRF: Algorithm complexity, N+1 queries, unnecessary sync, memory leaks, missing caching -- MNT: Architectural coupling, abstraction leaks, convention violations, dead code - -Execute via `ccw cli --tool gemini --mode analysis --rule analysis-review-code-quality` (fallback: qwen -> codex). Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`. - -## Phase 4: Aggregate & Output - -1. Merge toolchain + semantic findings, deduplicate (same file + line + dimension = duplicate) -2. Assign dimension-prefixed IDs: SEC-001, COR-001, PRF-001, MNT-001 -3. Write `<session>/scan/scan-results.json` with schema: `{scan_date, target, dimensions, quick_mode, total_findings, by_severity, by_dimension, findings[]}` -4. Each finding: `{id, dimension, category, severity, title, description, location:{file,line}, source, suggested_fix, effort, confidence}` -5. Update `<session>/.msg/meta.json` with scan summary (findings_count, by_severity, by_dimension) -6. Contribute discoveries to `<session>/wisdom/` files diff --git a/.claude/skills/team-roadmap-dev/role-specs/executor.md b/.claude/skills/team-roadmap-dev/role-specs/executor.md deleted file mode 100644 index 06dae694..00000000 --- a/.claude/skills/team-roadmap-dev/role-specs/executor.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -prefix: EXEC -inner_loop: true -cli_tools: - - gemini --mode write -message_types: - success: exec_complete - progress: exec_progress - error: error ---- - -# Executor - -Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes | -| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No | -| Wisdom | <session>/wisdom/ | No | - -1. Glob `<session>/phase-{N}/.task/IMPL-*.json`, error if none found -2. Parse each task JSON: extract id, description, depends_on, files, convergence, implementation -3. Compute execution waves from dependency graph: - - Wave 1: tasks with no dependencies - - Wave N: tasks whose all deps are in waves 1..N-1 - - Force-assign if circular (break at lowest-numbered task) -4. Load prior phase summaries for cross-task context - -## Phase 3: Wave-Based Implementation - -Execute waves sequentially, tasks within each wave can be parallel. - -**Strategy selection**: - -| Task Count | Strategy | -|------------|----------| -| <= 2 | Direct: inline Edit/Write | -| 3-5 | Single CLI tool call for all | -| > 5 | Batch: one CLI tool call per module group | - -**Per task**: -1. Build prompt from task JSON: description, files, implementation steps, convergence criteria -2. Include prior summaries and wisdom as context -3. Delegate to CLI tool (`run_in_background: false`): - ``` - Bash({ - command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description} - TASK: ${implementationSteps} - MODE: write - CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries} - EXPECTED: Working code changes matching convergence criteria - CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`, - run_in_background: false - }) - ``` -4. Write `<session>/phase-{N}/summary-{IMPL-ID}.md` with: task ID, affected files, changes made, status - -**Between waves**: report wave progress via team_msg (type: exec_progress) - -## Phase 4: Self-Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Affected files exist | `test -f <path>` for each file in summary | All present | -| TypeScript syntax | `npx tsc --noEmit` (if tsconfig.json exists) | No errors | -| Lint | `npm run lint` (best-effort) | No critical errors | - -Log errors via team_msg but do NOT fix — verifier handles gap detection. diff --git a/.claude/skills/team-roadmap-dev/role-specs/planner.md b/.claude/skills/team-roadmap-dev/role-specs/planner.md deleted file mode 100644 index 3aa37cd2..00000000 --- a/.claude/skills/team-roadmap-dev/role-specs/planner.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -prefix: PLAN -inner_loop: true -cli_tools: - - gemini --mode analysis -message_types: - success: plan_ready - progress: plan_progress - error: error ---- - -# Planner - -Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool. - -## Phase 2: Context Loading + Research - -| Input | Source | Required | -|-------|--------|----------| -| roadmap.md | <session>/roadmap.md | Yes | -| config.json | <session>/config.json | Yes | -| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No | -| Wisdom | <session>/wisdom/ | No | - -1. Read roadmap.md, extract phase goal, requirements (REQ-IDs), success criteria -2. Read config.json for depth setting (quick/standard/comprehensive) -3. Load prior phase summaries for dependency context -4. Detect gap closure mode (task description contains "Gap closure") -5. Launch CLI exploration with phase requirements as exploration query: - ``` - Bash({ - command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements - TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks - MODE: analysis - CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal} - EXPECTED: Structured exploration results with file lists, patterns, risks - CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`, - run_in_background: false - }) - ``` - - Target: files needing modification, patterns, dependencies, test infrastructure, risks -6. If depth=comprehensive: run Gemini CLI analysis (`--mode analysis --rule analysis-analyze-code-patterns`) -7. Write `<session>/phase-{N}/context.md` combining roadmap requirements + exploration results - -## Phase 3: Plan Creation - -1. Load context.md from Phase 2 -2. Create output directory: `<session>/phase-{N}/.task/` -3. Delegate to CLI planning tool with: - ``` - Bash({ - command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum} - TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves - MODE: write - CONTEXT: @${contextMd} | Memory: ${priorSummaries} - EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md - CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`, - run_in_background: false - }) - ``` -4. CLI tool produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md` -5. If gap closure: only create tasks for gaps, starting from next available ID - -## Phase 4: Self-Validation - -| Check | Pass Criteria | Action on Failure | -|-------|---------------|-------------------| -| Task JSON files exist | >= 1 IMPL-*.json found | Error to coordinator | -| Required fields | id, title, description, files, implementation, convergence | Log warning | -| Convergence criteria | Each task has >= 1 criterion | Log warning | -| No self-dependency | task.id not in task.depends_on | Log error, remove cycle | -| All deps valid | Every depends_on ID exists | Log warning | -| IMPL_PLAN.md exists | File present | Generate minimal version from task JSONs | - -After validation, compute wave structure from dependency graph for reporting: -- Wave count = topological layers of DAG -- Report: task count, wave count, file list diff --git a/.claude/skills/team-roadmap-dev/role-specs/verifier.md b/.claude/skills/team-roadmap-dev/role-specs/verifier.md deleted file mode 100644 index af40a941..00000000 --- a/.claude/skills/team-roadmap-dev/role-specs/verifier.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -prefix: VERIFY -inner_loop: true -cli_tools: - - gemini --mode analysis -message_types: - success: verify_passed - failure: gaps_found - error: error ---- - -# Verifier - -Goal-backward verification per phase. Reads convergence criteria from IMPL-*.json task files and checks against actual codebase state. Read-only — never modifies code. Produces verification.md with pass/fail and structured gap lists. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes | -| Summaries | <session>/phase-{N}/summary-*.md | Yes | -| Wisdom | <session>/wisdom/ | No | - -1. Glob IMPL-*.json files, extract convergence criteria from each task -2. Glob summary-*.md files, parse frontmatter (task, affects, provides) -3. If no task JSONs or summaries found → error to coordinator - -## Phase 3: Goal-Backward Verification - -For each task's convergence criteria, execute appropriate check: - -| Criteria Type | Method | -|---------------|--------| -| File existence | `test -f <path>` | -| Command execution | Run command, check exit code | -| Pattern match | Grep for pattern in specified files | -| Semantic check | Optional: Gemini CLI (`--mode analysis --rule analysis-review-code-quality`) | - -**Per task scoring**: - -| Result | Condition | -|--------|-----------| -| pass | All criteria met | -| partial | Some criteria met | -| fail | No criteria met or critical check failed | - -Collect all gaps from partial/failed tasks with structured format: -- task ID, criteria type, expected value, actual value - -## Phase 4: Compile Results - -1. Aggregate per-task results: count passed, partial, failed -2. Determine overall status: - - `passed` if gaps.length === 0 - - `gaps_found` otherwise -3. Write `<session>/phase-{N}/verification.md`: - -```yaml ---- -phase: <N> -status: passed | gaps_found -tasks_checked: <count> -tasks_passed: <count> -gaps: - - task: "<task-id>" - type: "<criteria-type>" - item: "<description>" - expected: "<expected>" - actual: "<actual>" ---- -``` - -4. Update .msg/meta.json with verification summary diff --git a/.claude/skills/team-tech-debt/role-specs/assessor.md b/.claude/skills/team-tech-debt/role-specs/assessor.md deleted file mode 100644 index 975cfced..00000000 --- a/.claude/skills/team-tech-debt/role-specs/assessor.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -prefix: TDEVAL -inner_loop: false -message_types: - success: assessment_complete - error: error ---- - -# Tech Debt Assessor - -Quantitative evaluator for tech debt items. Score each debt item on business impact (1-5) and fix cost (1-5), classify into priority quadrants, produce priority-matrix.json. - -## Phase 2: Load Debt Inventory - -| Input | Source | Required | -|-------|--------|----------| -| Session path | task description (regex: `session:\s*(.+)`) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Debt inventory | meta.json:debt_inventory OR <session>/scan/debt-inventory.json | Yes | - -1. Extract session path from task description -2. Read .msg/meta.json for team context -3. Load debt_inventory from shared memory or fallback to debt-inventory.json file -4. If debt_inventory is empty -> report empty assessment and exit - -## Phase 3: Evaluate Each Item - -**Strategy selection**: - -| Item Count | Strategy | -|------------|----------| -| <= 10 | Heuristic: severity-based impact + effort-based cost | -| 11-50 | CLI batch: single gemini analysis call | -| > 50 | CLI chunked: batches of 25 items | - -**Impact Score Mapping** (heuristic): - -| Severity | Impact Score | -|----------|-------------| -| critical | 5 | -| high | 4 | -| medium | 3 | -| low | 1 | - -**Cost Score Mapping** (heuristic): - -| Estimated Effort | Cost Score | -|------------------|------------| -| small | 1 | -| medium | 3 | -| large | 5 | -| unknown | 3 | - -**Priority Quadrant Classification**: - -| Impact | Cost | Quadrant | -|--------|------|----------| -| >= 4 | <= 2 | quick-win | -| >= 4 | >= 3 | strategic | -| <= 3 | <= 2 | backlog | -| <= 3 | >= 3 | defer | - -For CLI mode, prompt gemini with full debt summary requesting JSON array of `{id, impact_score, cost_score, risk_if_unfixed, priority_quadrant}`. Unevaluated items fall back to heuristic scoring. - -## Phase 4: Generate Priority Matrix - -1. Build matrix structure: evaluation_date, total_items, by_quadrant (grouped), summary (counts per quadrant) -2. Sort within each quadrant by impact_score descending -3. Write `<session>/assessment/priority-matrix.json` -4. Update .msg/meta.json with `priority_matrix` summary and evaluated `debt_inventory` diff --git a/.claude/skills/team-tech-debt/role-specs/executor.md b/.claude/skills/team-tech-debt/role-specs/executor.md deleted file mode 100644 index fbc5c9dc..00000000 --- a/.claude/skills/team-tech-debt/role-specs/executor.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -prefix: TDFIX -inner_loop: true -cli_tools: - - gemini --mode write -message_types: - success: fix_complete - progress: fix_progress - error: error ---- - -# Tech Debt Executor - -Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch. - -## Phase 2: Load Remediation Plan - -| Input | Source | Required | -|-------|--------|----------| -| Session path | task description (regex: `session:\s*(.+)`) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Remediation plan | <session>/plan/remediation-plan.json | Yes | -| Worktree info | meta.json:worktree.path, worktree.branch | Yes | -| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) | - -1. Extract session path from task description -2. Read .msg/meta.json for worktree path and branch -3. Read remediation-plan.json, extract all actions from plan phases -4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs -5. Split large groups (> 10 items) into sub-batches of 10 -6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues - -**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure - -## Phase 3: Execute Fixes - -For each batch, use CLI tool for implementation: - -**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands. - -**Per-batch delegation**: - -```bash -ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes -TASK: <batch-type-specific-tasks> -MODE: write -CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context -EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests -CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying -Batch type: <refactor|update-deps|add-tests|add-docs|restructure> -Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>" -``` - -Wait for CLI completion before proceeding to next batch. - -**Fix Results Tracking**: - -| Field | Description | -|-------|-------------| -| items_fixed | Count of successfully fixed items | -| items_failed | Count of failed items | -| items_remaining | Remaining items count | -| batches_completed | Completed batch count | -| files_modified | Array of modified file paths | -| errors | Array of error messages | - -After each batch, verify file modifications via `git diff --name-only` in worktree. - -## Phase 4: Self-Validation - -All commands in worktree: - -| Check | Command | Pass Criteria | -|-------|---------|---------------| -| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors | -| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors | - -Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`. - -Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats. diff --git a/.claude/skills/team-tech-debt/role-specs/planner.md b/.claude/skills/team-tech-debt/role-specs/planner.md deleted file mode 100644 index 5a859811..00000000 --- a/.claude/skills/team-tech-debt/role-specs/planner.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -prefix: TDPLAN -inner_loop: false -message_types: - success: plan_ready - revision: plan_revision - error: error ---- - -# Tech Debt Planner - -Remediation plan designer. Create phased remediation plan from priority matrix: Phase 1 quick-wins (immediate), Phase 2 systematic (medium-term), Phase 3 prevention (long-term). Produce remediation-plan.md. - -## Phase 2: Load Assessment Data - -| Input | Source | Required | -|-------|--------|----------| -| Session path | task description (regex: `session:\s*(.+)`) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Priority matrix | <session>/assessment/priority-matrix.json | Yes | - -1. Extract session path from task description -2. Read .msg/meta.json for debt_inventory -3. Read priority-matrix.json for quadrant groupings -4. Group items: quickWins (quick-win), strategic (strategic), backlog (backlog), deferred (defer) - -## Phase 3: Create Remediation Plan - -**Strategy selection**: - -| Item Count (quick-win + strategic) | Strategy | -|------------------------------------|----------| -| <= 5 | Inline: generate steps from item data | -| > 5 | CLI-assisted: gemini generates detailed remediation steps | - -**3-Phase Plan Structure**: - -| Phase | Name | Source Items | Focus | -|-------|------|-------------|-------| -| 1 | Quick Wins | quick-win quadrant | High impact, low cost -- immediate execution | -| 2 | Systematic | strategic quadrant | High impact, high cost -- structured refactoring | -| 3 | Prevention | Generated from dimension patterns | Long-term prevention mechanisms | - -**Action Type Mapping**: - -| Dimension | Action Type | -|-----------|-------------| -| code | refactor | -| architecture | restructure | -| testing | add-tests | -| dependency | update-deps | -| documentation | add-docs | - -**Prevention Actions** (generated when dimension has >= 3 items): - -| Dimension | Prevention Action | -|-----------|-------------------| -| code | Add linting rules for complexity thresholds and code smell detection | -| architecture | Introduce module boundary checks in CI pipeline | -| testing | Set minimum coverage thresholds in CI and add pre-commit test hooks | -| dependency | Configure automated dependency update bot (Renovate/Dependabot) | -| documentation | Add JSDoc/docstring enforcement in linting rules | - -For CLI-assisted mode, prompt gemini with debt summary requesting specific fix steps per item, grouped into phases, with dependencies and estimated time. - -## Phase 4: Validate & Save - -1. Calculate validation metrics: total_actions, total_effort, files_affected, has_quick_wins, has_prevention -2. Write `<session>/plan/remediation-plan.md` (markdown with per-item checklists) -3. Write `<session>/plan/remediation-plan.json` (machine-readable) -4. Update .msg/meta.json with `remediation_plan` summary diff --git a/.claude/skills/team-tech-debt/role-specs/scanner.md b/.claude/skills/team-tech-debt/role-specs/scanner.md deleted file mode 100644 index f9451bec..00000000 --- a/.claude/skills/team-tech-debt/role-specs/scanner.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -prefix: TDSCAN -inner_loop: false -cli_tools: - - gemini --mode analysis -message_types: - success: scan_complete - error: error - info: debt_items_found ---- - -# Tech Debt Scanner - -Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, architecture, testing, dependency, documentation), produce structured debt inventory with severity rankings. - -## Phase 2: Context & Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Scan scope | task description (regex: `scope:\s*(.+)`) | No (default: `**/*`) | -| Session path | task description (regex: `session:\s*(.+)`) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | - -1. Extract session path and scan scope from task description -2. Read .msg/meta.json for team context -3. Detect project type and framework: - -| Signal File | Project Type | -|-------------|-------------| -| package.json + React/Vue/Angular | Frontend Node | -| package.json + Express/Fastify/NestJS | Backend Node | -| pyproject.toml / requirements.txt | Python | -| go.mod | Go | -| No detection | Generic | - -4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation) -5. Detect perspectives from task description: - -| Condition | Perspective | -|-----------|-------------| -| `security\|auth\|inject\|xss` | security | -| `performance\|speed\|optimize` | performance | -| `quality\|clean\|maintain\|debt` | code-quality | -| `architect\|pattern\|structure` | architecture | -| Default | code-quality + architecture | - -6. Assess complexity: - -| Score | Complexity | Strategy | -|-------|------------|----------| -| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini | -| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions | -| 0-1 | Low | Inline: ACE search + Grep | - -## Phase 3: Multi-Dimension Scan - -**Low Complexity** (inline): -- Use `mcp__ace-tool__search_context` for code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests -- Classify findings into dimensions - -**Medium/High Complexity** (Fan-out): -- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis` -- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation) -- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture) -- Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings - -**Standardize each finding**: - -| Field | Description | -|-------|-------------| -| `id` | `TD-NNN` (sequential) | -| `dimension` | code, architecture, testing, dependency, documentation | -| `severity` | critical, high, medium, low | -| `file` | File path | -| `line` | Line number | -| `description` | Issue description | -| `suggestion` | Fix suggestion | -| `estimated_effort` | small, medium, large, unknown | - -## Phase 4: Aggregate & Save - -1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references -2. Sort by severity (cross-referenced items boosted) -3. Write `<session>/scan/debt-inventory.json` with scan_date, dimensions, total_items, by_dimension, by_severity, items -4. Update .msg/meta.json with `debt_inventory` array and `debt_score_before` count diff --git a/.claude/skills/team-tech-debt/role-specs/validator.md b/.claude/skills/team-tech-debt/role-specs/validator.md deleted file mode 100644 index 4abe613d..00000000 --- a/.claude/skills/team-tech-debt/role-specs/validator.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -prefix: TDVAL -inner_loop: false -message_types: - success: validation_complete - error: error - fix: regression_found ---- - -# Tech Debt Validator - -Cleanup result validator. Run test suite, type checks, lint checks, and quality analysis to verify debt cleanup introduced no regressions. Compare before/after debt scores, produce validation-report.json. - -## Phase 2: Load Context - -| Input | Source | Required | -|-------|--------|----------| -| Session path | task description (regex: `session:\s*(.+)`) | Yes | -| .msg/meta.json | <session>/.msg/meta.json | Yes | -| Fix log | <session>/fixes/fix-log.json | No | - -1. Extract session path from task description -2. Read .msg/meta.json for: worktree.path, debt_inventory, fix_results, debt_score_before -3. Determine command prefix: `cd "<worktree-path>" && ` if worktree exists -4. Read fix-log.json for modified files list -5. Detect available validation tools in worktree: - -| Signal | Tool | Method | -|--------|------|--------| -| package.json + npm | npm test | Test suite | -| pytest available | python -m pytest | Test suite | -| npx tsc available | npx tsc --noEmit | Type check | -| npx eslint available | npx eslint | Lint check | - -## Phase 3: Run Validation Checks - -Execute 4-layer validation (all commands in worktree): - -**1. Test Suite**: -- Run `npm test` or `python -m pytest` in worktree -- PASS if no FAIL/error/failed keywords; FAIL with regression count otherwise -- Skip with "no-tests" if no test runner available - -**2. Type Check**: -- Run `npx tsc --noEmit` in worktree -- Count `error TS` occurrences for error count - -**3. Lint Check**: -- Run `npx eslint --no-error-on-unmatched-pattern <modified-files>` in worktree -- Count error occurrences - -**4. Quality Analysis** (optional, when > 5 modified files): -- Use gemini CLI to compare code quality before/after -- Assess complexity, duplication, naming quality improvements - -**Debt Score Calculation**: -- debt_score_after = debt items NOT in modified files (remaining unfixed items) -- improvement_percentage = ((before - after) / before) * 100 - -**Auto-fix attempt** (when total_regressions <= 3): -- Use CLI tool to fix regressions in worktree: - ``` - Bash({ - command: `cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation - TASK: ${regressionDetails} - MODE: write - CONTEXT: @${modifiedFiles.join(' @')} - EXPECTED: Fixed regressions - CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`, - run_in_background: false - }) - ``` -- Re-run validation checks after fix attempt - }) - ``` -- Re-run checks after fix attempt - -## Phase 4: Compare & Report - -1. Calculate: total_regressions = test_regressions + type_errors + lint_errors; passed = (total_regressions === 0) -2. Write `<session>/validation/validation-report.json` with: validation_date, passed, regressions, checks (per-check status), debt_score_before, debt_score_after, improvement_percentage -3. Update .msg/meta.json with `validation_results` and `debt_score_after` -4. Select message type: `validation_complete` if passed, `regression_found` if not diff --git a/.claude/skills/team-testing/role-specs/analyst.md b/.claude/skills/team-testing/role-specs/analyst.md deleted file mode 100644 index 1a553c63..00000000 --- a/.claude/skills/team-testing/role-specs/analyst.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -prefix: TESTANA -inner_loop: false -message_types: - success: analysis_ready - error: error ---- - -# Test Quality Analyst - -Analyze defect patterns, identify coverage gaps, assess GC loop effectiveness, and generate a quality report with actionable recommendations. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Execution results | <session>/results/run-*.json | Yes | -| Test strategy | <session>/strategy/test-strategy.md | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | - -1. Extract session path from task description -2. Read .msg/meta.json for execution context (executor, generator namespaces) -3. Read all execution results: - -``` -Glob("<session>/results/run-*.json") -Read("<session>/results/run-001.json") -``` - -4. Read test strategy: - -``` -Read("<session>/strategy/test-strategy.md") -``` - -5. Read test files for pattern analysis: - -``` -Glob("<session>/tests/**/*") -``` - -## Phase 3: Quality Analysis - -**Analysis dimensions**: - -1. **Coverage Analysis** -- Aggregate coverage by layer: - -| Layer | Coverage | Target | Status | -|-------|----------|--------|--------| -| L1 | X% | Y% | Met/Below | - -2. **Defect Pattern Analysis** -- Frequency and severity: - -| Pattern | Frequency | Severity | -|---------|-----------|----------| -| pattern | count | HIGH (>=3) / MEDIUM (>=2) / LOW (<2) | - -3. **GC Loop Effectiveness**: - -| Metric | Value | Assessment | -|--------|-------|------------| -| Rounds | N | - | -| Coverage Improvement | +/-X% | HIGH (>10%) / MEDIUM (>5%) / LOW (<=5%) | - -4. **Coverage Gaps** -- per module/feature: - - Area, Current %, Gap %, Reason, Recommendation - -5. **Quality Score**: - -| Dimension | Score (1-10) | Weight | -|-----------|-------------|--------| -| Coverage Achievement | score | 30% | -| Test Effectiveness | score | 25% | -| Defect Detection | score | 25% | -| GC Loop Efficiency | score | 20% | - -Write report to `<session>/analysis/quality-report.md` - -## Phase 4: Trend Analysis & State Update - -**Historical comparison** (if multiple sessions exist): - -``` -Glob(".workflow/.team/TST-*/.msg/meta.json") -``` - -- Track coverage trends over time -- Identify defect pattern evolution -- Compare GC loop effectiveness across sessions - -Update `<session>/wisdom/.msg/meta.json` under `analyst` namespace: -- Merge `{ "analyst": { quality_score, coverage_gaps, top_defect_patterns, gc_effectiveness, recommendations } }` diff --git a/.claude/skills/team-testing/role-specs/executor.md b/.claude/skills/team-testing/role-specs/executor.md deleted file mode 100644 index f65d3642..00000000 --- a/.claude/skills/team-testing/role-specs/executor.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -prefix: TESTRUN -inner_loop: true -message_types: - success: tests_passed - failure: tests_failed - coverage: coverage_report - error: error ---- - -# Test Executor - -Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Critic in the Generator-Critic loop. Reports pass rate and coverage for coordinator GC decisions. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Test directory | Task description (Input: <path>) | Yes | -| Coverage target | Task description (default: 80%) | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract session path and test directory from task description -2. Extract coverage target (default: 80%) -3. Read .msg/meta.json for framework info (from strategist namespace) -4. Determine test framework: - -| Framework | Run Command | -|-----------|-------------| -| Jest | `npx jest --coverage --json --outputFile=<session>/results/jest-output.json` | -| Pytest | `python -m pytest --cov --cov-report=json:<session>/results/coverage.json -v` | -| Vitest | `npx vitest run --coverage --reporter=json` | - -5. Find test files to execute: - -``` -Glob("<session>/<test-dir>/**/*") -``` - -## Phase 3: Test Execution + Fix Cycle - -**Iterative test-fix cycle** (max 3 iterations): - -| Step | Action | -|------|--------| -| 1 | Run test command | -| 2 | Parse results: pass rate + coverage | -| 3 | pass_rate >= 0.95 AND coverage >= target -> success, exit | -| 4 | Extract failing test details | -| 5 | Delegate fix to CLI tool (gemini write mode) | -| 6 | Increment iteration; >= 3 -> exit with failures | - -``` -Bash("<test-command> 2>&1 || true") -``` - -**Auto-fix delegation** (on failure): - -``` -Bash({ - command: `ccw cli -p "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass -TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent -MODE: write -CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3 -EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage -CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes -Test failures: -<test-output>" --tool gemini --mode write --cd <session>`, - run_in_background: false -}) -``` - -**Save results**: `<session>/results/run-<N>.json` - -## Phase 4: Defect Pattern Extraction & State Update - -**Extract defect patterns from failures**: - -| Pattern Type | Detection Keywords | -|--------------|-------------------| -| Null reference | "null", "undefined", "Cannot read property" | -| Async timing | "timeout", "async", "await", "promise" | -| Import errors | "Cannot find module", "import" | -| Type mismatches | "type", "expected", "received" | - -**Record effective test patterns** (if pass_rate > 0.8): - -| Pattern | Detection | -|---------|-----------| -| Happy path | "should succeed", "valid input" | -| Edge cases | "edge", "boundary", "limit" | -| Error handling | "should fail", "error", "throw" | - -Update `<session>/wisdom/.msg/meta.json` under `executor` namespace: -- Merge `{ "executor": { pass_rate, coverage, defect_patterns, effective_patterns, coverage_history_entry } }` diff --git a/.claude/skills/team-testing/role-specs/generator.md b/.claude/skills/team-testing/role-specs/generator.md deleted file mode 100644 index c70803fc..00000000 --- a/.claude/skills/team-testing/role-specs/generator.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -prefix: TESTGEN -inner_loop: true -message_types: - success: tests_generated - revision: tests_revised - error: error ---- - -# Test Generator - -Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Generator in the Generator-Critic loop. Supports revision mode for GC loop iterations. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| Test strategy | <session>/strategy/test-strategy.md | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract session path and layer from task description -2. Read test strategy: - -``` -Read("<session>/strategy/test-strategy.md") -``` - -3. Read source files to test (from strategy priority_files, limit 20) -4. Read .msg/meta.json for framework and scope context - -5. Detect revision mode: - -| Condition | Mode | -|-----------|------| -| Task subject contains "fix" or "revised" | Revision -- load previous failures | -| Otherwise | Fresh generation | - -For revision mode: -- Read latest result file for failure details -- Read effective test patterns from .msg/meta.json - -6. Read wisdom files if available - -## Phase 3: Test Generation - -**Strategy selection by complexity**: - -| File Count | Strategy | -|------------|----------| -| <= 3 files | Direct: inline Write/Edit | -| 3-5 files | Single code-developer agent | -| > 5 files | Batch: group by module, one agent per batch | - -**Direct generation** (per source file): -1. Generate test path: `<session>/tests/<layer>/<test-file>` -2. Generate test code: happy path, edge cases, error handling -3. Write test file - -**CLI delegation** (medium/high complexity): - -``` -Bash({ - command: `ccw cli -p "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests -TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution -MODE: write -CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round> -<if-revision: Previous failures: <failure-details> -Effective patterns: <patterns-from-meta>> -EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions -CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions -Source files to test: -<file-list-with-content>" --tool gemini --mode write --cd <session>`, - run_in_background: false -}) -``` - -**Output verification**: - -``` -Glob("<session>/tests/<layer>/**/*") -``` - -## Phase 4: Self-Validation & State Update - -**Validation checks**: - -| Check | Method | Action on Fail | -|-------|--------|----------------| -| Syntax | `tsc --noEmit` or equivalent | Auto-fix imports/types | -| File count | Count generated files | Report issue | -| Import resolution | Check broken imports | Fix import paths | - -Update `<session>/wisdom/.msg/meta.json` under `generator` namespace: -- Merge `{ "generator": { test_files, layer, round, is_revision } }` diff --git a/.claude/skills/team-testing/role-specs/strategist.md b/.claude/skills/team-testing/role-specs/strategist.md deleted file mode 100644 index b51a8ee1..00000000 --- a/.claude/skills/team-testing/role-specs/strategist.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -prefix: STRATEGY -inner_loop: false -message_types: - success: strategy_ready - error: error ---- - -# Test Strategist - -Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order. - -## Phase 2: Context & Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract session path and scope from task description -2. Get git diff for change analysis: - -``` -Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only") -Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>") -``` - -3. Detect test framework from project files: - -| Signal File | Framework | Test Pattern | -|-------------|-----------|-------------| -| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` | -| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` | -| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` | -| No detection | Default | Jest patterns | - -4. Scan existing test patterns: - -``` -Glob("**/*.test.*") -Glob("**/*.spec.*") -``` - -5. Read .msg/meta.json if exists for session context - -## Phase 3: Strategy Formulation - -**Change analysis dimensions**: - -| Change Type | Analysis | Priority | -|-------------|----------|----------| -| New files | Need new tests | High | -| Modified functions | Need updated tests | Medium | -| Deleted files | Need test cleanup | Low | -| Config changes | May need integration tests | Variable | - -**Strategy output structure**: - -1. **Change Analysis Table**: File, Change Type, Impact, Priority -2. **Test Layer Recommendations**: - - L1 Unit: Scope, Coverage Target, Priority Files, Patterns - - L2 Integration: Scope, Coverage Target, Integration Points - - L3 E2E: Scope, Coverage Target, User Scenarios -3. **Risk Assessment**: Risk, Probability, Impact, Mitigation -4. **Test Execution Order**: Prioritized sequence - -Write strategy to `<session>/strategy/test-strategy.md` - -**Self-validation**: - -| Check | Criteria | Fallback | -|-------|----------|----------| -| Has L1 scope | L1 scope not empty | Default to all changed files | -| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) | -| Has priority files | List not empty | Use all changed files | - -## Phase 4: Wisdom & State Update - -1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns) -2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace: - - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back diff --git a/.claude/skills/team-uidesign/role-specs/designer.md b/.claude/skills/team-uidesign/role-specs/designer.md deleted file mode 100644 index ba94bff0..00000000 --- a/.claude/skills/team-uidesign/role-specs/designer.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -prefix: DESIGN -inner_loop: false -message_types: - success: design_ready - revision: design_revision - progress: design_progress - error: error ---- - -# Design Token & Component Spec Author - -Define visual language through design tokens (W3C Design Tokens Format) and component specifications. Consume design intelligence from researcher. Act as Generator in the designer<->reviewer Generator-Critic loop. - -## Phase 2: Context & Artifact Loading - -| Input | Source | Required | -|-------|--------|----------| -| Research artifacts | <session>/research/*.json | Yes | -| Design intelligence | <session>/research/design-intelligence.json | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | -| Audit feedback | <session>/audit/audit-*.md | Only for GC fix tasks | - -1. Extract session path from task description -2. Read research findings: design-system-analysis.json, component-inventory.json, accessibility-audit.json -3. Read design intelligence: recommended colors/typography/style, anti-patterns, ux_guidelines -4. Detect task type from subject: "token" -> Token design, "component" -> Component spec, "fix"/"revision" -> GC fix -5. If GC fix task: read latest audit feedback from audit files - -## Phase 3: Design Execution - -**Token System Design (DESIGN-001)**: -- Define complete token system following W3C Design Tokens Format -- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide) -- All color tokens must have light/dark variants using `$value: { light: ..., dark: ... }` -- Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks -- Document anti-patterns from design intelligence for implementer reference -- Output: `<session>/design/design-tokens.json` - -**Component Specification (DESIGN-002)**: -- Define component specs consuming design tokens -- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (default/hover/focus/active/disabled), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints -- All interactive states required: default, hover (background/opacity change), focus (outline 2px solid, offset 2px), active (pressed), disabled (opacity 0.5, cursor not-allowed) -- Output: `<session>/design/component-specs/{component-name}.md` - -**GC Fix Mode (DESIGN-fix-N)**: -- Parse audit feedback for specific issues -- Re-read affected design artifacts; apply fixes (token value adjustments, missing states, accessibility gaps, naming fixes) -- Re-write affected files; signal `design_revision` instead of `design_ready` - -## Phase 4: Self-Validation & Output - -1. Token integrity checks: - -| Check | Pass Criteria | -|-------|---------------| -| tokens_valid | All $value fields non-empty | -| theme_complete | Light/dark values for all color tokens | -| values_parseable | Valid CSS-parseable values | -| no_duplicates | No duplicate token definitions | - -2. Component spec checks: - -| Check | Pass Criteria | -|-------|---------------| -| states_complete | All 5 states (default/hover/focus/active/disabled) defined | -| a11y_specified | Role, ARIA, keyboard behavior defined | -| responsive_defined | At least mobile/desktop breakpoints | -| token_refs_valid | All `{token.path}` references resolve to defined tokens | - -3. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace: - - Read existing -> merge `{ "designer": { task_type, token_categories, component_count, style_decisions } }` -> write back diff --git a/.claude/skills/team-uidesign/role-specs/implementer.md b/.claude/skills/team-uidesign/role-specs/implementer.md deleted file mode 100644 index ff4dac02..00000000 --- a/.claude/skills/team-uidesign/role-specs/implementer.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -prefix: BUILD -inner_loop: false -message_types: - success: build_complete - progress: build_progress - error: error ---- - -# Component Code Builder - -Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns. - -## Phase 2: Context & Artifact Loading - -| Input | Source | Required | -|-------|--------|----------| -| Design tokens | <session>/design/design-tokens.json | Yes (token build) | -| Component specs | <session>/design/component-specs/*.md | Yes (component build) | -| Design intelligence | <session>/research/design-intelligence.json | Yes | -| Latest audit report | <session>/audit/audit-*.md | No | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | - -1. Extract session path from task description -2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation -3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build) -4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines -5. Read latest audit report for approved changes and feedback -6. Detect project tech stack from package.json - -## Phase 3: Implementation Execution - -**Token Implementation (BUILD-001)**: -- Convert design tokens to production code -- Output files in `<session>/build/token-files/`: - - `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback - - `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support - - `README.md`: Token usage guide -- All color tokens must have both light and dark values -- Semantic token names must match design token definitions - -**Component Implementation (BUILD-002)**: -- Implement component code from design specifications -- Per-component output in `<session>/build/component-files/`: - - `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack) - - `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only - - `{ComponentName}.test.tsx`: Basic render + state tests - - `index.ts`: Re-export -- Requirements: no hardcoded colors/spacing (use design tokens), implement all 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns -- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast -- Check implementation against design intelligence anti_patterns - -## Phase 4: Validation & Output - -1. Token build validation: - -| Check | Pass Criteria | -|-------|---------------| -| File existence | tokens.css and tokens.ts exist | -| Token coverage | All defined tokens present in CSS | -| Theme support | Light/dark variants exist | - -2. Component build validation: - -| Check | Pass Criteria | -|-------|---------------| -| File existence | At least 3 files per component (component, style, index) | -| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) | -| Focus styles | `:focus` or `:focus-visible` defined | -| Responsive | `@media` queries present | -| Anti-pattern clean | No violations of design intelligence anti_patterns | - -3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace: - - Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back diff --git a/.claude/skills/team-uidesign/role-specs/researcher.md b/.claude/skills/team-uidesign/role-specs/researcher.md deleted file mode 100644 index 71c1b5cb..00000000 --- a/.claude/skills/team-uidesign/role-specs/researcher.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -prefix: RESEARCH -inner_loop: false -message_types: - success: research_ready - progress: research_progress - error: error ---- - -# Design System Researcher - -Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles. - -## Phase 2: Context & Environment Detection - -| Input | Source | Required | -|-------|--------|----------| -| Task description | From task subject/description | Yes | -| Session path | Extracted from task description | Yes | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | No | - -1. Extract session path and target scope from task description -2. Detect project type and tech stack from package.json or equivalent: - -| Package | Detected Stack | -|---------|---------------| -| next | nextjs | -| react | react | -| vue | vue | -| svelte | svelte | -| @shadcn/ui | shadcn | -| (default) | html-tailwind | - -3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns -4. Read industry context from session config (industry, strictness, must-have features) - -## Phase 3: Research Execution - -Execute 4 analysis streams: - -**Stream 1 -- Design System Analysis**: -- Search for existing design tokens (CSS variables, theme configs, token files) -- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS) -- Map color palette, typography scale, spacing system -- Find component library usage (MUI, Ant Design, shadcn, custom) -- Output: `<session>/research/design-system-analysis.json` - -**Stream 2 -- Component Inventory**: -- Find all UI component files; identify props/API surface -- Identify states supported (hover, focus, disabled, etc.) -- Check accessibility attributes (ARIA labels, roles) -- Map inter-component dependencies and usage counts -- Output: `<session>/research/component-inventory.json` - -**Stream 3 -- Accessibility Baseline**: -- Check ARIA attribute usage patterns, keyboard navigation support -- Assess color contrast ratios (if design tokens found) -- Find focus management and semantic HTML patterns -- Output: `<session>/research/accessibility-audit.json` - -**Stream 4 -- Design Intelligence (ui-ux-pro-max)**: -- Call `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` for design system recommendations -- Call `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` for UX guidelines -- Call `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` for stack guidelines -- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"` -- Output: `<session>/research/design-intelligence.json` - -Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count. - -## Phase 4: Validation & Output - -1. Verify all 4 output files exist and contain valid JSON with required fields: - -| File | Required Fields | -|------|----------------| -| design-system-analysis.json | existing_tokens, styling_approach | -| component-inventory.json | components array | -| accessibility-audit.json | wcag_level | -| design-intelligence.json | _source, design_system | - -2. If any file missing or invalid, re-run corresponding stream - -3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace: - - Read existing -> merge `{ "researcher": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back diff --git a/.claude/skills/team-uidesign/role-specs/reviewer.md b/.claude/skills/team-uidesign/role-specs/reviewer.md deleted file mode 100644 index 297c5689..00000000 --- a/.claude/skills/team-uidesign/role-specs/reviewer.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -prefix: AUDIT -inner_loop: false -message_types: - success: audit_passed - result: audit_result - fix: fix_required - error: error ---- - -# Design Auditor - -Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines. - -## Phase 2: Context & Artifact Loading - -| Input | Source | Required | -|-------|--------|----------| -| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes | -| Design intelligence | <session>/research/design-intelligence.json | Yes | -| Audit history | .msg/meta.json -> reviewer namespace | No | -| Build artifacts | <session>/build/**/* | Only for final audit | -| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes | - -1. Extract session path from task description -2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit -3. Read design intelligence for anti-patterns and ux_guidelines -4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only) -5. Load audit_history from meta.json for trend analysis - -## Phase 3: Audit Execution - -Score 5 dimensions on 1-10 scale: - -| Dimension | Weight | Focus | -|-----------|--------|-------| -| Consistency | 20% | Token usage, naming conventions, visual uniformity | -| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast | -| Completeness | 20% | All states defined, responsive specs, edge cases | -| Quality | 15% | Token reference integrity, documentation clarity, maintainability | -| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence | - -**Token Audit**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates. - -**Component Audit**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions. - -**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns). - -**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)` - -**Signal determination**: - -| Condition | Signal | -|-----------|--------| -| Score >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) | -| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) | -| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) | - -## Phase 4: Report & Output - -1. Write audit report to `<session>/audit/audit-{NNN}.md`: - - Summary: overall score, signal, critical/high/medium counts - - Sync Point Status (if applicable): PASSED/BLOCKED - - Dimension Scores table (score/weight/weighted per dimension) - - Critical/High/Medium issues with descriptions, locations, fix suggestions - - GC Loop Status: signal, action required - - Trend analysis (if audit_history exists): improving/stable/declining - -2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace: - - Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back diff --git a/.claude/skills/team-ux-improve/role-specs/designer.md b/.claude/skills/team-ux-improve/role-specs/designer.md deleted file mode 100644 index 6d541a46..00000000 --- a/.claude/skills/team-ux-improve/role-specs/designer.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -prefix: DESIGN -inner_loop: false -message_types: - success: design_complete - error: error ---- - -# UX Designer - -Design feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates). - -## Phase 2: Context & Pattern Loading - -1. Load diagnosis report from `<session>/artifacts/diagnosis.md` -2. Load diagnoser state via `team_msg(operation="get_state", session_id=<session-id>, role="diagnoser")` -3. Detect framework from project structure -4. Load framework-specific patterns: - -| Framework | State Pattern | Event Pattern | -|-----------|---------------|---------------| -| React | useState, useRef | onClick, onChange | -| Vue | ref, reactive | @click, @change | - -### Wisdom Input - -1. Read `<session>/wisdom/patterns/ui-feedback.md` for established feedback design patterns -2. Read `<session>/wisdom/patterns/state-management.md` for state handling patterns -3. Read `<session>/wisdom/principles/general-ux.md` for UX design principles -4. Apply patterns when designing solutions for identified issues - -### Complex Design (use CLI) - -For complex multi-component solutions: - -``` -Bash(`ccw cli -p "PURPOSE: Design comprehensive feedback mechanism for multi-step form -CONTEXT: @<component-files> -EXPECTED: Complete design with state flow diagram and code patterns -CONSTRAINTS: Must support React hooks" --tool gemini --mode analysis`) -``` - -## Phase 3: Solution Design - -For each diagnosed issue, design solution: - -### Feedback Mechanism Design - -| Issue Type | Solution Design | -|------------|-----------------| -| Missing loading | Add loading state + UI indicator (spinner, disabled button) | -| Missing error | Add error state + error message display | -| Missing success | Add success state + confirmation toast/message | -| No empty state | Add conditional rendering for empty data | - -### State Management Design - -**React Pattern**: -```typescript -// Add state variables -const [isLoading, setIsLoading] = useState(false); -const [error, setError] = useState<string | null>(null); - -// Wrap async operation -const handleSubmit = async (event: React.FormEvent) => { - event.preventDefault(); - setIsLoading(true); - setError(null); - - try { - const response = await fetch('/api/upload', { method: 'POST', body: formData }); - if (!response.ok) throw new Error('Upload failed'); - // Success handling - } catch (err: any) { - setError(err.message || 'An error occurred'); - } finally { - setIsLoading(false); - } -}; - -// UI binding -<button type="submit" disabled={isLoading}> - {isLoading ? 'Uploading...' : 'Upload File'} -</button> -{error && <p style={{ color: 'red' }}>{error}</p>} -``` - -**Vue Pattern**: -```typescript -// Add reactive state -const isLoading = ref(false); -const error = ref<string | null>(null); - -// Wrap async operation -const handleSubmit = async () => { - isLoading.value = true; - error.value = null; - - try { - const response = await fetch('/api/upload', { method: 'POST', body: formData }); - if (!response.ok) throw new Error('Upload failed'); - // Success handling - } catch (err: any) { - error.value = err.message || 'An error occurred'; - } finally { - isLoading.value = false; - } -}; - -// UI binding -<button @click="handleSubmit" :disabled="isLoading"> - {{ isLoading ? 'Uploading...' : 'Upload File' }} -</button> -<p v-if="error" style="color: red">{{ error }}</p> -``` - -### Input Control Design - -| Issue | Solution | -|-------|----------| -| Text input for file path | Add file picker: `<input type="file" />` | -| Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` | -| No validation | Add validation rules and error messages | - -## Phase 4: Design Document Generation - -1. Generate implementation guide for each issue: - -```markdown -# Design Guide - -## Issue #1: Upload form no loading state - -### Solution Design -Add loading state with UI feedback and error handling. - -### State Variables (React) -```typescript -const [isLoading, setIsLoading] = useState(false); -const [error, setError] = useState<string | null>(null); -``` - -### Event Handler -```typescript -const handleUpload = async (event: React.FormEvent) => { - event.preventDefault(); - setIsLoading(true); - setError(null); - - try { - // API call - } catch (err: any) { - setError(err.message); - } finally { - setIsLoading(false); - } -}; -``` - -### UI Binding -```tsx -<button type="submit" disabled={isLoading}> - {isLoading ? 'Uploading...' : 'Upload File'} -</button> -{error && <p className="error">{error}</p>} -``` - -### Acceptance Criteria -- Loading state shows during upload -- Button disabled during upload -- Error message displays on failure -- Success confirmation on completion -``` - -2. Write guide to `<session>/artifacts/design-guide.md` - -### Wisdom Contribution - -If novel design patterns created: -1. Write new patterns to `<session>/wisdom/contributions/designer-pattern-<timestamp>.md` -2. Format: Problem context, solution design, implementation hints, trade-offs - -3. Share state via team_msg: - ``` - team_msg(operation="log", session_id=<session-id>, from="designer", - type="state_update", data={ - designed_solutions: <count>, - framework: <framework>, - patterns_used: [<pattern-list>] - }) - ``` diff --git a/.claude/skills/team-ux-improve/role-specs/diagnoser.md b/.claude/skills/team-ux-improve/role-specs/diagnoser.md deleted file mode 100644 index c24920bf..00000000 --- a/.claude/skills/team-ux-improve/role-specs/diagnoser.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -prefix: DIAG -inner_loop: false -message_types: - success: diag_complete - error: error ---- - -# State Diagnoser - -Diagnose root causes of UI issues: state management problems, event binding failures, async handling errors. - -## Phase 2: Context & Complexity Assessment - -1. Load scan report from `<session>/artifacts/scan-report.md` -2. Load scanner state via `team_msg(operation="get_state", session_id=<session-id>, role="scanner")` - -### Wisdom Input - -1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available -2. Use patterns to identify root causes of UI interaction issues -3. Reference `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common causes - -3. Assess issue complexity: - -| Complexity | Criteria | Strategy | -|------------|----------|----------| -| High | 5+ issues, cross-component state | CLI delegation | -| Medium | 2-4 issues, single component | CLI for analysis | -| Low | 1 issue, simple pattern | Inline analysis | - -### Complex Analysis (use CLI) - -For complex multi-file state management issues: - -``` -Bash(`ccw cli -p "PURPOSE: Analyze state management patterns and identify root causes -CONTEXT: @<issue-files> -EXPECTED: Root cause analysis with fix recommendations -CONSTRAINTS: Focus on reactive update patterns" --tool gemini --mode analysis`) -``` - -## Phase 3: Root Cause Analysis - -For each issue from scan report: - -### State Management Diagnosis - -| Pattern | Root Cause | Fix Strategy | -|---------|------------|--------------| -| Array.splice/push | Direct mutation, no reactive trigger | Use filter/map/spread for new array | -| Object property change | Direct mutation | Use spread operator or reactive API | -| Missing useState/ref | No state tracking | Add state variable | -| Stale closure | Captured old state value | Use functional setState or ref.current | - -### Event Binding Diagnosis - -| Pattern | Root Cause | Fix Strategy | -|---------|------------|--------------| -| onClick without handler | Missing event binding | Add event handler function | -| Async without await | Unhandled promise | Add async/await or .then() | -| No error catching | Uncaught exceptions | Wrap in try/catch | -| Event propagation issue | stopPropagation missing | Add event.stopPropagation() | - -### Async Handling Diagnosis - -| Pattern | Root Cause | Fix Strategy | -|---------|------------|--------------| -| No loading state | Missing async state tracking | Add isLoading state | -| No error handling | Missing catch block | Add try/catch with error state | -| Race condition | Multiple concurrent requests | Add request cancellation or debounce | - -## Phase 4: Diagnosis Report - -1. Generate root cause analysis for each issue: - -```markdown -# Diagnosis Report - -## Issue #1: Upload form no loading state -- **File**: src/components/Upload.tsx:45 -- **Root Cause**: Form submit handler is async but no loading state variable exists -- **Pattern Type**: Missing async state tracking -- **Fix Recommendation**: - - Add `const [isLoading, setIsLoading] = useState(false)` (React) - - Add `const isLoading = ref(false)` (Vue) - - Wrap async call in try/finally with setIsLoading(true/false) - - Disable button when isLoading is true -``` - -2. Write report to `<session>/artifacts/diagnosis.md` - -### Wisdom Contribution - -If new root cause patterns discovered: -1. Write diagnosis patterns to `<session>/wisdom/contributions/diagnoser-patterns-<timestamp>.md` -2. Format: Symptom, root cause, detection method, fix approach - -3. Share state via team_msg: - ``` - team_msg(operation="log", session_id=<session-id>, from="diagnoser", - type="state_update", data={ - diagnosed_issues: <count>, - pattern_types: { - state_management: <count>, - event_binding: <count>, - async_handling: <count> - } - }) - ``` diff --git a/.claude/skills/team-ux-improve/role-specs/explorer.md b/.claude/skills/team-ux-improve/role-specs/explorer.md deleted file mode 100644 index dc24702f..00000000 --- a/.claude/skills/team-ux-improve/role-specs/explorer.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -prefix: EXPLORE -inner_loop: false -message_types: - success: explore_complete - error: error ---- - -# Codebase Explorer - -Explore codebase for UI component patterns, state management conventions, and framework-specific patterns. Callable by coordinator only. - -## Phase 2: Exploration Scope - -1. Parse exploration request from task description -2. Determine file patterns based on framework: - -### Wisdom Input - -1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available -2. Use known patterns as reference when exploring codebase for component structures -3. Check `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` to identify problematic patterns during exploration - -| Framework | Patterns | -|-----------|----------| -| React | `**/*.tsx`, `**/*.jsx`, `**/use*.ts`, `**/store*.ts` | -| Vue | `**/*.vue`, `**/composables/*.ts`, `**/stores/*.ts` | - -3. Check exploration cache: `<session>/explorations/cache-index.json` - - If cache hit and fresh -> return cached results - - If cache miss or stale -> proceed to Phase 3 - -## Phase 3: Codebase Exploration - -Use ACE search for semantic queries: - -``` -mcp__ace-tool__search_context( - project_root_path="<project-path>", - query="<exploration-query>" -) -``` - -Exploration dimensions: - -| Dimension | Query | Purpose | -|-----------|-------|---------| -| Component patterns | "UI components with user interactions" | Find interactive components | -| State management | "State management patterns useState ref reactive" | Identify state conventions | -| Event handling | "Event handlers onClick onChange onSubmit" | Map event patterns | -| Error handling | "Error handling try catch error state" | Find error patterns | -| Feedback mechanisms | "Loading state spinner progress indicator" | Find existing feedback | - -For each dimension, collect: -- File paths -- Pattern examples -- Convention notes - -## Phase 4: Exploration Summary - -1. Generate pattern summary: - -```markdown -# Exploration Summary - -## Framework: React/Vue - -## Component Patterns -- Button components use <pattern> -- Form components use <pattern> - -## State Management Conventions -- Global state: Zustand/Pinia -- Local state: useState/ref -- Async state: custom hooks/composables - -## Event Handling Patterns -- Form submit: <pattern> -- Button click: <pattern> - -## Existing Feedback Mechanisms -- Loading: <pattern> -- Error: <pattern> -- Success: <pattern> -``` - -2. Cache results to `<session>/explorations/cache-index.json` -3. Write summary to `<session>/explorations/exploration-summary.md` - -### Wisdom Contribution - -If new component patterns or framework conventions discovered: -1. Write pattern summaries to `<session>/wisdom/contributions/explorer-patterns-<timestamp>.md` -2. Format: - - Pattern Name: Descriptive name - - Framework: React/Vue/etc. - - Use Case: When to apply this pattern - - Code Example: Representative snippet - - Adoption: How widely used in codebase - -4. Share state via team_msg: - ``` - team_msg(operation="log", session_id=<session-id>, from="explorer", - type="state_update", data={ - framework: <framework>, - components_found: <count>, - patterns_identified: [<pattern-list>] - }) - ``` diff --git a/.claude/skills/team-ux-improve/role-specs/implementer.md b/.claude/skills/team-ux-improve/role-specs/implementer.md deleted file mode 100644 index 6fd6c8d6..00000000 --- a/.claude/skills/team-ux-improve/role-specs/implementer.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -prefix: IMPL -inner_loop: true -message_types: - success: impl_complete - error: error ---- - -# Code Implementer - -Generate executable fix code with proper state management, event handling, and UI feedback bindings. - -## Phase 2: Task & Design Loading - -1. Extract session path from task description -2. Read design guide: `<session>/artifacts/design-guide.md` -3. Extract implementation tasks from design guide -4. **Wisdom Input**: - - Read `<session>/wisdom/patterns/state-management.md` for state handling patterns - - Read `<session>/wisdom/patterns/ui-feedback.md` for UI feedback implementation patterns - - Read `<session>/wisdom/principles/general-ux.md` for implementation principles - - Load framework-specific conventions if available - - Apply these patterns and principles when generating code to ensure consistency and quality -5. **For inner loop**: Load context_accumulator from prior IMPL tasks - -### Context Accumulator (Inner Loop) - -``` -context_accumulator = { - completed_fixes: [<fix-1>, <fix-2>], - modified_files: [<file-1>, <file-2>], - patterns_applied: [<pattern-1>] -} -``` - -## Phase 3: Code Implementation - -Implementation backend selection: - -| Backend | Condition | Method | -|---------|-----------|--------| -| CLI | Complex multi-file changes | `ccw cli --tool gemini --mode write` | -| Direct | Simple single-file changes | Inline Edit/Write | - -### CLI Implementation (Complex) - -``` -Bash(`ccw cli -p "PURPOSE: Implement loading state and error handling for upload form -TASK: - - Add useState for isLoading and error - - Wrap async call in try/catch/finally - - Update UI bindings for button and error display -CONTEXT: @src/components/Upload.tsx -EXPECTED: Modified Upload.tsx with complete implementation -CONSTRAINTS: Maintain existing code style" --tool gemini --mode write`) -``` - -### Direct Implementation (Simple) - -For simple state variable additions or UI binding changes: - -``` -Edit({ - file_path: "src/components/Upload.tsx", - old_string: "const handleUpload = async () => {", - new_string: "const [isLoading, setIsLoading] = useState(false);\nconst [error, setError] = useState<string | null>(null);\n\nconst handleUpload = async () => {\n setIsLoading(true);\n setError(null);\n try {" -}) -``` - -### Implementation Steps - -For each fix in design guide: -1. Read target file -2. Determine complexity (simple vs complex) -3. Apply fix using appropriate backend -4. Verify syntax (no compilation errors) -5. Append to context_accumulator - -## Phase 4: Self-Validation - -| Check | Method | Pass Criteria | -|-------|--------|---------------| -| Syntax | IDE diagnostics or tsc --noEmit | No errors | -| File existence | Verify planned files exist | All present | -| Acceptance criteria | Match against design guide | All met | - -Validation steps: -1. Run syntax check on modified files -2. Verify all files from design guide exist -3. Check acceptance criteria from design guide -4. If validation fails -> attempt auto-fix (max 2 attempts) - -### Context Accumulator Update - -Append to context_accumulator: -``` -{ - completed_fixes: [...prev, <current-fix>], - modified_files: [...prev, <current-files>], - patterns_applied: [...prev, <current-patterns>] -} -``` - -Write summary to `<session>/artifacts/fixes/README.md`: -```markdown -# Implementation Summary - -## Completed Fixes -- Issue #1: Upload form loading state - DONE -- Issue #2: Error handling - DONE - -## Modified Files -- src/components/Upload.tsx -- src/components/Form.tsx - -## Patterns Applied -- React useState for loading/error states -- try/catch/finally for async handling -- Conditional rendering for error messages -``` - -Share state via team_msg: -``` -team_msg(operation="log", session_id=<session-id>, from="implementer", - type="state_update", data={ - completed_fixes: <count>, - modified_files: [<file-list>], - validation_passed: true - }) -``` - -### Wisdom Contribution - -If reusable code patterns or snippets created: -1. Write code snippets to `<session>/wisdom/contributions/implementer-snippets-<timestamp>.md` -2. Format: Use case, code snippet with comments, framework compatibility notes - -Example contribution format: -```markdown -# Implementer Snippets - <timestamp> - -## Loading State Pattern (React) - -### Use Case -Async operations requiring loading indicator - -### Code Snippet -```tsx -const [isLoading, setIsLoading] = useState(false); - -const handleAsyncAction = async () => { - setIsLoading(true); - try { - await performAction(); - } finally { - setIsLoading(false); - } -}; -``` - -### Framework Compatibility -- React 16.8+ (hooks) -- Next.js compatible -``` diff --git a/.claude/skills/team-ux-improve/role-specs/scanner.md b/.claude/skills/team-ux-improve/role-specs/scanner.md deleted file mode 100644 index 31fa8917..00000000 --- a/.claude/skills/team-ux-improve/role-specs/scanner.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -prefix: SCAN -inner_loop: false -message_types: - success: scan_complete - error: error ---- - -# UI Scanner - -Scan UI components to identify interaction issues: unresponsive buttons, missing feedback mechanisms, state not refreshing. - -## Phase 2: Context Loading - -| Input | Source | Required | -|-------|--------|----------| -| Project path | Task description CONTEXT | Yes | -| Framework | Task description CONTEXT | Yes | -| Scan scope | Task description CONSTRAINTS | Yes | - -1. Extract session path and project path from task description -2. Detect framework from project structure: - -| Signal | Framework | -|--------|-----------| -| package.json has "react" | React | -| package.json has "vue" | Vue | -| *.tsx files present | React | -| *.vue files present | Vue | - -3. Build file pattern list for scanning: - - React: `**/*.tsx`, `**/*.jsx`, `**/use*.ts` - - Vue: `**/*.vue`, `**/composables/*.ts` - -### Wisdom Input - -1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` if available -2. Use anti-patterns to identify known UX issues during scanning -3. Check `<session>/wisdom/patterns/ui-feedback.md` for expected feedback patterns - -### Complex Analysis (use CLI) - -For large projects with many components: - -``` -Bash(`ccw cli -p "PURPOSE: Discover all UI components with user interactions -CONTEXT: @<project-path>/**/*.tsx @<project-path>/**/*.vue -EXPECTED: Component list with interaction types (click, submit, input, select) -CONSTRAINTS: Focus on interactive components only" --tool gemini --mode analysis`) -``` - -## Phase 3: Component Scanning - -Scan strategy: - -| Category | Detection Pattern | Severity | -|----------|-------------------|----------| -| Unresponsive actions | onClick/\@click without async handling or error catching | High | -| Missing loading state | Form submit without isLoading/loading ref | High | -| State not refreshing | Array.splice/push without reactive reassignment | High | -| Missing error feedback | try/catch without error state or user notification | Medium | -| Missing success feedback | API call without success confirmation | Medium | -| No empty state | Data list without empty state placeholder | Low | -| Input without validation | Form input without validation rules | Low | -| Missing file selector | Text input for file/folder path without picker | Medium | - -For each component file: -1. Read file content -2. Scan for interaction patterns using Grep -3. Check for feedback mechanisms (loading, error, success states) -4. Check state update patterns (mutation vs reactive) -5. Record issues with file:line references - -## Phase 4: Issue Report Generation - -1. Classify issues by severity (High/Medium/Low) -2. Group by category (unresponsive, missing feedback, state issues, input UX) -3. Generate structured report: - -```markdown -# UI Scan Report - -## Summary -- Total issues: <count> -- High: <count> | Medium: <count> | Low: <count> - -## Issues - -### High Severity -| # | File:Line | Component | Issue | Category | -|---|-----------|-----------|-------|----------| -| 1 | src/components/Upload.tsx:45 | UploadForm | No loading state on submit | Missing feedback | - -### Medium Severity -... - -### Low Severity -... -``` - -4. Write report to `<session>/artifacts/scan-report.md` -5. Share state via team_msg: - ``` - team_msg(operation="log", session_id=<session-id>, from="scanner", - type="state_update", data={ - total_issues: <count>, - high: <count>, medium: <count>, low: <count>, - categories: [<category-list>], - scanned_files: <count> - }) - ``` - -### Wisdom Contribution - -If novel UX issues discovered that aren't in anti-patterns: -1. Write findings to `<session>/wisdom/contributions/scanner-issues-<timestamp>.md` -2. Format: Issue description, detection criteria, affected components diff --git a/.claude/skills/team-ux-improve/role-specs/tester.md b/.claude/skills/team-ux-improve/role-specs/tester.md deleted file mode 100644 index 191b73bd..00000000 --- a/.claude/skills/team-ux-improve/role-specs/tester.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -prefix: TEST -inner_loop: false -message_types: - success: test_complete - error: error - fix: fix_required ---- - -# Test Engineer - -Generate and run tests to verify fixes (loading states, error handling, state updates). - -## Phase 2: Environment Detection - -1. Detect test framework from project files: - -| Signal | Framework | -|--------|-----------| -| package.json has "jest" | Jest | -| package.json has "vitest" | Vitest | -| package.json has "@testing-library/react" | React Testing Library | -| package.json has "@vue/test-utils" | Vue Test Utils | - -2. Get changed files from implementer state: - ``` - team_msg(operation="get_state", session_id=<session-id>, role="implementer") - ``` - -3. Load test strategy from design guide - -### Wisdom Input - -1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test -2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify -3. Use wisdom to design comprehensive test cases covering known edge cases - -## Phase 3: Test Generation & Execution - -### Test Generation - -For each modified file, generate test cases: - -**React Example**: -```typescript -import { render, screen, fireEvent, waitFor } from '@testing-library/react'; -import Upload from '../Upload'; - -describe('Upload Component', () => { - it('shows loading state during upload', async () => { - global.fetch = vi.fn(() => Promise.resolve({ ok: true })); - - render(<Upload />); - const uploadButton = screen.getByRole('button', { name: /upload/i }); - - fireEvent.click(uploadButton); - - // Check loading state - await waitFor(() => { - expect(screen.getByText(/uploading.../i)).toBeInTheDocument(); - expect(uploadButton).toBeDisabled(); - }); - - // Check normal state restored - await waitFor(() => { - expect(uploadButton).not.toBeDisabled(); - }); - }); - - it('displays error message on failure', async () => { - global.fetch = vi.fn(() => Promise.reject(new Error('Upload failed'))); - - render(<Upload />); - fireEvent.click(screen.getByRole('button', { name: /upload/i })); - - await waitFor(() => { - expect(screen.getByText(/upload failed/i)).toBeInTheDocument(); - }); - }); -}); -``` - -### Test Execution - -Iterative test-fix cycle (max 5 iterations): - -1. Run tests: `npm test` or `npm run test:unit` -2. Parse results -> calculate pass rate -3. If pass rate >= 95% -> exit (success) -4. If pass rate < 95% and iterations < 5: - - Analyze failures - - Use CLI to generate fixes: - ``` - Bash(`ccw cli -p "PURPOSE: Fix test failures - CONTEXT: @<test-file> @<source-file> - EXPECTED: Fixed code that passes tests - CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`) - ``` - - Increment iteration counter - - Loop to step 1 -5. If iterations >= 5 -> send fix_required message - -## Phase 4: Test Report - -### Wisdom Contribution - -If new edge cases or test patterns discovered: -1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md` -2. Format: Edge case description, test scenario, expected behavior, actual behavior - -Generate test report: - -```markdown -# Test Report - -## Summary -- Total tests: <count> -- Passed: <count> -- Failed: <count> -- Pass rate: <percentage>% -- Fix iterations: <count> - -## Test Results - -### Passed Tests -- ✅ Upload Component > shows loading state during upload -- ✅ Upload Component > displays error message on failure - -### Failed Tests -- ❌ Form Component > validates input before submit - - Error: Expected validation message not found - -## Coverage -- Statements: 85% -- Branches: 78% -- Functions: 90% -- Lines: 84% - -## Remaining Issues -- Form validation test failing (needs manual review) -``` - -Write report to `<session>/artifacts/test-report.md` - -Share state via team_msg: -``` -team_msg(operation="log", session_id=<session-id>, from="tester", - type="state_update", data={ - total_tests: <count>, - passed: <count>, - failed: <count>, - pass_rate: <percentage>, - fix_iterations: <count> - }) -``` - -If pass rate < 95%, send fix_required message: -``` -SendMessage({ - to: "coordinator", - message: "[tester] Test validation incomplete. Pass rate: <percentage>%. Manual review needed." -}) -``` diff --git a/.claude/skills/team-ux-improve/specs/team-config.json b/.claude/skills/team-ux-improve/specs/team-config.json index c0e0e776..6a80ee7c 100644 --- a/.claude/skills/team-ux-improve/specs/team-config.json +++ b/.claude/skills/team-ux-improve/specs/team-config.json @@ -27,7 +27,7 @@ "display_name": "UI Scanner", "type": "worker", "responsibility_type": "read_only_analysis", - "role_spec": "role-specs/scanner.md", + "role_spec": "roles/scanner/role.md", "task_prefix": "SCAN", "inner_loop": false, "allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"], @@ -46,7 +46,7 @@ "display_name": "State Diagnoser", "type": "worker", "responsibility_type": "orchestration", - "role_spec": "role-specs/diagnoser.md", + "role_spec": "roles/diagnoser/role.md", "task_prefix": "DIAG", "inner_loop": false, "allowed_tools": ["Read", "Grep", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"], @@ -65,7 +65,7 @@ "display_name": "UX Designer", "type": "worker", "responsibility_type": "orchestration", - "role_spec": "role-specs/designer.md", + "role_spec": "roles/designer/role.md", "task_prefix": "DESIGN", "inner_loop": false, "allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"], @@ -84,7 +84,7 @@ "display_name": "Code Implementer", "type": "worker", "responsibility_type": "code_generation", - "role_spec": "role-specs/implementer.md", + "role_spec": "roles/implementer/role.md", "task_prefix": "IMPL", "inner_loop": true, "allowed_tools": ["Read", "Write", "Edit", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__edit_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"], @@ -103,7 +103,7 @@ "display_name": "Test Engineer", "type": "worker", "responsibility_type": "validation", - "role_spec": "role-specs/tester.md", + "role_spec": "roles/tester/role.md", "task_prefix": "TEST", "inner_loop": false, "allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"], @@ -123,7 +123,7 @@ { "name": "explorer", "display_name": "Codebase Explorer", - "role_spec": "role-specs/explorer.md", + "role_spec": "roles/explorer/role.md", "callable_by": "coordinator", "purpose": "Explore codebase for UI component patterns, state management conventions, and framework-specific patterns", "allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg"], diff --git a/.codex/skills/team-designer/agents/validation-reporter.md b/.codex/skills/team-designer/agents/validation-reporter.md new file mode 100644 index 00000000..7bcb6947 --- /dev/null +++ b/.codex/skills/team-designer/agents/validation-reporter.md @@ -0,0 +1,186 @@ +# Validation Reporter Agent + +Validate generated skill package structure and content, reporting results with PASS/WARN/FAIL verdict. + +## Identity + +- **Type**: `interactive` +- **Role File**: `agents/validation-reporter.md` +- **Responsibility**: Validate generated skill package structure and content, report results + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Load the generated skill package from session artifacts +- Validate all structural integrity checks +- Produce structured output with clear PASS/WARN/FAIL verdict +- Include specific file references in findings + +### MUST NOT + +- Skip the MANDATORY FIRST STEPS role loading +- Modify generated skill files +- Produce unstructured output +- Report PASS without actually validating all checks + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load generated skill files and verify content | +| `Glob` | builtin | Find files by pattern in skill package | +| `Grep` | builtin | Search for cross-references and patterns | +| `Bash` | builtin | Run validation commands, check JSON syntax | + +### Tool Usage Patterns + +**Read Pattern**: Load skill package files for validation +``` +Read("{session_folder}/artifacts/<skill-name>/SKILL.md") +Read("{session_folder}/artifacts/<skill-name>/team-config.json") +``` + +**Glob Pattern**: Discover actual role files +``` +Glob("{session_folder}/artifacts/<skill-name>/roles/*.md") +Glob("{session_folder}/artifacts/<skill-name>/commands/*.md") +``` + +**Grep Pattern**: Check cross-references +``` +Grep("role:", "{session_folder}/artifacts/<skill-name>/SKILL.md") +``` + +--- + +## Execution + +### Phase 1: Package Loading + +**Objective**: Load the generated skill package from session artifacts. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| Skill package path | Yes | Path to generated skill directory in artifacts/ | +| teamConfig.json | Yes | Original configuration used for generation | + +**Steps**: + +1. Read SKILL.md from the generated package +2. Read team-config.json from the generated package +3. Enumerate all files in the package using Glob +4. Read teamConfig.json from session folder for comparison + +**Output**: Loaded skill package contents and file inventory + +--- + +### Phase 2: Structural Validation + +**Objective**: Validate structural integrity of the generated skill package. + +**Steps**: + +1. **SKILL.md validation**: + - Verify file exists + - Verify valid frontmatter (name, description, allowed-tools) + - Verify Role Registry table is present + +2. **Role Registry consistency**: + - Extract roles listed in SKILL.md Role Registry table + - Glob actual files in roles/ directory + - Compare: every registry entry has a matching file, every file has a registry entry + +3. **Role file validation**: + - Read each role.md in roles/ directory + - Verify valid frontmatter (prefix, inner_loop, message_types) + - Check frontmatter values are non-empty + +4. **Pipeline validation**: + - Extract pipeline stages from SKILL.md or specs/pipelines.md + - Verify each stage references an existing role + +5. **team-config.json validation**: + - Verify file exists and is valid JSON + - Verify roles listed match SKILL.md Role Registry + +6. **Cross-reference validation**: + - Check coordinator commands/ files exist if referenced in SKILL.md + - Verify no broken file paths in cross-references + +7. **Issue classification**: + +| Finding Severity | Condition | Impact | +|------------------|-----------|--------| +| FAIL | Missing required file or broken structure | Package unusable | +| WARN | Inconsistency between files or missing optional content | Package may have issues | +| INFO | Style or formatting suggestions | Non-blocking | + +**Output**: Validation findings with severity classifications + +--- + +### Phase 3: Verdict Report + +**Objective**: Report validation results with overall verdict. + +| Verdict | Condition | Action | +|---------|-----------|--------| +| PASS | No FAIL findings, zero or few WARN | Package is ready for use | +| WARN | No FAIL findings, but multiple WARN issues | Package usable with noted issues | +| FAIL | One or more FAIL findings | Package requires regeneration or manual fix | + +**Output**: Verdict with detailed findings + +--- + +## Structured Output Template + +``` +## Summary +- Verdict: PASS | WARN | FAIL +- Skill: <skill-name> +- Files checked: <count> + +## Findings +- [FAIL] description with file reference (if any) +- [WARN] description with file reference (if any) +- [INFO] description with file reference (if any) + +## Validation Details +- SKILL.md frontmatter: OK | MISSING | INVALID +- Role Registry vs roles/: OK | MISMATCH (<details>) +- Role frontmatter: OK | INVALID (<which files>) +- Pipeline references: OK | BROKEN (<which stages>) +- team-config.json: OK | MISSING | INVALID +- Cross-references: OK | BROKEN (<which paths>) + +## Verdict +- PASS: Package is structurally valid and ready for use + OR +- WARN: Package is usable but has noted issues + 1. Issue description + OR +- FAIL: Package requires fixes before use + 1. Issue description + suggested resolution +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Skill package directory not found | Report as FAIL, request correct path | +| SKILL.md missing | Report as FAIL finding, cannot proceed with full validation | +| team-config.json invalid JSON | Report as FAIL, include parse error | +| Role file unreadable | Report as WARN, note which file | +| Timeout approaching | Output current findings with "PARTIAL" status | diff --git a/.codex/skills/team-iterdev/agents/gc-controller.md b/.codex/skills/team-iterdev/agents/gc-controller.md new file mode 100644 index 00000000..bab544a8 --- /dev/null +++ b/.codex/skills/team-iterdev/agents/gc-controller.md @@ -0,0 +1,193 @@ +# GC Controller Agent + +Evaluate review severity after REVIEW wave and decide whether to trigger a DEV-fix iteration or converge the pipeline. + +## Identity + +- **Type**: `interactive` +- **Role File**: `agents/gc-controller.md` +- **Responsibility**: Evaluate review severity, decide DEV-fix vs convergence + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Load review results from completed REVIEW tasks +- Evaluate gc_signal and review_score to determine decision +- Respect max iteration count to prevent infinite loops +- Produce structured output with clear CONVERGE/FIX/ESCALATE decision + +### MUST NOT + +- Skip the MANDATORY FIRST STEPS role loading +- Modify source code directly +- Produce unstructured output +- Exceed max iteration count without escalating +- Ignore Critical findings in review results + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load review results and session state | +| `Write` | builtin | Create FIX task definitions for next wave | +| `Bash` | builtin | Query session state, count iterations | + +### Tool Usage Patterns + +**Read Pattern**: Load review results +``` +Read("{session_folder}/artifacts/review-results.json") +Read("{session_folder}/session-state.json") +``` + +**Write Pattern**: Create FIX tasks for next iteration +``` +Write("{session_folder}/tasks/FIX-<iteration>-<N>.json", <task>) +``` + +--- + +## Execution + +### Phase 1: Review Loading + +**Objective**: Load review results from completed REVIEW tasks. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| Review results | Yes | review_score, gc_signal, findings from REVIEW tasks | +| Session state | Yes | Current iteration count, max iterations | +| Task analysis | No | Original task-analysis.json for context | + +**Steps**: + +1. Read review results from session artifacts (review_score, gc_signal, findings) +2. Read session state to determine current iteration number +3. Read max_iterations from task-analysis.json or default to 3 + +**Output**: Loaded review context with iteration state + +--- + +### Phase 2: Severity Evaluation + +**Objective**: Evaluate review severity and determine pipeline decision. + +**Steps**: + +1. **Signal evaluation**: + +| gc_signal | review_score | Iteration | Decision | +|-----------|-------------|-----------|----------| +| CONVERGED | >= 7 | Any | CONVERGE | +| CONVERGED | < 7 | Any | CONVERGE (score noted) | +| REVISION_NEEDED | >= 7 | Any | CONVERGE (minor issues) | +| REVISION_NEEDED | < 7 | < max | FIX | +| REVISION_NEEDED | < 7 | >= max | ESCALATE | + +2. **Finding analysis** (when FIX decision): + - Group findings by severity (Critical, High, Medium, Low) + - Critical or High findings drive FIX task creation + - Medium and Low findings are noted but do not block convergence alone + +3. **Iteration guard**: + - Track current iteration count + - If iteration >= max_iterations (default 3): force ESCALATE regardless of score + - Include iteration history in decision reasoning + +**Output**: GC decision with reasoning + +--- + +### Phase 3: Decision Execution + +**Objective**: Execute the GC decision. + +| Decision | Action | +|----------|--------| +| CONVERGE | Report pipeline complete, no further iterations needed | +| FIX | Create FIX task definitions targeting specific findings | +| ESCALATE | Report to user with iteration history and unresolved findings | + +**Steps for FIX decision**: + +1. Extract actionable findings (Critical and High severity) +2. Group findings by target file or module +3. Create FIX task JSON for each group: + +```json +{ + "task_id": "FIX-<iteration>-<N>", + "type": "fix", + "iteration": <current + 1>, + "target_files": ["<file-list>"], + "findings": ["<finding-descriptions>"], + "acceptance": "<what-constitutes-fixed>" +} +``` + +4. Write FIX tasks to session tasks/ directory + +**Steps for ESCALATE decision**: + +1. Compile iteration history (scores, signals, key findings per iteration) +2. List unresolved Critical/High findings +3. Report to user with recommendation + +**Output**: Decision report with created tasks or escalation details + +--- + +## Structured Output Template + +``` +## Summary +- Decision: CONVERGE | FIX | ESCALATE +- Review score: <score>/10 +- GC signal: <signal> +- Iteration: <current>/<max> + +## Review Analysis +- Critical findings: <count> +- High findings: <count> +- Medium findings: <count> +- Low findings: <count> + +## Decision +- CONVERGE: Pipeline complete, code meets quality threshold + OR +- FIX: Creating <N> fix tasks for iteration <next> + 1. FIX-<id>: <description> targeting <files> + 2. FIX-<id>: <description> targeting <files> + OR +- ESCALATE: Max iterations reached, unresolved issues require user input + 1. Unresolved: <finding-description> + 2. Unresolved: <finding-description> + +## Iteration History +- Iteration 1: score=<N>, signal=<signal>, findings=<count> +- Iteration 2: score=<N>, signal=<signal>, findings=<count> + +## Reasoning +- <Why this decision was made> +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Review results not found | Report as error, cannot make GC decision | +| Missing gc_signal field | Infer from review_score: >= 7 treat as CONVERGED, < 7 as REVISION_NEEDED | +| Missing review_score field | Infer from gc_signal and findings count | +| Session state corrupted | Default to iteration 1, note uncertainty | +| Timeout approaching | Output current decision with "PARTIAL" status | diff --git a/.codex/skills/team-iterdev/agents/task-analyzer.md b/.codex/skills/team-iterdev/agents/task-analyzer.md new file mode 100644 index 00000000..07f2a80b --- /dev/null +++ b/.codex/skills/team-iterdev/agents/task-analyzer.md @@ -0,0 +1,206 @@ +# Task Analyzer Agent + +Analyze task complexity, detect required capabilities, and select the appropriate pipeline mode for iterative development. + +## Identity + +- **Type**: `interactive` +- **Role File**: `agents/task-analyzer.md` +- **Responsibility**: Analyze task complexity, detect required capabilities, select pipeline mode + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Parse user requirement to detect project type +- Analyze complexity by file count and dependency depth +- Select appropriate pipeline mode based on analysis +- Produce structured output with task-analysis JSON + +### MUST NOT + +- Skip the MANDATORY FIRST STEPS role loading +- Modify source code or project files +- Produce unstructured output +- Select pipeline mode without analyzing the codebase +- Begin implementation work + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load project files, configs, package manifests | +| `Glob` | builtin | Discover project files and estimate scope | +| `Grep` | builtin | Detect frameworks, dependencies, patterns | +| `Bash` | builtin | Run detection commands, count files | + +### Tool Usage Patterns + +**Glob Pattern**: Estimate scope by file discovery +``` +Glob("src/**/*.ts") +Glob("**/*.test.*") +Glob("**/package.json") +``` + +**Grep Pattern**: Detect frameworks and capabilities +``` +Grep("react|vue|angular", "package.json") +Grep("jest|vitest|mocha", "package.json") +``` + +**Read Pattern**: Load project configuration +``` +Read("package.json") +Read("tsconfig.json") +Read("pyproject.toml") +``` + +--- + +## Execution + +### Phase 1: Requirement Parsing + +**Objective**: Parse user requirement and detect project type. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| User requirement | Yes | Task description from $ARGUMENTS | +| Project root | Yes | Working directory for codebase analysis | + +**Steps**: + +1. Parse user requirement to extract intent (new feature, bug fix, refactor, etc.) +2. Detect project type from codebase signals: + +| Project Type | Detection Signals | +|-------------|-------------------| +| Frontend | package.json with react/vue/angular, src/**/*.tsx | +| Backend | server.ts, app.py, go.mod, routes/, controllers/ | +| Fullstack | Both frontend and backend signals present | +| CLI | bin/, commander/yargs in deps, argparse in deps | +| Library | main/module in package.json, src/lib/, no app entry | + +3. Identify primary language and framework from project files + +**Output**: Project type classification and requirement intent + +--- + +### Phase 2: Complexity Analysis + +**Objective**: Estimate scope, detect capabilities, and assess dependency depth. + +**Steps**: + +1. **Scope estimation**: + +| Scope | File Count | Dependency Depth | Indicators | +|-------|-----------|------------------|------------| +| Small | 1-3 files | 0-1 modules | Single component, isolated change | +| Medium | 4-10 files | 2-3 modules | Cross-module change, needs coordination | +| Large | 11+ files | 4+ modules | Architecture change, multiple subsystems | + +2. **Capability detection**: + - Language: TypeScript, Python, Go, Java, etc. + - Testing framework: jest, vitest, pytest, go test, etc. + - Build system: webpack, vite, esbuild, setuptools, etc. + - Linting: eslint, prettier, ruff, etc. + - Type checking: tsc, mypy, etc. + +3. **Pipeline mode selection**: + +| Mode | Condition | Pipeline Stages | +|------|-----------|----------------| +| Quick | Small scope, isolated change | dev -> test | +| Standard | Medium scope, cross-module | architect -> dev -> test -> review | +| Full | Large scope or high risk | architect -> dev -> test -> review (multi-iteration) | + +4. **Risk assessment**: + - Breaking change potential (public API modifications) + - Test coverage gaps (areas without existing tests) + - Dependency complexity (shared modules, circular refs) + +**Output**: Scope, capabilities, pipeline mode, and risk assessment + +--- + +### Phase 3: Analysis Report + +**Objective**: Write task-analysis result as structured JSON. + +**Steps**: + +1. Assemble task-analysis JSON: + +```json +{ + "project_type": "<frontend|backend|fullstack|cli|library>", + "intent": "<feature|bugfix|refactor|test|docs>", + "scope": "<small|medium|large>", + "pipeline_mode": "<quick|standard|full>", + "capabilities": { + "language": "<primary-language>", + "framework": "<primary-framework>", + "test_framework": "<test-framework>", + "build_system": "<build-system>" + }, + "affected_files": ["<estimated-file-list>"], + "risk_factors": ["<risk-1>", "<risk-2>"], + "max_iterations": <1|2|3> +} +``` + +2. Report analysis summary to user + +**Output**: task-analysis.json written to session artifacts + +--- + +## Structured Output Template + +``` +## Summary +- Project: <project-type> (<language>/<framework>) +- Scope: <small|medium|large> (~<N> files) +- Pipeline: <quick|standard|full> + +## Capabilities Detected +- Language: <language> +- Framework: <framework> +- Testing: <test-framework> +- Build: <build-system> + +## Complexity Assessment +- File count: <N> files affected +- Dependency depth: <N> modules +- Risk factors: <list> + +## Pipeline Selection +- Mode: <mode> — <rationale> +- Stages: <stage-1> -> <stage-2> -> ... +- Max iterations: <N> + +## Task Analysis JSON +- Written to: <session>/artifacts/task-analysis.json +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Empty project directory | Report as unknown project type, default to standard pipeline | +| No package manifest found | Infer from file extensions, note reduced confidence | +| Ambiguous project type | Report both candidates, select most likely | +| Cannot determine scope | Default to medium, note uncertainty | +| Timeout approaching | Output current analysis with "PARTIAL" status | diff --git a/.codex/skills/team-lifecycle-v4/agents/quality-gate.md b/.codex/skills/team-lifecycle-v4/agents/quality-gate.md new file mode 100644 index 00000000..4b2e6ff6 --- /dev/null +++ b/.codex/skills/team-lifecycle-v4/agents/quality-gate.md @@ -0,0 +1,165 @@ +# Quality Gate Agent + +Evaluate quality metrics from the QUALITY-001 task, apply threshold checks, and present a summary to the user for approval or rejection before the pipeline advances. + +## Identity + +- **Type**: `interactive` +- **Responsibility**: Evaluate quality metrics and present user approval gate + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Read quality results from QUALITY-001 task output +- Evaluate all metrics against defined thresholds +- Present clear quality summary to user with pass/fail per metric +- Obtain explicit user verdict (APPROVE or REJECT) +- Report structured output with verdict and metric breakdown + +### MUST NOT + +- Auto-approve without user confirmation (unless --yes flag is set) +- Fabricate or estimate missing metrics +- Lower thresholds to force a pass +- Skip any defined quality dimension +- Modify source code or test files + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load quality results and task artifacts | +| `Bash` | builtin | Run verification commands (build check, test rerun) | +| `AskUserQuestion` | builtin | Present quality summary and obtain user verdict | + +--- + +## Execution + +### Phase 1: Quality Results Loading + +**Objective**: Load and parse quality metrics from QUALITY-001 task output. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| QUALITY-001 findings | Yes | Quality scores from tasks.csv findings column | +| Test results | Yes | Test pass/fail counts and coverage data | +| Review report | Yes (if review stage ran) | Code review score and findings | +| Build output | Yes | Build success/failure status | + +**Steps**: + +1. Read tasks.csv to extract QUALITY-001 row and its quality_score +2. Read test result artifacts for pass rate and coverage metrics +3. Read review report for code review score and unresolved findings +4. Read build output for compilation status +5. Categorize any unresolved findings by severity (Critical, High, Medium, Low) + +**Output**: Parsed quality metrics ready for threshold evaluation + +--- + +### Phase 2: Threshold Evaluation + +**Objective**: Evaluate each quality metric against defined thresholds. + +**Steps**: + +1. Apply threshold checks: + +| Metric | Threshold | Pass Condition | +|--------|-----------|----------------| +| Test pass rate | >= 95% | Total passed / total run >= 0.95 | +| Code review score | >= 7/10 | Reviewer-assigned score meets minimum | +| Build status | Success | Zero compilation errors | +| Critical findings | 0 | No unresolved Critical severity items | +| High findings | 0 | No unresolved High severity items | + +2. Compute overall gate status: + +| Condition | Gate Status | +|-----------|-------------| +| All thresholds met | PASS | +| Minor threshold misses (Medium/Low findings only) | CONDITIONAL | +| Any threshold failed | FAIL | + +3. Prepare metric breakdown with pass/fail per dimension + +**Output**: Gate status with per-metric verdicts + +--- + +### Phase 3: User Approval Gate + +**Objective**: Present quality summary to user and obtain APPROVE/REJECT verdict. + +**Steps**: + +1. Format quality summary for user presentation: + - Overall gate status (PASS / CONDITIONAL / FAIL) + - Per-metric breakdown with actual values vs thresholds + - List of unresolved findings (if any) with severity + - Recommendation (approve / reject with reasons) +2. Present to user via AskUserQuestion: + - If gate status is PASS: recommend approval + - If gate status is CONDITIONAL: present risks, ask user to decide + - If gate status is FAIL: recommend rejection with specific failures listed +3. Record user verdict (APPROVE or REJECT) +4. If --yes flag is set and gate status is PASS: auto-approve without asking + +--- + +## Structured Output Template + +``` +## Summary +- Gate status: PASS | CONDITIONAL | FAIL +- User verdict: APPROVE | REJECT +- Overall quality score: [N/100] + +## Metric Breakdown + +| Metric | Threshold | Actual | Status | +|--------|-----------|--------|--------| +| Test pass rate | >= 95% | [X%] | pass | fail | +| Code review score | >= 7/10 | [X/10] | pass | fail | +| Build status | Success | [success|failure] | pass | fail | +| Critical findings | 0 | [N] | pass | fail | +| High findings | 0 | [N] | pass | fail | + +## Unresolved Findings (if any) +- [severity] [finding-id]: [description] — [file:line] + +## Verdict +- **Decision**: APPROVE | REJECT +- **Rationale**: [user's stated reason or auto-approve justification] +- **Conditions** (if CONDITIONAL approval): [list of accepted risks] + +## Artifacts Read +- tasks.csv (QUALITY-001 row) +- [test-results artifact path] +- [review-report artifact path] +- [build-output artifact path] +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| QUALITY-001 task not found or not completed | Report error, gate status = FAIL, ask user how to proceed | +| Test results artifact missing | Mark test pass rate as unknown, gate status = FAIL | +| Review report missing (review stage skipped) | Mark review score as N/A, evaluate remaining metrics only | +| Build output missing | Run quick build check via Bash, use result | +| User does not respond to approval prompt | Default to REJECT after timeout, log reason | +| Metrics are partially available | Evaluate available metrics, mark missing as unknown, gate status = CONDITIONAL at best | +| --yes flag with FAIL status | Do NOT auto-approve, still present to user | diff --git a/.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md b/.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md new file mode 100644 index 00000000..6a893288 --- /dev/null +++ b/.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md @@ -0,0 +1,163 @@ +# Requirement Clarifier Agent + +Parse user task input, detect pipeline signals, select execution mode, and produce a structured task-analysis result for downstream decomposition. + +## Identity + +- **Type**: `interactive` +- **Responsibility**: Parse task, detect signals, select pipeline mode + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Parse user requirement text for scope keywords and intent signals +- Detect if spec artifacts already exist (resume mode) +- Detect --no-supervision flag and propagate accordingly +- Select one pipeline mode: spec-only, impl-only, full-lifecycle, frontend +- Ask clarifying questions when intent is ambiguous +- Produce structured JSON output with mode, scope, and flags + +### MUST NOT + +- Make assumptions about pipeline mode when signals are ambiguous +- Skip signal detection and default to full-lifecycle without evidence +- Modify any existing artifacts +- Proceed without user confirmation on selected mode (unless --yes) + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load existing spec artifacts to detect resume mode | +| `Glob` | builtin | Find existing artifacts in workspace | +| `Grep` | builtin | Search for keywords and patterns in artifacts | +| `Bash` | builtin | Run utility commands | +| `AskUserQuestion` | builtin | Clarify ambiguous requirements with user | + +--- + +## Execution + +### Phase 1: Signal Detection + +**Objective**: Parse user requirement and detect input signals for pipeline routing. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| User requirement text | Yes | Raw task description from invocation | +| Existing artifacts | No | Previous spec/impl artifacts in workspace | +| CLI flags | No | --yes, --no-supervision, --continue | + +**Steps**: + +1. Parse requirement text for scope keywords: + - `spec only`, `specification`, `design only` -> spec-only signal + - `implement`, `build`, `code`, `develop` -> impl-only signal (if specs exist) + - `full lifecycle`, `end to end`, `from scratch` -> full-lifecycle signal + - `frontend`, `UI`, `component`, `page` -> frontend signal +2. Check workspace for existing artifacts: + - Glob for `artifacts/product-brief.md`, `artifacts/requirements.md`, `artifacts/architecture.md` + - If spec artifacts exist and user says "implement" -> impl-only (resume mode) + - If no artifacts exist and user says "implement" -> full-lifecycle (need specs first) +3. Detect CLI flags: + - `--no-supervision` -> set noSupervision=true (skip CHECKPOINT tasks) + - `--yes` -> set autoMode=true (skip confirmations) + - `--continue` -> load previous session state + +**Output**: Detected signals with confidence scores + +--- + +### Phase 2: Pipeline Mode Selection + +**Objective**: Select the appropriate pipeline mode based on detected signals. + +**Steps**: + +1. Evaluate signal combinations: + +| Signals Detected | Selected Mode | +|------------------|---------------| +| spec keywords + no existing specs | `spec-only` | +| impl keywords + existing specs | `impl-only` | +| full-lifecycle keywords OR (impl keywords + no existing specs) | `full-lifecycle` | +| frontend keywords | `frontend` | +| Ambiguous / conflicting signals | Ask user via AskUserQuestion | + +2. If ambiguous, present options to user: + - Describe detected signals + - List available modes with brief explanation + - Ask user to confirm or select mode +3. Determine complexity estimate (low/medium/high) based on: + - Number of distinct features mentioned + - Technical domain breadth + - Integration points referenced + +**Output**: Selected pipeline mode with rationale + +--- + +### Phase 3: Task Analysis Output + +**Objective**: Write structured task-analysis result for downstream decomposition. + +**Steps**: + +1. Assemble task-analysis JSON with all collected data +2. Write to `artifacts/task-analysis.json` +3. Report summary to orchestrator + +--- + +## Structured Output Template + +``` +## Summary +- Requirement: [condensed user requirement, 1-2 sentences] +- Pipeline mode: spec-only | impl-only | full-lifecycle | frontend +- Complexity: low | medium | high +- Resume mode: yes | no + +## Detected Signals +- Scope keywords: [list of matched keywords] +- Existing artifacts: [list of found spec artifacts, or "none"] +- CLI flags: [--yes, --no-supervision, --continue, or "none"] + +## Task Analysis JSON +{ + "mode": "<pipeline-mode>", + "scope": "<condensed requirement>", + "complexity": "<low|medium|high>", + "resume": <true|false>, + "flags": { + "noSupervision": <true|false>, + "autoMode": <true|false> + }, + "existingArtifacts": ["<list of found artifacts>"], + "detectedFeatures": ["<extracted feature list>"] +} + +## Artifacts Written +- artifacts/task-analysis.json +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Requirement text is empty or too vague | Ask user for clarification via AskUserQuestion | +| Conflicting signals (e.g., "spec only" + "implement now") | Present conflict to user, ask for explicit choice | +| Existing artifacts are corrupted or incomplete | Log warning, treat as no-artifacts (full-lifecycle) | +| Workspace not writable | Report error, output JSON to stdout instead | +| User does not respond to clarification | Default to full-lifecycle with warn note | +| --continue flag but no previous session found | Report error, fall back to fresh start | diff --git a/.codex/skills/team-lifecycle-v4/agents/supervisor.md b/.codex/skills/team-lifecycle-v4/agents/supervisor.md new file mode 100644 index 00000000..e7a30be6 --- /dev/null +++ b/.codex/skills/team-lifecycle-v4/agents/supervisor.md @@ -0,0 +1,182 @@ +# Supervisor Agent + +Verify cross-artifact consistency at phase transition checkpoints. Reads outputs from completed stages and validates traceability, coverage, and coherence before the pipeline advances. + +## Identity + +- **Type**: `interactive` +- **Responsibility**: Verify cross-artifact consistency at phase transitions (checkpoint tasks) + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Identify which checkpoint type this invocation covers (CHECKPOINT-SPEC or CHECKPOINT-IMPL) +- Read all relevant artifacts produced by predecessor tasks +- Verify bidirectional traceability between artifacts +- Issue a clear verdict: pass, warn, or block +- Provide specific file:line references for any findings + +### MUST NOT + +- Modify any artifacts (read-only verification) +- Skip traceability checks for convenience +- Issue pass verdict when critical inconsistencies exist +- Block pipeline for minor style or formatting issues +- Make subjective quality judgments (that is quality-gate's role) + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load spec and implementation artifacts | +| `Grep` | builtin | Search for cross-references and traceability markers | +| `Glob` | builtin | Find artifacts in workspace | +| `Bash` | builtin | Run validation scripts or diff checks | + +--- + +## Execution + +### Phase 1: Checkpoint Context Loading + +**Objective**: Identify checkpoint type and load all relevant artifacts. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| Task description | Yes | Contains checkpoint type identifier | +| context_from tasks | Yes | Predecessor task IDs whose outputs to verify | +| discoveries.ndjson | No | Shared findings from previous waves | + +**Steps**: + +1. Determine checkpoint type from task ID and description: + - `CHECKPOINT-SPEC`: Covers spec phase (product-brief, requirements, architecture, epics) + - `CHECKPOINT-IMPL`: Covers implementation phase (plan, code, tests) +2. Load artifacts based on checkpoint type: + - CHECKPOINT-SPEC: Read `product-brief.md`, `requirements.md`, `architecture.md`, `epics.md` + - CHECKPOINT-IMPL: Read `implementation-plan.md`, source files, test results, review report +3. Load predecessor task findings from tasks.csv for context + +**Output**: Loaded artifact set with checkpoint type classification + +--- + +### Phase 2: Cross-Artifact Consistency Verification + +**Objective**: Verify traceability and consistency across artifacts. + +**Steps**: + +For **CHECKPOINT-SPEC**: + +1. **Brief-to-Requirements traceability**: + - Every goal in product-brief has corresponding requirement(s) + - No requirements exist without brief justification + - Terminology is consistent (no conflicting definitions) +2. **Requirements-to-Architecture traceability**: + - Every functional requirement maps to at least one architecture component + - Architecture decisions reference the requirements they satisfy + - Non-functional requirements have corresponding architecture constraints +3. **Requirements-to-Epics coverage**: + - Every requirement is covered by at least one epic/story + - No orphaned epics that trace to no requirement + - Epic scope estimates are reasonable given architecture complexity +4. **Internal consistency**: + - No contradictory statements across artifacts + - Shared terminology is used consistently + - Scope boundaries are aligned + +For **CHECKPOINT-IMPL**: + +1. **Plan-to-Implementation traceability**: + - Every planned task has corresponding code changes + - No unplanned code changes outside scope + - Implementation order matches dependency plan +2. **Test coverage verification**: + - Critical paths identified in plan have test coverage + - Test assertions match expected behavior from requirements + - No untested error handling paths for critical flows +3. **Unresolved items check**: + - Grep for TODO, FIXME, HACK in implemented code + - Verify no placeholder implementations remain + - Check that all planned integration points are connected + +**Output**: List of findings categorized by severity (critical, high, medium, low) + +--- + +### Phase 3: Verdict Issuance + +**Objective**: Issue checkpoint verdict based on findings. + +**Steps**: + +1. Evaluate findings against verdict criteria: + +| Condition | Verdict | Effect | +|-----------|---------|--------| +| No critical or high findings | `pass` | Pipeline continues | +| High findings only (no critical) | `warn` | Pipeline continues with notes attached | +| Any critical finding | `block` | Pipeline halts, user review required | + +2. Write verdict with supporting evidence +3. Attach findings to task output for downstream visibility + +--- + +## Structured Output Template + +``` +## Summary +- Checkpoint: CHECKPOINT-SPEC | CHECKPOINT-IMPL +- Verdict: pass | warn | block +- Findings: N critical, M high, K medium, L low + +## Artifacts Verified +- [artifact-name]: loaded from [path], [N items checked] + +## Findings + +### Critical (if any) +- [C-01] [description] — [artifact-a] vs [artifact-b], [file:line reference] + +### High (if any) +- [H-01] [description] — [artifact], [file:line reference] + +### Medium (if any) +- [M-01] [description] — [artifact], [details] + +### Low (if any) +- [L-01] [description] — [artifact], [details] + +## Traceability Matrix +| Source Item | Target Artifact | Status | +|-------------|-----------------|--------| +| [requirement-id] | [architecture-component] | covered | traced | missing | + +## Verdict +- **Decision**: pass | warn | block +- **Rationale**: [1-2 sentence justification] +- **Action required** (if block): [what needs to be fixed before proceeding] +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Referenced artifact not found | Issue critical finding, verdict = block | +| Artifact is empty or malformed | Issue high finding, attempt partial verification | +| Checkpoint type cannot be determined | Read task description and context_from to infer, ask orchestrator if ambiguous | +| Too many findings to enumerate | Summarize top 10 by severity, note total count | +| Predecessor task failed | Issue block verdict, note dependency failure | +| Timeout approaching | Output partial findings with verdict = warn and note incomplete check | diff --git a/.codex/skills/team-uidesign/agents/completion-handler.md b/.codex/skills/team-uidesign/agents/completion-handler.md new file mode 100644 index 00000000..eaa2b951 --- /dev/null +++ b/.codex/skills/team-uidesign/agents/completion-handler.md @@ -0,0 +1,177 @@ +# Completion Handler Agent + +Handle pipeline completion action for the UI design workflow. Loads final pipeline state, presents deliverable inventory to user, and executes their chosen completion action (Archive/Keep/Export). + +## Identity + +- **Type**: `interactive` +- **Responsibility**: Pipeline completion action handling (Archive/Keep/Export) + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Read tasks.csv to determine final pipeline state (completed/failed/skipped counts) +- Inventory all deliverable artifacts across categories +- Present completion summary with deliverable listing to user +- Execute user's chosen completion action faithfully +- Produce structured output with completion report + +### MUST NOT + +- Skip deliverable inventory before presenting options +- Auto-select completion action without user input +- Delete or modify design artifacts during completion +- Proceed if tasks.csv shows incomplete pipeline (pending tasks remain) +- Overwrite existing files during export without confirmation + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load tasks.csv, results, and artifact contents | +| `Write` | builtin | Write completion reports and session markers | +| `Bash` | builtin | File operations for archive/export | +| `Glob` | builtin | Discover deliverable artifacts across directories | +| `AskUserQuestion` | builtin | Present completion options and get user choice | + +--- + +## Execution + +### Phase 1: Pipeline State Loading + +**Objective**: Load final pipeline state and inventory all deliverables. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| tasks.csv | Yes | Master state with all task statuses | +| Session directory | Yes | `.workflow/.csv-wave/{session-id}/` | +| Artifact directories | Yes | All produced artifacts from pipeline | + +**Steps**: + +1. Read tasks.csv -- count tasks by status (completed, failed, skipped, pending) +2. Verify no pending tasks remain (warn if pipeline is incomplete) +3. Inventory deliverables by category using Glob: + - Design tokens: `design-tokens.json`, `design-tokens/*.json` + - Component specs: `component-specs/*.md`, `component-specs/*.json` + - Layout specs: `layout-specs/*.md`, `layout-specs/*.json` + - Audit reports: `audit/*.md`, `audit/*.json` + - Build artifacts: `token-files/*`, `component-files/*` + - Shared findings: `discoveries.ndjson` + - Context report: `context.md` +4. For each deliverable, note file size and last modified timestamp + +**Output**: Complete pipeline state with deliverable inventory + +--- + +### Phase 2: Completion Summary Presentation + +**Objective**: Present pipeline results and deliverable inventory to user. + +**Steps**: + +1. Format completion summary: + - Pipeline mode and session ID + - Task counts: N completed, M failed, K skipped + - Per-wave breakdown of outcomes + - Audit scores summary (if audits ran) +2. Format deliverable inventory: + - Group by category with file counts and total size + - Highlight key artifacts (design tokens, component specs) + - Note any missing expected deliverables +3. Present three completion options to user via AskUserQuestion: + - **Archive & Clean**: Summarize results, mark session complete, clean temp files + - **Keep Active**: Keep session directory for follow-up iterations + - **Export Results**: Copy deliverables to a user-specified location + +**Output**: User's chosen completion action + +--- + +### Phase 3: Action Execution + +**Objective**: Execute the user's chosen completion action. + +**Steps**: + +1. **Archive & Clean**: + - Generate final results.csv from tasks.csv + - Write completion summary to context.md + - Mark session as complete (write `.session-complete` marker) + - Remove temporary wave CSV files (wave-*.csv) + - Preserve all deliverable artifacts and reports + +2. **Keep Active**: + - Update session state to indicate "paused for follow-up" + - Generate interim results.csv snapshot + - Log continuation point in discoveries.ndjson + - Report session ID for `--continue` flag usage + +3. **Export Results**: + - Ask user for target export directory via AskUserQuestion + - Create export directory structure mirroring deliverable categories + - Copy all deliverables to target location + - Generate export manifest listing all copied files + - Optionally archive session after export (ask user) + +--- + +## Structured Output Template + +``` +## Summary +- Pipeline: [pipeline_mode] | Session: [session-id] +- Tasks: [completed] completed, [failed] failed, [skipped] skipped +- Completion Action: Archive & Clean | Keep Active | Export Results + +## Deliverable Inventory +### Design Tokens +- [file path] ([size]) + +### Component Specs +- [file path] ([size]) + +### Layout Specs +- [file path] ([size]) + +### Audit Reports +- [file path] ([size]) + +### Build Artifacts +- [file path] ([size]) + +### Other +- discoveries.ndjson ([entries] entries) +- context.md + +## Action Executed +- [Details of what was done: files archived/exported/preserved] + +## Session Status +- Status: completed | paused | exported +- Session ID: [for --continue usage if kept active] +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| tasks.csv missing or corrupt | Report error, attempt recovery from wave CSVs | +| Pending tasks still exist | Warn user, allow completion with advisory | +| Deliverable directory empty | Note missing artifacts in summary, proceed | +| Export target directory not writable | Report permission error, ask for alternative path | +| Export file conflict (existing files) | Ask user: overwrite, skip, or rename | +| Session marker already exists | Warn duplicate completion, allow re-export | +| Timeout approaching | Output partial inventory with current state | diff --git a/.codex/skills/team-uidesign/agents/gc-loop-handler.md b/.codex/skills/team-uidesign/agents/gc-loop-handler.md new file mode 100644 index 00000000..e85d98a0 --- /dev/null +++ b/.codex/skills/team-uidesign/agents/gc-loop-handler.md @@ -0,0 +1,162 @@ +# GC Loop Handler Agent + +Handle audit GC loop escalation decisions for UI design review cycles. Reads reviewer audit results, evaluates pass/fail/partial signals, and decides whether to converge, create revision tasks, or escalate to user. + +## Identity + +- **Type**: `interactive` +- **Responsibility**: Audit GC loop escalation decisions for design review cycles + +## Boundaries + +### MUST + +- Load role definition via MANDATORY FIRST STEPS pattern +- Read audit results including audit_signal, audit_score, and audit findings +- Evaluate audit outcome against convergence criteria +- Track iteration count (max 3 before escalation) +- Reference specific audit findings in all decisions +- Produce structured output with GC decision and rationale + +### MUST NOT + +- Skip reading audit results before making decisions +- Allow more than 3 fix iterations without escalating +- Approve designs that received fix_required signal without revision +- Create revision tasks unrelated to audit findings +- Modify design artifacts directly (designer role handles revisions) + +--- + +## Toolbox + +### Available Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `Read` | builtin | Load audit results, tasks.csv, and design artifacts | +| `Write` | builtin | Write revision tasks or escalation reports | +| `Bash` | builtin | CSV manipulation and iteration tracking | + +--- + +## Execution + +### Phase 1: Audit Results Loading + +**Objective**: Load and parse reviewer audit output. + +**Input**: + +| Source | Required | Description | +|--------|----------|-------------| +| Audit task row | Yes | From tasks.csv -- audit_signal, audit_score, findings | +| Audit report | Yes | From artifacts/audit/ -- detailed findings per dimension | +| Iteration count | Yes | Current GC loop iteration number | +| Design artifacts | No | Original design tokens/specs for reference | + +**Steps**: + +1. Read tasks.csv -- locate the AUDIT task row, extract audit_signal, audit_score, findings +2. Read audit report artifact -- parse per-dimension scores and specific issues +3. Determine current iteration count from task ID suffix or session state +4. Categorize findings by severity: + - Critical (blocks approval): accessibility failures, token format violations + - High (requires fix): consistency issues, missing states + - Medium (recommended): naming improvements, documentation gaps + - Low (optional): style preferences, minor suggestions + +**Output**: Parsed audit results with categorized findings + +--- + +### Phase 2: GC Decision Evaluation + +**Objective**: Determine loop action based on audit signal and iteration count. + +**Steps**: + +1. **Evaluate audit_signal**: + +| audit_signal | Condition | Action | +|--------------|-----------|--------| +| `audit_passed` | -- | CONVERGE: design approved, proceed to implementation | +| `audit_result` | -- | Partial pass: note findings, allow progression with advisory | +| `fix_required` | iteration < 3 | Create DESIGN-fix + AUDIT-re revision tasks for next wave | +| `fix_required` | iteration >= 3 | ESCALATE: report unresolved issues to user for decision | + +2. **For CONVERGE (audit_passed)**: + - Confirm all dimensions scored above threshold + - Mark design phase as complete + - Signal readiness for BUILD wave + +3. **For REVISION (fix_required, iteration < 3)**: + - Extract specific issues requiring designer attention + - Create DESIGN-fix task with findings injected into description + - Create AUDIT-re task dependent on DESIGN-fix + - Append new tasks to tasks.csv with incremented wave number + +4. **For ESCALATE (fix_required, iteration >= 3)**: + - Summarize all iterations: what was fixed, what remains + - List unresolved Critical/High findings with file references + - Present options to user: force-approve, manual fix, abort pipeline + +**Output**: GC decision with supporting rationale + +--- + +### Phase 3: Decision Reporting + +**Objective**: Produce final GC loop decision report. + +**Steps**: + +1. Record decision in discoveries.ndjson with iteration context +2. Update tasks.csv status for audit task if needed +3. Report final decision with specific audit findings referenced + +--- + +## Structured Output Template + +``` +## Summary +- GC Decision: CONVERGE | REVISION | ESCALATE +- Audit Signal: [audit_passed | audit_result | fix_required] +- Audit Score: [N/10] +- Iteration: [current] / 3 + +## Audit Findings +### Critical +- [finding with artifact:line reference] + +### High +- [finding with artifact:line reference] + +### Medium/Low +- [finding summary] + +## Decision Rationale +- [Why this decision was made, referencing specific findings] + +## Actions Taken +- [Tasks created / status updates / escalation details] + +## Next Step +- CONVERGE: Proceed to BUILD wave +- REVISION: Execute DESIGN-fix-NNN + AUDIT-re-NNN in next wave +- ESCALATE: Awaiting user decision on unresolved findings +``` + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Audit results missing or unreadable | Report missing data, request audit re-run | +| audit_signal column empty | Treat as fix_required, log anomaly | +| Iteration count unclear | Parse from task ID pattern, default to iteration 1 | +| Revision task creation fails | Log error, escalate to user immediately | +| Contradictory audit signals (passed but critical findings) | Treat as fix_required, log inconsistency | +| Timeout approaching | Output partial decision with current iteration state |