refactor: Clarify agent schema reading with explicit cat commands

Replaced ambiguous "Read: schema.json" instructions with explicit "Execute: cat schema.json" commands to eliminate orchestrator/agent responsibility confusion. Updated in three key sections: - MANDATORY FIRST STEPS: Added "Execute by Agent" header with explicit cat command for schema retrieval - Expected Deliverables: Shortened to reference prior schema step - Success Criteria: Simplified to "Schema obtained via cat" Files modified: - lite-plan.md: explore-json-schema.json + plan-json-schema.json - review-module-cycle.md: dimension results + deep-dive schemas - review-session-cycle.md: dimension results + deep-dive schemas Benefits: - Removes ambiguity about who reads schema (always agent, never orchestrator) - Uses direct command syntax ("cat") instead of passive language - Consistent English-only phrasing across all three files - Three-point reinforcement ensures agents execute schema reading
2026-02-05 01:50:27 +08:00 · 2025-11-26 16:02:00 +08:00
parent 2cf8efec74
commit 7b692ce415
3 changed files with 60 additions and 46 deletions
--- a/.claude/commands/workflow/lite-plan.md
+++ b/.claude/commands/workflow/lite-plan.md
@@ -156,10 +156,11 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
 - **Exploration Index**: ${index + 1} of ${selectedAngles.length}
 - **Output File**: ${sessionFolder}/exploration-${angle}.json

-## MANDATORY FIRST STEPS
+## MANDATORY FIRST STEPS (Execute by Agent)
+**You (cli-explore-agent) MUST execute these steps in order:**
 1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
 2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
-3. Read: ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (output schema)
+3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)

 ## Exploration Strategy (${angle} focus)

@@ -181,6 +182,8 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro

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

+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
+
 **Required Fields** (all ${angle} focused):
 - project_structure: Modules/architecture relevant to ${angle}
 - relevant_files: Files affected from ${angle} perspective
@@ -192,12 +195,13 @@ Execute **${angle}** exploration for task planning context. Analyze codebase fro
 - _metadata.exploration_angle: "${angle}"

 ## Success Criteria
+- [ ] Schema obtained via cat explore-json-schema.json
 - [ ] get_modules_by_depth.sh executed
 - [ ] At least 3 relevant files identified with ${angle} rationale
 - [ ] Patterns are actionable (code examples, not generic advice)
 - [ ] Integration points include file:line locations
 - [ ] Constraints are project-specific to ${angle}
- [ ] JSON follows schema exactly
+- [ ] JSON output follows schema exactly
 - [ ] clarification_needs includes options array

 ## Output
@@ -344,7 +348,7 @@ Task(
 Generate implementation plan and write plan.json.

 ## Output Schema Reference
-~/.claude/workflows/cli-templates/schemas/plan-json-schema.json
+Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan)

 ## Task Description
 ${task_description}
--- a/.claude/commands/workflow/review-module-cycle.md
+++ b/.claude/commands/workflow/review-module-cycle.md
@@ -432,10 +432,12 @@ Task(
    - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
    - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)

-    ## MANDATORY FIRST STEPS
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
    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 ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)

    ## Review Context
    - Review Type: module (independent)
@@ -452,9 +454,8 @@ Task(
    - Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}

    ## Expected Deliverables
-    **MANDATORY**: Before generating any JSON output, read the schema first:
-    - Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
-    - Extract and follow EXACT field names from schema
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 4, follow schema exactly

    1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json

@@ -489,12 +490,13 @@ Task(
    ${getDimensionGuidance(dimension)}

    ## Success Criteria
-    - All target files analyzed for ${dimension} concerns
-    - All findings include file:line references with code snippets
-    - Severity assessment follows established criteria (see reference)
-    - Recommendations are actionable with code examples
-    - JSON output is valid and follows schema exactly
-    - Report is comprehensive and well-organized
+    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] All target files analyzed for ${dimension} concerns
+    - [ ] All findings include file:line references with code snippets
+    - [ ] Severity assessment follows established criteria (see reference)
+    - [ ] Recommendations are actionable with code examples
+    - [ ] JSON output follows schema exactly
+    - [ ] Report is comprehensive and well-organized
  `
 )
 ```
@@ -530,11 +532,13 @@ Task(
    - Original Description: ${description}
    - Iteration: ${iteration}

-    ## MANDATORY FIRST STEPS
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
    1. Read original finding: ${dimensionJsonPath}
    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 ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)

    ## CLI Configuration
    - Tool Priority: gemini → qwen → codex
@@ -542,9 +546,8 @@ Task(
    - Mode: analysis (READ-ONLY)

    ## Expected Deliverables
-    **MANDATORY**: Before generating any JSON output, read the schema first:
-    - Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
-    - Extract and follow EXACT field names from schema
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly

    1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json

@@ -566,13 +569,15 @@ Task(
       - Impact assessment and rollback strategy

    ## Success Criteria
-    - 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
-    - Impact fully assessed (files, tests, breaking changes, dependencies)
-    - Severity re-evaluation justified with evidence
-    - Confidence score accurately reflects certainty of analysis
-    - References include project-specific and external documentation
+    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] 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
+    - [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
+    - [ ] Severity re-evaluation justified with evidence
+    - [ ] Confidence score accurately reflects certainty of analysis
+    - [ ] JSON output follows schema exactly
+    - [ ] References include project-specific and external documentation
  `
 )
 ```
--- a/.claude/commands/workflow/review-session-cycle.md
+++ b/.claude/commands/workflow/review-session-cycle.md
@@ -442,11 +442,13 @@ Task(
    - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
    - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)

-    ## MANDATORY FIRST STEPS
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
    1. Read session metadata: ${sessionMetadataPath}
    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 ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)

    ## Session Context
    - Session ID: ${sessionId}
@@ -463,9 +465,8 @@ Task(
    - Mode: analysis (READ-ONLY)

    ## Expected Deliverables
-    **MANDATORY**: Before generating any JSON output, read the schema first:
-    - Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json
-    - Extract and follow EXACT field names from schema
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly

    1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json

@@ -500,12 +501,13 @@ Task(
    ${getDimensionGuidance(dimension)}

    ## Success Criteria
-    - All changed files analyzed for ${dimension} concerns
-    - All findings include file:line references with code snippets
-    - Severity assessment follows established criteria (see reference)
-    - Recommendations are actionable with code examples
-    - JSON output is valid and follows schema exactly
-    - Report is comprehensive and well-organized
+    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] All changed files analyzed for ${dimension} concerns
+    - [ ] All findings include file:line references with code snippets
+    - [ ] Severity assessment follows established criteria (see reference)
+    - [ ] Recommendations are actionable with code examples
+    - [ ] JSON output follows schema exactly
+    - [ ] Report is comprehensive and well-organized
  `
 )
 ```
@@ -541,11 +543,13 @@ Task(
    - Original Description: ${description}
    - Iteration: ${iteration}

-    ## MANDATORY FIRST STEPS
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
    1. Read original finding: ${dimensionJsonPath}
    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 ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)

    ## CLI Configuration
    - Tool Priority: gemini → qwen → codex
@@ -554,9 +558,8 @@ Task(
    - Mode: analysis (READ-ONLY)

    ## Expected Deliverables
-    **MANDATORY**: Before generating any JSON output, read the schema first:
-    - Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json
-    - Extract and follow EXACT field names from schema
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly

    1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json

@@ -578,13 +581,15 @@ Task(
       - Impact assessment and rollback strategy

    ## Success Criteria
-    - 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
-    - Impact fully assessed (files, tests, breaking changes, dependencies)
-    - Severity re-evaluation justified with evidence
-    - Confidence score accurately reflects certainty of analysis
-    - References include project-specific and external documentation
+    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] 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
+    - [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
+    - [ ] Severity re-evaluation justified with evidence
+    - [ ] Confidence score accurately reflects certainty of analysis
+    - [ ] JSON output follows schema exactly
+    - [ ] References include project-specific and external documentation
  `
 )
 ```