feat: add json_builder tool with schema-aware JSON construction and validation

Unified tool replacing manual schema reading (cat schema) across all agents and skills. Supports 5 commands: init (skeleton), set (incremental field setting with instant validation), validate (full structural + semantic), merge (dedup multiple JSONs), info (compact schema summary). Registers 24 schemas in schema-registry.ts. Updates all agent/skill/command files to use json_builder info/init/validate instead of cat schema references. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-29 20:11:04 +08:00 · 2026-03-29 13:37:41 +08:00
parent bbceef3d36
commit 21a6d29701
16 changed files with 1145 additions and 110 deletions
--- a/.claude/skills/review-cycle/phases/review-module.md
+++ b/.claude/skills/review-cycle/phases/review-module.md
@@ -401,7 +401,7 @@ Task(
    1. Read review state: ${reviewStateJsonPath}
    2. Get target files: Read resolved_files from review-state.json
    3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
-    4. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+    4. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"review-dim"}' (get output schema summary)
    5. Read: .workflow/project-tech.json (technology stack and architecture context)
    6. Read: .workflow/specs/*.md (user-defined constraints and conventions to validate against)

@@ -456,7 +456,7 @@ Task(
    ${getDimensionGuidance(dimension)}

    ## Success Criteria
-    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] Schema obtained via json_builder info
    - [ ] All target files analyzed for ${dimension} concerns
    - [ ] All findings include file:line references with code snippets
    - [ ] Severity assessment follows established criteria (see reference)
@@ -505,7 +505,7 @@ Task(
    2. Read affected file: ${file}
    3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
    4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
-    5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+    5. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"review-deep"}' (get output schema summary)
    6. Read: .workflow/project-tech.json (technology stack and architecture context)
    7. Read: .workflow/specs/*.md (user-defined constraints for remediation compliance)

@@ -538,7 +538,7 @@ Task(
       - Impact assessment and rollback strategy

    ## Success Criteria
-    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] Schema obtained via json_builder info
    - [ ] Root cause clearly identified with supporting evidence
    - [ ] Remediation plan is step-by-step actionable with exact file:line references
    - [ ] Each step includes specific commands and validation tests
--- a/.claude/skills/review-cycle/phases/review-session.md
+++ b/.claude/skills/review-cycle/phases/review-session.md
@@ -412,7 +412,7 @@ Task(
    2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
    3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
    4. Read review state: ${reviewStateJsonPath}
-    5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+    5. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"review-dim"}' (get output schema summary)
    6. Read: .workflow/project-tech.json (technology stack and architecture context)
    7. Read: .workflow/specs/*.md (user-defined constraints and conventions to validate against)

@@ -467,7 +467,7 @@ Task(
    ${getDimensionGuidance(dimension)}

    ## Success Criteria
-    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] Schema obtained via json_builder info
    - [ ] All changed files analyzed for ${dimension} concerns
    - [ ] All findings include file:line references with code snippets
    - [ ] Severity assessment follows established criteria (see reference)
@@ -516,7 +516,7 @@ Task(
    2. Read affected file: ${file}
    3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts")
    4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f)
-    5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+    5. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"review-deep"}' (get output schema summary)
    6. Read: .workflow/project-tech.json (technology stack and architecture context)
    7. Read: .workflow/specs/*.md (user-defined constraints for remediation compliance)

@@ -550,7 +550,7 @@ Task(
       - Impact assessment and rollback strategy

    ## Success Criteria
-    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] Schema obtained via json_builder info
    - [ ] Root cause clearly identified with supporting evidence
    - [ ] Remediation plan is step-by-step actionable with exact file:line references
    - [ ] Each step includes specific commands and validation tests
--- a/.claude/skills/workflow-multi-cli-plan/SKILL.md
+++ b/.claude/skills/workflow-multi-cli-plan/SKILL.md
@@ -246,8 +246,8 @@ Agent({
  description: "Generate implementation plan",
  prompt: `
 ## Schema Reference
-Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
-Execute: cat ~/.ccw/workflows/cli-templates/schemas/task-schema.json
+Execute: ccw tool exec json_builder '{"cmd":"info","schema":"plan"}'
+Execute: ccw tool exec json_builder '{"cmd":"info","schema":"task"}'

 ## Output Format: Two-Layer Structure
 - plan.json: Overview with task_ids[] referencing .task/ files (NO tasks[] array)
--- a/.claude/skills/workflow-plan/phases/03-conflict-resolution.md
+++ b/.claude/skills/workflow-plan/phases/03-conflict-resolution.md
@@ -70,7 +70,7 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
  ## Analysis Steps

  ### 0. Load Output Schema (MANDATORY)
-  Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json
+  Execute: ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}' (get schema summary)

  ### 1. Load Context
  - Read existing files from conflict_detection.existing_files
@@ -119,7 +119,7 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`

  Output to conflict-resolution.json (generated in Phase 4)

-  **Schema Reference**: Execute cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json to get full schema
+  **Schema Reference**: Execute ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}' to get schema summary

  Return JSON following the schema. Key requirements:
  - Minimum 2 strategies per conflict, max 4
--- a/.claude/skills/workflow-plan/phases/05-plan-verify.md
+++ b/.claude/skills/workflow-plan/phases/05-plan-verify.md
@@ -195,8 +195,8 @@ Task(
 ## Plan Verification Task

 ### MANDATORY FIRST STEPS
-1. Read: ~/.ccw/workflows/cli-templates/schemas/plan-verify-agent-schema.json (dimensions & rules)
-2. Read: ~/.ccw/workflows/cli-templates/schemas/verify-json-schema.json (output schema)
+1. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"plan-verify"}' (dimensions & rules)
+2. Execute: ccw tool exec json_builder '{"cmd":"info","schema":"verify"}' (output schema)
 3. Read: ${session_file} (user intent)
 4. Read: ${PLANNING_NOTES} (constraints & N+1 context)
 5. Read: ${IMPL_PLAN} (implementation plan)
--- a/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md
+++ b/.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md
@@ -99,7 +99,7 @@ Execute **${angle}** exploration for TDD task planning context. Analyze codebase
 ## MANDATORY FIRST STEPS (Execute by Agent)
 1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
 2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
-3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
+3. Execute: ccw tool exec json_builder '{"cmd":"init","schema":"explore","output":"${sessionFolder}/exploration-${angle}.json"}' (init output + get schema info)

 ## Exploration Strategy (${angle} focus)

@@ -121,7 +121,7 @@ Execute **${angle}** exploration for TDD task planning context. Analyze codebase

 **File**: ${sessionFolder}/exploration-${angle}.json

-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
+**Schema Reference**: Skeleton initialized via json_builder in step 3. Use `set` to populate fields, `validate` before returning.

 **Required Fields** (all ${angle} focused):
 - project_structure: Modules/architecture relevant to ${angle}
@@ -141,7 +141,7 @@ Execute **${angle}** exploration for TDD task planning context. Analyze codebase
 - _metadata.exploration_angle: "${angle}"

 ## Success Criteria
- [ ] Schema obtained via cat explore-json-schema.json
+- [ ] Schema initialized via json_builder init
 - [ ] get_modules_by_depth.sh executed
 - [ ] At least 3 relevant files identified with ${angle} rationale
 - [ ] Patterns are actionable (code examples, not generic advice)
--- a/.claude/skills/workflow-tdd-plan/phases/04-conflict-resolution.md
+++ b/.claude/skills/workflow-tdd-plan/phases/04-conflict-resolution.md
@@ -70,7 +70,7 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
  ## Analysis Steps

  ### 0. Load Output Schema (MANDATORY)
-  Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json
+  Execute: ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}'

  ### 1. Load Context
  - Read existing files from conflict_detection.existing_files
@@ -119,7 +119,7 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`

  Output to conflict-resolution.json (generated in Phase 4)

-  **Schema Reference**: Execute cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json to get full schema
+  **Schema Reference**: Execute ccw tool exec json_builder '{"cmd":"info","schema":"conflict"}' to get schema summary

  Return JSON following the schema. Key requirements:
  - Minimum 2 strategies per conflict, max 4
--- a/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md
+++ b/.claude/skills/workflow-test-fix/phases/02-test-context-gather.md
@@ -223,7 +223,7 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
 ## MANDATORY FIRST STEPS (Execute by Agent)
 1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
 2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
-3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
+3. Execute: ccw tool exec json_builder '{"cmd":"init","schema":"explore","output":"${sessionFolder}/exploration-${angle}.json"}' (init output + get schema info)

 ## Exploration Strategy (${angle} focus)

@@ -265,7 +265,7 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
 - _metadata.exploration_angle: "${angle}"

 ## Success Criteria
- [ ] Schema obtained via cat explore-json-schema.json
+- [ ] Schema initialized via json_builder init
 - [ ] get_modules_by_depth.sh executed
 - [ ] At least 3 relevant files identified with ${angle} rationale
 - [ ] Patterns are actionable (code examples, not generic advice)