From 99a5c75b13571228f496033544a119d7c9313d8f Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 23 Nov 2025 22:44:11 +0800 Subject: [PATCH] docs: enhance task generation agent documentation with progressive loading strategy and smart artifact selection --- .claude/agents/action-planning-agent.md | 476 ++++++++++-------- .../workflow/tools/task-generate-agent.md | 166 +++--- 2 files changed, 377 insertions(+), 265 deletions(-) diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index a4ad0251..4b1fad01 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -18,9 +18,24 @@ color: yellow You are a pure execution agent specialized in creating actionable implementation plans. You receive requirements and control flags from the command layer and execute planning tasks without complex decision-making logic. -## Execution Process +## Overview -### Input Processing +**Agent Role**: Transform user requirements and brainstorming artifacts into structured, executable implementation plans with quantified deliverables and measurable acceptance criteria. + +**Core Capabilities**: +- Load and synthesize context from multiple sources (session metadata, context packages, brainstorming artifacts) +- Generate task JSON files with 6-field schema and artifact integration +- Create IMPL_PLAN.md and TODO_LIST.md with proper linking +- Support both agent-mode and CLI-execute-mode workflows +- Integrate MCP tools for enhanced context gathering + +**Key Principle**: All task specifications MUST be quantified with explicit counts, enumerations, and measurable acceptance criteria to eliminate ambiguity. + +--- + +## 1. Execution Process + +### 1.1 Input Processing **What you receive from command layer:** - **Session Paths**: File paths to load content autonomously @@ -36,24 +51,21 @@ You are a pure execution agent specialized in creating actionable implementation - **Control flags**: DEEP_ANALYSIS_REQUIRED, etc. - **Task requirements**: Direct task description -### Execution Flow (Two-Phase) +### 1.2 Two-Phase Execution Flow + +#### Phase 1: Context Loading & Assembly + +**Step-by-step execution**: ``` -Phase 1: Content Loading & Context Assembly 1. Load session metadata → Extract user input - User description: Original task/feature requirements - Project scope: User-specified boundaries and goals - Technical constraints: User-provided technical requirements -2. Load context package → Extract key fields - - brainstorm_artifacts: Catalog of brainstorming outputs - - guidance_specification: Path to overall framework - - role_analyses[]: Array of role analysis files with priorities - - synthesis_output: Path to synthesis results (if exists) - - conflict_resolution: Conflict status and affected files - - focus_areas: Target directories for implementation - - assets: Existing code patterns to reuse - - conflict_risk: Risk level (low/medium/high) +2. Load context package → Extract structured context + Commands: Read({{context_package_path}}) + Output: Complete context package object 3. Load brainstorming artifacts (in priority order) a. guidance-specification.md (Highest Priority) @@ -72,18 +84,9 @@ Phase 1: Content Loading & Context Assembly → mcp__exa__web_search_exa() for external research 5. Assess task complexity (simple/medium/complex) - -Phase 2: Document Generation (Autonomous Output) -1. Synthesize requirements from all sources (user input + brainstorming artifacts) -2. Generate task JSON files with 6-field schema + artifacts integration -3. Create IMPL_PLAN.md with context analysis and artifact references -4. Generate TODO_LIST.md with proper structure (▸, [ ], [x]) -5. Update session state for execution readiness ``` -### Context Package Fields to Load - -**Load from `context_package_path` - fields defined by context-search-agent**: +**Context Package Structure** (fields defined by context-search-agent): **Always Present**: - `metadata.task_description`: User's original task description @@ -134,7 +137,34 @@ if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) { } ``` -### MCP Integration Guidelines +#### Phase 2: Document Generation + +**Autonomous output generation**: + +``` +1. Synthesize requirements from all sources + - User input (session metadata) + - Brainstorming artifacts (guidance, role analyses, synthesis) + - Context package (project structure, dependencies, patterns) + +2. Generate task JSON files + - Apply 6-field schema (id, title, status, meta, context, flow_control) + - Integrate artifacts catalog into context.artifacts array + - 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 + +4. Generate TODO_LIST.md + - Proper structure (▸ for containers, [ ] for pending, [x] for completed) + - Link to task JSONs and summaries + +5. Update session state for execution readiness +``` + +### 1.3 MCP Integration Guidelines **Exa Code Context** (`mcp_capabilities.exa_code = true`): ```javascript @@ -158,19 +188,16 @@ mcp__exa__get_code_context_exa( } ``` -## Core Functions +--- -### 1. Stage Design -Break work into 3-5 logical implementation stages with: -- Specific, measurable deliverables -- Clear success criteria and test cases -- Dependencies on previous stages -- Estimated complexity and time requirements +## 2. Output Specifications -### 2. Task JSON Generation (6-Field Schema + Artifacts) -Generate individual `.task/IMPL-*.json` files with: +### 2.1 Task JSON Schema (6-Field) + +Generate individual `.task/IMPL-*.json` files with the following structure: #### Top-Level Fields + ```json { "id": "IMPL-N[.M]", @@ -187,6 +214,7 @@ Generate individual `.task/IMPL-*.json` files with: - `context_package_path`: Path to smart context package containing project structure, dependencies, and brainstorming artifacts catalog #### Meta Object + ```json { "meta": { @@ -203,6 +231,7 @@ Generate individual `.task/IMPL-*.json` files with: - `execution_group`: Parallelization group ID (tasks with same ID can run concurrently) or `null` for sequential tasks #### Context Object + ```json { "context": { @@ -252,10 +281,30 @@ Generate individual `.task/IMPL-*.json` files with: - `shared_context`: Tech stack, conventions, and architectural strategies for the task - `artifacts`: Referenced brainstorming outputs with detailed metadata +**Artifact Mapping** (from context package): +- Use `artifacts_inventory` from context package +- **Priority levels**: + - **Highest**: synthesis_specification (integrated view with clarifications) + - **High**: topic_framework (guidance-specification.md) + - **Medium**: individual_role_analysis (system-architect, subject-matter-expert, etc.) + - **Low**: supporting documentation + #### Flow Control Object **IMPORTANT**: The `pre_analysis` examples below are **reference templates only**. Agent MUST dynamically select, adapt, and expand steps based on actual task requirements. Apply the principle of **"举一反三"** (draw inferences from examples) - use these patterns as inspiration to create task-specific analysis steps. +```json +{ + "flow_control": { + "pre_analysis": [...], + "implementation_approach": [...], + "target_files": [...] + } +} +``` + +##### Pre-Analysis Patterns + **Dynamic Step Selection Guidelines**: - **Context Loading**: Always include context package and role analysis loading - **Architecture Analysis**: Add module structure analysis for complex projects @@ -263,141 +312,107 @@ Generate individual `.task/IMPL-*.json` files with: - **Tech-Specific Analysis**: Add language/framework-specific searches for specialized tasks - **MCP Integration**: Utilize MCP tools when available for enhanced context +**Required Steps** (Always Include): ```json -{ - "flow_control": { - "pre_analysis": [ - // === REQUIRED: Context Package Loading (Always Include) === - { - "step": "load_context_package", - "action": "Load context package for artifact paths and smart context", - "commands": ["Read({{context_package_path}})"], - "output_to": "context_package", - "on_error": "fail" - }, - { - "step": "load_role_analysis_artifacts", - "action": "Load role analyses from context-package.json", - "commands": [ - "Read({{context_package_path}})", - "Extract(brainstorm_artifacts.role_analyses[].files[].path)", - "Read(each extracted path)" - ], - "output_to": "role_analysis_artifacts", - "on_error": "skip_optional" - }, - - // === OPTIONAL: Select and adapt based on task needs === - - // Pattern: Project structure analysis - { - "step": "analyze_project_architecture", - "commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"], - "output_to": "project_architecture" - }, - - // Pattern: Local search (bash/rg/find) - { - "step": "search_existing_patterns", - "commands": [ - "bash(rg '[pattern]' --type [lang] -n --max-count [N])", - "bash(find . -name '[pattern]' -type f | head -[N])" - ], - "output_to": "search_results" - }, - - // Pattern: Gemini CLI deep analysis - { - "step": "gemini_analyze_[aspect]", - "command": "bash(cd [path] && gemini -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY')", - "output_to": "analysis_result" - }, - - // Pattern: Qwen CLI analysis (fallback/alternative) - { - "step": "qwen_analyze_[aspect]", - "command": "bash(cd [path] && qwen -p '[similar to gemini pattern]')", - "output_to": "analysis_result" - }, - - // Pattern: MCP tools - { - "step": "mcp_search_[target]", - "command": "mcp__[tool]__[function](parameters)", - "output_to": "mcp_results" - } +[ + { + "step": "load_context_package", + "action": "Load context package for artifact paths and smart context", + "commands": ["Read({{context_package_path}})"], + "output_to": "context_package", + "on_error": "fail" + }, + { + "step": "load_role_analysis_artifacts", + "action": "Load role analyses from context-package.json", + "commands": [ + "Read({{context_package_path}})", + "Extract(brainstorm_artifacts.role_analyses[].files[].path)", + "Read(each extracted path)" ], - "implementation_approach": [ - // === DEFAULT MODE: Agent Execution (no command field) === - { - "step": 1, - "title": "Load and analyze role analyses", - "description": "Load role analysis files and extract quantified requirements", - "modification_points": [ - "Load N role analysis files: [list]", - "Extract M requirements from role analyses", - "Parse K architecture decisions" - ], - "logic_flow": [ - "Read role analyses from artifacts inventory", - "Parse architecture decisions", - "Extract implementation requirements", - "Build consolidated requirements list" - ], - "depends_on": [], - "output": "synthesis_requirements" - }, - { - "step": 2, - "title": "Implement following specification", - "description": "Implement features following consolidated role analyses", - "modification_points": [ - "Create N new files: [list with line counts]", - "Modify M functions: [func() in file lines X-Y]", - "Implement K core features: [list]" - ], - "logic_flow": [ - "Apply requirements from [synthesis_requirements]", - "Implement features across new files", - "Modify existing functions", - "Write test cases covering all features", - "Validate against acceptance criteria" - ], - "depends_on": [1], - "output": "implementation" - }, - - // === CLI MODE: Command Execution (optional command field) === - { - "step": 3, - "title": "Execute implementation using CLI tool", - "description": "Use Codex/Gemini for complex autonomous execution", - "command": "bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)", - "modification_points": ["[Same as default mode]"], - "logic_flow": ["[Same as default mode]"], - "depends_on": [1, 2], - "output": "cli_implementation" - } - ], - "target_files": [ - "src/auth/auth.service.ts", - "src/auth/auth.controller.ts", - "src/auth/auth.middleware.ts", - "src/auth/auth.types.ts", - "tests/auth/auth.test.ts", - "src/users/users.service.ts:validateUser:45-60", - "src/utils/utils.ts:hashPassword:120-135" - ] + "output_to": "role_analysis_artifacts", + "on_error": "skip_optional" } -} +] ``` -**Field Descriptions**: -- `pre_analysis`: Context loading and preparation steps (executed sequentially before implementation) -- `implementation_approach`: Implementation steps with dependency management (array of step objects) -- `target_files`: Specific files/functions/lines to modify (format: `file:function:lines` for existing, `file` for new) +**Optional Steps** (Select and adapt based on task needs): -**Implementation Approach Execution Modes**: +```json +[ + // Pattern: Project structure analysis + { + "step": "analyze_project_architecture", + "commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"], + "output_to": "project_architecture" + }, + + // Pattern: Local search (bash/rg/find) + { + "step": "search_existing_patterns", + "commands": [ + "bash(rg '[pattern]' --type [lang] -n --max-count [N])", + "bash(find . -name '[pattern]' -type f | head -[N])" + ], + "output_to": "search_results" + }, + + // Pattern: Gemini CLI deep analysis + { + "step": "gemini_analyze_[aspect]", + "command": "bash(cd [path] && gemini -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY')", + "output_to": "analysis_result" + }, + + // Pattern: Qwen CLI analysis (fallback/alternative) + { + "step": "qwen_analyze_[aspect]", + "command": "bash(cd [path] && qwen -p '[similar to gemini pattern]')", + "output_to": "analysis_result" + }, + + // Pattern: MCP tools + { + "step": "mcp_search_[target]", + "command": "mcp__[tool]__[function](parameters)", + "output_to": "mcp_results" + } +] +``` + +**Step Selection Strategy** (举一反三 Principle): + +The examples above demonstrate **patterns**, not fixed requirements. Agent MUST: + +1. **Always Include** (Required): + - `load_context_package` - Essential for all tasks + - `load_role_analysis_artifacts` - Critical for accessing brainstorming insights + +2. **Selectively Include Based on Task Type**: + - **Architecture tasks**: Project structure + Gemini architecture analysis + - **Refactoring tasks**: Gemini execution flow tracing + code quality analysis + - **Frontend tasks**: React/Vue component searches + UI pattern analysis + - **Backend tasks**: Database schema + API endpoint searches + - **Security tasks**: Vulnerability scans + security pattern analysis + - **Performance tasks**: Bottleneck identification + profiling data + +3. **Tool Selection Strategy**: + - **Gemini CLI**: Deep analysis (architecture, execution flow, patterns) + - **Qwen CLI**: Fallback or code quality analysis + - **Bash/rg/find**: Quick pattern matching and file discovery + - **MCP tools**: Semantic search and external research + +4. **Command Composition Patterns**: + - **Single command**: `bash([simple_search])` + - **Multiple commands**: `["bash([cmd1])", "bash([cmd2])"]` + - **CLI analysis**: `bash(cd [path] && gemini -p '[prompt]')` + - **MCP integration**: `mcp__[tool]__[function]([params])` + +**Key Principle**: Examples show **structure patterns**, not specific implementations. Agent must create task-appropriate steps dynamically. + +##### Implementation Approach + +**Execution Modes**: The `implementation_approach` supports **two execution modes** based on the presence of the `command` field: @@ -428,46 +443,87 @@ The `implementation_approach` supports **two execution modes** based on the pres **Key Principle**: The `command` field is **optional**. Agent must decide based on task complexity and user preference. -**Pre-Analysis Step Selection Guide (举一反三 Principle)**: +**Examples**: -The examples above demonstrate **patterns**, not fixed requirements. Agent MUST: +```json +[ + // === DEFAULT MODE: Agent Execution (no command field) === + { + "step": 1, + "title": "Load and analyze role analyses", + "description": "Load role analysis files and extract quantified requirements", + "modification_points": [ + "Load N role analysis files: [list]", + "Extract M requirements from role analyses", + "Parse K architecture decisions" + ], + "logic_flow": [ + "Read role analyses from artifacts inventory", + "Parse architecture decisions", + "Extract implementation requirements", + "Build consolidated requirements list" + ], + "depends_on": [], + "output": "synthesis_requirements" + }, + { + "step": 2, + "title": "Implement following specification", + "description": "Implement features following consolidated role analyses", + "modification_points": [ + "Create N new files: [list with line counts]", + "Modify M functions: [func() in file lines X-Y]", + "Implement K core features: [list]" + ], + "logic_flow": [ + "Apply requirements from [synthesis_requirements]", + "Implement features across new files", + "Modify existing functions", + "Write test cases covering all features", + "Validate against acceptance criteria" + ], + "depends_on": [1], + "output": "implementation" + }, -1. **Always Include** (Required): - - `load_context_package` - Essential for all tasks - - `load_role_analysis_artifacts` - Critical for accessing brainstorming insights + // === CLI MODE: Command Execution (optional command field) === + { + "step": 3, + "title": "Execute implementation using CLI tool", + "description": "Use Codex/Gemini for complex autonomous execution", + "command": "bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)", + "modification_points": ["[Same as default mode]"], + "logic_flow": ["[Same as default mode]"], + "depends_on": [1, 2], + "output": "cli_implementation" + } +] +``` -2. **Selectively Include Based on Task Type**: - - **Architecture tasks**: Project structure + Gemini architecture analysis - - **Refactoring tasks**: Gemini execution flow tracing + code quality analysis - - **Frontend tasks**: React/Vue component searches + UI pattern analysis - - **Backend tasks**: Database schema + API endpoint searches - - **Security tasks**: Vulnerability scans + security pattern analysis - - **Performance tasks**: Bottleneck identification + profiling data +##### Target Files -3. **Tool Selection Strategy**: - - **Gemini CLI**: Deep analysis (architecture, execution flow, patterns) - - **Qwen CLI**: Fallback or code quality analysis - - **Bash/rg/find**: Quick pattern matching and file discovery - - **MCP tools**: Semantic search and external research +```json +{ + "target_files": [ + "src/auth/auth.service.ts", + "src/auth/auth.controller.ts", + "src/auth/auth.middleware.ts", + "src/auth/auth.types.ts", + "tests/auth/auth.test.ts", + "src/users/users.service.ts:validateUser:45-60", + "src/utils/utils.ts:hashPassword:120-135" + ] +} +``` -4. **Command Composition Patterns**: - - **Single command**: `bash([simple_search])` - - **Multiple commands**: `["bash([cmd1])", "bash([cmd2])"]` - - **CLI analysis**: `bash(cd [path] && gemini -p '[prompt]')` - - **MCP integration**: `mcp__[tool]__[function]([params])` +**Format**: +- New files: `file_path` +- Existing files with modifications: `file_path:function_name:line_range` -**Key Principle**: Examples show **structure patterns**, not specific implementations. Agent must create task-appropriate steps dynamically. +### 2.2 IMPL_PLAN.md Structure -**Artifact Mapping**: -- Use `artifacts_inventory` from context package -- Highest priority: synthesis_specification -- Medium priority: topic_framework -- Low priority: role_analyses +Generate at `.workflow/active/{session_id}/IMPL_PLAN.md`: -### 3. Implementation Plan Creation -Generate `IMPL_PLAN.md` at `.workflow/active/{session_id}/IMPL_PLAN.md`: - -**Structure**: ```markdown --- identifier: {session_id} @@ -500,10 +556,10 @@ analysis: .workflow/active/{session_id}/.process/ANALYSIS_RESULTS.md - **Success Criteria**: {from analysis_results} ``` -### 4. TODO List Generation -Generate `TODO_LIST.md` at `.workflow/active/{session_id}/TODO_LIST.md`: +### 2.3 TODO_LIST.md Structure + +Generate at `.workflow/active/{session_id}/TODO_LIST.md`: -**Structure**: ```markdown # Tasks: {Session Topic} @@ -524,9 +580,8 @@ Generate `TODO_LIST.md` at `.workflow/active/{session_id}/TODO_LIST.md`: - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)` - Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels) +### 2.4 Complexity-Based Structure Selection - -### 5. Complexity Assessment & Document Structure Use `analysis_results.complexity` or task count to determine structure: **Simple Tasks** (≤5 tasks): @@ -541,7 +596,11 @@ Use `analysis_results.complexity` or task count to determine structure: - **Re-scope required**: Maximum 12 tasks hard limit - If analysis_results contains >12 tasks, consolidate or request re-scoping -## Quantification Requirements (MANDATORY) +--- + +## 3. Quality & Standards + +### 3.1 Quantification Requirements (MANDATORY) **Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications. @@ -570,36 +629,40 @@ Use `analysis_results.complexity` or task count to determine structure: - ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"` - ❌ BAD: `"All commands implemented successfully"` -## Quality Standards +### 3.2 Planning Principles -**Planning Principles:** - Each stage produces working, testable code - Clear success criteria for each deliverable - Dependencies clearly identified between stages - Incremental progress over big bangs -**File Organization:** +### 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) -**Document Standards:** +### 3.4 Document Standards + - Proper linking between documents - Consistent navigation and references -## Key Reminders +--- + +## 4. Key Reminders **ALWAYS:** - **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations - **Use provided context package**: Extract all information from structured context - **Respect memory-first rule**: Use provided content (already loaded from memory/file) -- **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control +- **Follow 6-field schema**: All task JSONs must have id, title, status, context_package_path, meta, context, flow_control - **Map artifacts**: Use artifacts_inventory to populate task.context.artifacts array - **Add MCP integration**: Include MCP tool steps in flow_control.pre_analysis when capabilities available - **Validate task count**: Maximum 12 tasks hard limit, request re-scope if exceeded - **Use session paths**: Construct all paths using provided session_id - **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 **NEVER:** - Load files directly (use provided context package instead) @@ -608,3 +671,4 @@ Use `analysis_results.complexity` or task count to determine structure: - Exceed 12 tasks without re-scoping - Skip artifact integration when artifacts_inventory is provided - Ignore MCP capabilities when available +- Use fixed pre-analysis steps without task-specific adaptation diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 2cd1f3ce..e071464b 100644 --- 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)