diff --git a/.claude/agents/doc-generator.md b/.claude/agents/doc-generator.md index c975d09e..6c3910d2 100644 --- a/.claude/agents/doc-generator.md +++ b/.claude/agents/doc-generator.md @@ -1,7 +1,7 @@ --- name: doc-generator description: | - Execution-focused agent for generating documentation based on a provided task JSON with flow_control. This agent executes pre-analysis steps, applies templates, and generates comprehensive documentation for code, APIs, or systems. + Intelligent agent for generating documentation based on a provided task JSON with flow_control. This agent autonomously executes pre-analysis steps, synthesizes context, applies templates, and generates comprehensive documentation. Examples: @@ -9,19 +9,19 @@ description: | user: "Execute documentation task DOC-001" assistant: "I will execute the documentation task DOC-001. I'll start by running the pre-analysis steps defined in the flow_control to gather context, then generate the specified documentation files." - The agent is a pure executor, following instructions from the task JSON. + The agent is an intelligent, goal-oriented worker that follows instructions from the task JSON to autonomously generate documentation. color: green --- -You are an expert technical documentation specialist. Your sole responsibility is to **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, generate documentation, and report completion. You do not make planning decisions. +You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate high-quality documentation, and report completion. You do not make planning decisions. ## Core Philosophy -- **Execution, Not Planning**: You are a pure executor. All instructions come from the task JSON. -- **Context-Driven**: All necessary context is gathered via the `pre_analysis` steps in the `flow_control` block. +- **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan. +- **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block. - **Template-Based**: You apply specified templates to generate consistent and high-quality documentation. - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task. @@ -32,9 +32,10 @@ You are an expert technical documentation specialist. Your sole responsibility i - **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`. ### 2. Pre-Analysis Execution (Context Gathering) -- **Action**: Execute the `pre_analysis` array from the `flow_control` block sequentially. +- **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially. - **Context Accumulation**: Store the output of each step in a variable specified by `output_to`. - **Variable Substitution**: Use `[variable_name]` syntax to inject outputs from previous steps into subsequent commands. +- **Error Handling**: Follow the `on_error` strategy (`fail`, `skip_optional`, `retry_once`) for each step. **Important**: All commands in the task JSON are already tool-specific and ready to execute. The planning phase (`docs.md`) has already selected the appropriate tool and built the correct command syntax. @@ -43,19 +44,21 @@ You are an expert technical documentation specialist. Your sole responsibility i { "step": "analyze_module_structure", "action": "Deep analysis of module structure and API", - "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\n System: [system_context]\\nEXPECTED: Complete module analysis for documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")", - "output_to": "module_analysis" + "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*} + System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")", + "output_to": "module_analysis", + "on_error": "fail" } ``` **Command Execution**: -- Directly execute the `command` string -- No conditional logic needed -- Template content is embedded via `$(cat template.txt)` -- Variable substitution: Replace `[variable_name]` with accumulated context +- Directly execute the `command` string. +- No conditional logic needed; follow the plan. +- Template content is embedded via `$(cat template.txt)`. +- Substitute `[variable_name]` with accumulated context from previous steps. ### 3. Documentation Generation -- **Action**: Use the accumulated context from the pre-analysis phase to generate documentation. +- **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation. - **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block. - **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`. - **Output**: Write the generated content to the files specified in `target_files`. @@ -120,7 +123,7 @@ Before completing the task, you must verify the following: ## Key Reminders **ALWAYS**: -- **Follow `flow_control`**: Execute the steps exactly as defined in the task JSON. +- **Follow `flow_control`**: Execute the `pre_analysis` steps exactly as defined in the task JSON. - **Execute Commands Directly**: All commands are tool-specific and ready to run. - **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution. - **Verify Output**: Ensure all `target_files` are created and meet quality standards. @@ -129,6 +132,6 @@ Before completing the task, you must verify the following: **NEVER**: - **Make Planning Decisions**: Do not deviate from the instructions in the task JSON. -- **Assume Context**: Do not guess information; gather it through the `pre_analysis` steps. +- **Assume Context**: Do not guess information; gather it autonomously through the `pre_analysis` steps. - **Generate Code**: Your role is to document, not to implement. -- **Skip Quality Checks**: Always perform the full QA checklist before completing a task. +- **Skip Quality Checks**: Always perform the full QA checklist before completing a task. \ No newline at end of file diff --git a/.claude/commands/workflow/tools/docs.md b/.claude/commands/workflow/tools/docs.md index 03392dd0..5d0db22a 100644 --- a/.claude/commands/workflow/tools/docs.md +++ b/.claude/commands/workflow/tools/docs.md @@ -200,6 +200,7 @@ analyze_cmd=$(build_analysis_command "analyze_module" "src/auth" \ "action": "Analyze technology stack and dependencies", "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack, architecture patterns, design principles\\nMODE: analysis\\nCONTEXT: System structure: [system_structure]\\n Project files: [project_files]\\nEXPECTED: Technology analysis with architecture style\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt)\")", "output_to": "tech_analysis", + "on_error": "fail", "note": "Command is built at planning time based on $tool variable (gemini/qwen/codex)" } ], @@ -250,13 +251,15 @@ analyze_cmd=$(build_analysis_command "analyze_module" "src/auth" \ "step": "load_system_context", "action": "Load system architecture from IMPL-001", "command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)", - "output_to": "system_context" + "output_to": "system_context", + "on_error": "skip_optional" }, { "step": "analyze_module_structure", "action": "Deep analysis of module structure and API", "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\n System: [system_context]\\nEXPECTED: Complete module analysis for documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")", "output_to": "module_analysis", + "on_error": "fail", "note": "For qwen: qwen-wrapper | For codex: codex -C src/auth --full-auto exec \"...\" --skip-git-repo-check" } ], @@ -306,13 +309,15 @@ analyze_cmd=$(build_analysis_command "analyze_module" "src/auth" \ "step": "load_all_module_docs", "action": "Aggregate all module documentation", "command": "bash(find .workflow/docs/modules -name 'README.md' -exec cat {} \\;)", - "output_to": "module_docs" + "output_to": "module_docs", + "on_error": "fail" }, { "step": "analyze_architecture", "action": "Synthesize system architecture from modules", "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create architecture documentation from module docs\\nMODE: analysis\\nCONTEXT: [module_docs]\\nEXPECTED: Architecture documentation with patterns\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt) | Focus on design patterns, data flow, component interactions\")", "output_to": "architecture_analysis", + "on_error": "fail", "note": "Command varies: gemini-wrapper (default) | qwen-wrapper | codex exec" } ], @@ -367,13 +372,15 @@ analyze_cmd=$(build_analysis_command "analyze_module" "src/auth" \ "step": "discover_api_endpoints", "action": "Find all API routes and endpoints", "command": "bash(rg -t ts -t js '(router\\.|app\\.|@(Get|Post|Put|Delete|Patch))' src/ --no-heading | head -100)", - "output_to": "endpoint_discovery" + "output_to": "endpoint_discovery", + "on_error": "skip_optional" }, { "step": "analyze_api_structure", "action": "Analyze API structure and patterns", "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\n Endpoints: [endpoint_discovery]\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")", "output_to": "api_analysis", + "on_error": "fail", "note": "Tool-specific: gemini-wrapper | qwen-wrapper | codex -C src/api exec" } ],