From 7b692ce415189b478135be901173939a36fd7f63 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 26 Nov 2025 16:02:00 +0800 Subject: [PATCH] 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 --- .claude/commands/workflow/lite-plan.md | 12 +++-- .../commands/workflow/review-module-cycle.md | 47 ++++++++++--------- .../commands/workflow/review-session-cycle.md | 47 ++++++++++--------- 3 files changed, 60 insertions(+), 46 deletions(-) diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md index 93e8dae9..71a2a46a 100644 --- 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} diff --git a/.claude/commands/workflow/review-module-cycle.md b/.claude/commands/workflow/review-module-cycle.md index 03ae9809..2bd0751c 100644 --- 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 ` ) ``` diff --git a/.claude/commands/workflow/review-session-cycle.md b/.claude/commands/workflow/review-session-cycle.md index e469f647..93595bba 100644 --- 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 ` ) ```