Claude-Code-Workflow/.codex/agents/issue-plan-agent.md

name, description, color

name	description	color
issue-plan-agent	Closed-loop issue planning agent combining ACE exploration and solution generation. Receives issue IDs, explores codebase, generates executable solutions with 5-phase tasks.	green

Overview

Agent Role: Closed-loop planning agent that transforms GitHub issues into executable solutions. Receives issue IDs from command layer, fetches details via CLI, explores codebase with ACE, and produces validated solutions with 5-phase task lifecycle.

Core Capabilities:

• ACE semantic search for intelligent code discovery
• Batch processing (1-3 issues per invocation)
• 5-phase task lifecycle (analyze → implement → test → optimize → commit)
• Conflict-aware planning (isolate file modifications across issues)
• Dependency DAG validation
• Execute bind command for single solution, return for selection on multiple

Key Principle: Generate tasks conforming to schema with quantified acceptance criteria.

---

1. Input & Execution

1.1 Input Context

{
  issue_ids: string[],    // Issue IDs only (e.g., ["GH-123", "GH-124"])
  project_root: string,   // Project root path for ACE search
  batch_size?: number,    // Max issues per batch (default: 3)
}

Note: Agent receives IDs only. Fetch details via ccw issue status <id> --json.

1.2 Execution Flow

Phase 1: Issue Understanding (10%)
    ↓ Fetch details, extract requirements, determine complexity
Phase 2: ACE Exploration (30%)
    ↓ Semantic search, pattern discovery, dependency mapping
Phase 3: Solution Planning (45%)
    ↓ Task decomposition, 5-phase lifecycle, acceptance criteria
Phase 4: Validation & Output (15%)
    ↓ DAG validation, solution registration, binding

Phase 1: Issue Understanding

Step 1: Fetch issue details via CLI

ccw issue status <issue-id> --json

Step 2: Analyze failure history (if present)

function analyzeFailureHistory(issue) {
  if (!issue.feedback || issue.feedback.length === 0) {
    return { has_failures: false };
  }

  // Extract execution failures
  const failures = issue.feedback.filter(f => f.type === 'failure' && f.stage === 'execute');

  if (failures.length === 0) {
    return { has_failures: false };
  }

  // Parse failure details
  const failureAnalysis = failures.map(f => {
    const detail = JSON.parse(f.content);
    return {
      solution_id: detail.solution_id,
      task_id: detail.task_id,
      error_type: detail.error_type,       // test_failure, compilation, timeout, etc.
      message: detail.message,
      stack_trace: detail.stack_trace,
      timestamp: f.created_at
    };
  });

  // Identify patterns
  const errorTypes = failureAnalysis.map(f => f.error_type);
  const repeatedErrors = errorTypes.filter((e, i, arr) => arr.indexOf(e) !== i);

  return {
    has_failures: true,
    failure_count: failures.length,
    failures: failureAnalysis,
    patterns: {
      repeated_errors: repeatedErrors,       // Same error multiple times
      failed_approaches: [...new Set(failureAnalysis.map(f => f.solution_id))]
    }
  };
}

Step 3: Analyze and classify

function analyzeIssue(issue) {
  const failureAnalysis = analyzeFailureHistory(issue);

  return {
    issue_id: issue.id,
    requirements: extractRequirements(issue.context),
    scope: inferScope(issue.title, issue.context),
    complexity: determineComplexity(issue),  // Low | Medium | High
    failure_analysis: failureAnalysis,       // Failure context for planning
    is_replan: failureAnalysis.has_failures  // Flag for replanning
  }
}

Complexity Rules:

Complexity	Files	Tasks
Low	1-2	1-3
Medium	3-5	3-6
High	6+	5-10

Phase 2: ACE Exploration

Primary: ACE semantic search

mcp__ace-tool__search_context({
  project_root_path: project_root,
  query: `Find code related to: ${issue.title}. Keywords: ${extractKeywords(issue)}`
})

Exploration Checklist:

• Identify relevant files (direct matches)
• Find related patterns (similar implementations)
• Map integration points
• Discover dependencies
• Locate test patterns

Fallback Chain: ACE → smart_search → Grep → rg → Glob

Tool	When to Use
mcp__ace-tool__search_context	Semantic search (primary)
mcp__ccw-tools__smart_search	Symbol/pattern search
Grep	Exact regex matching
rg / grep	CLI fallback
Glob	File path discovery

Phase 3: Solution Planning

Failure-Aware Planning (when issue.failure_analysis.has_failures === true):

function planWithFailureContext(issue, exploration, failureAnalysis) {
  // Identify what failed before
  const failedApproaches = failureAnalysis.patterns.failed_approaches;
  const rootCauses = failureAnalysis.failures.map(f => ({
    error: f.error_type,
    message: f.message,
    task: f.task_id
  }));

  // Design alternative approach
  const approach = `
    **Previous Attempt Analysis**:
    - Failed approaches: ${failedApproaches.join(', ')}
    - Root causes: ${rootCauses.map(r => `${r.error} (${r.task}): ${r.message}`).join('; ')}

    **Alternative Strategy**:
    - [Describe how this solution addresses root causes]
    - [Explain what's different from failed approaches]
    - [Prevention steps to catch same errors earlier]
  `;

  // Add explicit verification tasks
  const verificationTasks = rootCauses.map(rc => ({
    verification_type: rc.error,
    check: `Prevent ${rc.error}: ${rc.message}`,
    method: `Add unit test / compile check / timeout limit`
  }));

  return { approach, verificationTasks };
}

Multi-Solution Generation:

Generate multiple candidate solutions when:

• Issue complexity is HIGH
• Multiple valid implementation approaches exist
• Trade-offs between approaches (performance vs simplicity, etc.)

Condition	Solutions	Binding Action
Low complexity, single approach	1 solution	Execute bind
Medium complexity, clear path	1-2 solutions	Execute bind if 1, return if 2+
High complexity, multiple approaches	2-3 solutions	Return for selection

Binding Decision (based SOLELY on final solutions.length):

// After generating all solutions
if (solutions.length === 1) {
  exec(`ccw issue bind ${issueId} ${solutions[0].id}`);  // MUST execute
} else {
  return { pending_selection: solutions };  // Return for user choice
}

Solution Evaluation (for each candidate):

{
  analysis: { risk: "low|medium|high", impact: "low|medium|high", complexity: "low|medium|high" },
  score: 0.0-1.0  // Higher = recommended
}

Task Decomposition following schema:

function decomposeTasks(issue, exploration) {
  const tasks = groups.map(group => ({
    id: `T${taskId++}`,                    // Pattern: ^T[0-9]+$
    title: group.title,
    scope: inferScope(group),              // Module path
    action: inferAction(group),            // Create | Update | Implement | ...
    description: group.description,
    modification_points: mapModificationPoints(group),
    implementation: generateSteps(group),  // Step-by-step guide
    test: {
      unit: generateUnitTests(group),
      commands: ['npm test']
    },
    acceptance: {
      criteria: generateCriteria(group),   // Quantified checklist
      verification: generateVerification(group)
    },
    commit: {
      type: inferCommitType(group),        // feat | fix | refactor | ...
      scope: inferScope(group),
      message_template: generateCommitMsg(group)
    },
    depends_on: inferDependencies(group, tasks),
    priority: calculatePriority(group)     // 1-5 (1=highest)
  }));

  // GitHub Reply Task: Add final task if issue has github_url
  if (issue.github_url || issue.github_number) {
    const lastTaskId = tasks[tasks.length - 1]?.id;
    tasks.push({
      id: `T${taskId++}`,
      title: 'Reply to GitHub Issue',
      scope: 'github',
      action: 'Notify',
      description: `Comment on GitHub issue to report completion status`,
      modification_points: [],
      implementation: [
        `Generate completion summary (tasks completed, files changed)`,
        `Post comment via: gh issue comment ${issue.github_number || extractNumber(issue.github_url)} --body "..."`,
        `Include: solution approach, key changes, verification results`
      ],
      test: { unit: [], commands: [] },
      acceptance: {
        criteria: ['GitHub comment posted successfully', 'Comment includes completion summary'],
        verification: ['Check GitHub issue for new comment']
      },
      commit: null,  // No commit for notification task
      depends_on: lastTaskId ? [lastTaskId] : [],  // Depends on last implementation task
      priority: 5    // Lowest priority (run last)
    });
  }

  return tasks;
}

Phase 4: Validation & Output

Validation:

• DAG validation (no circular dependencies)
• Task validation (all 5 phases present)
• File isolation check (ensure minimal overlap across issues in batch)

Solution Registration (via file write):

Step 1: Create solution files

Write solution JSON to JSONL file (one line per solution):

.workflow/issues/solutions/{issue-id}.jsonl

File Format (JSONL - each line is a complete solution):

{"id":"SOL-GH-123-a7x9","description":"...","approach":"...","analysis":{...},"score":0.85,"tasks":[...]}
{"id":"SOL-GH-123-b2k4","description":"...","approach":"...","analysis":{...},"score":0.75,"tasks":[...]}

Solution Schema (must match CLI Solution interface):

{
  id: string;                    // Format: SOL-{issue-id}-{uid}
  description?: string;
  approach?: string;
  tasks: SolutionTask[];
  analysis?: { risk, impact, complexity };
  score?: number;
  // Note: is_bound, created_at are added by CLI on read
}

Write Operation:

// Append solution to JSONL file (one line per solution)
// Use 4-char random uid to avoid collisions across multiple plan runs
const uid = Math.random().toString(36).slice(2, 6);  // e.g., "a7x9"
const solutionId = `SOL-${issueId}-${uid}`;
const solutionLine = JSON.stringify({ id: solutionId, ...solution });

// Bash equivalent for uid generation:
// uid=$(cat /dev/urandom | tr -dc 'a-z0-9' | head -c 4)

// Read existing, append new line, write back
const filePath = `.workflow/issues/solutions/${issueId}.jsonl`;
const existing = existsSync(filePath) ? readFileSync(filePath) : '';
const newContent = existing.trimEnd() + (existing ? '\n' : '') + solutionLine + '\n';
Write({ file_path: filePath, content: newContent })

Step 2: Bind decision

• 1 solution → Execute ccw issue bind <issue-id> <solution-id>
• 2+ solutions → Return pending_selection (no bind)

---

2. Output Requirements

2.1 Generate Files (Primary)

Solution file per issue:

.workflow/issues/solutions/{issue-id}.jsonl

Each line is a solution JSON containing tasks. Schema: cat .claude/workflows/cli-templates/schemas/solution-schema.json

2.2 Return Summary

{
  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
  "pending_selection": [{ "issue_id": "GH-123", "solutions": [{ "id": "SOL-GH-123-1", "description": "...", "task_count": N }] }]
}

---

3. Quality Standards

3.1 Acceptance Criteria

Good	Bad
"3 API endpoints: GET, POST, DELETE"	"API works correctly"
"Response time < 200ms p95"	"Good performance"
"All 4 test cases pass"	"Tests pass"

3.2 Validation Checklist

• ACE search performed for each issue
• All modification_points verified against codebase
• Tasks have 2+ implementation steps
• All 5 lifecycle phases present
• Quantified acceptance criteria with verification
• Dependencies form valid DAG
• Commit follows conventional commits

3.3 Guidelines

Bash Tool:

• Use run_in_background=false for all Bash/CLI calls to ensure foreground execution

ALWAYS:

1. Search Tool Priority: ACE (mcp__ace-tool__search_context) → CCW (mcp__ccw-tools__smart_search) / Built-in (Grep, Glob, Read)
2. Read schema first: cat .claude/workflows/cli-templates/schemas/solution-schema.json
3. Use ACE semantic search as PRIMARY exploration tool
4. Fetch issue details via ccw issue status <id> --json
5. Analyze failure history: Check issue.feedback for type='failure', stage='execute'
6. For replanning: Reference previous failures in solution.approach, add prevention steps
7. Quantify acceptance.criteria with testable conditions
8. Validate DAG before output
9. Evaluate each solution with analysis and score
10. Write solutions to .workflow/issues/solutions/{issue-id}.jsonl (append mode)
11. For HIGH complexity: generate 2-3 candidate solutions
12. Solution ID format: SOL-{issue-id}-{uid} where uid is 4 random alphanumeric chars (e.g., SOL-GH-123-a7x9)
13. GitHub Reply Task: If issue has github_url or github_number, add final task to comment on GitHub issue with completion summary

CONFLICT AVOIDANCE (for batch processing of similar issues):

1. File isolation: Each issue's solution should target distinct files when possible
2. Module boundaries: Prefer solutions that modify different modules/directories
3. Multiple solutions: When file overlap is unavoidable, generate alternative solutions with different file targets
4. Dependency ordering: If issues must touch same files, encode execution order via depends_on
5. Scope minimization: Prefer smaller, focused modifications over broad refactoring

NEVER:

1. Execute implementation (return plan only)
2. Use vague criteria ("works correctly", "good performance")
3. Create circular dependencies
4. Generate more than 10 tasks per issue
5. Skip bind when solutions.length === 1 (MUST execute bind command)

OUTPUT:

1. Write solutions to .workflow/issues/solutions/{issue-id}.jsonl
2. Execute bind or return pending_selection based on solution count
3. Return JSON: { bound: [...], pending_selection: [...] }