--- name: issue-resolve description: Unified issue resolution pipeline with source selection. Plan issues via AI exploration, convert from artifacts, import from brainstorm sessions, or form execution queues. Triggers on "issue:plan", "issue:queue", "issue:convert-to-plan", "issue:from-brainstorm", "resolve issue", "plan issue", "queue issues", "convert plan to issue". allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep --- # Issue Resolve (Codex Version) Unified issue resolution pipeline that orchestrates solution creation from multiple sources and queue formation for execution. ## Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ Issue Resolve Orchestrator (SKILL.md) │ │ → Source selection → Route to phase → Execute → Summary │ └───────────────┬─────────────────────────────────────────────────┘ │ ├─ ASK_USER: Select issue source │ ┌───────────┼───────────┬───────────┬───────────┐ ↓ ↓ ↓ ↓ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ │ │ Explore │ │ Convert │ │ From │ │ Form │ │ │ & Plan │ │Artifact │ │Brainstorm│ │ Queue │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ ↓ ↓ ↓ ↓ │ Solutions Solutions Issue+Sol Exec Queue │ (bound) (bound) (bound) (ordered) │ │ ┌────────────────────────────────┘ ↓ /issue:execute ``` ## Key Design Principles 1. **Source-Driven Routing**: ASK_USER selects workflow, then load single phase 2. **Progressive Phase Loading**: Only read the selected phase document 3. **CLI-First Data Access**: All issue/solution CRUD via `ccw issue` CLI commands 4. **Auto Mode Support**: `-y` flag skips source selection (defaults to Explore & Plan) ## Subagent API Reference ### spawn_agent Create a new subagent with task assignment. ```javascript const agentId = spawn_agent({ message: ` ## TASK ASSIGNMENT ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) 2. Read: {projectRoot}/.workflow/project-tech.json 3. Read: {projectRoot}/.workflow/project-guidelines.json ## TASK CONTEXT ${taskContext} ## DELIVERABLES ${deliverables} ` }) ``` ### wait Get results from subagent (only way to retrieve results). ```javascript const result = wait({ ids: [agentId], timeout_ms: 600000 // 10 minutes }) if (result.timed_out) { // Handle timeout - can continue waiting or send_input to prompt completion } ``` ### send_input Continue interaction with active subagent (for clarification or follow-up). ```javascript send_input({ id: agentId, message: ` ## CLARIFICATION ANSWERS ${answers} ## NEXT STEP Continue with updated analysis. ` }) ``` ### close_agent Clean up subagent resources (irreversible). ```javascript close_agent({ id: agentId }) ``` ## Auto Mode When `--yes` or `-y`: Skip source selection, use Explore & Plan for issue IDs, or auto-detect source type for paths. ## Usage ``` codex -p "@.codex/prompts/issue-resolve.md " codex -p "@.codex/prompts/issue-resolve.md [FLAGS] \"\"" # Flags -y, --yes Skip all confirmations (auto mode) --source Pre-select source: plan|convert|brainstorm|queue --batch-size Max issues per agent batch (plan mode, default: 3) --issue Bind to existing issue (convert mode) --supplement Add tasks to existing solution (convert mode) --queues Number of parallel queues (queue mode, default: 1) # Examples codex -p "@.codex/prompts/issue-resolve.md GH-123,GH-124" # Explore & plan issues codex -p "@.codex/prompts/issue-resolve.md --source plan --all-pending" # Plan all pending issues codex -p "@.codex/prompts/issue-resolve.md --source convert \".workflow/.lite-plan/my-plan\"" # Convert artifact codex -p "@.codex/prompts/issue-resolve.md --source brainstorm SESSION=\"BS-rate-limiting\"" # From brainstorm codex -p "@.codex/prompts/issue-resolve.md --source queue" # Form execution queue codex -p "@.codex/prompts/issue-resolve.md -y GH-123" # Auto mode, plan single issue ``` ## Execution Flow ``` Input Parsing: └─ Parse flags (--source, -y, --issue, etc.) and positional args Source Selection: ├─ --source flag provided → Route directly ├─ Auto-detect from input: │ ├─ Issue IDs (GH-xxx, ISS-xxx) → Explore & Plan │ ├─ SESSION="..." → From Brainstorm │ ├─ File/folder path → Convert from Artifact │ └─ No input or --all-pending → Explore & Plan (all pending) └─ Otherwise → ASK_USER to select source Phase Execution (load one phase): ├─ Phase 1: Explore & Plan → phases/01-issue-plan.md ├─ Phase 2: Convert Artifact → phases/02-convert-to-plan.md ├─ Phase 3: From Brainstorm → phases/03-from-brainstorm.md └─ Phase 4: Form Queue → phases/04-issue-queue.md Post-Phase: └─ Summary + Next steps recommendation ``` ### Phase Reference Documents | Phase | Document | Load When | Purpose | |-------|----------|-----------|---------| | Phase 1 | [phases/01-issue-plan.md](phases/01-issue-plan.md) | Source = Explore & Plan | Batch plan issues via issue-plan-agent | | Phase 2 | [phases/02-convert-to-plan.md](phases/02-convert-to-plan.md) | Source = Convert Artifact | Convert lite-plan/session/markdown to solutions | | Phase 3 | [phases/03-from-brainstorm.md](phases/03-from-brainstorm.md) | Source = From Brainstorm | Convert brainstorm ideas to issue + solution | | Phase 4 | [phases/04-issue-queue.md](phases/04-issue-queue.md) | Source = Form Queue | Order bound solutions into execution queue | ## Core Rules 1. **Source Selection First**: Always determine source before loading any phase 2. **Single Phase Load**: Only read the selected phase document, never load all phases 3. **CLI Data Access**: Use `ccw issue` CLI for all issue/solution operations, NEVER read files directly 4. **Content Preservation**: Each phase contains complete execution logic from original commands 5. **Auto-Detect Input**: Smart input parsing reduces need for explicit --source flag 6. **DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next 7. **Explicit Lifecycle**: Always close_agent after wait completes to free resources ## Input Processing ### Auto-Detection Logic ```javascript function detectSource(input, flags) { // 1. Explicit --source flag if (flags.source) return flags.source; // 2. Auto-detect from input content const trimmed = input.trim(); // Issue IDs pattern (GH-xxx, ISS-xxx, comma-separated) if (trimmed.match(/^[A-Z]+-\d+/i) || trimmed.includes(',')) { return 'plan'; } // --all-pending or empty input → plan all pending if (flags.allPending || trimmed === '') { return 'plan'; } // SESSION="..." pattern → brainstorm if (trimmed.includes('SESSION=')) { return 'brainstorm'; } // File/folder path → convert if (trimmed.match(/\.(md|json)$/) || trimmed.includes('.workflow/')) { return 'convert'; } // Cannot auto-detect → ask user return null; } ``` ### Source Selection (ASK_USER) ```javascript // When source cannot be auto-detected const answer = ASK_USER([{ id: "source", type: "select", prompt: "How would you like to create/manage issue solutions?", options: [ { label: "Explore & Plan (Recommended)", description: "AI explores codebase and generates solutions for issues" }, { label: "Convert from Artifact", description: "Convert existing lite-plan, workflow session, or markdown to solution" }, { label: "From Brainstorm", description: "Convert brainstorm session ideas into issue with solution" }, { label: "Form Execution Queue", description: "Order bound solutions into execution queue for /issue:execute" } ] }]); // BLOCKS (wait for user response) // Route based on selection const sourceMap = { "Explore & Plan": "plan", "Convert from Artifact": "convert", "From Brainstorm": "brainstorm", "Form Execution Queue": "queue" }; ``` ## Data Flow ``` User Input (issue IDs / artifact path / session ID / flags) ↓ [Parse Flags + Auto-Detect Source] ↓ [Source Selection] ← ASK_USER (if needed) ↓ [Read Selected Phase Document] ↓ [Execute Phase Logic] ↓ [Summary + Next Steps] ├─ After Plan/Convert/Brainstorm → Suggest /issue:queue or /issue:execute └─ After Queue → Suggest /issue:execute ``` ## Task Tracking Pattern ```javascript // Initialize plan with phase steps update_plan({ explanation: "Issue resolve workflow started", plan: [ { step: "Select issue source", status: "completed" }, { step: "Execute: [selected phase name]", status: "in_progress" }, { step: "Summary & next steps", status: "pending" } ] }) ``` Phase-specific sub-tasks are attached when the phase executes (see individual phase docs for details). ## Core Guidelines **Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow: | Operation | Correct | Incorrect | |-----------|---------|-----------| | List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` | | Read issue details | `ccw issue status --json` | `Read('issues.jsonl')` | | Update status | `ccw issue update --status ...` | Direct file edit | | Bind solution | `ccw issue bind ` | Direct file edit | | Batch solutions | `ccw issue solutions --status planned --brief` | Loop individual queries | **Output Options**: - `--brief`: JSON with minimal fields (orchestrator use) - `--json`: Full JSON (agent use only) **ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly. ## Error Handling | Error | Resolution | |-------|------------| | No source detected | Show ASK_USER with all 4 options | | Invalid source type | Show available sources, re-prompt | | Phase execution fails | Report error, suggest manual intervention | | No pending issues (plan) | Suggest creating issues first | | No bound solutions (queue) | Suggest running plan/convert/brainstorm first | ## Post-Phase Next Steps After successful phase execution, recommend next action: ```javascript // After Plan/Convert/Brainstorm (solutions created) ASK_USER([{ id: "next_action", type: "select", prompt: "Solutions created. What next?", options: [ { label: "Form Queue", description: "Order solutions for execution (/issue:queue)" }, { label: "Plan More Issues", description: "Continue creating solutions" }, { label: "View Issues", description: "Review issue details" }, { label: "Done", description: "Exit workflow" } ] }]); // BLOCKS (wait for user response) // After Queue (queue formed) // → Suggest /issue:execute directly ``` ## Related Commands - `issue-manage` - Interactive issue CRUD operations - `/issue:execute` - Execute queue with DAG-based parallel orchestration - `ccw issue list` - List all issues - `ccw issue status ` - View issue details