catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
catlog22
2025-11-23 22:44:11 +08:00
parent 7453987cfe
commit 99a5c75b13
2 changed files with 377 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

476
.claude/agents/action-planning-agent.md
View File

@@ -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

166
.claude/commands/workflow/tools/task-generate-agent.md
View File

@@ -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)