refactor: enhance doc-generator agent and add error handling

- Update doc-generator agent description to emphasize intelligent autonomous execution
- Add on_error field to all flow_control pre_analysis steps
- Clarify agent role as goal-oriented worker vs script runner
- Improve error handling documentation in workflow examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.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:
   <example>
@@ -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."
   <commentary>
-  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.
   </commentary>
   </example>
 
 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.
+- **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 via the `pre_analysis` steps in the `flow_control` block.
+- **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)\")",
+  "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: @{**/*}
-  "output_to": "module_analysis"
+         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
+- Directly execute the `command` string.
-- No conditional logic needed
+- No conditional logic needed; follow the plan.
-- Template content is embedded via `$(cat template.txt)`
+- Template content is embedded via `$(cat template.txt)`.
-- Variable substitution: Replace `[variable_name]` with accumulated context
+- 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.

.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"
       }
     ],