docs: enhance task generation agent documentation with progressive loading strategy and smart artifact selection

2026-02-13 02:41:50 +08:00 · 2025-11-23 22:44:11 +08:00
parent 7453987cfe
commit 99a5c75b13
2 changed files with 377 additions and 265 deletions
--- a/.claude/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/commands/workflow/tools/task-generate-agent.md
@@ -14,8 +14,10 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit

 ## Core Philosophy
 - **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
+- **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)
 - **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`)

@@ -47,7 +49,7 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
   - `execution_mode` (agent-mode | cli-execute-mode)
   - `mcp_capabilities` (available MCP tools)

-**Note**: Agent autonomously loads files based on context package content (dynamic, not fixed template). Brainstorming artifacts only loaded if they exist in session.
+**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)

@@ -57,100 +59,146 @@ Task(
  subagent_type="action-planning-agent",
  description="Generate task JSON and implementation plan",
  prompt=`
-## Task Objective
+## TASK OBJECTIVE
 Generate implementation plan (IMPL_PLAN.md), task JSONs, and TODO list for workflow session

+CRITICAL: Use PROGRESSIVE loading to avoid token overflow - DO NOT load all files at once
+
 ## MANDATORY FIRST STEPS
 1. Read session metadata: {session.session_metadata_path}
-2. Load context package: {session.context_package_path}
-3. **Dynamically load files based on context package content** (see below)
+2. Load context package STRUCTURE ONLY: {session.context_package_path}
+3. Use PROGRESSIVE 4-phase loading strategy (detailed below)

-## Dynamic Content Loading Strategy
+## PROGRESSIVE LOADING STRATEGY (4 Phases)

-**Load files based on what exists in context package - NOT a fixed template**
+### PHASE 1: Core Context (REQUIRED - Always Load First)
+Purpose: Establish baseline understanding without token overflow

-### Step 1: Always Load (Required)
- **Session Metadata** → Extract user input
-  - User description: Original task requirements
-  - Project scope and boundaries
-  - Technical constraints
+Step 1.1 - Session Metadata:
+  Read: {session.session_metadata_path}
+  Extract: User description, project scope, technical constraints

-### Step 2: Check Context Package (Conditional Loading)
+Step 1.2 - Context Package Structure (catalog only, NOT file contents):
+  Read: {session.context_package_path}
+  Extract fields:
+    - metadata (task_description, keywords, complexity)
+    - project_context (architecture_patterns, tech_stack, conventions)
+    - assets (file PATHS only, not contents)
+    - brainstorm_artifacts (catalog structure with paths and priorities)
+    - conflict_detection (risk_level)

-**If `brainstorm_artifacts` exists in context package:**
- Load artifacts **in priority order** as listed below
- **If `brainstorm_artifacts` does NOT exist**: Skip to Step 3
+Step 1.3 - Existing Plan (if resuming/refining):
+  Check: .workflow/active/{session-id}/IMPL_PLAN.md
+  Action: If exists, load for continuity; else skip

-**Priority Loading (when artifacts exist):**
-1. **guidance-specification.md** (if `guidance_specification.exists = true`)
-   - Overall design framework - use as primary reference
+### PHASE 2: Selective Artifacts (CONDITIONAL - Load Smart, Not All)
+Purpose: Get architectural guidance efficiently

-2. **Role Analyses** (if `role_analyses[]` array exists)
-   - Load ALL role analysis files listed in array
-   - Each file path: `role_analyses[i].files[j].path`
+Decision Tree (choose ONE option):

-3. **Synthesis Output** (if `synthesis_output.exists = true`)
-   - Integrated view with clarifications
+  OPTION A: synthesis_output exists (PREFERRED - most efficient)
+    Load ONLY: brainstorm_artifacts.synthesis_output.path
+    Skip: All role analyses (already integrated in synthesis)
+    Reason: Synthesis already combines all perspectives

-4. **Conflict Resolution** (if `conflict_risk` = "medium" or "high")
-   - Check `conflict_resolution.status`
-   - If "resolved": Use updated artifacts (conflicts pre-addressed)
+  OPTION B: NO synthesis, but guidance_specification exists
+    Load: brainstorm_artifacts.guidance_specification.path
+    Then load 1-2 most relevant role analyses based on task type:
+      - Architecture/System: system-architect + data-architect
+      - Frontend/UI: ui-designer + ux-expert
+      - Backend/API: api-designer + subject-matter-expert
+      - General: system-architect + subject-matter-expert
+    Skip: Other role analyses (load on-demand only if needed)

-### Step 3: Extract Project Context
- `focus_areas`: Target directories for implementation
- `assets`: Existing code patterns to reuse
+  OPTION C: ONLY role analyses exist (no synthesis/guidance)
+    Load: Top 2 highest-priority role analyses ONLY
+    Skip: Other analyses (use selection guide from Option B)

-## Session Paths
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
- Context Package: .workflow/active/{session-id}/.process/context-package.json
- Output Task Dir: .workflow/active/{session-id}/.task/
- Output IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
- Output TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
+Conflict Handling:
+  If conflict_risk >= "medium":
+    Check: conflict_detection.status
+    If "resolved": Use latest artifact versions (conflicts pre-addressed)

-## Context Metadata
- Session ID: {session-id}
- Execution Mode: {agent-mode | cli-execute-mode}
- MCP Capabilities Available: {exa_code, exa_web, code_index}
+### PHASE 3: On-Demand Deep Dive (OPTIONAL - Only When Insufficient)
+Purpose: Load additional analysis files ONLY if Phase 2 lacks required detail

-**Note**: Content loading is **dynamic** based on actual files in session, not a fixed template
+When to use:
+  - Complex tasks requiring multi-role coordination
+  - Specific expertise not covered in loaded artifacts
+  - Task breakdown requires detailed role-specific requirements

-## Expected Deliverables
-1. **Task JSON Files** (.task/IMPL-*.json)
+How to load:
+  - Load ONE additional analysis at a time
+  - Prioritize based on task requirements
+  - Justify each additional load explicitly
+
+### PHASE 4: Project Assets (FINAL)
+Purpose: Get concrete implementation context
+
+Extract from context_package:
+  - focus_areas: Target directories
+  - assets.source_code: File PATHS (read content selectively if needed)
+  - assets.documentation: Reference docs
+  - dependencies: Internal and external
+
+Rule: Load source code content ONLY when necessary for patterns/integration
+
+## SESSION PATHS
+Input:
+  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
+  - Context Package: .workflow/active/{session-id}/.process/context-package.json
+
+Output:
+  - Task Dir: .workflow/active/{session-id}/.task/
+  - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
+  - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
+
+## CONTEXT METADATA
+Session ID: {session-id}
+Execution Mode: {agent-mode | cli-execute-mode}
+MCP Capabilities: {exa_code, exa_web, code_index}
+
+## EXPECTED DELIVERABLES
+1. Task JSON Files (.task/IMPL-*.json)
   - 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
   - Quantified requirements with explicit counts
   - Artifacts integration from context package
   - Flow control with pre_analysis steps

-2. **Implementation Plan** (IMPL_PLAN.md)
+2. Implementation Plan (IMPL_PLAN.md)
   - Context analysis and artifact references
   - Task breakdown and execution strategy
   - Complete structure per agent definition

-3. **TODO List** (TODO_LIST.md)
-   - Hierarchical structure with status indicators (▸, [ ], [x])
+3. TODO List (TODO_LIST.md)
+   - Hierarchical structure (containers, pending, completed markers)
   - Links to task JSONs and summaries
   - Matches task JSON hierarchy

-## Quality Standards
- Task count ≤12 (hard limit)
- All requirements quantified (explicit counts and lists)
- Acceptance criteria measurable (verification commands)
- Artifact references mapped from context package
- All documents follow agent-defined structure
+## QUALITY STANDARDS
+Hard Constraints:
+  - Task count <= 12 (hard limit - request re-scope if exceeded)
+  - All requirements quantified (explicit counts and enumerated lists)
+  - Acceptance criteria measurable (include verification commands)
+  - Artifact references mapped from context package
+  - All documents follow agent-defined structure

-## Success Criteria
+## 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
+- Return completion status with file count and task breakdown summary
 `
 )
 ```

 **Key Changes from Previous Version**:
-1. **Paths over Content**: Provide file paths for agent to read, not embedded content
-2. **MANDATORY FIRST STEPS**: Explicit requirement to load session metadata and context package
-3. **Complete Session Paths**: All file paths provided for agent operations
-4. **Emphasized Deliverables**: Clear deliverable requirements with quality standards
-5. **No Agent Self-Reference**: Removed "Refer to action-planning-agent.md" (agent knows its own definition)
-6. **No Template Paths**: Removed all template references (agent has complete schema/structure definitions)
+1. **Progressive Loading Strategy**: 4-phase incremental loading (Core → Selective → On-Demand → Assets) to prevent token overflow from loading all files at once
+2. **Smart Artifact Selection**: Load synthesis_output (if exists) OR guidance + 1-2 role analyses, NOT all role analyses simultaneously
+3. **Existing Plan Priority**: Check and load previous IMPL_PLAN.md first for context continuity when resuming/refining
+4. **Paths over Content**: Provide file paths for agent to read, not embedded content
+5. **MANDATORY FIRST STEPS**: Explicit requirement to load session metadata and context package structure
+6. **Complete Session Paths**: All file paths provided for agent operations
+7. **Emphasized Deliverables**: Clear deliverable requirements with quality standards
+8. **No Agent Self-Reference**: Removed "Refer to action-planning-agent.md" (agent knows its own definition)
+9. **No Template Paths**: Removed all template references (agent has complete schema/structure definitions)