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>
2026-02-05 01:50:27 +08:00 · 2025-10-05 22:20:03 +08:00
parent d76ccac8e4
commit fa6034bf6b
2 changed files with 29 additions and 19 deletions
--- 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:
  <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.
- **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.
--- 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"
      }
    ],