diff --git a/.claude/agents/doc-generator.md b/.claude/agents/doc-generator.md index 3c93c5a9..54f2f825 100644 --- a/.claude/agents/doc-generator.md +++ b/.claude/agents/doc-generator.md @@ -16,14 +16,30 @@ description: | color: green --- -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. +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 or execute documentation generation, and report completion. You do not make planning decisions. + +## Execution Modes + +The agent supports **two execution modes** based on task JSON's `meta.cli_execute` field: + +1. **Agent Mode** (`cli_execute: false`, default): + - CLI analyzes in `pre_analysis` with MODE=analysis + - Agent generates documentation content in `implementation_approach` + - Agent role: Content generator + +2. **CLI Mode** (`cli_execute: true`): + - CLI generates docs in `implementation_approach` with MODE=write + - Agent executes CLI commands via Bash tool + - Agent role: CLI executor and validator ## Core Philosophy - **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan. +- **Mode-Aware**: You adapt execution strategy based on `meta.cli_execute` mode (Agent Mode vs CLI Mode). - **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block. - **Scope-Limited Analysis**: You perform **targeted deep analysis** only within the `focus_paths` specified in the task context. -- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation. +- **Template-Based** (Agent Mode): You apply specified templates to generate consistent and high-quality documentation. +- **CLI-Executor** (CLI Mode): You execute CLI commands that generate documentation directly. - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task. ## Documentation Quality Principles @@ -114,6 +130,9 @@ Before completion, verify: ### 1. Task Ingestion - **Input**: A single task JSON file path. - **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`. +- **Mode Detection**: Check `meta.cli_execute` to determine execution mode: + - `cli_execute: false` → **Agent Mode**: Agent generates documentation content + - `cli_execute: true` → **CLI Mode**: Agent executes CLI commands for doc generation ### 2. Pre-Analysis Execution (Context Gathering) - **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially. @@ -142,6 +161,7 @@ Before completion, verify: ### 3. Documentation Generation - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation. +- **Mode Detection**: Check `meta.cli_execute` field to determine execution mode. - **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially: 1. **Array Structure**: `implementation_approach` is an array of step objects 2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies @@ -151,9 +171,16 @@ Before completion, verify: - Follow `modification_points` and `logic_flow` for each step - Execute `command` if present, otherwise use agent capabilities - Store result in `output` variable for future steps - 5. **CLI Command Execution**: When step contains `command` field, execute via Bash tool (Codex/Gemini CLI). For Codex with dependencies, use `resume --last` flag. -- **Templates**: Apply templates as specified in `meta.template` or step-level templates. -- **Output**: Write the generated content to the files specified in `target_files`. + 5. **CLI Command Execution** (CLI Mode): + - When step contains `command` field, execute via Bash tool + - Commands use gemini/qwen/codex CLI with MODE=write + - CLI directly generates documentation files + - Agent validates CLI output and ensures completeness + 6. **Agent Generation** (Agent Mode): + - When no `command` field, agent generates documentation content + - Apply templates as specified in `meta.template` or step-level templates + - Agent writes files to paths specified in `target_files` +- **Output**: Ensure all files specified in `target_files` are created or updated. ### 4. Progress Tracking with TodoWrite Use `TodoWrite` to provide real-time visibility into the execution process. @@ -215,9 +242,13 @@ Before completing the task, you must verify the following: ## Key Reminders **ALWAYS**: +- **Detect Mode**: Check `meta.cli_execute` to determine execution mode (Agent or CLI). - **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. +- **Mode-Aware Execution**: + - **Agent Mode**: Generate documentation content using agent capabilities + - **CLI Mode**: Execute CLI commands that generate documentation, validate output - **Verify Output**: Ensure all `target_files` are created and meet quality standards. - **Update Progress**: Use `TodoWrite` to track each step of the execution. - **Generate a Summary**: Create a detailed summary upon task completion. @@ -226,4 +257,5 @@ Before completing the task, you must verify the following: - **Make Planning Decisions**: Do not deviate from the instructions in the task JSON. - **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. \ No newline at end of file +- **Skip Quality Checks**: Always perform the full QA checklist before completing a task. +- **Mix Modes**: Do not generate content in CLI Mode or execute CLI in Agent Mode - respect the `cli_execute` flag. \ No newline at end of file diff --git a/.claude/commands/memory/docs.md b/.claude/commands/memory/docs.md index e11c0978..aedbdf17 100644 --- a/.claude/commands/memory/docs.md +++ b/.claude/commands/memory/docs.md @@ -1,7 +1,7 @@ --- name: docs description: Documentation planning and orchestration - creates structured documentation tasks for execution -argument-hint: "[path] [--tool ] [--mode ] [--cli-generate]" +argument-hint: "[path] [--tool ] [--mode ] [--cli-execute]" --- # Documentation Workflow (/memory:docs) @@ -15,8 +15,8 @@ Lightweight planner that analyzes project structure, decomposes documentation wo - Source: `my_app/src/modules/auth/` → Docs: `.workflow/docs/my_app/src/modules/auth/API.md` **Two Execution Modes**: -- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach` -- **--cli-generate**: CLI generates docs in `implementation_approach` (MODE=write) +- **Default (Agent Mode)**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach` +- **--cli-execute (CLI Mode)**: CLI generates docs in `implementation_approach` (MODE=write), agent executes CLI commands ## Path Mirroring Strategy @@ -37,7 +37,7 @@ Lightweight planner that analyzes project structure, decomposes documentation wo ## Parameters ```bash -/memory:docs [path] [--tool ] [--mode ] [--cli-generate] +/memory:docs [path] [--tool ] [--mode ] [--cli-execute] ``` - **path**: Target directory (default: current directory) @@ -57,9 +57,9 @@ Lightweight planner that analyzes project structure, decomposes documentation wo - `qwen`: Architecture analysis, system design focus - `codex`: Implementation validation, code quality -- **--cli-generate**: Enable CLI-based documentation generation (optional) - - When enabled: CLI generates docs with MODE=write in implementation_approach - - When disabled (default): CLI analyzes with MODE=analysis in pre_analysis +- **--cli-execute**: Enable CLI-based documentation generation (optional) + - When enabled: CLI generates docs with MODE=write in implementation_approach, agent executes CLI commands + - When disabled (default): CLI analyzes with MODE=analysis in pre_analysis, agent generates documentation content ## Planning Workflow @@ -100,7 +100,7 @@ bash(touch .workflow/.active-WFS-docs-20240120-143022) #### Step 3: Create Workflow Session Metadata ```bash # Create workflow-session.json in session root (replace values with actual data) -bash(echo '{"session_id":"WFS-docs-20240120-143022","project":"Claude_dms3 documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/Claude_dms3","project_root":"/d/Claude_dms3","project_name":"Claude_dms3","mode":"full","tool":"gemini","cli_generate":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/workflow-session.json) +bash(echo '{"session_id":"WFS-docs-20240120-143022","project":"Claude_dms3 documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/Claude_dms3","project_root":"/d/Claude_dms3","project_name":"Claude_dms3","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/workflow-session.json) ``` **Output**: @@ -108,7 +108,7 @@ bash(echo '{"session_id":"WFS-docs-20240120-143022","project":"Claude_dms3 docum ✓ Session initialized: WFS-docs-20240120-143022 ✓ Target: /d/Claude_dms3 ✓ Mode: full -✓ Tool: gemini, CLI generate: false +✓ Tool: gemini, CLI execute: false ``` ### Phase 2: Analyze Structure @@ -221,7 +221,7 @@ bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/workflow-session.json) bash(jq -r '.update_mode' .workflow/WFS-docs-20240120-143022/workflow-session.json) bash(jq -r '.existing_docs' .workflow/WFS-docs-20240120-143022/workflow-session.json) bash(jq -r '.tool' .workflow/WFS-docs-20240120-143022/workflow-session.json) -bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120-143022/workflow-session.json) +bash(jq -r '.cli_execute' .workflow/WFS-docs-20240120-143022/workflow-session.json) bash(jq -r '.target_path' .workflow/WFS-docs-20240120-143022/workflow-session.json) ``` @@ -291,8 +291,8 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo # Read tool selection bash(jq -r '.tool' .workflow/WFS-docs-20240120-143022/workflow-session.json) -# Read cli_generate flag -bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120-143022/workflow-session.json) +# Read cli_execute flag +bash(jq -r '.cli_execute' .workflow/WFS-docs-20240120-143022/workflow-session.json) # Read mode bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/workflow-session.json) @@ -300,22 +300,24 @@ bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/workflow-session.json) **Output**: - `tool`: `gemini` -- `cli_generate`: `false` +- `cli_execute`: `false` - `mode`: `full` #### Step 2: Determine CLI Strategy -**If cli_generate = false**: +**If cli_execute = false (Agent Mode)**: - MODE: `analysis` - Placement: `pre_analysis` - Approval flag: (none) - Command pattern: `cd dir && gemini -p "..."` +- Agent role: Generate documentation content in implementation_approach -**If cli_generate = true**: +**If cli_execute = true (CLI Mode)**: - MODE: `write` - Placement: `implementation_approach` - Approval flag: `--approval-mode yolo` - Command pattern: `cd dir && gemini --approval-mode yolo -p "..."` +- Agent role: Execute CLI commands, validate output **If tool = codex**: - Command pattern: `codex -C dir --full-auto exec "..." --skip-git-repo-check -s danger-full-access` @@ -338,7 +340,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. - Source: `{project_name}/src/modules/` - Output: `.workflow/docs/{project_name}/src/modules/` -**Default Mode (cli_generate=false)**: +**Agent Mode (cli_execute=false)**: ```json { "id": "IMPL-001", @@ -348,7 +350,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "type": "docs-tree", "agent": "@doc-generator", "tool": "gemini", - "cli_generate": false, + "cli_execute": false, "source_path": "src/modules", "output_path": ".workflow/docs/${project_name}/src/modules" }, @@ -413,7 +415,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. } ``` -**CLI Generate Mode (cli_generate=true)**: +**CLI Execute Mode (cli_execute=true)**: ```json { "id": "IMPL-001", @@ -423,7 +425,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "type": "docs-tree", "agent": "@doc-generator", "tool": "gemini", - "cli_generate": true, + "cli_execute": true, "source_path": "src/modules", "output_path": ".workflow/docs/${project_name}/src/modules" }, @@ -487,7 +489,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. ### Level 2: Project README Task -**Default Mode**: +**Agent Mode**: ```json { "id": "IMPL-004", @@ -498,7 +500,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "type": "docs", "agent": "@doc-generator", "tool": "gemini", - "cli_generate": false + "cli_execute": false }, "flow_control": { "pre_analysis": [ @@ -537,7 +539,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. ### Level 3: Architecture & Examples Documentation Task -**Default Mode**: +**Agent Mode**: ```json { "id": "IMPL-005", @@ -548,7 +550,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "type": "docs", "agent": "@doc-generator", "tool": "gemini", - "cli_generate": false + "cli_execute": false }, "flow_control": { "pre_analysis": [ @@ -600,7 +602,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. ### Level 3: HTTP API Documentation Task (Optional) -**Default Mode**: +**Agent Mode**: ```json { "id": "IMPL-006", @@ -611,7 +613,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "type": "docs", "agent": "@doc-generator", "tool": "gemini", - "cli_generate": false + "cli_execute": false }, "flow_control": { "pre_analysis": [ @@ -682,7 +684,7 @@ Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX. "project_name": "my_app", "mode": "full", "tool": "gemini", - "cli_generate": false, + "cli_execute": false, "update_mode": "update", "existing_docs": 5, "analysis": { @@ -758,7 +760,7 @@ bash(touch .workflow/.active-WFS-docs-20240120-143022) bash(basename "$(pwd)") # Create workflow-session.json (replace values) -bash(echo '{"session_id":"WFS-docs-20240120-143022","project":"project documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/project","project_root":"/d/project","project_name":"project","mode":"full","tool":"gemini","cli_generate":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/workflow-session.json) +bash(echo '{"session_id":"WFS-docs-20240120-143022","project":"project documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/project","project_root":"/d/project","project_name":"project","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/workflow-session.json) # Read workflow session metadata bash(cat .workflow/WFS-docs-20240120-143022/workflow-session.json) @@ -799,12 +801,12 @@ bash(test -d .workflow/docs/my_project && echo "exists" || echo "not exists") **Template Location**: `~/.claude/workflows/cli-templates/prompts/documentation/` -## CLI Generate Mode Summary +## Execution Mode Summary | Mode | CLI Placement | CLI MODE | Agent Role | |------|---------------|----------|------------| -| **Default** | pre_analysis | analysis | Generates documentation files | -| **--cli-generate** | implementation_approach | write | Validates and coordinates CLI output | +| **Agent Mode (default)** | pre_analysis | analysis | Generates documentation files based on analysis | +| **CLI Mode (--cli-execute)** | implementation_approach | write | Executes CLI commands to generate docs, validates output | ## Related Commands - `/workflow:execute` - Execute documentation tasks diff --git a/.claude/commands/memory/skill-memory.md b/.claude/commands/memory/skill-memory.md index a555333f..c22d27fc 100644 --- a/.claude/commands/memory/skill-memory.md +++ b/.claude/commands/memory/skill-memory.md @@ -1,7 +1,7 @@ --- name: skill-memory description: Generate SKILL package index from project documentation -argument-hint: "[path] [--tool ] [--regenerate] [--mode ]" +argument-hint: "[path] [--tool ] [--regenerate] [--mode ] [--cli-execute]" allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*) --- @@ -63,6 +63,7 @@ bash(git rev-parse --show-toplevel 2>/dev/null || pwd) # - tool: "gemini" # - mode: "full" # - regenerate: false (no --regenerate flag) +# - cli_execute: false (no --cli-execute flag) ``` **Step 3: Check Existing Documentation** @@ -93,6 +94,7 @@ bash(test -d .workflow/docs/my_project && echo "still_exists" || echo "deleted") - `DOCS_PATH`: `.workflow/docs/my_project` - `TOOL`: `gemini` (default) or user-specified - `MODE`: `full` (default) or user-specified +- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag - `REGENERATE`: `false` (default) or `true` if --regenerate flag - `EXISTING_DOCS`: `0` (after regenerate) or actual count @@ -108,12 +110,13 @@ bash(test -d .workflow/docs/my_project && echo "still_exists" || echo "deleted") **Command**: ```bash -SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode]") +SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]") ``` **Example**: ```bash /memory:docs /d/my_app --tool gemini --mode full +/memory:docs /d/my_app --tool gemini --mode full --cli-execute ``` **Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection. @@ -122,6 +125,7 @@ SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode]") - `targetPath` from Phase 1 - `tool` from Phase 1 - `mode` from Phase 1 +- `cli_execute` from Phase 1 (optional) **Parse Output**: - Extract session ID pattern: `WFS-docs-[timestamp]` (store as `docsSessionId`) @@ -331,7 +335,7 @@ TodoWrite({todos: [ ## Parameters ```bash -/memory:skill-memory [path] [--tool ] [--regenerate] [--mode ] +/memory:skill-memory [path] [--tool ] [--regenerate] [--mode ] [--cli-execute] ``` - **path**: Target directory (default: current directory) @@ -345,6 +349,9 @@ TodoWrite({todos: [ - **--mode**: Documentation mode (default: full) - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES) - `partial`: Module docs only +- **--cli-execute**: Enable CLI-based documentation generation (optional) + - When enabled: CLI generates docs directly in implementation_approach + - When disabled (default): Agent generates documentation content ## Examples @@ -356,7 +363,7 @@ TodoWrite({todos: [ **Workflow**: 1. Phase 1: Detects current directory, checks existing docs -2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` +2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode) 3. Phase 3: Executes documentation generation via `/workflow:execute` 4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md` @@ -368,7 +375,7 @@ TodoWrite({todos: [ **Workflow**: 1. Phase 1: Parses target path, detects regenerate flag -2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full --regenerate` +2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full` (regenerate handled in Phase 1) 3. Phase 3: Executes documentation regeneration 4. Phase 4: Generates updated SKILL.md @@ -380,10 +387,22 @@ TodoWrite({todos: [ **Workflow**: 1. Phase 1: Detects partial mode -2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` +2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode) 3. Phase 3: Executes module documentation only 4. Phase 4: Generates SKILL.md with module-only index +### Example 4: CLI Execute Mode + +```bash +/memory:skill-memory --cli-execute +``` + +**Workflow**: +1. Phase 1: Detects CLI execute mode +2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode) +3. Phase 3: Executes CLI-based documentation generation +4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md` + ## Benefits - ✅ **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs