claude-code-workflow 6.3.12 → 6.3.15

package/.claude/commands/issue/plan.md

@@ -11,55 +11,42 @@ allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Bash(
 
 Unified planning command using **issue-plan-agent** that combines exploration and planning into a single closed-loop workflow.
 
-## Output Requirements
+**Behavior:**
+- Single solution per issue → auto-bind
+- Multiple solutions → return for user selection
+- Agent handles file generation
 
-**Generate Files:**
-1. `.workflow/issues/solutions/{issue-id}.jsonl` - Solution with tasks for each issue
+## Core Guidelines
 
-**Return Summary:**
-```json
-{
-  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
-  "pending_selection": [{ "issue_id": "...", "solutions": [...] }],
-  "conflicts": [{ "file": "...", "issues": [...] }]
-}
-```
+**⚠️ Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow:
 
-**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/solution-schema.json`
-- [ ] Each task has quantified `acceptance.criteria`
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| Update status | `ccw issue update <id> --status ...` | Direct file edit |
+| Bind solution | `ccw issue bind <id> <sol-id>` | Direct file edit |
 
-## Core Capabilities
+**Output Options**:
+- `--brief`: JSON with minimal fields (id, title, status, priority, tags)
+- `--json`: Full JSON (agent use only)
 
-- **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
+**Orchestration vs Execution**:
+- **Command (orchestrator)**: Use `--brief` for minimal context
+- **Agent (executor)**: Fetch full details → `ccw issue status <id> --json`
 
-## 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)
-    └── ...
-```
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly. 
 
 ## Usage
 
 ```bash
-/issue:plan <issue-id>[,<issue-id>,...] [FLAGS]
+/issue:plan [<issue-id>[,<issue-id>,...]] [FLAGS]
 
 # Examples
+/issue:plan                           # Default: --all-pending
 /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
+/issue:plan --all-pending             # All pending issues (explicit)
 
 # Flags
 --batch-size <n>      Max issues per agent batch (default: 3)
@@ -97,14 +84,17 @@ Phase 4: Summary
 
 ## Implementation
 
-### Phase 1: Issue Loading (ID + Title + Tags)
+### Phase 1: Issue Loading (Brief Info Only)
 
 ```javascript
 const batchSize = flags.batchSize || 3;
-let issues = [];  // {id, title, tags}
+let issues = [];  // {id, title, tags} - brief info for grouping only
+
+// Default to --all-pending if no input provided
+const useAllPending = flags.allPending || !userInput || userInput.trim() === '';
 
-if (flags.allPending) {
-  // Get pending issues with metadata via CLI (JSON output)
+if (useAllPending) {
+  // Get pending issues with brief metadata via CLI
   const result = Bash(`ccw issue list --status pending,registered --json`).trim();
   const parsed = result ? JSON.parse(result) : [];
   issues = parsed.map(i => ({ id: i.id, title: i.title || '', tags: i.tags || [] }));
@@ -115,7 +105,7 @@ if (flags.allPending) {
   }
   console.log(`Found ${issues.length} pending issues`);
 } else {
-  // Parse comma-separated issue IDs, fetch metadata
+  // Parse comma-separated issue IDs, fetch brief metadata
   const ids = userInput.includes(',')
     ? userInput.split(',').map(s => s.trim())
     : [userInput.trim()];
@@ -127,41 +117,48 @@ if (flags.allPending) {
     issues.push({ id, title: parsed.title || '', tags: parsed.tags || [] });
   }
 }
+// Note: Agent fetches full issue content via `ccw issue status <id> --json`
+
+// Semantic grouping via Gemini CLI (max 4 issues per group)
+async function groupBySimilarityGemini(issues) {
+  const issueSummaries = issues.map(i => ({
+    id: i.id, title: i.title, tags: i.tags
+  }));
+
+  const prompt = `
+PURPOSE: Group similar issues by semantic similarity for batch processing; maximize within-group coherence; max 4 issues per group
+TASK: • Analyze issue titles/tags semantically • Identify functional/architectural clusters • Assign each issue to one group
+MODE: analysis
+CONTEXT: Issue metadata only
+EXPECTED: JSON with groups array, each containing max 4 issue_ids, theme, rationale
+RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Each issue in exactly one group | Max 4 issues per group | Balance group sizes
+
+INPUT:
+${JSON.stringify(issueSummaries, null, 2)}
+
+OUTPUT FORMAT:
+{"groups":[{"group_id":1,"theme":"...","issue_ids":["..."],"rationale":"..."}],"ungrouped":[]}
+`;
 
-// Intelligent grouping by similarity (tags → title keywords)
-function groupBySimilarity(issues, maxSize) {
-  const batches = [];
-  const used = new Set();
-
-  for (const issue of issues) {
-    if (used.has(issue.id)) continue;
-
-    const batch = [issue];
-    used.add(issue.id);
-    const issueTags = new Set(issue.tags);
-    const issueWords = new Set(issue.title.toLowerCase().split(/\s+/));
-
-    // Find similar issues
-    for (const other of issues) {
-      if (used.has(other.id) || batch.length >= maxSize) continue;
-
-      // Similarity: shared tags or shared title keywords
-      const sharedTags = other.tags.filter(t => issueTags.has(t)).length;
-      const otherWords = other.title.toLowerCase().split(/\s+/);
-      const sharedWords = otherWords.filter(w => issueWords.has(w) && w.length > 3).length;
+  const taskId = Bash({
+    command: `ccw cli -p "${prompt}" --tool gemini --mode analysis`,
+    run_in_background: true, timeout: 600000
+  });
+  const output = TaskOutput({ task_id: taskId, block: true });
 
-      if (sharedTags > 0 || sharedWords >= 2) {
-        batch.push(other);
-        used.add(other.id);
-      }
-    }
-    batches.push(batch);
+  // Extract JSON from potential markdown code blocks
+  function extractJsonFromMarkdown(text) {
+    const jsonMatch = text.match(/```json\s*\n([\s\S]*?)\n```/) ||
+                      text.match(/```\s*\n([\s\S]*?)\n```/);
+    return jsonMatch ? jsonMatch[1] : text;
   }
-  return batches;
+
+  const result = JSON.parse(extractJsonFromMarkdown(output));
+  return result.groups.map(g => g.issue_ids.map(id => issues.find(i => i.id === id)));
 }
 
-const batches = groupBySimilarity(issues, batchSize);
-console.log(`Processing ${issues.length} issues in ${batches.length} batch(es) (grouped by similarity)`);
+const batches = await groupBySimilarityGemini(issues);
+console.log(`Processing ${issues.length} issues in ${batches.length} batch(es) (max 4 issues/agent)`);
 
 TodoWrite({
   todos: batches.map((_, i) => ({
@@ -177,6 +174,7 @@ TodoWrite({
 ```javascript
 Bash(`mkdir -p .workflow/issues/solutions`);
 const pendingSelections = [];  // Collect multi-solution issues for user selection
+const agentResults = [];       // Collect all agent results for conflict aggregation
 
 // Build prompts for all batches
 const agentTasks = batches.map((batch, batchIndex) => {
@@ -191,34 +189,26 @@ ${issueList}
 
 **Project Root**: ${process.cwd()}
 
-### Project Context (MANDATORY - Read Both Files First)
-1. Read: .workflow/project-tech.json (technology stack, architecture, key components)
-2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
+### Project Context (MANDATORY)
+1. Read: .workflow/project-tech.json (technology stack, architecture)
+2. Read: .workflow/project-guidelines.json (constraints and conventions)
 
-**CRITICAL**: All solution tasks MUST comply with constraints in project-guidelines.json
+### Workflow
+1. Fetch issue details: ccw issue status <id> --json
+2. Load project context files
+3. Explore codebase (ACE semantic search)
+4. Plan solution with tasks (schema: solution-schema.json)
+5. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
+6. Single solution → auto-bind; Multiple → return for selection
 
-### Steps
-1. Fetch: \`ccw issue status <id> --json\`
-2. Load project context (project-tech.json + project-guidelines.json)
-3. **If source=discovery**: Use discovery_context (file, line, snippet, suggested_fix) as planning hints
-4. Explore (ACE) → Plan solution (respecting guidelines)
-5. 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/solution-schema.json)
-
-### Binding Rules
-- **Single solution**: Auto-bind via \`ccw issue bind <id> --solution <file>\`
-- **Multiple solutions**: Register only, return for user selection
+### Rules
+- Solution ID format: SOL-{issue-id}-{seq}
+- Single solution per issue → auto-bind via ccw issue bind
+- Multiple solutions → register only, return pending_selection
+- Tasks must have quantified acceptance.criteria
 
 ### Return Summary
-\`\`\`json
-{
-  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
-  "pending_selection": [{ "issue_id": "...", "solutions": [{ "id": "...", "description": "...", "task_count": N }] }],
-  "conflicts": [{ "file": "...", "issues": [...] }]
-}
-\`\`\`
+{"bound":[{"issue_id":"...","solution_id":"...","task_count":N}],"pending_selection":[{"issue_id":"...","solutions":[{"id":"...","description":"...","task_count":N}]}]}
 `;
 
   return { batchIndex, batchIds, issuePrompt, batch };
@@ -247,7 +237,18 @@ for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
   // Collect results from this chunk
   for (const { taskId, batchIndex } of taskIds) {
     const result = TaskOutput(task_id=taskId, block=true);
-    const summary = JSON.parse(result);
+
+    // Extract JSON from potential markdown code blocks (agent may wrap in ```json...```)
+    const jsonText = extractJsonFromMarkdown(result);
+    let summary;
+    try {
+      summary = JSON.parse(jsonText);
+    } catch (e) {
+      console.log(`⚠ Batch ${batchIndex + 1}: Failed to parse agent result, skipping`);
+      updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
+      continue;
+    }
+    agentResults.push(summary);  // Store for Phase 3 conflict aggregation
 
     for (const item of summary.bound || []) {
       console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
@@ -258,49 +259,33 @@ for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
       pendingSelections.push(pending);
     }
     if (summary.conflicts?.length > 0) {
-      console.log(`⚠ Conflicts: ${summary.conflicts.map(c => c.file).join(', ')}`);
+      console.log(`⚠ Conflicts: ${summary.conflicts.length} detected (will resolve in Phase 3)`);
     }
     updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
   }
 }
 ```
 
-### Phase 3: Multi-Solution Selection (MANDATORY when pendingSelections > 0)
+### Phase 3: Conflict Resolution & Solution Selection
 
-```javascript
-// MUST trigger user selection when multiple solutions exist
-if (pendingSelections.length > 0) {
-  console.log(`\n## User Selection Required: ${pendingSelections.length} issue(s) have multiple solutions\n`);
-
-  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
-      }))
-    }))
-  });
+**Conflict Handling:**
+- Collect `conflicts` from all agent results
+- Low/Medium severity → auto-resolve with `recommended_resolution`
+- High severity → use `AskUserQuestion` to let user choose resolution
 
-  // 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`);
-    }
-  }
-}
-```
+**Multi-Solution Selection:**
+- If `pending_selection` contains issues with multiple solutions:
+  - Use `AskUserQuestion` to present options (solution ID + task count + description)
+  - Extract selected solution ID from user response
+  - Verify solution file exists, recover from payload if missing
+  - Bind selected solution via `ccw issue bind <issue-id> <solution-id>`
 
 ### Phase 4: Summary
 
 ```javascript
 // Count planned issues via CLI
-const plannedIds = Bash(`ccw issue list --status planned --ids`).trim();
-const plannedCount = plannedIds ? plannedIds.split('\n').length : 0;
+const planned = JSON.parse(Bash(`ccw issue list --status planned --brief`) || '[]');
+const plannedCount = planned.length;
 
 console.log(`
 ## Done: ${issues.length} issues → ${plannedCount} planned
@@ -319,6 +304,18 @@ Next: \`/issue:queue\` → \`/issue:execute\`
 | User cancels selection | Skip issue, continue with others |
 | File conflicts | Agent detects and suggests resolution order |
 
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] All input issues have solutions in `solutions/{issue-id}.jsonl`
+- [ ] Single solution issues are auto-bound (`bound_solution_id` set)
+- [ ] Multi-solution issues returned in `pending_selection` for user choice
+- [ ] Each solution has executable tasks with `modification_points`
+- [ ] Task acceptance criteria are quantified (not vague)
+- [ ] Conflicts detected and reported (if multiple issues touch same files)
+- [ ] Issue status updated to `planned` after binding
+
 ## Related Commands
 
 - `/issue:queue` - Form execution queue from bound solutions