docs: update task-generate-agent documentation for clarity on planning document generation and execution phases

2026-02-05 01:50:27 +08:00 · 2025-11-23 22:57:43 +08:00
parent 99a5c75b13
commit ff808ed539
2 changed files with 61 additions and 74 deletions
--- a/.claude/agents/action-planning-agent.md
+++ b/.claude/agents/action-planning-agent.md
@@ -153,12 +153,14 @@ if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
   - Add quantified requirements and measurable acceptance criteria

 3. Create IMPL_PLAN.md
-   - Summarize context analysis
-   - List brainstorming artifacts with priorities
-   - Document task breakdown and dependencies
+   - Load template: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
+   - Follow template structure and validation checklist
+   - Populate all 8 sections with synthesized context
+   - Document CCW workflow phase progression
+   - Update quality gate status

 4. Generate TODO_LIST.md
-   - Proper structure (▸ for containers, [ ] for pending, [x] for completed)
+   - Flat structure ([ ] for pending, [x] for completed)
   - Link to task JSONs and summaries

 5. Update session state for execution readiness
@@ -200,17 +202,17 @@ Generate individual `.task/IMPL-*.json` files with the following structure:

 ```json
 {
-  "id": "IMPL-N[.M]",
+  "id": "IMPL-N",
  "title": "Descriptive task name",
-  "status": "pending|active|completed|blocked|container",
+  "status": "pending|active|completed|blocked",
  "context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json"
 }
 ```

 **Field Descriptions**:
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks, max 2 levels)
+- `id`: Task identifier (format: `IMPL-N`)
 - `title`: Descriptive task name summarizing the work
- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies), `container` (has subtasks, cannot be executed directly)
+- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies)
 - `context_package_path`: Path to smart context package containing project structure, dependencies, and brainstorming artifacts catalog

 #### Meta Object
@@ -246,7 +248,6 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
      "5 files created: verify by ls src/auth/*.ts | wc -l = 5",
      "Test coverage >=80%: verify by npm test -- --coverage | grep auth"
    ],
-    "parent": "IMPL-N",
    "depends_on": ["IMPL-N"],
    "inherited": {
      "from": "IMPL-N",
@@ -275,7 +276,6 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
 - `requirements`: **QUANTIFIED** implementation requirements (MUST include explicit counts and enumerated lists, e.g., "5 files: [list]")
 - `focus_paths`: Target directories/files (concrete paths without wildcards)
 - `acceptance`: **MEASURABLE** acceptance criteria (MUST include verification commands, e.g., "verify by ls ... | wc -l = N")
- `parent`: Parent task ID for subtasks (establishes container/subtask hierarchy)
 - `depends_on`: Prerequisite task IDs that must complete before this task starts
 - `inherited`: Context, patterns, and dependencies passed from parent task
 - `shared_context`: Tech stack, conventions, and architectural strategies for the task
@@ -522,39 +522,20 @@ The `implementation_approach` supports **two execution modes** based on the pres

 ### 2.2 IMPL_PLAN.md Structure

-Generate at `.workflow/active/{session_id}/IMPL_PLAN.md`:
+**Template-Based Generation**:

-```markdown
---
-identifier: {session_id}
-source: "User requirements"
-analysis: .workflow/active/{session_id}/.process/ANALYSIS_RESULTS.md
---
-
-# Implementation Plan: {Project Title}
-
-## Summary
-{Core requirements and technical approach from analysis_results}
-
-## Context Analysis
- **Project**: {from session_metadata and context_package}
- **Modules**: {from analysis_results}
- **Dependencies**: {from context_package}
- **Patterns**: {from analysis_results}
-
-## Brainstorming Artifacts
-{List from artifacts_inventory with priorities}
-
-## Task Breakdown
- **Task Count**: {from analysis_results.tasks.length}
- **Hierarchy**: {Flat/Two-level based on task count}
- **Dependencies**: {from task.depends_on relationships}
-
-## Implementation Plan
- **Execution Strategy**: {Sequential/Parallel}
- **Resource Requirements**: {Tools, dependencies}
- **Success Criteria**: {from analysis_results}
 ```
+1. Load template: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
+2. Populate all sections following template structure
+3. Complete template validation checklist
+4. Generate at .workflow/active/{session_id}/IMPL_PLAN.md
+```
+
+**Data Sources**:
+- Session metadata (user requirements, session_id)
+- Context package (project structure, dependencies, focus_paths)
+- Analysis results (technical approach, architecture decisions)
+- Brainstorming artifacts (role analyses, guidance specifications)

 ### 2.3 TODO_LIST.md Structure

@@ -564,21 +545,19 @@ Generate at `.workflow/active/{session_id}/TODO_LIST.md`:
 # Tasks: {Session Topic}

 ## Task Progress
-▸ **IMPL-001**: [Main Task] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-
- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
+- [ ] **IMPL-001**: [Task Title] → [📋](./.task/IMPL-001.json)
+- [ ] **IMPL-002**: [Task Title] → [📋](./.task/IMPL-002.json)
+- [x] **IMPL-003**: [Task Title] → [✅](./.summaries/IMPL-003-summary.md)

 ## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task
+- `- [ ]` = Pending task
+- `- [x]` = Completed task
 ```

 **Linking Rules**:
 - Todo items → task JSON: `[📋](./.task/IMPL-XXX.json)`
 - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)`
- Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels)
+- Consistent ID schemes: IMPL-XXX

 ### 2.4 Complexity-Based Structure Selection

@@ -586,11 +565,11 @@ Use `analysis_results.complexity` or task count to determine structure:

 **Simple Tasks** (≤5 tasks):
 - Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
- No container tasks, all leaf tasks
+- All tasks at same level

 **Medium Tasks** (6-12 tasks):
- Two-level hierarchy: IMPL_PLAN.md + TODO_LIST.md + task JSONs
- Optional container tasks for grouping
+- Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
+- All tasks at same level

 **Complex Tasks** (>12 tasks):
 - **Re-scope required**: Maximum 12 tasks hard limit
@@ -639,8 +618,8 @@ Use `analysis_results.complexity` or task count to determine structure:
 ### 3.3 File Organization

 - Session naming: `WFS-[topic-slug]`
- Task IDs: IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z
- Directory structure follows complexity (Level 0/1/2)
+- Task IDs: IMPL-XXX (flat structure only)
+- Directory structure: flat task organization

 ### 3.4 Document Standards

@@ -653,6 +632,7 @@ Use `analysis_results.complexity` or task count to determine structure:

 **ALWAYS:**
 - **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
+- **Load IMPL_PLAN template**: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt) before generating IMPL_PLAN.md
 - **Use provided context package**: Extract all information from structured context
 - **Respect memory-first rule**: Use provided content (already loaded from memory/file)
 - **Follow 6-field schema**: All task JSONs must have id, title, status, context_package_path, meta, context, flow_control
@@ -663,6 +643,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
 - **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
 - **Apply 举一反三 principle**: Adapt pre-analysis patterns to task-specific needs dynamically
+- **Follow template validation**: Complete IMPL_PLAN.md template validation checklist before finalization

 **NEVER:**
 - Load files directly (use provided context package instead)
--- a/.claude/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/commands/workflow/tools/task-generate-agent.md
@@ -1,31 +1,32 @@
 ---
 name: task-generate-agent
-description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
+description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
 argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
  - /workflow:tools:task-generate-agent --session WFS-auth
  - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
 ---

-# Autonomous Task Generation Command
+# Generate Implementation Plan Command

 ## Overview
-Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
+Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **planning artifacts only** - it does NOT execute code implementation. Actual code implementation requires separate execution command (e.g., /workflow:execute).

 ## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
+- **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code
+- **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent
 - **Progressive Loading**: Load content incrementally (Core → Selective → On-Demand) to avoid token overflow - NEVER load all files at once
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
+- **Two-Phase Flow**: Discovery (context gathering) → Output (planning document generation)
 - **Memory-First**: Reuse loaded documents from conversation memory
 - **Smart Selection**: Load synthesis_output OR guidance + 1-2 role analyses, NOT all role analyses
 - **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
 - **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)

-## Execution Lifecycle
+## Document Generation Lifecycle

 ### Phase 1: Context Preparation (Command Responsibility)

-**Command prepares session paths and metadata, agent loads content autonomously.**
+**Command prepares session paths and metadata for planning document generation.**

 **Session Path Structure**:
 ```
@@ -51,16 +52,20 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit

 **Note**: Agent uses **progressive loading strategy** to avoid token overflow. Load context incrementally (Core → Selective → On-Demand), NOT all files at once. Brainstorming artifacts loaded selectively based on availability and relevance.

-### Phase 2: Agent Execution (Document Generation)
+### Phase 2: Planning Document Generation (Agent Responsibility)
+
+**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.

 **Agent Invocation**:
 ```javascript
 Task(
  subagent_type="action-planning-agent",
-  description="Generate task JSON and implementation plan",
+  description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
  prompt=`
 ## TASK OBJECTIVE
-Generate implementation plan (IMPL_PLAN.md), task JSONs, and TODO list for workflow session
+Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
+
+IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.

 CRITICAL: Use PROGRESSIVE loading to avoid token overflow - DO NOT load all files at once

@@ -92,7 +97,7 @@ Step 1.3 - Existing Plan (if resuming/refining):
  Action: If exists, load for continuity; else skip

 ### PHASE 2: Selective Artifacts (CONDITIONAL - Load Smart, Not All)
-Purpose: Get architectural guidance efficiently
+Purpose: Get architectural guidance for planning task breakdown

 Decision Tree (choose ONE option):

@@ -120,20 +125,20 @@ Conflict Handling:
    If "resolved": Use latest artifact versions (conflicts pre-addressed)

 ### PHASE 3: On-Demand Deep Dive (OPTIONAL - Only When Insufficient)
-Purpose: Load additional analysis files ONLY if Phase 2 lacks required detail
+Purpose: Load additional analysis files ONLY if Phase 2 lacks detail for task planning

 When to use:
-  - Complex tasks requiring multi-role coordination
+  - Complex planning requiring multi-role coordination
  - Specific expertise not covered in loaded artifacts
  - Task breakdown requires detailed role-specific requirements

 How to load:
  - Load ONE additional analysis at a time
-  - Prioritize based on task requirements
+  - Prioritize based on planning needs
  - Justify each additional load explicitly

 ### PHASE 4: Project Assets (FINAL)
-Purpose: Get concrete implementation context
+Purpose: Get concrete project context for task planning

 Extract from context_package:
  - focus_areas: Target directories
@@ -155,7 +160,7 @@ Output:

 ## CONTEXT METADATA
 Session ID: {session-id}
-Execution Mode: {agent-mode | cli-execute-mode}
+Planning Mode: {agent-mode | cli-execute-mode}
 MCP Capabilities: {exa_code, exa_web, code_index}

 ## EXPECTED DELIVERABLES
@@ -184,10 +189,11 @@ Hard Constraints:
  - All documents follow agent-defined structure

 ## SUCCESS CRITERIA
- All task JSONs valid and saved to .task/ directory
- IMPL_PLAN.md created with complete structure
- TODO_LIST.md generated matching task JSONs
- Return completion status with file count and task breakdown summary
+- All planning documents generated successfully:
+  - Task JSONs valid and saved to .task/ directory
+  - IMPL_PLAN.md created with complete structure
+  - TODO_LIST.md generated matching task JSONs
+- Return completion status with document count and task breakdown summary
 `
 )
 ```