mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
c62d26183b
- Implemented `prep-loop.md` for ccw-loop, detailing source discovery, validation, task transformation, and auto-loop configuration. - Created `prep-plan.md` for workflow planning, covering environment checks, task quality assessment, execution preferences, and final confirmation. - Defined schemas and integration points for `prep-package.json` in both ccw-loop and workflow-plan skills, ensuring proper validation and task handling. - Added error handling mechanisms for various scenarios during the preparation phases.
758 lines
32 KiB
Markdown
758 lines
32 KiB
Markdown
# Phase 3: Task Generation
|
|
|
|
Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation.
|
|
|
|
## Auto Mode
|
|
|
|
When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool).
|
|
|
|
## 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
|
|
- **NO Redundant Context Sorting**: Context priority sorting is ALREADY completed in context-gather Phase 2
|
|
- Use `context-package.json.prioritized_context` directly
|
|
- DO NOT re-sort files or re-compute priorities
|
|
- `priority_tiers` and `dependency_order` are pre-computed and ready-to-use
|
|
- **N+1 Parallel Planning**: Auto-detect multi-module projects, enable parallel planning (2+1 or 3+1 mode)
|
|
- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
|
|
- **Memory-First**: Reuse loaded documents from conversation memory
|
|
- **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`)
|
|
- **Explicit Lifecycle**: Manage subagent lifecycle with spawn_agent → wait → close_agent
|
|
|
|
## Execution Process
|
|
|
|
```
|
|
Input Parsing:
|
|
├─ Parse flags: --session
|
|
└─ Validation: session_id REQUIRED
|
|
|
|
Phase 0: User Configuration (Interactive)
|
|
├─ Question 1: Supplementary materials/guidelines?
|
|
├─ Question 2: Execution method preference (Agent/CLI/Hybrid)
|
|
├─ Question 3: CLI tool preference (if CLI selected)
|
|
└─ Store: userConfig for agent prompt
|
|
|
|
Phase 1: Context Preparation & Module Detection (Command)
|
|
├─ Assemble session paths (metadata, context package, output dirs)
|
|
├─ Provide metadata (session_id, execution_mode, mcp_capabilities)
|
|
├─ Auto-detect modules from context-package + directory structure
|
|
└─ Decision:
|
|
├─ modules.length == 1 → Single Agent Mode (Phase 2A)
|
|
└─ modules.length >= 2 → Parallel Mode (Phase 2B + Phase 3)
|
|
|
|
Phase 2A: Single Agent Planning (Original Flow)
|
|
├─ Spawn action-planning-agent
|
|
├─ Wait for completion
|
|
├─ Close agent
|
|
├─ Outputs: Task JSONs, IMPL_PLAN.md, TODO_LIST.md
|
|
└─ Lifecycle: spawn_agent → wait → close_agent
|
|
|
|
Phase 2B: N Parallel Planning (Multi-Module)
|
|
├─ Spawn N action-planning-agents simultaneously (one per module)
|
|
├─ Wait for all agents (batch wait)
|
|
├─ Close all agents
|
|
├─ Each generates module-scoped tasks (IMPL-{prefix}{seq}.json)
|
|
├─ Task ID format: IMPL-A1, IMPL-A2... / IMPL-B1, IMPL-B2...
|
|
└─ Each module limited to ≤9 tasks
|
|
|
|
Phase 3: Integration (+1 Coordinator, Multi-Module Only)
|
|
├─ Spawn coordinator agent
|
|
├─ Wait for completion
|
|
├─ Close agent
|
|
├─ Collect all module task JSONs
|
|
├─ Resolve cross-module dependencies (CROSS::{module}::{pattern} → actual ID)
|
|
├─ Generate unified IMPL_PLAN.md (grouped by module)
|
|
└─ Generate TODO_LIST.md (hierarchical: module → tasks)
|
|
```
|
|
|
|
## Document Generation Lifecycle
|
|
|
|
### Phase 0: User Configuration (Interactive)
|
|
|
|
**Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations.
|
|
|
|
**Auto Mode Check**:
|
|
```javascript
|
|
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
|
|
|
// Check for prep-package auto-configuration (from /prompts:prep-plan)
|
|
const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json`
|
|
const prepExec = fs.existsSync(prepPath) ? JSON.parse(Read(prepPath))?.execution : null
|
|
|
|
if (autoYes || prepExec) {
|
|
const source = prepExec ? 'prep-package' : '--yes flag'
|
|
console.log(`[${source}] Using defaults: ${prepExec?.execution_method || 'agent'} executor, ${prepExec?.preferred_cli_tool || 'codex'} CLI`)
|
|
userConfig = {
|
|
supplementaryMaterials: prepExec?.supplementary_materials || { type: "none", content: [] },
|
|
executionMethod: prepExec?.execution_method || "agent",
|
|
preferredCliTool: prepExec?.preferred_cli_tool || "codex",
|
|
enableResume: true
|
|
}
|
|
// Skip to Phase 1
|
|
}
|
|
```
|
|
|
|
**User Questions** (skipped if autoYes):
|
|
```javascript
|
|
if (!autoYes) ASK_USER([
|
|
{
|
|
id: "materials",
|
|
type: "select",
|
|
prompt: "Do you have supplementary materials or guidelines to include?",
|
|
options: [
|
|
{ label: "No additional materials", description: "Use existing context only" },
|
|
{ label: "Provide file paths", description: "I'll specify paths to include" },
|
|
{ label: "Provide inline content", description: "I'll paste content directly" }
|
|
]
|
|
},
|
|
{
|
|
id: "execution-method",
|
|
type: "select",
|
|
prompt: "Select execution method for generated tasks:",
|
|
options: [
|
|
{ label: "Agent (Recommended)", description: "Claude agent executes tasks directly" },
|
|
{ label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps" },
|
|
{ label: "CLI Only", description: "All execution via CLI tools (codex/gemini/qwen)" }
|
|
]
|
|
},
|
|
{
|
|
id: "cli-tool",
|
|
type: "select",
|
|
prompt: "If using CLI, which tool do you prefer?",
|
|
options: [
|
|
{ label: "Codex (Recommended)", description: "Best for implementation tasks" },
|
|
{ label: "Gemini", description: "Best for analysis and large context" },
|
|
{ label: "Qwen", description: "Alternative analysis tool" },
|
|
{ label: "Auto", description: "Let agent decide per-task" }
|
|
]
|
|
}
|
|
]) // BLOCKS (wait for user response)
|
|
```
|
|
|
|
**Handle Materials Response** (skipped if autoYes):
|
|
```javascript
|
|
if (!autoYes && userConfig.materials === "Provide file paths") {
|
|
// Follow-up question for file paths
|
|
const pathsResponse = ASK_USER([{
|
|
id: "material-paths",
|
|
type: "input",
|
|
prompt: "Enter file paths to include (comma-separated or one per line):",
|
|
options: [
|
|
{ label: "Enter paths", description: "Provide paths in text input" }
|
|
]
|
|
}]) // BLOCKS (wait for user response)
|
|
userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
|
|
}
|
|
```
|
|
|
|
**Build userConfig**:
|
|
```javascript
|
|
const userConfig = {
|
|
supplementaryMaterials: {
|
|
type: "none|paths|inline",
|
|
content: [...], // Parsed paths or inline content
|
|
},
|
|
executionMethod: "agent|hybrid|cli",
|
|
preferredCliTool: "codex|gemini|qwen|auto",
|
|
enableResume: true // Always enable resume for CLI executions
|
|
}
|
|
```
|
|
|
|
**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2A/2B.
|
|
|
|
### Phase 1: Context Preparation & Module Detection (Command Responsibility)
|
|
|
|
**Command prepares session paths, metadata, detects module structure. Context priority sorting is NOT performed here - it's already completed in context-gather Phase 2.**
|
|
|
|
**Session Path Structure**:
|
|
```
|
|
{projectRoot}/.workflow/active/WFS-{session-id}/
|
|
├── workflow-session.json # Session metadata
|
|
├── planning-notes.md # Consolidated planning notes
|
|
├── .process/
|
|
│ └── context-package.json # Context package with artifact catalog
|
|
├── .task/ # Output: Task JSON files
|
|
│ ├── IMPL-A1.json # Multi-module: prefixed by module
|
|
│ ├── IMPL-A2.json
|
|
│ ├── IMPL-B1.json
|
|
│ └── ...
|
|
├── IMPL_PLAN.md # Output: Implementation plan (grouped by module)
|
|
└── TODO_LIST.md # Output: TODO list (hierarchical)
|
|
```
|
|
|
|
**Command Preparation**:
|
|
1. **Assemble Session Paths** for agent prompt:
|
|
- `session_metadata_path`
|
|
- `context_package_path`
|
|
- Output directory paths
|
|
|
|
2. **Provide Metadata** (simple values):
|
|
- `session_id`
|
|
- `mcp_capabilities` (available MCP tools)
|
|
|
|
3. **Auto Module Detection** (determines single vs parallel mode):
|
|
```javascript
|
|
function autoDetectModules(contextPackage, projectRoot) {
|
|
// === Complexity Gate: Only parallelize for High complexity ===
|
|
const complexity = contextPackage.metadata?.complexity || 'Medium';
|
|
if (complexity !== 'High') {
|
|
// Force single agent mode for Low/Medium complexity
|
|
// This maximizes agent context reuse for related tasks
|
|
return [{ name: 'main', prefix: '', paths: ['.'] }];
|
|
}
|
|
|
|
// Priority 1: Explicit frontend/backend separation
|
|
if (exists('src/frontend') && exists('src/backend')) {
|
|
return [
|
|
{ name: 'frontend', prefix: 'A', paths: ['src/frontend'] },
|
|
{ name: 'backend', prefix: 'B', paths: ['src/backend'] }
|
|
];
|
|
}
|
|
|
|
// Priority 2: Monorepo structure
|
|
if (exists('packages/*') || exists('apps/*')) {
|
|
return detectMonorepoModules(); // Returns 2-3 main packages
|
|
}
|
|
|
|
// Priority 3: Context-package dependency clustering
|
|
const modules = clusterByDependencies(contextPackage.dependencies?.internal);
|
|
if (modules.length >= 2) return modules.slice(0, 3);
|
|
|
|
// Default: Single module (original flow)
|
|
return [{ name: 'main', prefix: '', paths: ['.'] }];
|
|
}
|
|
```
|
|
|
|
**Decision Logic**:
|
|
- `complexity !== 'High'` → Force Phase 2A (Single Agent, maximize context reuse)
|
|
- `modules.length == 1` → Phase 2A (Single Agent, original flow)
|
|
- `modules.length >= 2 && complexity == 'High'` → Phase 2B + Phase 3 (N+1 Parallel)
|
|
|
|
**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags.
|
|
|
|
### Phase 2A: Single Agent Planning (Original Flow)
|
|
|
|
**Condition**: `modules.length == 1` (no multi-module detected)
|
|
|
|
**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
|
|
|
|
**Agent Invocation**:
|
|
```javascript
|
|
// Spawn action-planning-agent
|
|
const planningAgentId = spawn_agent({
|
|
message: `
|
|
## TASK ASSIGNMENT
|
|
|
|
### MANDATORY FIRST STEPS (Agent Execute)
|
|
1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
|
|
2. Read: ${projectRoot}/.workflow/project-tech.json
|
|
3. Read: ${projectRoot}/.workflow/project-guidelines.json
|
|
|
|
---
|
|
|
|
## TASK OBJECTIVE
|
|
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: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
|
|
|
|
## PLANNING NOTES (PHASE 1-2 CONTEXT)
|
|
Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
|
|
|
|
This document contains:
|
|
- User Intent: Original GOAL and KEY_CONSTRAINTS from Phase 1
|
|
- Context Findings: Critical files, architecture, and constraints from Phase 2
|
|
- Conflict Decisions: Resolved conflicts and planning constraints from Phase 2
|
|
- Consolidated Constraints: All constraints from all phases
|
|
|
|
**USAGE**: Read planning-notes.md FIRST. Use Consolidated Constraints list to guide task sequencing and dependencies.
|
|
|
|
## SESSION PATHS
|
|
Input:
|
|
- Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
|
|
- Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
|
|
- Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
|
|
|
|
Output:
|
|
- Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/
|
|
- IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md
|
|
- TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md
|
|
|
|
## CONTEXT METADATA
|
|
Session ID: ${session_id}
|
|
MCP Capabilities: {exa_code, exa_web, code_index}
|
|
|
|
## USER CONFIGURATION (from Phase 0)
|
|
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
|
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
|
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
|
|
|
## EXECUTION METHOD MAPPING
|
|
Based on userConfig.executionMethod, set task-level meta.execution_config:
|
|
|
|
"agent" →
|
|
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
|
Agent executes implementation_approach steps directly
|
|
|
|
"cli" →
|
|
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
|
|
Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()
|
|
|
|
"hybrid" →
|
|
Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task
|
|
- Simple tasks (≤3 files, straightforward logic) → method: "agent"
|
|
- Complex tasks (>3 files, complex logic, refactoring) → method: "cli"
|
|
CLI tool: userConfig.preferredCliTool, enable_resume: true
|
|
|
|
IMPORTANT: Do NOT add command field to implementation_approach steps. Execution routing is controlled by task-level meta.execution_config.method only.
|
|
|
|
## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
|
|
Context sorting is ALREADY COMPLETED in context-gather Phase 2. DO NOT re-sort.
|
|
Direct usage:
|
|
- **user_intent**: Use goal/scope/key_constraints for task alignment
|
|
- **priority_tiers.critical**: These files are PRIMARY focus for task generation
|
|
- **priority_tiers.high**: These files are SECONDARY focus
|
|
- **dependency_order**: Use this for task sequencing - already computed
|
|
- **sorting_rationale**: Reference for understanding priority decisions
|
|
|
|
## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
|
|
If prioritized_context is incomplete, fall back to exploration_results:
|
|
- Load exploration_results from context-package.json
|
|
- Use aggregated_insights.critical_files for focus_paths generation
|
|
- Apply aggregated_insights.constraints to acceptance criteria
|
|
- Reference aggregated_insights.all_patterns for implementation approach
|
|
- Use aggregated_insights.all_integration_points for precise modification locations
|
|
- Use conflict_indicators for risk-aware task sequencing
|
|
|
|
## CONFLICT RESOLUTION CONTEXT (if exists)
|
|
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
|
- If exists, load .process/conflict-resolution.json:
|
|
- Apply planning_constraints as task constraints (for brainstorm-less workflows)
|
|
- Reference resolved_conflicts for implementation approach alignment
|
|
- Handle custom_conflicts with explicit task notes
|
|
|
|
## 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
|
|
- **focus_paths generated directly from prioritized_context.priority_tiers (critical + high)**
|
|
- NO re-sorting or re-prioritization - use pre-computed tiers as-is
|
|
- Critical files are PRIMARY focus, High files are SECONDARY
|
|
- Flow control with pre_analysis steps (use prioritized_context.dependency_order for task sequencing)
|
|
- **CLI Execution IDs and strategies (MANDATORY)**
|
|
|
|
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 (containers, pending, completed markers)
|
|
- Links to task JSONs and summaries
|
|
- Matches task JSON hierarchy
|
|
|
|
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
|
Each task JSON MUST include:
|
|
- **cli_execution_id**: Unique ID for CLI execution (format: \`{session_id}-{task_id}\`)
|
|
- **cli_execution**: Strategy object based on depends_on:
|
|
- No deps → \`{ "strategy": "new" }\`
|
|
- 1 dep (single child) → \`{ "strategy": "resume", "resume_from": "parent-cli-id" }\`
|
|
- 1 dep (multiple children) → \`{ "strategy": "fork", "resume_from": "parent-cli-id" }\`
|
|
- N deps → \`{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }\`
|
|
|
|
**CLI Execution Strategy Rules**:
|
|
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
|
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
|
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
|
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
|
|
|
**Execution Command Patterns**:
|
|
- new: \`ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]\`
|
|
- resume: \`ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write\`
|
|
- fork: \`ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write\`
|
|
- merge_fork: \`ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write\`
|
|
|
|
## QUALITY STANDARDS
|
|
Hard Constraints:
|
|
- Task count <= 18 (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
|
|
- 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
|
|
|
|
## PLANNING NOTES RECORD (REQUIRED)
|
|
After completing, update planning-notes.md:
|
|
|
|
**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
|
|
|
|
1. **Task Generation (Phase 3)**: Task count and key tasks
|
|
2. **N+1 Context**: Key decisions (with rationale) + deferred items
|
|
|
|
\`\`\`markdown
|
|
## Task Generation (Phase 3)
|
|
### [Action-Planning Agent] YYYY-MM-DD
|
|
- **Tasks**: [count] ([IDs])
|
|
|
|
## N+1 Context
|
|
### Decisions
|
|
| Decision | Rationale | Revisit? |
|
|
|----------|-----------|----------|
|
|
| [choice] | [why] | [Yes/No] |
|
|
|
|
### Deferred
|
|
- [ ] [item] - [reason]
|
|
\`\`\`
|
|
`
|
|
});
|
|
|
|
// Wait for planning agent to complete
|
|
const planningResult = wait({
|
|
ids: [planningAgentId],
|
|
timeout_ms: 900000 // 15 minutes
|
|
});
|
|
|
|
// Close planning agent
|
|
close_agent({ id: planningAgentId });
|
|
```
|
|
|
|
### Phase 2B: N Parallel Planning (Multi-Module)
|
|
|
|
**Condition**: `modules.length >= 2` (multi-module detected)
|
|
|
|
**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task JSON generation.
|
|
|
|
**Note**: Phase 2B agents generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md are generated by Phase 3 Coordinator.
|
|
|
|
**Parallel Agent Invocation**:
|
|
```javascript
|
|
// Spawn N agents in parallel (one per module)
|
|
const moduleAgents = [];
|
|
|
|
modules.forEach(module => {
|
|
const agentId = spawn_agent({
|
|
message: `
|
|
## TASK ASSIGNMENT
|
|
|
|
### MANDATORY FIRST STEPS (Agent Execute)
|
|
1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
|
|
2. Read: ${projectRoot}/.workflow/project-tech.json
|
|
3. Read: ${projectRoot}/.workflow/project-guidelines.json
|
|
|
|
---
|
|
|
|
## TASK OBJECTIVE
|
|
Generate task JSON files for ${module.name} module within workflow session
|
|
|
|
IMPORTANT: This is PLANNING ONLY - generate task JSONs, NOT implementing code.
|
|
IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Coordinator.
|
|
|
|
CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
|
|
|
|
## PLANNING NOTES (PHASE 1-2 CONTEXT)
|
|
Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
|
|
|
|
This document contains consolidated constraints and user intent to guide module-scoped task generation.
|
|
|
|
## MODULE SCOPE
|
|
- Module: ${module.name} (${module.type})
|
|
- Focus Paths: ${module.paths.join(', ')}
|
|
- Task ID Prefix: IMPL-${module.prefix}
|
|
- Task Limit: ≤6 tasks (hard limit for this module)
|
|
- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them)
|
|
|
|
## SESSION PATHS
|
|
Input:
|
|
- Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
|
|
- Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
|
|
- Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
|
|
|
|
Output:
|
|
- Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/
|
|
|
|
## CONTEXT METADATA
|
|
Session ID: ${session_id}
|
|
MCP Capabilities: {exa_code, exa_web, code_index}
|
|
|
|
## USER CONFIGURATION (from Phase 0)
|
|
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
|
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
|
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
|
|
|
## EXECUTION METHOD MAPPING
|
|
Based on userConfig.executionMethod, set task-level meta.execution_config:
|
|
|
|
"agent" →
|
|
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
|
Agent executes implementation_approach steps directly
|
|
|
|
"cli" →
|
|
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
|
|
Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()
|
|
|
|
"hybrid" →
|
|
Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task
|
|
- Simple tasks (≤3 files, straightforward logic) → method: "agent"
|
|
- Complex tasks (>3 files, complex logic, refactoring) → method: "cli"
|
|
CLI tool: userConfig.preferredCliTool, enable_resume: true
|
|
|
|
IMPORTANT: Do NOT add command field to implementation_approach steps. Execution routing is controlled by task-level meta.execution_config.method only.
|
|
|
|
## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
|
|
Context sorting is ALREADY COMPLETED in context-gather Phase 2. DO NOT re-sort.
|
|
Filter by module scope (${module.paths.join(', ')}):
|
|
- **user_intent**: Use for task alignment within module
|
|
- **priority_tiers.critical**: Filter for files in ${module.paths.join(', ')} → PRIMARY focus
|
|
- **priority_tiers.high**: Filter for files in ${module.paths.join(', ')} → SECONDARY focus
|
|
- **dependency_order**: Use module-relevant entries for task sequencing
|
|
|
|
## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
|
|
If prioritized_context is incomplete for this module, fall back to exploration_results:
|
|
- Load exploration_results from context-package.json
|
|
- Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')}
|
|
- Apply module-relevant constraints from aggregated_insights.constraints
|
|
- Reference aggregated_insights.all_patterns applicable to ${module.name}
|
|
- Use aggregated_insights.all_integration_points for precise modification locations within module scope
|
|
- Use conflict_indicators for risk-aware task sequencing
|
|
|
|
## CONFLICT RESOLUTION CONTEXT (if exists)
|
|
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
|
- If exists, load .process/conflict-resolution.json:
|
|
- Apply planning_constraints relevant to ${module.name} as task constraints
|
|
- Reference resolved_conflicts affecting ${module.name} for implementation approach alignment
|
|
- Handle custom_conflicts with explicit task notes
|
|
|
|
## CROSS-MODULE DEPENDENCIES
|
|
- For dependencies ON other modules: Use placeholder depends_on: ["CROSS::{module}::{pattern}"]
|
|
- Example: depends_on: ["CROSS::B::api-endpoint"] (this module depends on B's api-endpoint task)
|
|
- Phase 3 Coordinator resolves to actual task IDs
|
|
- For dependencies FROM other modules: Document in task context as "provides_for" annotation
|
|
|
|
## EXPECTED DELIVERABLES
|
|
Task JSON Files (.task/IMPL-${module.prefix}*.json):
|
|
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
|
|
- Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ...
|
|
- Quantified requirements with explicit counts
|
|
- Artifacts integration from context package (filtered for ${module.name})
|
|
- **focus_paths generated directly from prioritized_context.priority_tiers filtered by ${module.paths.join(', ')}**
|
|
- NO re-sorting - use pre-computed tiers filtered for this module
|
|
- Critical files are PRIMARY focus, High files are SECONDARY
|
|
- Flow control with pre_analysis steps (use prioritized_context.dependency_order for module task sequencing)
|
|
- **CLI Execution IDs and strategies (MANDATORY)**
|
|
- Focus ONLY on ${module.name} module scope
|
|
|
|
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
|
Each task JSON MUST include:
|
|
- **cli_execution_id**: Unique ID for CLI execution (format: \`{session_id}-IMPL-${module.prefix}{seq}\`)
|
|
- **cli_execution**: Strategy object based on depends_on:
|
|
- No deps → \`{ "strategy": "new" }\`
|
|
- 1 dep (single child) → \`{ "strategy": "resume", "resume_from": "parent-cli-id" }\`
|
|
- 1 dep (multiple children) → \`{ "strategy": "fork", "resume_from": "parent-cli-id" }\`
|
|
- N deps → \`{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }\`
|
|
- Cross-module dep → \`{ "strategy": "cross_module_fork", "resume_from": "CROSS::{module}::{pattern}" }\`
|
|
|
|
**CLI Execution Strategy Rules**:
|
|
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
|
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
|
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
|
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
|
5. **cross_module_fork**: Task depends on task from another module - Phase 3 resolves placeholder
|
|
|
|
**Execution Command Patterns**:
|
|
- new: \`ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]\`
|
|
- resume: \`ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write\`
|
|
- fork: \`ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write\`
|
|
- merge_fork: \`ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write\`
|
|
- cross_module_fork: (Phase 3 resolves placeholder, then uses fork pattern)
|
|
|
|
## QUALITY STANDARDS
|
|
Hard Constraints:
|
|
- Task count <= 9 for this module (hard limit - coordinate with Phase 3 if exceeded)
|
|
- All requirements quantified (explicit counts and enumerated lists)
|
|
- Acceptance criteria measurable (include verification commands)
|
|
- Artifact references mapped from context package (module-scoped filter)
|
|
- Focus paths use absolute paths or clear relative paths from project root
|
|
- Cross-module dependencies use CROSS:: placeholder format
|
|
|
|
## SUCCESS CRITERIA
|
|
- Task JSONs saved to .task/ with IMPL-${module.prefix}* naming
|
|
- All task JSONs include cli_execution_id and cli_execution strategy
|
|
- Cross-module dependencies use CROSS:: placeholder format consistently
|
|
- Focus paths scoped to ${module.paths.join(', ')} only
|
|
- Return: task count, task IDs, dependency summary (internal + cross-module)
|
|
|
|
## PLANNING NOTES RECORD (REQUIRED)
|
|
After completing, append to planning-notes.md:
|
|
|
|
\`\`\`markdown
|
|
### [${module.name}] YYYY-MM-DD
|
|
- **Tasks**: [count] ([IDs])
|
|
- **CROSS deps**: [placeholders used]
|
|
\`\`\`
|
|
`
|
|
});
|
|
|
|
moduleAgents.push(agentId);
|
|
});
|
|
|
|
// Batch wait for all module agents
|
|
const moduleResults = wait({
|
|
ids: moduleAgents,
|
|
timeout_ms: 900000 // 15 minutes
|
|
});
|
|
|
|
// Close all module agents
|
|
moduleAgents.forEach(agentId => {
|
|
close_agent({ id: agentId });
|
|
});
|
|
```
|
|
|
|
**Output Structure** (direct to .task/):
|
|
```
|
|
.task/
|
|
├── IMPL-A1.json # Module A (e.g., frontend)
|
|
├── IMPL-A2.json
|
|
├── IMPL-B1.json # Module B (e.g., backend)
|
|
├── IMPL-B2.json
|
|
└── IMPL-C1.json # Module C (e.g., shared)
|
|
```
|
|
|
|
**Task ID Naming**:
|
|
- Format: `IMPL-{prefix}{seq}.json`
|
|
- Prefix: A, B, C... (assigned by detection order)
|
|
- Sequence: 1, 2, 3... (per-module increment)
|
|
|
|
### Phase 3: Integration (+1 Coordinator Agent, Multi-Module Only)
|
|
|
|
**Condition**: Only executed when `modules.length >= 2`
|
|
|
|
**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified IMPL_PLAN.md and TODO_LIST.md documents.
|
|
|
|
**Coordinator Agent Invocation**:
|
|
```javascript
|
|
// Wait for all Phase 2B agents to complete (already done above)
|
|
|
|
// Spawn +1 Coordinator Agent
|
|
const coordinatorAgentId = spawn_agent({
|
|
message: `
|
|
## TASK ASSIGNMENT
|
|
|
|
### MANDATORY FIRST STEPS (Agent Execute)
|
|
1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
|
|
2. Read: ${projectRoot}/.workflow/project-tech.json
|
|
3. Read: ${projectRoot}/.workflow/project-guidelines.json
|
|
|
|
---
|
|
|
|
## TASK OBJECTIVE
|
|
Integrate all module task JSONs, resolve cross-module dependencies, and generate unified IMPL_PLAN.md and TODO_LIST.md
|
|
|
|
IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creating new tasks.
|
|
|
|
## SESSION PATHS
|
|
Input:
|
|
- Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
|
|
- Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
|
|
- Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (from Phase 2B)
|
|
Output:
|
|
- Updated Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (resolved dependencies)
|
|
- IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md
|
|
- TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md
|
|
|
|
## CONTEXT METADATA
|
|
Session ID: ${session_id}
|
|
Modules: ${modules.map(m => m.name + '(' + m.prefix + ')').join(', ')}
|
|
Module Count: ${modules.length}
|
|
|
|
## INTEGRATION STEPS
|
|
1. Collect all .task/IMPL-*.json, group by module prefix
|
|
2. Resolve CROSS:: dependencies → actual task IDs, update task JSONs
|
|
3. Generate IMPL_PLAN.md (multi-module format per agent specification)
|
|
4. Generate TODO_LIST.md (hierarchical format per agent specification)
|
|
|
|
## CROSS-MODULE DEPENDENCY RESOLUTION
|
|
- Pattern: CROSS::{module}::{pattern} → IMPL-{module}* matching title/context
|
|
- Example: CROSS::B::api-endpoint → IMPL-B1 (if B1 title contains "api-endpoint")
|
|
- Log unresolved as warnings
|
|
|
|
## EXPECTED DELIVERABLES
|
|
1. Updated Task JSONs with resolved dependency IDs
|
|
2. IMPL_PLAN.md - multi-module format with cross-dependency section
|
|
3. TODO_LIST.md - hierarchical by module with cross-dependency section
|
|
|
|
## SUCCESS CRITERIA
|
|
- No CROSS:: placeholders remaining in task JSONs
|
|
- IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure
|
|
- Return: task count, per-module breakdown, resolved dependency count
|
|
|
|
## PLANNING NOTES RECORD (REQUIRED)
|
|
After integration, update planning-notes.md:
|
|
|
|
\`\`\`markdown
|
|
### [Coordinator] YYYY-MM-DD
|
|
- **Total**: [count] tasks
|
|
- **Resolved**: [CROSS:: resolutions]
|
|
|
|
## N+1 Context
|
|
### Decisions
|
|
| Decision | Rationale | Revisit? |
|
|
|----------|-----------|----------|
|
|
| CROSS::X → IMPL-Y | [why this resolution] | [Yes/No] |
|
|
|
|
### Deferred
|
|
- [ ] [unresolved CROSS or conflict] - [reason]
|
|
\`\`\`
|
|
`
|
|
});
|
|
|
|
// Wait for coordinator agent to complete
|
|
const coordinatorResult = wait({
|
|
ids: [coordinatorAgentId],
|
|
timeout_ms: 600000 // 10 minutes
|
|
});
|
|
|
|
// Close coordinator agent
|
|
close_agent({ id: coordinatorAgentId });
|
|
```
|
|
|
|
**Dependency Resolution Algorithm**:
|
|
```javascript
|
|
function resolveCrossModuleDependency(placeholder, allTasks) {
|
|
const [, targetModule, pattern] = placeholder.match(/CROSS::(\w+)::(.+)/);
|
|
const candidates = allTasks.filter(t =>
|
|
t.id.startsWith(`IMPL-${targetModule}`) &&
|
|
(t.title.toLowerCase().includes(pattern.toLowerCase()) ||
|
|
t.context?.description?.toLowerCase().includes(pattern.toLowerCase()))
|
|
);
|
|
return candidates.length > 0
|
|
? candidates.sort((a, b) => a.id.localeCompare(b.id))[0].id
|
|
: placeholder; // Keep for manual resolution
|
|
}
|
|
```
|
|
|
|
## Output
|
|
|
|
- **Files**:
|
|
- `{projectRoot}/.workflow/active/{sessionId}/IMPL_PLAN.md`
|
|
- `{projectRoot}/.workflow/active/{sessionId}/.task/IMPL-*.json`
|
|
- `{projectRoot}/.workflow/active/{sessionId}/TODO_LIST.md`
|
|
- **Updated**: `planning-notes.md` with task generation record and N+1 context
|
|
|
|
## Next Step
|
|
|
|
Return to orchestrator. Present user with action choices (or auto-continue if `--yes`):
|
|
1. Verify Plan Quality (Recommended) → `workflow:plan-verify`
|
|
2. Start Execution → Phase 4 (phases/04-execution.md)
|
|
3. Review Status Only → `workflow:status`
|