claude-code-workflow 7.2.28 → 7.2.30

package/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json

@@ -38,8 +38,8 @@
     },
     "recommended_execution": {
       "type": "string",
-      "enum": ["Agent", "Codex"],
-      "description": "推荐执行方式"
+      "enum": ["Agent", "Codex", "Sequential", "Parallel", "Phased"],
+      "description": "推荐执行方式 (工具: Agent/Codex, 策略: Sequential/Parallel/Phased)"
     },
 
     "data_flow": {

package/.ccw/workflows/cli-templates/schemas/task-schema.json

@@ -25,7 +25,7 @@
     "_comment_CLASSIFICATION": "CLASSIFICATION 区块 (可选) — 任务分类",
     "type": {
       "type": "string",
-      "enum": ["infrastructure", "feature", "enhancement", "fix", "refactor", "testing", "docs", "chore"],
+      "enum": ["infrastructure", "feature", "enhancement", "fix", "bugfix", "refactor", "testing", "test-gen", "test-fix", "docs", "chore"],
       "description": "任务类型"
     },
     "priority": {
@@ -148,8 +148,13 @@
             "type": "object",
             "required": ["step", "description"],
             "properties": {
-              "step": { "type": "string", "description": "步骤编号/名称" },
+              "step": { "oneOf": [{ "type": "string" }, { "type": "integer" }], "description": "步骤编号/名称" },
+              "title": { "type": "string", "description": "步骤标题" },
               "description": { "type": "string", "description": "步骤描述" },
+              "modification_points": { "type": "array", "items": { "type": "string" }, "description": "量化修改点 (文件/函数/行数)" },
+              "logic_flow": { "type": "array", "items": { "type": "string" }, "description": "实施逻辑序列" },
+              "depends_on": { "type": "array", "items": { "oneOf": [{ "type": "string" }, { "type": "integer" }] }, "description": "依赖步骤" },
+              "output": { "type": "string", "description": "输出变量名" },
               "tdd_phase": { "type": "string", "enum": ["red", "green", "refactor"], "description": "TDD 阶段" },
               "actions": { "type": "array", "items": { "type": "string" }, "description": "具体操作列表" },
               "test_fix_cycle": {
@@ -164,15 +169,17 @@
           }
         ]
       },
-      "description": "步骤化实施指南 — 支持字符串 (简单步骤) 或对象 (含 TDD 阶段等详情)"
+      "description": "步骤化实施指南 — 支持字符串 (简单步骤) 或对象 (含 modification_points/logic_flow/TDD 阶段等详情)"
     },
     "test": {
       "type": "object",
       "properties": {
         "commands": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "测试命令"
+          "oneOf": [
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "object", "additionalProperties": { "type": "string" } }
+          ],
+          "description": "测试命令 (数组或命名对象如 {run_tests, run_coverage, run_specific})"
         },
         "unit": {
           "type": "array",
@@ -513,7 +520,7 @@
     "_comment_RUNTIME": "RUNTIME 区块 (执行时填充) — 运行时状态",
     "status": {
       "type": "string",
-      "enum": ["pending", "in_progress", "completed", "failed", "skipped", "blocked"],
+      "enum": ["pending", "in_progress", "active", "completed", "failed", "skipped", "blocked"],
       "default": "pending",
       "description": "执行状态 (执行引擎填充)"
     },

package/.claude/agents/action-planning-agent.md

@@ -829,11 +829,14 @@ Generate at `.workflow/active/{session_id}/plan.json` following `plan-overview-b
 
 **Generation Timing**: After all `.task/IMPL-*.json` files are generated, aggregate into plan.json.
 
-**Validation**: After writing plan.json and task files, validate with json_builder:
-```bash
-ccw tool exec json_builder '{"cmd":"validate","target":"<session>/plan.json","schema":"plan"}'
-ccw tool exec json_builder '{"cmd":"validate","target":"<session>/.task/IMPL-001.json","schema":"task"}'
+**Schema Reference Fallback** (resolve enum/field conflicts):
+
+If unsure about field enums or structure, read authoritative schema files before generating:
+```
+Read(~/.ccw/workflows/cli-templates/schemas/task-schema.json)
+Read(~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json)
 ```
+Rule: If this agent doc's inline examples conflict with schema file → **schema file wins**.
 
 ### 2.3 IMPL_PLAN.md Structure
 

package/.claude/agents/cli-explore-agent.md

@@ -5,7 +5,6 @@ description: |
   Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation.
   Spawned by /explore command orchestrator.
 tools: Read, Bash, Glob, Grep
-# json_builder available via: ccw tool exec json_builder '{"cmd":"..."}' (Bash)
 color: yellow
 ---
 
@@ -67,9 +66,9 @@ Phase 4: Output Generation
    Store result as `project_structure` for module-aware file discovery in Phase 2.
 
 2. **Output Schema Loading** (if output file path specified in prompt):
-   - Get schema summary: `ccw tool exec json_builder '{"cmd":"info","schema":"explore"}'` (or "diagnosis" for bug analysis)
-   - Initialize output file: `ccw tool exec json_builder '{"cmd":"init","schema":"explore","output":"<output_path>"}'`
-   - The tool returns requiredFields, arrayFields, and enumFields — memorize these for Phase 2.
+   - Exploration output → `cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json`
+   - Other schemas as specified in prompt
+   Read and memorize schema requirements BEFORE any analysis begins (feeds Phase 3 validation).
 
 3. **Project Context Loading** (from spec system):
    - Load exploration specs using: `ccw spec load --category exploration`
@@ -151,56 +150,55 @@ RULES: {from prompt, if template specified} | analysis=READ-ONLY
 ---
 
 <schema_validation>
-## Phase 3: Incremental Build & Validation (via json_builder)
+## Phase 3: Schema Validation
 
-**This phase replaces manual JSON writing + self-validation with tool-assisted construction.**
+### CRITICAL: Schema Compliance Protocol
 
-**Step 1: Set text fields** (discovered during Phase 2 analysis)
-```bash
-ccw tool exec json_builder '{"cmd":"set","target":"<output_path>","ops":[
-  {"path":"project_structure","value":"..."},
-  {"path":"patterns","value":"..."},
-  {"path":"dependencies","value":"..."},
-  {"path":"integration_points","value":"..."},
-  {"path":"constraints","value":"..."}
-]}'
-```
-
-**Step 2: Append file entries** (as discovered — one `set` per batch)
-```bash
-ccw tool exec json_builder '{"cmd":"set","target":"<output_path>","ops":[
-  {"path":"relevant_files[+]","value":{"path":"src/auth.ts","relevance":0.9,"rationale":"Contains AuthService.login() entry point for JWT generation","role":"modify_target","discovery_source":"bash-scan","key_code":[{"symbol":"login()","location":"L45-78","description":"JWT token generation with bcrypt verification"}],"topic_relation":"Security target — JWT generation lacks token rotation"}},
-  {"path":"relevant_files[+]","value":{...}}
-]}'
-```
+**This phase is MANDATORY when schema file is specified in prompt.**
 
-The tool **automatically validates** each operation:
-- enum values (role, discovery_source) → rejects invalid
-- minLength (rationale >= 10) → rejects too short
-- type checking → rejects wrong types
-
-**Step 3: Set metadata**
-```bash
-ccw tool exec json_builder '{"cmd":"set","target":"<output_path>","ops":[
-  {"path":"_metadata.timestamp","value":"auto"},
-  {"path":"_metadata.task_description","value":"..."},
-  {"path":"_metadata.source","value":"cli-explore-agent"},
-  {"path":"_metadata.exploration_angle","value":"..."},
-  {"path":"_metadata.exploration_index","value":1},
-  {"path":"_metadata.total_explorations","value":2}
-]}'
+**Step 1: Read Schema FIRST**
 ```
-
-**Step 4: Final validation**
-```bash
-ccw tool exec json_builder '{"cmd":"validate","target":"<output_path>"}'
+Read(schema_file_path)
 ```
-Returns `{valid, errors, warnings, stats}`. If errors exist → fix with `set` → re-validate.
 
-**Quality reminders** (enforced by tool, but be aware):
-- `rationale`: Must be specific, not generic ("Related to auth" → rejected by semantic check)
-- `key_code`: Strongly recommended for relevance >= 0.7 (warnings if missing)
-- `topic_relation`: Strongly recommended for relevance >= 0.7 (warnings if missing)
+**Step 2: Extract Schema Requirements**
+
+Parse and memorize:
+1. **Root structure** - Is it array `[...]` or object `{...}`?
+2. **Required fields** - List all `"required": [...]` arrays
+3. **Field names EXACTLY** - Copy character-by-character (case-sensitive)
+4. **Enum values** - Copy exact strings (e.g., `"critical"` not `"Critical"`)
+5. **Nested structures** - Note flat vs nested requirements
+
+**Step 3: File Rationale Validation** (MANDATORY for relevant_files / affected_files)
+
+Every file entry MUST have:
+- `rationale` (required, minLength 10): Specific reason tied to the exploration topic, NOT generic
+  - GOOD: "Contains AuthService.login() which is the entry point for JWT token generation"
+  - BAD: "Related to auth" or "Relevant file"
+- `role` (required, enum): Structural classification of why it was selected
+- `discovery_source` (optional but recommended): How the file was found
+- `key_code` (strongly recommended for relevance >= 0.7): Array of {symbol, location?, description}
+  - GOOD: [{"symbol": "AuthService.login()", "location": "L45-L78", "description": "JWT token generation with bcrypt verification, returns token pair"}]
+  - BAD: [{"symbol": "login", "description": "login function"}]
+- `topic_relation` (strongly recommended for relevance >= 0.7): Connection from exploration angle perspective
+  - GOOD: "Security exploration targets this file because JWT generation lacks token rotation"
+  - BAD: "Related to security"
+
+**Step 4: Pre-Output Validation Checklist**
+
+Before writing ANY JSON output, verify:
+
+- [ ] Root structure matches schema (array vs object)
+- [ ] ALL required fields present at each level
+- [ ] Field names EXACTLY match schema (character-by-character)
+- [ ] Enum values EXACTLY match schema (case-sensitive)
+- [ ] Nested structures follow schema pattern (flat vs nested)
+- [ ] Data types correct (string, integer, array, object)
+- [ ] Every file in relevant_files has: path + relevance + rationale + role
+- [ ] Every rationale is specific (>10 chars, not generic)
+- [ ] Files with relevance >= 0.7 have key_code with symbol + description (minLength 10)
+- [ ] Files with relevance >= 0.7 have topic_relation explaining connection to angle (minLength 15)
 </schema_validation>
 
 ---
@@ -214,12 +212,16 @@ Brief summary:
 - Task completion status
 - Key findings summary
 - Generated file paths (if any)
-- Validation result (from Phase 3 Step 4)
 
-### File Output
+### File Output (as specified in prompt)
+
+**MANDATORY WORKFLOW**:
 
-File is already written by json_builder during Phase 3 (init + set operations).
-Phase 4 only verifies the final validation passed and returns the summary.
+1. `Read()` schema file BEFORE generating output
+2. Extract ALL field names from schema
+3. Build JSON using ONLY schema field names
+4. Validate against checklist before writing
+5. Write file with validated content
 </output_generation>
 
 ---
@@ -241,19 +243,28 @@ Phase 4 only verifies the final validation passed and returns the summary.
 
 **ALWAYS**:
 1. **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
-2. **Use json_builder** for all JSON output: `init` → `set` (incremental) → `validate`
-3. Include file:line references in findings
-4. **Every file MUST have rationale + role** (enforced by json_builder set validation)
-5. **Track discovery source**: Record how each file was found (bash-scan/cli-analysis/ace-search/dependency-trace/manual)
-6. **Populate key_code + topic_relation for high-relevance files** (relevance >= 0.7; json_builder warns if missing)
+2. Read schema file FIRST before generating any output (if schema specified)
+3. Copy field names EXACTLY from schema (case-sensitive)
+4. Verify root structure matches schema (array vs object)
+5. Match nested/flat structures as schema requires
+6. Use exact enum values from schema (case-sensitive)
+7. Include ALL required fields at every level
+8. Include file:line references in findings
+9. **Every file MUST have rationale**: Specific selection basis tied to the topic (not generic)
+10. **Every file MUST have role**: Classify as modify_target/dependency/pattern_reference/test_target/type_definition/integration_point/config/context_only
+11. **Track discovery source**: Record how each file was found (bash-scan/cli-analysis/ace-search/dependency-trace/manual)
+12. **Populate key_code for high-relevance files**: relevance >= 0.7 → key_code array with symbol, location, description
+13. **Populate topic_relation for high-relevance files**: relevance >= 0.7 → topic_relation explaining file-to-angle connection
 
 **Bash Tool**:
 - Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
 
 **NEVER**:
-1. Modify any source code files (read-only agent — json_builder writes only output JSON)
-2. Hand-write JSON output — always use json_builder
-3. Skip the `validate` step before returning
+1. Modify any files (read-only agent)
+2. Skip schema reading step when schema is specified
+3. Guess field names - ALWAYS copy from schema
+4. Assume structure - ALWAYS verify against schema
+5. Omit required fields
 </operational_rules>
 
 <output_contract>
@@ -271,8 +282,11 @@ When exploration is complete, return one of:
 
 Before returning, verify:
 - [ ] All 4 phases were executed (or skipped with justification)
-- [ ] json_builder `init` was called at start
-- [ ] json_builder `validate` returned `valid: true` (or all errors were fixed)
+- [ ] Schema was read BEFORE output generation (if schema specified)
+- [ ] All field names match schema exactly (case-sensitive)
+- [ ] Every file entry has rationale (specific, >10 chars) and role
+- [ ] High-relevance files (>= 0.7) have key_code and topic_relation
 - [ ] Discovery sources are tracked for all findings
-- [ ] No source code files were modified (read-only agent)
+- [ ] No files were modified (read-only agent)
+- [ ] Output format matches schema root structure (array vs object)
 </quality_gate>

package/.claude/agents/cli-lite-planning-agent.md

@@ -139,15 +139,16 @@ When `process_docs: true`, generate planning-context.md before sub-plan.json:
 
 ## Schema-Driven Output
 
-**CRITICAL**: Get schema info via json_builder to determine output structure:
-- `ccw tool exec json_builder '{"cmd":"info","schema":"plan"}'` → Implementation plan with `approach`, `complexity`
-- `ccw tool exec json_builder '{"cmd":"info","schema":"plan-fix"}'` → Fix plan with `root_cause`, `severity`, `risk_level`
+**CRITICAL**: Read the schema reference first to determine output structure:
+- `plan-overview-base-schema.json` → Implementation plan with `approach`, `complexity`
+- `plan-overview-fix-schema.json` → Fix plan with `root_cause`, `severity`, `risk_level`
 
-After generating plan.json and .task/*.json, validate:
-```bash
-ccw tool exec json_builder '{"cmd":"validate","target":"<session>/plan.json","schema":"plan"}'
-# For each task file:
-ccw tool exec json_builder '{"cmd":"validate","target":"<session>/.task/TASK-001.json","schema":"task"}'
+```javascript
+// Step 1: Always read schema first
+const schema = Bash(`cat ${schema_path}`)
+
+// Step 2: Generate plan conforming to schema
+const planObject = generatePlanFromSchema(schema, context)
 ```
 
 </schema_driven_output>
@@ -862,7 +863,7 @@ function validateTask(task) {
 
 **ALWAYS**:
 - **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
-- **Get schema info via json_builder** to determine output structure
+- **Read schema first** to determine output structure
 - Generate task IDs (TASK-001/TASK-002 for plan, FIX-001/FIX-002 for fix-plan)
 - Include depends_on (even if empty [])
 - **Assign cli_execution_id** (`{sessionId}-{taskId}`)
@@ -980,7 +981,7 @@ Upon completion, return one of:
 
 Before returning, verify:
 
-- [ ] Schema info was obtained via json_builder and output structure matches schema type (base vs fix)
+- [ ] Schema reference was read and output structure matches schema type (base vs fix)
 - [ ] All tasks have valid IDs (TASK-NNN or FIX-NNN format)
 - [ ] All tasks have 2+ implementation steps
 - [ ] All convergence criteria are quantified and testable (no vague language)