From d843112094a1139a5b8a852b759e6f9dd63de225 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 20 Mar 2026 15:06:57 +0800 Subject: [PATCH] feat: enhance spec loading capabilities and add new categories - Added support for loading specs from new categories: debug, test, review, and validation. - Updated various agents and skills to include instructions for loading project context from the new spec categories. - Introduced new spec documents for test conventions, review standards, and validation rules to improve project guidelines. - Enhanced the frontend to support new watcher settings and display auto-watch status. - Improved the spec index builder to accommodate new categories and ensure proper loading of specifications. --- .claude/agents/cli-planning-agent.md | 3 + .claude/agents/debug-explore-agent.md | 1 + .claude/agents/tdd-developer.md | 1 + .claude/agents/test-action-planning-agent.md | 3 + .claude/agents/test-context-search-agent.md | 1 + .claude/agents/test-fix-agent.md | 3 + .claude/skills/review-code/SKILL.md | 2 + .claude/skills/review-cycle/SKILL.md | 4 + .../skill-simplify/phases/02-optimize.md | 4 + .../spec-generator/phases/05-epics-stories.md | 4 + .../roles/analyzer/role.md | 5 +- .../roles/executor/role.md | 3 +- .../skills/team-review/roles/reviewer/role.md | 3 +- .../team-tech-debt/roles/scanner/role.md | 3 +- .../team-testing/roles/executor/role.md | 3 +- .../team-testing/roles/generator/role.md | 3 +- .../team-ultra-analyze/roles/explorer/role.md | 3 +- .../workflow-execute/phases/06-review.md | 8 +- .../skills/workflow-lite-test-review/SKILL.md | 2 + .../workflow-plan/phases/05-plan-verify.md | 4 + .../phases/02-context-gathering.md | 1 + .../phases/05-tdd-task-generation.md | 3 +- .../phases/02-test-context-gather.md | 1 + .../phases/05-test-cycle-execute.md | 3 +- .../skills/workflow-tune/phases/01-setup.md | 98 ++++++++++++- .codex/skills/analyze-with-file/SKILL.md | 2 + .codex/skills/debug-with-file/SKILL.md | 4 + .codex/skills/issue-discover/SKILL.md | 1 + .../review-cycle/phases/02-parallel-review.md | 3 + .../phases/01-test-fix-gen.md | 4 + .../phases/02-test-cycle-execute.md | 2 + .../components/codexlens/EnvSettingsTab.tsx | 11 ++ .../components/codexlens/IndexManagerTab.tsx | 11 +- ccw/frontend/src/hooks/useCodexLens.ts | 15 ++ ccw/src/commands/spec.ts | 15 +- ccw/src/core/routes/codexlens-routes.ts | 4 +- ccw/src/tools/spec-index-builder.ts | 12 +- ccw/src/tools/spec-init.ts | 129 +++++++++++++++++- ccw/src/tools/spec-loader.ts | 3 +- 39 files changed, 356 insertions(+), 29 deletions(-) diff --git a/.claude/agents/cli-planning-agent.md b/.claude/agents/cli-planning-agent.md index 2dc5699f..af7b7901 100644 --- a/.claude/agents/cli-planning-agent.md +++ b/.claude/agents/cli-planning-agent.md @@ -31,6 +31,9 @@ If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. +**Load Project Context** (from spec system): +- Run: `ccw spec load --category test` for test framework context, coverage targets, and conventions + **Core responsibilities:** - **FIRST: Execute CLI analysis** with appropriate templates and context - Parse structured results (fix strategies, root causes, modification points) diff --git a/.claude/agents/debug-explore-agent.md b/.claude/agents/debug-explore-agent.md index ba591711..d7ae3b4d 100644 --- a/.claude/agents/debug-explore-agent.md +++ b/.claude/agents/debug-explore-agent.md @@ -36,6 +36,7 @@ Phase 5: Fix & Verification ## Phase 1: Bug Analysis **Load Project Context** (from spec system): +- Load debug specs using: `ccw spec load --category debug` for known issues, workarounds, and root-cause notes - Load exploration specs using: `ccw spec load --category exploration` for tech stack context and coding constraints **Session Setup**: diff --git a/.claude/agents/tdd-developer.md b/.claude/agents/tdd-developer.md index 36a980e0..7096123e 100644 --- a/.claude/agents/tdd-developer.md +++ b/.claude/agents/tdd-developer.md @@ -383,6 +383,7 @@ Bash( ### Context Loading (Inherited from code-developer) **Standard Context Sources**: +- Test specs: Run `ccw spec load --category test` for test framework context, conventions, and coverage targets - Task JSON: `description`, `convergence.criteria`, `focus_paths` - Context Package: `context_package_path` → brainstorm artifacts, exploration results - Tech Stack: `meta.shared_context.tech_stack` (skip auto-detection if present) diff --git a/.claude/agents/test-action-planning-agent.md b/.claude/agents/test-action-planning-agent.md index ff4f2ea9..a03f0354 100644 --- a/.claude/agents/test-action-planning-agent.md +++ b/.claude/agents/test-action-planning-agent.md @@ -52,6 +52,9 @@ Read("d:\Claude_dms3\.claude\agents\action-planning-agent.md") ``` +**Load Project Context** (from spec system): +- Run: `ccw spec load --category test` for test framework, coverage targets, and conventions + diff --git a/.claude/agents/test-context-search-agent.md b/.claude/agents/test-context-search-agent.md index c072192e..06915029 100644 --- a/.claude/agents/test-context-search-agent.md +++ b/.claude/agents/test-context-search-agent.md @@ -25,6 +25,7 @@ You are a test context discovery specialist focused on gathering test coverage i **Mandatory Initial Read:** - Project `CLAUDE.md` for coding standards and conventions - Test session metadata (`workflow-session.json`) for session context +- Run: `ccw spec load --category test` for test framework, coverage targets, and conventions **Core Responsibilities:** - Coverage-first analysis of existing tests diff --git a/.claude/agents/test-fix-agent.md b/.claude/agents/test-fix-agent.md index c925657d..338bafa2 100644 --- a/.claude/agents/test-fix-agent.md +++ b/.claude/agents/test-fix-agent.md @@ -34,6 +34,9 @@ If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. +**Load Project Context** (from spec system): +- Run: `ccw spec load --category test` for test framework, coverage targets, and conventions + ## Core Philosophy **"Tests Are the Review"** - When all tests pass across all layers, the code is approved and ready. No separate review process is needed. diff --git a/.claude/skills/review-code/SKILL.md b/.claude/skills/review-code/SKILL.md index ba657f32..878b4383 100644 --- a/.claude/skills/review-code/SKILL.md +++ b/.claude/skills/review-code/SKILL.md @@ -40,6 +40,8 @@ Multi-dimensional code review skill that analyzes code across 6 key dimensions a └─────────────────────────────────────────────────────────────────┘ ``` +**Project Context**: Run `ccw spec load --category review` for review standards, checklists, and approval gates. + ## Key Design Principles 1. **多维度审查**: 覆盖正确性、可读性、性能、安全性、测试覆盖、架构一致性六大维度 diff --git a/.claude/skills/review-cycle/SKILL.md b/.claude/skills/review-cycle/SKILL.md index 432e8ea6..7a61a358 100644 --- a/.claude/skills/review-cycle/SKILL.md +++ b/.claude/skills/review-cycle/SKILL.md @@ -98,6 +98,10 @@ Skill(skill="review-cycle", args="-y src/auth/**") | module | [phases/review-module.md](phases/review-module.md) | review-module-cycle.md | Module-based review: path patterns → 7-dimension parallel analysis → aggregation → deep-dive → completion | | fix | [phases/review-fix.md](phases/review-fix.md) | review-cycle-fix.md | Automated fix: export file → intelligent batching → parallel planning → execution → completion | +## Project Context + +Run `ccw spec load --category review` for review standards, checklists, and approval gates. + ## Core Rules 1. **Mode Detection First**: Parse input to determine session/module/fix mode before anything else diff --git a/.claude/skills/skill-simplify/phases/02-optimize.md b/.claude/skills/skill-simplify/phases/02-optimize.md index d3e3807e..84c38030 100644 --- a/.claude/skills/skill-simplify/phases/02-optimize.md +++ b/.claude/skills/skill-simplify/phases/02-optimize.md @@ -9,6 +9,10 @@ Apply simplification rules from analysisResult to produce optimized content. Wri - Fix pseudo-code format issues - Write optimized content back to target file +## Pre-Step: Load Context + +Run `ccw spec load --category validation` for verification rules and acceptance criteria to validate optimization preserves functional integrity. + ## Execution ### Step 2.1: Apply Operations in Order diff --git a/.claude/skills/spec-generator/phases/05-epics-stories.md b/.claude/skills/spec-generator/phases/05-epics-stories.md index b248d098..2b7e5310 100644 --- a/.claude/skills/spec-generator/phases/05-epics-stories.md +++ b/.claude/skills/spec-generator/phases/05-epics-stories.md @@ -19,6 +19,10 @@ Decompose the specification into executable Epics and Stories with dependency ma ## Execution Steps +### Step 0: Load Validation Context + +Run `ccw spec load --category validation` for verification rules and acceptance criteria to validate epic decomposition. + ### Step 1: Load Phase 2-4 Context ```javascript diff --git a/.claude/skills/team-frontend-debug/roles/analyzer/role.md b/.claude/skills/team-frontend-debug/roles/analyzer/role.md index b8eeaf12..3b39612e 100644 --- a/.claude/skills/team-frontend-debug/roles/analyzer/role.md +++ b/.claude/skills/team-frontend-debug/roles/analyzer/role.md @@ -31,8 +31,9 @@ Root cause analysis from debug evidence. ## Phase 2: Load Evidence -1. Read upstream artifacts via team_msg(operation="get_state", role="reproducer") -2. Extract evidence paths from reproducer's state_update ref +1. Load debug specs: Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes +2. Read upstream artifacts via team_msg(operation="get_state", role="reproducer") +3. Extract evidence paths from reproducer's state_update ref 3. Load evidence-summary.json from session evidence/ 4. Load all evidence files: - Read screenshot files (visual inspection) diff --git a/.claude/skills/team-quality-assurance/roles/executor/role.md b/.claude/skills/team-quality-assurance/roles/executor/role.md index 4908be7e..6f4ab5df 100644 --- a/.claude/skills/team-quality-assurance/roles/executor/role.md +++ b/.claude/skills/team-quality-assurance/roles/executor/role.md @@ -26,7 +26,8 @@ Run test suites, collect coverage data, and perform automatic fix cycles when te | 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 +2. Load validation specs: Run `ccw spec load --category validation` for verification rules and acceptance criteria +3. Read .msg/meta.json for strategy and generated test file list 3. Detect test command by framework: | Framework | Command | diff --git a/.claude/skills/team-review/roles/reviewer/role.md b/.claude/skills/team-review/roles/reviewer/role.md index 4c9cce73..c2f3ab35 100644 --- a/.claude/skills/team-review/roles/reviewer/role.md +++ b/.claude/skills/team-review/roles/reviewer/role.md @@ -21,7 +21,8 @@ Deep analysis on scan findings: triage, root cause / impact / optimization enric | .msg/meta.json | /.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 +2. Load review specs: Run `ccw spec load --category review` for review standards, checklists, and approval gates +3. Load scan results. If missing or empty -> report clean, complete immediately 3. Load wisdom files from `/wisdom/` 4. Triage findings into two buckets: diff --git a/.claude/skills/team-tech-debt/roles/scanner/role.md b/.claude/skills/team-tech-debt/roles/scanner/role.md index 46ef29b4..3a610e92 100644 --- a/.claude/skills/team-tech-debt/roles/scanner/role.md +++ b/.claude/skills/team-tech-debt/roles/scanner/role.md @@ -18,7 +18,8 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch | .msg/meta.json | /.msg/meta.json | Yes | 1. Extract session path and scan scope from task description -2. Read .msg/meta.json for team context +2. Load debug specs: Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes +3. Read .msg/meta.json for team context 3. Detect project type and framework: | Signal File | Project Type | diff --git a/.claude/skills/team-testing/roles/executor/role.md b/.claude/skills/team-testing/roles/executor/role.md index 09e20fef..ee2f0f51 100644 --- a/.claude/skills/team-testing/roles/executor/role.md +++ b/.claude/skills/team-testing/roles/executor/role.md @@ -24,7 +24,8 @@ Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Crit | .msg/meta.json | /wisdom/.msg/meta.json | No | 1. Extract session path and test directory from task description -2. Extract coverage target (default: 80%) +2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets +3. Extract coverage target (default: 80%) 3. Read .msg/meta.json for framework info (from strategist namespace) 4. Determine test framework: diff --git a/.claude/skills/team-testing/roles/generator/role.md b/.claude/skills/team-testing/roles/generator/role.md index a80d69ca..3af47b50 100644 --- a/.claude/skills/team-testing/roles/generator/role.md +++ b/.claude/skills/team-testing/roles/generator/role.md @@ -22,7 +22,8 @@ Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Gen | .msg/meta.json | /wisdom/.msg/meta.json | No | 1. Extract session path and layer from task description -2. Read test strategy: +2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets +3. Read test strategy: ``` Read("/strategy/test-strategy.md") diff --git a/.claude/skills/team-ultra-analyze/roles/explorer/role.md b/.claude/skills/team-ultra-analyze/roles/explorer/role.md index 994eb140..40797208 100644 --- a/.claude/skills/team-ultra-analyze/roles/explorer/role.md +++ b/.claude/skills/team-ultra-analyze/roles/explorer/role.md @@ -18,7 +18,8 @@ Explore codebase structure through cli-explore-agent, collecting structured cont | Task description | From task subject/description | Yes | | Session path | Extracted from task description | Yes | -1. Extract session path, topic, perspective, dimensions from task description: +1. Load debug specs: Run `ccw spec load --category debug` for known issues and root-cause notes +2. Extract session path, topic, perspective, dimensions from task description: | Field | Pattern | Default | |-------|---------|---------| diff --git a/.claude/skills/workflow-execute/phases/06-review.md b/.claude/skills/workflow-execute/phases/06-review.md index 57799840..310aad16 100644 --- a/.claude/skills/workflow-execute/phases/06-review.md +++ b/.claude/skills/workflow-execute/phases/06-review.md @@ -93,7 +93,7 @@ rg "password|token|secret|auth" -g "*.{ts,js,py}" rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}" # Gemini security analysis -ccw spec load --category execution +ccw spec load --category review ccw cli -p " PURPOSE: Security audit of completed implementation TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues @@ -105,7 +105,7 @@ RULES: Focus on OWASP Top 10, authentication, authorization, data validation, in **Architecture Review** (`architecture`): ```bash -ccw spec load --category execution +ccw spec load --category review ccw cli -p " PURPOSE: Architecture compliance review TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions @@ -117,7 +117,7 @@ RULES: Check for patterns, separation of concerns, modularity, scalability **Quality Review** (`quality`): ```bash -ccw spec load --category execution +ccw spec load --category review ccw cli -p " PURPOSE: Code quality and best practices review TASK: Assess code readability, maintainability, adherence to best practices @@ -139,7 +139,7 @@ for task_file in ${sessionPath}/.task/*.json; do done # Cross-check implementation against requirements -ccw spec load --category execution +ccw spec load --category review ccw cli -p " PURPOSE: Verify all requirements and acceptance criteria are met TASK: Cross-check implementation summaries against original requirements diff --git a/.claude/skills/workflow-lite-test-review/SKILL.md b/.claude/skills/workflow-lite-test-review/SKILL.md index 6c0d364c..1628f85f 100644 --- a/.claude/skills/workflow-lite-test-review/SKILL.md +++ b/.claude/skills/workflow-lite-test-review/SKILL.md @@ -8,6 +8,8 @@ allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash Test review and fix engine for lite-execute chain or standalone invocation. +**Project Context**: Run `ccw spec load --category test` for test framework conventions, coverage targets, and fixtures. + --- ## Usage diff --git a/.claude/skills/workflow-plan/phases/05-plan-verify.md b/.claude/skills/workflow-plan/phases/05-plan-verify.md index dd4ff2be..709d34ab 100644 --- a/.claude/skills/workflow-plan/phases/05-plan-verify.md +++ b/.claude/skills/workflow-plan/phases/05-plan-verify.md @@ -34,6 +34,10 @@ You **MUST** consider the user input before proceeding (if not empty). ## Execution +### Step 5.0: Load Validation Context + +Run `ccw spec load --category validation` for verification rules and acceptance criteria. + ### Step 5.1: Initialize Analysis Context ```bash diff --git a/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md b/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md index 4fe12b2f..23f6759a 100644 --- a/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md +++ b/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md @@ -222,6 +222,7 @@ Execute complete context-search-agent workflow for TDD implementation planning: ### Phase 1: Initialization & Pre-Analysis 1. **Project State Loading**: - Run: \`ccw spec load --category execution\` to load project context, tech stack, and guidelines. + - Run: \`ccw spec load --category test\` to load test framework conventions, coverage targets, and fixtures. - If files don't exist, proceed with fresh analysis. 2. **Detection**: Check for existing context-package (early exit if valid) 3. **Foundation**: Initialize CodexLens, get project structure, load docs diff --git a/.claude/skills/workflow-tdd-plan/phases/05-tdd-task-generation.md b/.claude/skills/workflow-tdd-plan/phases/05-tdd-task-generation.md index 96e8c766..16d546d0 100644 --- a/.claude/skills/workflow-tdd-plan/phases/05-tdd-task-generation.md +++ b/.claude/skills/workflow-tdd-plan/phases/05-tdd-task-generation.md @@ -237,13 +237,14 @@ MCP Capabilities: {exa_code, exa_web, code_index} These files provide project-level constraints that apply to ALL tasks: 1. **ccw spec load --category execution** (project specs and tech analysis) +2. **ccw spec load --category test** (test framework, coverage targets, conventions) - Contains: tech_stack, architecture_type, key_components, build_system, test_framework, coding_conventions, naming_rules, forbidden_patterns, quality_gates, custom_constraints - Usage: Populate plan.json shared_context, align task tech choices, set correct test commands - Apply as HARD CONSTRAINTS on all generated tasks — task implementation steps, acceptance criteria, and convergence.verification MUST respect these guidelines - If empty/missing: No additional constraints (proceed normally) -Loading order: \`ccw spec load --category execution\` → planning-notes.md → context-package.json +Loading order: \`ccw spec load --category execution\` → \`ccw spec load --category test\` → planning-notes.md → context-package.json ## USER CONFIGURATION (from Phase 0) Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli diff --git a/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md b/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md index 74c3c48f..14903c75 100644 --- a/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md +++ b/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md @@ -346,6 +346,7 @@ Execute complete context-search-agent workflow for implementation planning: ### Phase 1: Initialization & Pre-Analysis 1. **Project State Loading**: - Run: \`ccw spec load --category execution\` to load project context, tech stack, and guidelines. + - Run: \`ccw spec load --category test\` to load test framework conventions, coverage targets, and fixtures. - If files don't exist, proceed with fresh analysis. 2. **Detection**: Check for existing context-package (early exit if valid) 3. **Foundation**: Initialize CodexLens, get project structure, load docs diff --git a/.claude/skills/workflow-test-fix/phases/05-test-cycle-execute.md b/.claude/skills/workflow-test-fix/phases/05-test-cycle-execute.md index af8562a7..90ca87ac 100644 --- a/.claude/skills/workflow-test-fix/phases/05-test-cycle-execute.md +++ b/.claude/skills/workflow-test-fix/phases/05-test-cycle-execute.md @@ -249,7 +249,8 @@ Task( ${selectedStrategy} - ${strategyDescription} ## PROJECT CONTEXT (MANDATORY) - 1. Run: \`ccw spec load --category execution\` (tech stack, test framework, build system, constraints) + 1. Run: \`ccw spec load --category execution\` (tech stack, build system, constraints) + 2. Run: \`ccw spec load --category test\` (test framework, coverage targets, conventions) ## MANDATORY FIRST STEPS 1. Read test results: ${session.test_results_path} diff --git a/.claude/skills/workflow-tune/phases/01-setup.md b/.claude/skills/workflow-tune/phases/01-setup.md index 1b534998..4c5ce03a 100644 --- a/.claude/skills/workflow-tune/phases/01-setup.md +++ b/.claude/skills/workflow-tune/phases/01-setup.md @@ -377,6 +377,99 @@ if (invalidSteps.length > 0) { } ``` +### Step 1.2b: Generate Test Requirements (Acceptance Criteria) + +> 调优的前提：为每一步生成跟任务匹配的验收标准。没有预期基准，就无法判断命令执行是否达标。 + +用 Gemini 根据 step command + workflow context + 上下游关系，自动推断每步的验收标准。 + +```javascript +// Build step chain description for context +const stepChainDesc = steps.map((s, i) => + `Step ${i + 1}: ${s.name} (${s.type}) — ${s.command}` +).join('\n'); + +const reqGenPrompt = `PURPOSE: Generate concrete acceptance criteria (test requirements) for each step in a workflow pipeline. These criteria will be used to objectively judge whether each step's execution succeeded or failed. + +WORKFLOW: +Name: ${workflowName} +Goal: ${workflowContext} + +STEP CHAIN: +${stepChainDesc} + +TASK: +For each step, generate: +1. **expected_outputs** — what files/artifacts should be produced (specific filenames or patterns) +2. **content_signals** — what content patterns indicate success (keywords, structures, data shapes) +3. **quality_thresholds** — minimum quality bar (e.g., "no empty files", "JSON must be parseable", "must contain at least N items") +4. **pass_criteria** — 1-2 sentence description of what "pass" looks like for this step +5. **fail_signals** — what patterns indicate failure (error messages, empty output, wrong format) +6. **handoff_contract** — what this step must provide for the next step to work (data format, required fields) + +CONTEXT RULES: +- Infer from the command what the step is supposed to do +- Consider workflow goal when judging what "good enough" means +- Each step's handoff_contract should match what the next step needs as input +- Be specific: "report.md with ## Summary section" not "a report file" + +EXPECTED OUTPUT (strict JSON, no markdown): +{ + "step_requirements": [ + { + "step_index": 0, + "step_name": "", + "expected_outputs": [""], + "content_signals": [""], + "quality_thresholds": [""], + "pass_criteria": "", + "fail_signals": [""], + "handoff_contract": "" + } + ] +} + +CONSTRAINTS: Be specific to each command, output ONLY JSON`; + +Bash({ + command: `ccw cli -p "${escapeForShell(reqGenPrompt)}" --tool gemini --mode analysis --rule universal-rigorous-style`, + run_in_background: true, + timeout: 300000 +}); + +// STOP — wait for hook callback +// After callback: parse JSON, attach requirements to each step + +const reqOutput = /* CLI output from callback */; +const reqJsonMatch = reqOutput.match(/\{[\s\S]*\}/); + +if (reqJsonMatch) { + try { + const reqData = JSON.parse(reqJsonMatch[0]); + (reqData.step_requirements || []).forEach(req => { + const idx = req.step_index; + if (idx >= 0 && idx < steps.length) { + steps[idx].test_requirements = { + expected_outputs: req.expected_outputs || [], + content_signals: req.content_signals || [], + quality_thresholds: req.quality_thresholds || [], + pass_criteria: req.pass_criteria || '', + fail_signals: req.fail_signals || [], + handoff_contract: req.handoff_contract || '' + }; + } + }); + } catch (e) { + // Fallback: proceed without generated requirements + // Steps will use any manually provided success_criteria + } +} + +// Capture session ID for resume chain start +const reqSessionMatch = reqOutput.match(/\[CCW_EXEC_ID=([^\]]+)\]/); +const reqSessionId = reqSessionMatch ? reqSessionMatch[1] : null; +``` + ### Step 1.3: Create Workspace ```javascript @@ -414,9 +507,10 @@ const initialState = { index: i, status: 'pending', execution: null, - analysis: null + analysis: null, + test_requirements: s.test_requirements || null // from Step 1.2b })), - analysis_session_id: null, // ccw cli resume chain + analysis_session_id: reqSessionId || null, // resume chain starts from requirements generation process_log_entries: [], synthesis: null, errors: [], diff --git a/.codex/skills/analyze-with-file/SKILL.md b/.codex/skills/analyze-with-file/SKILL.md index 8310a9cf..42eaf69e 100644 --- a/.codex/skills/analyze-with-file/SKILL.md +++ b/.codex/skills/analyze-with-file/SKILL.md @@ -96,6 +96,7 @@ Step 1: Topic Understanding Step 2: Exploration (Inline, No Agents) ├─ Detect codebase → search relevant modules, patterns │ ├─ Run `ccw spec load --category exploration` (if spec system available) + │ ├─ Run `ccw spec load --category debug` (known issues and root-cause notes) │ └─ Use Grep, Glob, Read, mcp__ace-tool__search_context ├─ Multi-perspective analysis (if selected, serial) │ ├─ Single: Comprehensive analysis @@ -320,6 +321,7 @@ const hasCodebase = Bash(` if (hasCodebase !== 'none') { // 1. Read project metadata (if exists) // - Run `ccw spec load --category exploration` (load project specs) + // - Run `ccw spec load --category debug` (known issues and root-cause notes) // - .workflow/specs/*.md (project conventions) // 2. Search codebase for relevant content diff --git a/.codex/skills/debug-with-file/SKILL.md b/.codex/skills/debug-with-file/SKILL.md index 9e0de000..ed4f3a19 100644 --- a/.codex/skills/debug-with-file/SKILL.md +++ b/.codex/skills/debug-with-file/SKILL.md @@ -22,6 +22,10 @@ Enhanced evidence-based debugging with **documented exploration process**. Recor **$BUG** +## Project Context + +Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes. + ## Execution Process ``` diff --git a/.codex/skills/issue-discover/SKILL.md b/.codex/skills/issue-discover/SKILL.md index 4562522d..4b37273a 100644 --- a/.codex/skills/issue-discover/SKILL.md +++ b/.codex/skills/issue-discover/SKILL.md @@ -232,6 +232,7 @@ const agentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) 2. Execute: ccw spec load --category exploration +3. Execute: ccw spec load --category debug (known issues cross-reference) ## TASK CONTEXT ${taskContext} diff --git a/.codex/skills/review-cycle/phases/02-parallel-review.md b/.codex/skills/review-cycle/phases/02-parallel-review.md index 71e4c059..da9111a1 100644 --- a/.codex/skills/review-cycle/phases/02-parallel-review.md +++ b/.codex/skills/review-cycle/phases/02-parallel-review.md @@ -95,6 +95,7 @@ dimensions.forEach(dimension => { 4. Validate file access: bash(ls -la ${targetFiles.join(' ')}) 5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference) 6. Execute: ccw spec load --category "exploration execution" (technology stack and constraints) +7. Execute: ccw spec load --category review (review standards and checklists) --- @@ -217,6 +218,7 @@ dimensions.forEach(dimension => { 5. Read review state: ${reviewStateJsonPath} 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference) 7. Execute: ccw spec load --category "exploration execution" (technology stack and constraints) +8. Execute: ccw spec load --category review (review standards and checklists) --- @@ -335,6 +337,7 @@ const deepDiveAgentId = spawn_agent({ 5. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f) 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference) 7. Execute: ccw spec load --category "exploration execution" (technology stack and constraints for remediation) +8. Execute: ccw spec load --category review (review standards and checklists) --- diff --git a/.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md b/.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md index e1d9fab0..0f95c494 100644 --- a/.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md +++ b/.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md @@ -76,6 +76,7 @@ const contextAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/test-context-search-agent.md (MUST read first) 2. Run: `ccw spec load --category planning` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- @@ -102,6 +103,7 @@ const contextAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first) 2. Run: `ccw spec load --category planning` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- @@ -175,6 +177,7 @@ const analysisAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first) 2. Run: `ccw spec load --category planning` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- @@ -243,6 +246,7 @@ const taskGenAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first) 2. Run: `ccw spec load --category planning` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- diff --git a/.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md b/.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md index b2176232..de74ef87 100644 --- a/.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md +++ b/.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md @@ -91,6 +91,7 @@ const analysisAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first) 2. Run: `ccw spec load --category planning` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- @@ -157,6 +158,7 @@ const fixAgentId = spawn_agent({ ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/test-fix-agent.md (MUST read first) 2. Run: `ccw spec load --category execution` +3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions) --- diff --git a/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx b/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx index 2d9548ef..85289874 100644 --- a/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx +++ b/ccw/frontend/src/components/codexlens/EnvSettingsTab.tsx @@ -66,11 +66,19 @@ const ENV_GROUPS: EnvGroup[] = [ { key: 'CODEXLENS_DB_PATH', label: 'DB Path' }, { key: 'CODEXLENS_INDEX_WORKERS', label: 'Index Workers' }, { key: 'CODEXLENS_CODE_AWARE_CHUNKING', label: 'Code Aware Chunking' }, + { key: 'CODEXLENS_AST_CHUNKING', label: 'AST Chunking' }, { key: 'CODEXLENS_MAX_FILE_SIZE', label: 'Max File Size' }, { key: 'CODEXLENS_HNSW_EF', label: 'HNSW EF' }, { key: 'CODEXLENS_HNSW_M', label: 'HNSW M' }, ], }, + { + title: 'watcher', + fields: [ + { key: 'CODEXLENS_AUTO_WATCH', label: 'Auto Watch' }, + { key: 'CODEXLENS_WATCHER_DEBOUNCE_MS', label: 'Watch Debounce (ms)' }, + ], + }, ]; // Fields that are only relevant in API mode @@ -95,6 +103,9 @@ const FIELD_DEFAULTS: Record = { CODEXLENS_RERANKER_BATCH_SIZE: '32', CODEXLENS_INDEX_WORKERS: '2', CODEXLENS_CODE_AWARE_CHUNKING: 'true', + CODEXLENS_AST_CHUNKING: 'true', + CODEXLENS_AUTO_WATCH: 'false', + CODEXLENS_WATCHER_DEBOUNCE_MS: '1000', CODEXLENS_MAX_FILE_SIZE: '1000000', CODEXLENS_HNSW_EF: '150', CODEXLENS_HNSW_M: '32', diff --git a/ccw/frontend/src/components/codexlens/IndexManagerTab.tsx b/ccw/frontend/src/components/codexlens/IndexManagerTab.tsx index ffab8dbe..c04c2845 100644 --- a/ccw/frontend/src/components/codexlens/IndexManagerTab.tsx +++ b/ccw/frontend/src/components/codexlens/IndexManagerTab.tsx @@ -10,7 +10,7 @@ import { useQueryClient } from '@tanstack/react-query'; import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/Card'; import { Button } from '@/components/ui/Button'; import { Input } from '@/components/ui/Input'; -import { useIndexStatus, useSyncIndex, useRebuildIndex, codexLensKeys, type IndexStatusData } from '@/hooks/useCodexLens'; +import { useIndexStatus, useSyncIndex, useRebuildIndex, useWatcherStatus, codexLensKeys, type IndexStatusData } from '@/hooks/useCodexLens'; import { useWorkflowStore, selectProjectPath } from '@/stores/workflowStore'; interface ProjectStatusCardProps { @@ -131,8 +131,17 @@ export function IndexManagerTab() { } }; + const { autoWatch } = useWatcherStatus(); + return (
+ {/* Global watcher status */} +
+ + {autoWatch ? 'Auto-watch ON' : 'Auto-watch OFF'} + +
+ {/* Add project path */}
{ const result = await loadSpecs({ projectPath, dimension: dimension as 'specs' | 'personal' | undefined, - category: category as 'general' | 'exploration' | 'planning' | 'execution' | undefined, + category: category as 'general' | 'exploration' | 'planning' | 'execution' | 'debug' | 'test' | 'review' | 'validation' | undefined, keywords, outputFormat: stdin ? 'hook' : 'cli', stdinData, @@ -367,11 +367,16 @@ ${chalk.bold('OPTIONS')} --stdin Read input from stdin (Hook mode) --json Output as JSON -${chalk.bold('KEYWORD CATEGORIES')} - Use these predefined keywords to load specs for specific workflow stages: - ${chalk.cyan('exploration')} - Code exploration, analysis, debugging context +${chalk.bold('CATEGORIES')} + Use --category to load specs for specific workflow stages: + ${chalk.cyan('general')} - Applies to all stages (always included) + ${chalk.cyan('exploration')} - Code exploration, analysis, codebase understanding ${chalk.cyan('planning')} - Task planning, requirements context - ${chalk.cyan('execution')} - Implementation, testing, deployment context + ${chalk.cyan('execution')} - Implementation, coding, deployment context + ${chalk.cyan('debug')} - Debugging, known issues, workarounds + ${chalk.cyan('test')} - Test conventions, frameworks, coverage + ${chalk.cyan('review')} - Code review standards, checklists, gates + ${chalk.cyan('validation')} - Verification rules, acceptance criteria ${chalk.bold('EXAMPLES')} ${chalk.gray('# Initialize spec system:')} diff --git a/ccw/src/core/routes/codexlens-routes.ts b/ccw/src/core/routes/codexlens-routes.ts index af39dcdb..447824f8 100644 --- a/ccw/src/core/routes/codexlens-routes.ts +++ b/ccw/src/core/routes/codexlens-routes.ts @@ -101,6 +101,8 @@ const CODEXLENS_ENV_DEFAULTS: Record = { CODEXLENS_CODE_AWARE_CHUNKING: 'true', CODEXLENS_AST_CHUNKING: 'true', CODEXLENS_MAX_FILE_SIZE: '1000000', + CODEXLENS_AUTO_WATCH: 'false', + CODEXLENS_WATCHER_DEBOUNCE_MS: '1000', CODEXLENS_HNSW_EF: '150', CODEXLENS_HNSW_M: '32', }; @@ -147,7 +149,7 @@ function buildMcpServerConfig(savedEnv: Record): Record 0 ? { env: filteredEnv } : {}), }; } diff --git a/ccw/src/tools/spec-index-builder.ts b/ccw/src/tools/spec-index-builder.ts index 59b84b32..5df297fa 100644 --- a/ccw/src/tools/spec-index-builder.ts +++ b/ccw/src/tools/spec-index-builder.ts @@ -28,17 +28,21 @@ import { homedir } from 'os'; /** * Spec categories for workflow stage-based loading. - * - general: Applies to all stages (e.g. coding conventions) - * - exploration: Code exploration, analysis, debugging context + * - general: Applies to all stages (e.g. coding conventions) — always included + * - exploration: Code exploration, analysis, codebase understanding * - planning: Task planning, roadmap, requirements context - * - execution: Implementation, testing, deployment context + * - execution: Implementation, coding, deployment context + * - debug: Debugging, known issues, workarounds, root-cause notes + * - test: Test conventions, frameworks, coverage, fixtures + * - review: Code review standards, checklists, approval gates + * - validation: Verification rules, acceptance criteria, quality checks * * Usage: Set category field in spec frontmatter: * category: exploration * * System-level loading by stage: ccw spec load --category exploration */ -export const SPEC_CATEGORIES = ['general', 'exploration', 'planning', 'execution'] as const; +export const SPEC_CATEGORIES = ['general', 'exploration', 'planning', 'execution', 'debug', 'test', 'review', 'validation'] as const; export type SpecCategory = typeof SPEC_CATEGORIES[number]; diff --git a/ccw/src/tools/spec-init.ts b/ccw/src/tools/spec-init.ts index 80403e40..6e92fe6e 100644 --- a/ccw/src/tools/spec-init.ts +++ b/ccw/src/tools/spec-init.ts @@ -18,7 +18,7 @@ import { join } from 'path'; export interface SpecFrontmatter { title: string; dimension: string; - category?: 'general' | 'exploration' | 'planning' | 'execution'; + category?: 'general' | 'exploration' | 'planning' | 'execution' | 'debug' | 'test' | 'review' | 'validation'; keywords: string[]; readMode: 'required' | 'optional'; priority: 'high' | 'medium' | 'low'; @@ -117,6 +117,133 @@ export const SEED_DOCS: Map = new Map([ - External dependencies require justification - Prefer standard library when available - Pin dependency versions for reproducibility +`, + }, + { + filename: 'debug-notes.md', + frontmatter: { + title: 'Debug Notes', + dimension: 'specs', + category: 'debug', + keywords: ['debug', 'issue', 'workaround', 'root-cause', 'gotcha'], + readMode: 'optional', + priority: 'medium', + }, + body: `# Debug Notes + +## Known Issues + +- Document known bugs and their workarounds here +- Include root-cause analysis for resolved issues + +## Common Gotchas + +- List environment-specific pitfalls +- Note platform differences that cause unexpected behavior + +## Debugging Tips + +- Preferred debugging workflows for this project +- Key log locations and diagnostic commands +`, + }, + { + filename: 'test-conventions.md', + frontmatter: { + title: 'Test Conventions', + dimension: 'specs', + category: 'test', + keywords: ['test', 'coverage', 'mock', 'fixture', 'assertion', 'framework'], + readMode: 'required', + priority: 'high', + }, + body: `# Test Conventions + +## Framework + +- Test runner and assertion library used in this project +- Configuration file locations + +## Structure + +- Test file naming conventions (e.g., *.test.ts, *.spec.ts) +- Test directory organization +- Fixture and mock patterns + +## Coverage + +- Minimum coverage thresholds +- Coverage report configuration +- Files excluded from coverage + +## Best Practices + +- Prefer unit tests for business logic +- Use integration tests for API boundaries +- Mock external dependencies, not internal modules +`, + }, + { + filename: 'review-standards.md', + frontmatter: { + title: 'Review Standards', + dimension: 'specs', + category: 'review', + keywords: ['review', 'checklist', 'gate', 'approval', 'standard'], + readMode: 'required', + priority: 'medium', + }, + body: `# Review Standards + +## Code Review Checklist + +- Correctness: Does it do what it claims? +- Clarity: Is the intent obvious without comments? +- Tests: Are changes covered by tests? +- Security: No new vulnerabilities introduced? +- Performance: No unnecessary allocations or O(n²) loops? + +## Approval Gates + +- All CI checks must pass +- At least one approving review required +- No unresolved conversations + +## Style + +- Follow existing project conventions +- Keep PRs focused and reviewable (< 400 lines preferred) +`, + }, + { + filename: 'validation-rules.md', + frontmatter: { + title: 'Validation Rules', + dimension: 'specs', + category: 'validation', + keywords: ['validation', 'verification', 'acceptance', 'criteria', 'check'], + readMode: 'required', + priority: 'high', + }, + body: `# Validation Rules + +## Acceptance Criteria + +- Define clear pass/fail conditions for each feature +- Include edge cases in acceptance criteria +- Specify performance thresholds where applicable + +## Verification Steps + +- Build must succeed without warnings +- All existing tests must continue to pass +- New features must include corresponding tests + +## Quality Checks + +- No TypeScript strict mode errors +- No linter warnings in changed files +- Bundle size regression checks (if applicable) `, }, ], diff --git a/ccw/src/tools/spec-loader.ts b/ccw/src/tools/spec-loader.ts index 364393f9..5089ca10 100644 --- a/ccw/src/tools/spec-loader.ts +++ b/ccw/src/tools/spec-loader.ts @@ -255,7 +255,8 @@ export function filterSpecs( for (const entry of index.entries) { // Category filter: skip if category specified and doesn't match - if (category && entry.category !== category) { + // 'general' category always passes through (applies to all stages) + if (category && entry.category !== category && entry.category !== 'general') { continue; }