docs: enhance action-planning-agent and task-generate-agent documentation with progressive loading strategy and smart artifact selection

.claude/agents/action-planning-agent.md

@@ -70,10 +70,9 @@ You are a pure execution agent specialized in creating actionable implementation
 3. Load brainstorming artifacts (in priority order)
    a. guidance-specification.md (Highest Priority)
       → Overall design framework and architectural decisions
-   b. Role analyses (High Priority - load ALL files)
+   b. Role analyses (progressive loading: load incrementally by priority)
-      → system-architect/analysis.md
+      → Load role analysis files one at a time as needed
-      → subject-matter-expert/analysis.md
+      → Reason: Each analysis.md is long; progressive loading prevents token overflow
-      → (Other roles as listed in context package)
    c. Synthesis output (if exists)
       → Integrated view with clarifications
    d. Conflict resolution (if conflict_risk ≥ medium)
@@ -129,9 +128,10 @@ if (contextPackage.brainstorm_artifacts?.guidance_specification?.exists) {
 }
 
 if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
+  // Progressive loading: load role analyses incrementally by priority
   contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
     role.files.forEach(file => {
-      const analysis = file.content || Read(file.path);
+      const analysis = file.content || Read(file.path); // Load one at a time
     });
   });
 }
@@ -324,11 +324,11 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
   },
   {
     "step": "load_role_analysis_artifacts",
-    "action": "Load role analyses from context-package.json",
+    "action": "Load role analyses from context-package.json (progressive loading by priority)",
     "commands": [
       "Read({{context_package_path}})",
       "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-      "Read(each extracted path)"
+      "Read(extracted paths progressively)"
     ],
     "output_to": "role_analysis_artifacts",
     "on_error": "skip_optional"
@@ -388,13 +388,16 @@ The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:
    - `load_context_package` - Essential for all tasks
    - `load_role_analysis_artifacts` - Critical for accessing brainstorming insights
 
-2. **Selectively Include Based on Task Type**:
+2. **Progressive Addition of Analysis Steps**:
-   - **Architecture tasks**: Project structure + Gemini architecture analysis
+   Include additional analysis steps as needed for comprehensive planning:
-   - **Refactoring tasks**: Gemini execution flow tracing + code quality analysis
+   - **Architecture analysis**: Project structure + architecture patterns
-   - **Frontend tasks**: React/Vue component searches + UI pattern analysis
+   - **Execution flow analysis**: Code tracing + quality analysis
-   - **Backend tasks**: Database schema + API endpoint searches
+   - **Component analysis**: Component searches + pattern analysis
-   - **Security tasks**: Vulnerability scans + security pattern analysis
+   - **Data analysis**: Schema review + endpoint searches
-   - **Performance tasks**: Bottleneck identification + profiling data
+   - **Security analysis**: Vulnerability scans + security patterns
+   - **Performance analysis**: Bottleneck identification + profiling
+
+   Default: Include progressively based on planning requirements, not limited by task type.
 
 3. **Tool Selection Strategy**:
    - **Gemini CLI**: Deep analysis (architecture, execution flow, patterns)

.claude/commands/workflow/tools/task-generate-agent.md

@@ -15,10 +15,10 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
 ## Core Philosophy
 - **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
+- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
 - **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
+- **Smart Selection**: Load synthesis_output OR guidance + relevant 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`)
 
@@ -50,8 +50,6 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
    - `execution_mode` (agent-mode | cli-execute-mode)
    - `mcp_capabilities` (available MCP tools)
 
-**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: Planning Document Generation (Agent Responsibility)
 
 **Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
@@ -67,7 +65,7 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
 
 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
+CRITICAL: Use progressive loading due to analysis.md file size
 
 ## MANDATORY FIRST STEPS
 1. Read session metadata: {session.session_metadata_path}
@@ -77,77 +75,45 @@ CRITICAL: Use PROGRESSIVE loading to avoid token overflow - DO NOT load all file
 ## PROGRESSIVE LOADING STRATEGY (4 Phases)
 
 ### PHASE 1: Core Context (REQUIRED - Always Load First)
-Purpose: Establish baseline understanding without token overflow
+Purpose: Establish baseline understanding
 
 Step 1.1 - Session Metadata:
   Read: {session.session_metadata_path}
   Extract: User description, project scope, technical constraints
 
-Step 1.2 - Context Package Structure (catalog only, NOT file contents):
+Step 1.2 - Context Package Structure (catalog only):
   Read: {session.context_package_path}
-  Extract fields:
+  Extract: metadata, project_context, assets (PATHS only), brainstorm_artifacts (catalog), conflict_detection
-    - 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)
 
-Step 1.3 - Existing Plan (if resuming/refining):
+Step 1.3 - Existing Plan (if resuming):
   Check: .workflow/active/{session-id}/IMPL_PLAN.md
-  Action: If exists, load for continuity; else skip
+  Action: If exists, load for continuity
 
-### PHASE 2: Selective Artifacts (CONDITIONAL - Load Smart, Not All)
+### PHASE 2: Selective Artifacts (Load Smart)
-Purpose: Get architectural guidance for planning task breakdown
+Purpose: Get architectural guidance for task planning
 
-Decision Tree (choose ONE option):
+Loading strategy (choose based on availability):
+- **If synthesis_output exists**: Load ONLY synthesis_output.path (already integrates all role perspectives)
+- **If guidance_specification exists**: Load guidance first, then progressively load role analyses as needed
+- **If only role analyses exist**: Progressively load role analyses by priority
 
-  OPTION A: synthesis_output exists (PREFERRED - most efficient)
+Default approach: Progressive loading - load artifacts incrementally, one at a time, to manage file size.
-    Load ONLY: brainstorm_artifacts.synthesis_output.path
-    Skip: All role analyses (already integrated in synthesis)
-    Reason: Synthesis already combines all perspectives
 
-  OPTION B: NO synthesis, but guidance_specification exists
+Conflict handling: If conflict_risk≥medium, check conflict_detection.status for resolved conflicts
-    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)
 
-  OPTION C: ONLY role analyses exist (no synthesis/guidance)
+### PHASE 3: Load More Analysis (if needed)
-    Load: Top 2 highest-priority role analyses ONLY
+Continue loading additional role analysis.md files ONE at a time when current context lacks detail.
-    Skip: Other analyses (use selection guide from Option B)
+Reason: Each analysis.md is long; progressive loading prevents token overflow.
-
-Conflict Handling:
-  If conflict_risk >= "medium":
-    Check: conflict_detection.status
-    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 detail for task planning
-
-When to use:
-  - 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 planning needs
-  - Justify each additional load explicitly
 
 ### PHASE 4: Project Assets (FINAL)
-Purpose: Get concrete project context for task planning
+Purpose: Get concrete project context
 
 Extract from context_package:
   - focus_areas: Target directories
-  - assets.source_code: File PATHS (read content selectively if needed)
+  - assets.source_code: File PATHS (read content selectively)
   - 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
@@ -198,13 +164,4 @@ Hard Constraints:
 )
 ```
 
-**Key Changes from Previous Version**:
+、
-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)