SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscodex-issue-plan-execute

codex-issue-plan-execute

Office & productivity

View repository

Updated 10-15 17:32

About this skill

Codex Issue Plan-Execute Workflow

Streamlined autonomous workflow for Codex that integrates issue planning, queue management, and solution execution in a single stateful Skill. Supports batch processing with minimal queue overhead and dual-agent execution strategy.

Architecture Overview

For complete architecture details, system diagrams, and design principles, see ARCHITECTURE.md.

Key concepts:

  • Persistent Dual-Agent System: Two long-running agents (Planning + Execution) that maintain context across all tasks
  • Sequential Pipeline: Issues → Planning Agent → Solutions → Execution Agent → Results
  • Unified Results: All results accumulated in single planning-results.json and execution-results.json files
  • Efficient Communication: Uses send_input() for task routing without agent recreation overhead

⚠️ Mandatory Prerequisites (强制前置条件)

⛔ Skipping is prohibited: Before performing any operation, youmustread the following two P0 specification documents. Executing directly without understanding the specifications will result in output quality that does not meet the standard.

Document Purpose When
specs/issue-handling.md Issue handling specifications and data structures Required reading before execution
specs/solution-schema.md Solution data structures and validation rules Required reading before execution

Execution Flow

Phase 1: Initialize Persistent Agents

→ Refer to: ARCHITECTURE.md - System architecture
→ Refer to: phases/orchestrator.md - Orchestration logic
→ Spawn Planning Agent with prompts/planning-agent.md (stays alive)
→ Spawn Execution Agent with prompts/execution-agent.md (stays alive)

Phase 2: Planning Pipeline

→ Refer to: phases/actions/action-plan.md, specs/subagent-roles.md For each issue sequentially:

  1. Send issue to Planning Agent via send_input() with planning request
  2. Wait for Planning Agent to return solution JSON
  3. Store result in unified planning-results.json array
  4. Continue to next issue (agent stays alive)

Phase 3: Execution Pipeline

→ Refer to: phases/actions/action-execute.md, specs/quality-standards.md For each successful planning result sequentially:

  1. Send solution to Execution Agent via send_input() with execution request
  2. Wait for Execution Agent to complete implementation and testing
  3. Store result in unified execution-results.json array
  4. Continue to next solution (agent stays alive)

Phase 4: Finalize

→ Refer to: phases/actions/action-complete.md → Close Planning Agent (after all issues planned) → Close Execution Agent (after all solutions executed) → Generate final report with statistics

State Schema

{
  "status": "pending|running|completed",
  "phase": "init|listing|planning|executing|complete",
  "issues": {
    "{issue_id}": {
      "id": "ISS-xxx",
      "status": "registered|planning|planned|executing|completed",
      "solution_id": "SOL-xxx-1",
      "planned_at": "ISO-8601",
      "executed_at": "ISO-8601"
    }
  },
  "queue": [
    {
      "item_id": "S-1",
      "issue_id": "ISS-xxx",
      "solution_id": "SOL-xxx-1",
      "status": "pending|executing|completed"
    }
  ],
  "context": {
    "work_dir": ".workflow/.scratchpad/...",
    "total_issues": 0,
    "completed_count": 0,
    "failed_count": 0
  },
  "errors": []
}

Directory Setup

const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = `.workflow/.scratchpad/codex-issue-${timestamp}`;

Bash(`mkdir -p "${workDir}"`);
Bash(`mkdir -p "${workDir}/solutions"`);
Bash(`mkdir -p "${workDir}/snapshots"`);

Output Structure

.workflow/.scratchpad/codex-issue-{timestamp}/
├── planning-results.json               # All planning results in single file
│   ├── phase: "planning"
│   ├── created_at: "ISO-8601"
│   └── results: [
│       { issue_id, solution_id, status, solution, planned_at }
│     ]
├── execution-results.json              # All execution results in single file
│   ├── phase: "execution"
│   ├── created_at: "ISO-8601"
│   └── results: [
│       { issue_id, solution_id, status, commit_hash, files_modified, executed_at }
│     ]
└── final-report.md                     # Summary statistics and report

Reference Documents by Phase

🔧 Setup & Understanding (初始化阶段)

Used to understand the entire system architecture and execution flow

Document Purpose Key Topics
phases/orchestrator.md Orchestrator core logic How to manage agents, pipeline flow, and state transitions
phases/state-schema.md State structure definition Complete state model, validation rules, persistence
specs/agent-roles.md Agent role and responsibility definitions Detailed description of Planning & Execution Agent

📋 Planning Phase (规划阶段)

Refer to when executing Phase 2 - Planning logic and Issue handling

Document Purpose When to Use
phases/actions/action-plan.md Detailed explanation of the Planning process Understand the issue→solution conversion logic
phases/actions/action-list.md Issue list handling Learn issue loading and listing logic
specs/issue-handling.md Issue data specification Understand issue structure and validation rules ✅ Required reading
specs/solution-schema.md Solution data structure Understand the solution JSON format ✅ Required reading

⚙️ Execution Phase (执行阶段)

Refer to when executing Phase 3 - Implementation and validation logic

Document Purpose When to Use
phases/actions/action-execute.md Detailed explanation of the Execution process Understand the solution→implementation logic
specs/quality-standards.md Quality standards and acceptance criteria Check whether the implementation meets the standard

🏁 Completion Phase (完成阶段)

Refer to when executing Phase 4 - Wrap-up and reporting logic

Document Purpose When to Use
phases/actions/action-complete.md Completion process Generate the final report and statistics

🔍 Debugging & Troubleshooting (问题排查)

Refer to when encountering problems - quickly locate and resolve them

Issue Solution Document
Abnormal state during execution phases/state-schema.md - Validate state structure
Planning Agent output does not meet expectations phases/actions/action-plan.md + specs/solution-schema.md
Execution Agent implementation failed phases/actions/action-execute.md + specs/quality-standards.md
Issue data format error specs/issue-handling.md

📚 Architecture & Agent Definitions (架构和Agent定义)

Core design documents

Document Purpose Notes
ARCHITECTURE.md System architecture and design principles Required reading before startup
specs/agent-roles.md Agent role definitions Detailed responsibilities of Planning & Execution Agent
prompts/planning-agent.md Planning Agent unified prompt Used to initialize the Planning Agent
prompts/execution-agent.md Execution Agent unified prompt Used to initialize the Execution Agent

Usage Examples

Batch Process Specific Issues

codex -p "@.codex/prompts/codex-issue-plan-execute ISS-001,ISS-002,ISS-003"

Interactive Selection

codex -p "@.codex/prompts/codex-issue-plan-execute"
# Then select issues from the list

Resume from Snapshot

codex -p "@.codex/prompts/codex-issue-plan-execute --resume snapshot-path"

Skill Version: 1.0 Execution Mode: Autonomous Status: Ready for Customization