Claude-Code-Workflow/.codex/skills/workflow-lite-plan-execute/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
workflow-lite-plan-execute	Lightweight planning + execution workflow. Serial CLI exploration → Search verification → Clarification → Planning → Unified JSONL output → Execution via unified-execute.	AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context

Planning Workflow

Lite Plan produces a unified JSONL (tasks.jsonl) implementation plan via serial CLI exploration and direct planning, then hands off to unified-execute-with-file for task execution.

Key Design Principles

1. Serial Execution: All phases execute serially inline, no agent delegation
2. CLI Exploration: Multi-angle codebase exploration via ccw cli calls (default gemini, fallback claude)
3. Search Verification: Verify CLI findings with ACE search / Grep / Glob before incorporating
4. Unified JSONL Output: Produces tasks.jsonl compatible with collaborative-plan-with-file and unified-execute-with-file
5. Progressive Phase Loading: Only load phase docs when about to execute

Auto Mode

When --yes or -y:

• Auto-approve plan and use default execution settings
• Skip non-critical clarifications; still ask minimal clarifications if required for safety/correctness

Usage (Pseudo)

This section describes the skill input shape; actual invocation depends on the host runtime.

$workflow-lite-plan-execute <task description>
$workflow-lite-plan-execute [FLAGS] "<task description or file path>"

# Flags
-y, --yes                              Skip confirmations (auto mode)
-e, --explore                          Force exploration phase

Examples:

$workflow-lite-plan-execute "Implement JWT authentication"
$workflow-lite-plan-execute -y "Add user profile page"
$workflow-lite-plan-execute -e "Refactor payment module"
$workflow-lite-plan-execute "docs/todo.md"

Implementation sketch: 编排器内部使用 $workflow-lite-plan-execute "..." 接口调用，此为伪代码示意，非命令行语法。

Phase Reference Documents (Read On Demand)

Phase	Document	Purpose
1	phases/01-lite-plan.md	Serial CLI exploration, clarification, plan generation → tasks.jsonl
2	phases/02-lite-execute.md	Handoff to unified-execute-with-file for task execution

Orchestrator Logic

// Flag parsing
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e')

// Task extraction rule:
// - Strip known flags: -y/--yes, -e/--explore
// - Remaining args are joined as the task description
// - Treat it as a file path ONLY if (a) exactly one arg remains AND (b) the path exists
function extractTaskDescription(args) {
  const knownFlags = new Set(['--yes', '-y', '--explore', '-e'])
  const rest = args.filter(a => !knownFlags.has(a))
  if (rest.length === 1 && file_exists(rest[0])) return rest[0]
  return rest.join(' ').trim()
}

const taskDescription = extractTaskDescription($ARGUMENTS)

// Phase 1: Lite Plan → tasks.jsonl
Read('phases/01-lite-plan.md')
// Execute planning phase...

// Gate: only continue when confirmed (or --yes)
if (planResult?.userSelection?.confirmation !== 'Allow' && !autoYes) {
  // Stop: user cancelled or requested modifications
  return
}

// Phase 2: Handoff to unified-execute-with-file
Read('phases/02-lite-execute.md')
// Invoke unified-execute-with-file with tasks.jsonl path

Output Contract

Phase 1 produces tasks.jsonl (unified JSONL format) — compatible with collaborative-plan-with-file and consumable by unified-execute-with-file.

Output Directory: {projectRoot}/.workflow/.lite-plan/{session-id}/

{projectRoot}/.workflow/.lite-plan/{session-id}/
├── exploration-{angle1}.md            # Per-angle CLI exploration results
├── exploration-{angle2}.md            # (1-4 files based on complexity)
├── explorations-manifest.json         # Exploration index
├── exploration-notes.md               # Synthesized exploration notes
├── requirement-analysis.json          # Complexity assessment
├── tasks.jsonl                        # ⭐ Unified JSONL (collaborative-plan-with-file compatible)
└── plan.md                            # Human-readable summary

Unified JSONL Task Format (one task per line):

{
  id: "TASK-001",
  title: string,
  description: string,
  type: "feature|fix|refactor|enhancement|testing|infrastructure",
  priority: "high|medium|low",
  effort: "small|medium|large",
  scope: string,
  depends_on: ["TASK-xxx"],
  convergence: {
    criteria: string[],           // Testable conditions
    verification: string,         // Executable command or manual steps
    definition_of_done: string    // Business language
  },
  files: [{
    path: string,
    action: "modify|create|delete",
    changes: string[],
    conflict_risk: "low|medium|high"
  }],
  source: {
    tool: "workflow-lite-plan-execute",
    session_id: string,
    original_id: string
  }
}

TodoWrite Pattern

Initialization:

[
  {"content": "Lite Plan - Planning", "status": "in_progress", "activeForm": "Planning"},
  {"content": "Execution (unified-execute)", "status": "pending", "activeForm": "Executing tasks"}
]

After planning completes:

[
  {"content": "Lite Plan - Planning", "status": "completed", "activeForm": "Planning"},
  {"content": "Execution (unified-execute)", "status": "in_progress", "activeForm": "Executing tasks"}
]

Core Rules

1. Planning phase NEVER modifies project code — it may write planning artifacts, but all implementation is delegated to unified-execute
2. All phases serial, no agent delegation — everything runs inline, no spawn_agent
3. CLI exploration with search verification — CLI calls produce findings, ACE/Grep/Glob verify them
4. tasks.jsonl is the output contract — unified JSONL format passed to unified-execute-with-file
5. Progressive loading: Read phase doc only when about to execute
6. File-path detection: Treat input as a file path only if the path exists; do not infer from file extensions

Error Handling

Error	Resolution
CLI exploration failure	Skip angle, continue with remaining; fallback gemini → claude
Planning phase failure	Display error, offer retry
tasks.jsonl missing	Error: planning phase did not produce output
Phase file not found	Error with file path for debugging

Related Skills

• Collaborative planning: ../collaborative-plan-with-file/SKILL.md
• Unified execution: ../unified-execute-with-file/SKILL.md
• Full planning workflow: ../workflow-plan-execute/SKILL.md