Claude-Code-Workflow/.claude/commands/issue/plan.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
plan	Batch plan issue resolution using issue-plan-agent (explore + plan closed-loop)	<issue-id>[,<issue-id>,...] [--batch-size 3] --all-pending	TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Bash(*), Read(*), Write(*)

Issue Plan Command (/issue:plan)

Overview

Unified planning command using issue-plan-agent that combines exploration and planning into a single closed-loop workflow.

Output Requirements

Generate Files:

1. .workflow/issues/solutions/{issue-id}.jsonl - Solution with tasks for each issue

Return Summary:

{
  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
  "pending_selection": [{ "issue_id": "...", "solutions": [...] }],
  "conflicts": [{ "file": "...", "issues": [...] }]
}

Completion Criteria:

• Solution file generated for each issue
• Single solution → auto-bound via ccw issue bind
• Multiple solutions → returned for user selection
• Tasks conform to schema: cat .claude/workflows/cli-templates/schemas/issue-task-jsonl-schema.json
• Each task has quantified delivery_criteria

Core Capabilities

• Closed-loop agent: issue-plan-agent combines explore + plan
• Batch processing: 1 agent processes 1-3 issues
• ACE semantic search integrated into planning
• Solution with executable tasks and delivery criteria
• Automatic solution registration and binding

Storage Structure (Flat JSONL)

.workflow/issues/
├── issues.jsonl              # All issues (one per line)
├── queue.json                # Execution queue
└── solutions/
    ├── {issue-id}.jsonl      # Solutions for issue (one per line)
    └── ...

Usage

/issue:plan <issue-id>[,<issue-id>,...] [FLAGS]

# Examples
/issue:plan GH-123                    # Single issue
/issue:plan GH-123,GH-124,GH-125      # Batch (up to 3)
/issue:plan --all-pending             # All pending issues

# Flags
--batch-size <n>      Max issues per agent batch (default: 3)

Execution Process

Phase 1: Issue Loading
   ├─ Parse input (single, comma-separated, or --all-pending)
   ├─ Load issues from .workflow/issues/issues.jsonl
   ├─ Validate issues exist (create if needed)
   └─ Group into batches (max 3 per batch)

Phase 2: Unified Explore + Plan (issue-plan-agent)
   ├─ Launch issue-plan-agent per batch
   ├─ Agent performs:
   │   ├─ ACE semantic search for each issue
   │   ├─ Codebase exploration (files, patterns, dependencies)
   │   ├─ Solution generation with task breakdown
   │   └─ Conflict detection across issues
   └─ Output: solution JSON per issue

Phase 3: Solution Registration & Binding
   ├─ Append solutions to solutions/{issue-id}.jsonl
   ├─ Single solution per issue → auto-bind
   ├─ Multiple candidates → AskUserQuestion to select
   └─ Update issues.jsonl with bound_solution_id

Phase 4: Summary
   ├─ Display bound solutions
   ├─ Show task counts per issue
   └─ Display next steps (/issue:queue)

Implementation

Phase 1: Issue Loading (IDs Only)

const batchSize = flags.batchSize || 3;
let issueIds = [];

if (flags.allPending) {
  // Get pending issue IDs directly via CLI
  const ids = Bash(`ccw issue list --status pending,registered --ids`).trim();
  issueIds = ids ? ids.split('\n').filter(Boolean) : [];

  if (issueIds.length === 0) {
    console.log('No pending issues found.');
    return;
  }
  console.log(`Found ${issueIds.length} pending issues`);
} else {
  // Parse comma-separated issue IDs
  issueIds = userInput.includes(',')
    ? userInput.split(',').map(s => s.trim())
    : [userInput.trim()];

  // Create if not exists
  for (const id of issueIds) {
    Bash(`ccw issue init ${id} --title "Issue ${id}" 2>/dev/null || true`);
  }
}

// Group into batches
const batches = [];
for (let i = 0; i < issueIds.length; i += batchSize) {
  batches.push(issueIds.slice(i, i + batchSize));
}

console.log(`Processing ${issueIds.length} issues in ${batches.length} batch(es)`);

TodoWrite({
  todos: batches.map((_, i) => ({
    content: `Plan batch ${i+1}`,
    status: 'pending',
    activeForm: `Planning batch ${i+1}`
  }))
});

Phase 2: Unified Explore + Plan (issue-plan-agent)

Bash(`mkdir -p .workflow/issues/solutions`);
const pendingSelections = [];  // Collect multi-solution issues for user selection

for (const [batchIndex, batch] of batches.entries()) {
  updateTodo(`Plan batch ${batchIndex + 1}`, 'in_progress');

  // Build minimal prompt - agent handles exploration, planning, and binding
  const issuePrompt = `
## Plan Issues

**Issue IDs**: ${batch.join(', ')}
**Project Root**: ${process.cwd()}

### Steps
1. Fetch: \`ccw issue status <id> --json\`
2. Explore (ACE) → Plan solution
3. Register & bind: \`ccw issue bind <id> --solution <file>\`

### Generate Files
\`.workflow/issues/solutions/{issue-id}.jsonl\` - Solution with tasks (schema: cat .claude/workflows/cli-templates/schemas/issue-task-jsonl-schema.json)

### Binding Rules
- **Single solution**: Auto-bind via \`ccw issue bind <id> --solution <file>\`
- **Multiple solutions**: Register only, return for user selection

### Return Summary
\`\`\`json
{
  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
  "pending_selection": [{ "issue_id": "...", "solutions": [{ "id": "...", "description": "...", "task_count": N }] }],
  "conflicts": [{ "file": "...", "issues": [...] }]
}
\`\`\`
`;

  // Launch issue-plan-agent - agent writes solutions directly
  const result = Task(
    subagent_type="issue-plan-agent",
    run_in_background=false,
    description=`Explore & plan ${batch.length} issues`,
    prompt=issuePrompt
  );

  // Parse summary from agent
  const summary = JSON.parse(result);

  // Display auto-bound solutions
  for (const item of summary.bound || []) {
    console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
  }

  // Collect pending selections for Phase 3
  pendingSelections.push(...(summary.pending_selection || []));

  // Show conflicts
  if (summary.conflicts?.length > 0) {
    console.log(`⚠ Conflicts: ${summary.conflicts.map(c => c.file).join(', ')}`);
  }

  updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
}

Phase 3: Multi-Solution Selection

// Only handle issues where agent generated multiple solutions
if (pendingSelections.length > 0) {
  const answer = AskUserQuestion({
    questions: pendingSelections.map(({ issue_id, solutions }) => ({
      question: `Select solution for ${issue_id}:`,
      header: issue_id,
      multiSelect: false,
      options: solutions.map(s => ({
        label: `${s.id} (${s.task_count} tasks)`,
        description: s.description
      }))
    }))
  });

  // Bind user-selected solutions
  for (const { issue_id } of pendingSelections) {
    const selectedId = extractSelectedSolutionId(answer, issue_id);
    if (selectedId) {
      Bash(`ccw issue bind ${issue_id} ${selectedId}`);
      console.log(`✓ ${issue_id}: ${selectedId} bound`);
    }
  }
}

Phase 4: Summary

// Count planned issues via CLI
const plannedIds = Bash(`ccw issue list --status planned --ids`).trim();
const plannedCount = plannedIds ? plannedIds.split('\n').length : 0;

console.log(`
## Done: ${issueIds.length} issues → ${plannedCount} planned

Next: \`/issue:queue\` → \`/issue:execute\`
`);

Error Handling

Error	Resolution
Issue not found	Auto-create in issues.jsonl
ACE search fails	Agent falls back to ripgrep
No solutions generated	Display error, suggest manual planning
User cancels selection	Skip issue, continue with others
File conflicts	Agent detects and suggests resolution order

Related Commands

• /issue:queue - Form execution queue from bound solutions
• /issue:execute - Execute queue with codex
• ccw issue list - List all issues
• ccw issue status - View issue and solution details