From ff808ed5394bdf751a894c1f0b7ac35f454818e9 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 23 Nov 2025 22:57:43 +0800 Subject: [PATCH] docs: update task-generate-agent documentation for clarity on planning document generation and execution phases --- .claude/agents/action-planning-agent.md | 89 ++++++++----------- .../workflow/tools/task-generate-agent.md | 46 +++++----- 2 files changed, 61 insertions(+), 74 deletions(-) diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 4b1fad01..3f0534bd 100644 --- 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) diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index e071464b..da1d1524 100644 --- 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 ` ) ```