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)      │
     │           │           │                       │
     └─────┬─────┘───────────┘                       │
           ↓ (optional --export-tasks)               │
    .task/TASK-*.json                                 │
                                                     │
                    ┌────────────────────────────────┘
                    ↓
              /issue:execute

Key Design Principles

Source-Driven Routing: ASK_USER selects workflow, then load single phase
Progressive Phase Loading: Only read the selected phase document
CLI-First Data Access: All issue/solution CRUD via
```
ccw issue
```
CLI commands
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

-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 <task description or issue IDs>"
codex -p "@.codex/prompts/issue-resolve.md [FLAGS] \"<input>\""

# Flags
-y, --yes              Skip all confirmations (auto mode)
--source <type>        Pre-select source: plan|convert|brainstorm|queue
--batch-size <n>       Max issues per agent batch (plan mode, default: 3)
--issue <id>           Bind to existing issue (convert mode)
--supplement           Add tasks to existing solution (convert mode)
--queues <n>           Number of parallel queues (queue mode, default: 1)
--export-tasks         Export solution tasks to .task/TASK-*.json (task-schema.json format)

# 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:
   ├─ Export to Task JSON (optional, with --export-tasks flag)
   │   └─ For each solution.tasks[] → write .task/TASK-{T-id}.json
   └─ Summary + Next steps recommendation

Phase Reference Documents

Phase	Document	Load When	Purpose
Phase 1	phases/01-issue-plan.md	Source = Explore & Plan	Batch plan issues via issue-plan-agent
Phase 2	phases/02-convert-to-plan.md	Source = Convert Artifact	Convert lite-plan/session/markdown to solutions
Phase 3	phases/03-from-brainstorm.md	Source = From Brainstorm	Convert brainstorm ideas to issue + solution
Phase 4	phases/04-issue-queue.md	Source = Form Queue	Order bound solutions into execution queue

Core Rules

Source Selection First: Always determine source before loading any phase
Single Phase Load: Only read the selected phase document, never load all phases
CLI Data Access: Use
```
ccw issue
```
CLI for all issue/solution operations, NEVER read files directly
Content Preservation: Each phase contains complete execution logic from original commands
Auto-Detect Input: Smart input parsing reduces need for explicit --source flag
DO NOT STOP: Continuous multi-phase workflow. After completing each phase, immediately proceed to next
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

(Optional) Export to Task JSON (when --export-tasks flag is set):
    ├─ For each solution.tasks[] entry:
    │   ├─ solution.task.id             → id (prefixed as TASK-{T-id})
    │   ├─ solution.task.title          → title
    │   ├─ solution.task.description    → description
    │   ├─ solution.task.action         → action
    │   ├─ solution.task.scope          → scope
    │   ├─ solution.task.modification_points[] → files[]
    │   │   ├─ mp.file                  → files[].path
    │   │   ├─ mp.target                → files[].target
    │   │   └─ mp.change                → files[].changes[]
    │   ├─ solution.task.acceptance     → convergence
    │   │   ├─ acceptance.criteria[]    → convergence.criteria[]
    │   │   └─ acceptance.verification[]→ convergence.verification (joined)
    │   ├─ solution.task.implementation → implementation[]
    │   ├─ solution.task.test           → test
    │   ├─ solution.task.depends_on     → depends_on
    │   ├─ solution.task.commit         → commit
    │   └─ solution.task.priority       → priority (1→critical, 2→high, 3→medium, 4-5→low)
    ├─ Output path: .workflow/issues/{issue-id}/.task/TASK-{T-id}.json
    ├─ Each file follows task-schema.json (IDENTITY + CONVERGENCE + FILES required)
    └─ source.tool = "issue-resolve", source.issue_id = {issue-id}

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 <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
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

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 <id>
```
- View issue details

issue-resolve

NPX Install

Tags

SKILL.md Content

Issue Resolve (Codex Version)

Architecture Overview

Key Design Principles

Subagent API Reference

spawn_agent

wait

send_input

close_agent

Auto Mode

Usage

Execution Flow

Phase Reference Documents

Core Rules

Input Processing

Auto-Detection Logic

Source Selection (ASK_USER)

Data Flow

Task Tracking Pattern

Core Guidelines

Error Handling

Post-Phase Next Steps

Related Commands