Claude-Code-Workflow/.claude/skills/skill-generator/specs/cli-integration.md

CLI Integration Specification

CCW CLI integration specification that defines how to properly call external CLI tools within Skills.

---

Execution Modes

1. Synchronous Execution (Blocking)

Suitable for scenarios that need immediate results.

// Agent call - synchronous
const result = Task({
  subagent_type: 'universal-executor',
  prompt: 'Execute task...',
  run_in_background: false  // Key: synchronous execution
});

// Result immediately available
console.log(result);

2. Asynchronous Execution (Background)

Suitable for long-running CLI commands.

// CLI call - asynchronous
const task = Bash({
  command: 'ccw cli -p "..." --tool gemini --mode analysis',
  run_in_background: true  // Key: background execution
});

// Returns immediately without waiting for result
// task.task_id available for later queries

---

CCW CLI Call Specification

Basic Command Structure

ccw cli -p "<PROMPT>" --tool <gemini|qwen|codex> --mode <analysis|write>

Parameter Description

Parameter	Required	Description
-p "<prompt>"	Yes	Prompt text (use double quotes)
--tool <tool>	Yes	Tool selection: gemini, qwen, codex
--mode <mode>	Yes	Execution mode: analysis, write
--cd <path>	-	Working directory
--includeDirs <dirs>	-	Additional directories (comma-separated)
--resume [id]	-	Resume session

Mode Selection

- Analysis/Documentation tasks?
  → --mode analysis (read-only)

- Implementation/Modification tasks?
  → --mode write (read-write)

---

Agent Types and Selection

universal-executor

General-purpose executor, the most commonly used agent type.

Task({
  subagent_type: 'universal-executor',
  prompt: `
Execute task:
1. Read configuration file
2. Analyze dependencies
3. Generate report to ${outputPath}
  `,
  run_in_background: false
});

Applicable Scenarios:

• Multi-step task execution
• File operations (read/write/edit)
• Tasks that require tool invocation

Explore

Code exploration agent for quick codebase understanding.

Task({
  subagent_type: 'Explore',
  prompt: `
Explore src/ directory:
- Identify main modules
- Understand directory structure
- Find entry points

Thoroughness: medium
  `,
  run_in_background: false
});

Applicable Scenarios:

• Codebase exploration
• File discovery
• Structure understanding

cli-explore-agent

Deep code analysis agent.

Task({
  subagent_type: 'cli-explore-agent',
  prompt: `
Deep analysis of src/auth/ module:
- Authentication flow
- Session management
- Security mechanisms
  `,
  run_in_background: false
});

Applicable Scenarios:

• Deep code understanding
• Design pattern identification
• Complex logic analysis

---

Session Management

Session Recovery

// Save session ID
const session = Bash({
  command: 'ccw cli -p "Initial analysis..." --tool gemini --mode analysis',
  run_in_background: true
});

// Resume later
const continuation = Bash({
  command: `ccw cli -p "Continue analysis..." --tool gemini --mode analysis --resume ${session.id}`,
  run_in_background: true
});

Multi-Session Merge

// Merge context from multiple sessions
const merged = Bash({
  command: `ccw cli -p "Aggregate analysis..." --tool gemini --mode analysis --resume ${id1},${id2}`,
  run_in_background: true
});

---

CLI Integration Patterns in Skills

Pattern 1: Single Call

Simple tasks completed in one call.

// Phase execution
async function executePhase(context) {
  const result = Bash({
    command: `ccw cli -p "
PURPOSE: Analyze project structure
TASK: Identify modules, dependencies, entry points
MODE: analysis
CONTEXT: @src/**/*
EXPECTED: JSON format structure report
" --tool gemini --mode analysis --cd ${context.projectRoot}`,
    run_in_background: true,
    timeout: 600000
  });

  // Wait for completion
  return await waitForCompletion(result.task_id);
}

Pattern 2: Chained Calls

Multi-step tasks where each step depends on previous results.

async function executeChain(context) {
  // Step 1: Collect
  const collectId = await runCLI('collect', context);

  // Step 2: Analyze (depends on Step 1)
  const analyzeId = await runCLI('analyze', context, `--resume ${collectId}`);

  // Step 3: Generate (depends on Step 2)
  const generateId = await runCLI('generate', context, `--resume ${analyzeId}`);

  return generateId;
}

async function runCLI(step, context, resumeFlag = '') {
  const prompts = {
    collect: 'PURPOSE: Collect code files...',
    analyze: 'PURPOSE: Analyze code patterns...',
    generate: 'PURPOSE: Generate documentation...'
  };

  const result = Bash({
    command: `ccw cli -p "${prompts[step]}" --tool gemini --mode analysis ${resumeFlag}`,
    run_in_background: true
  });

  return await waitForCompletion(result.task_id);
}

Pattern 3: Parallel Calls

Independent tasks executed in parallel.

async function executeParallel(context) {
  const tasks = [
    { type: 'structure', tool: 'gemini' },
    { type: 'dependencies', tool: 'gemini' },
    { type: 'patterns', tool: 'qwen' }
  ];

  // Start tasks in parallel
  const taskIds = tasks.map(task =>
    Bash({
      command: `ccw cli -p "Analyze ${task.type}..." --tool ${task.tool} --mode analysis`,
      run_in_background: true
    }).task_id
  );

  // Wait for all to complete
  const results = await Promise.all(
    taskIds.map(id => waitForCompletion(id))
  );

  return results;
}

Pattern 4: Fallback Chain

Automatically switch tools on failure.

async function executeWithFallback(context) {
  const tools = ['gemini', 'qwen', 'codex'];
  let result = null;

  for (const tool of tools) {
    try {
      result = await runWithTool(tool, context);
      if (result.success) break;
    } catch (error) {
      console.log(`${tool} failed, trying next...`);
    }
  }

  if (!result?.success) {
    throw new Error('All tools failed');
  }

  return result;
}

async function runWithTool(tool, context) {
  const task = Bash({
    command: `ccw cli -p "..." --tool ${tool} --mode analysis`,
    run_in_background: true,
    timeout: 600000
  });

  return await waitForCompletion(task.task_id);
}

---

Prompt Template Integration

Reference Protocol Templates

# Analysis mode - use --rule to auto-load protocol and template (appended to prompt)
ccw cli -p "
CONSTRAINTS: ...
..." --tool gemini --mode analysis --rule analysis-code-patterns

# Write mode - use --rule to auto-load protocol and template (appended to prompt)
ccw cli -p "
CONSTRAINTS: ...
..." --tool codex --mode write --rule development-feature

Dynamic Template Building

function buildPrompt(config) {
  const { purpose, task, mode, context, expected, constraints } = config;

  return `
PURPOSE: ${purpose}
TASK: ${task.map(t => `• ${t}`).join('\n')}
MODE: ${mode}
CONTEXT: ${context}
EXPECTED: ${expected}
CONSTRAINTS: ${constraints || ''}
`; // Use --rule option to auto-append protocol + template
}

---

Timeout Configuration

Recommended Timeout Values

Task Type	Timeout (ms)	Description
Quick analysis	300000	5 minutes
Standard analysis	600000	10 minutes
Deep analysis	1200000	20 minutes
Code generation	1800000	30 minutes
Complex tasks	3600000	60 minutes

Special Codex Handling

Codex requires longer timeout (recommend 3x).

const timeout = tool === 'codex' ? baseTimeout * 3 : baseTimeout;

Bash({
  command: `ccw cli -p "..." --tool ${tool} --mode write`,
  run_in_background: true,
  timeout: timeout
});

---

Error Handling

Common Errors

Error	Cause	Handler
ETIMEDOUT	Network timeout	Retry or switch tool
Exit code 1	Command execution failed	Check parameters, switch tool
Context overflow	Input context too large	Reduce input scope

Retry Strategy

async function executeWithRetry(command, maxRetries = 3) {
  let lastError = null;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const task = Bash({
        command,
        run_in_background: true,
        timeout: 600000
      });

      return await waitForCompletion(task.task_id);
    } catch (error) {
      lastError = error;
      console.log(`Attempt ${attempt} failed: ${error.message}`);

      // Exponential backoff
      if (attempt < maxRetries) {
        await sleep(Math.pow(2, attempt) * 1000);
      }
    }
  }

  throw lastError;
}

---

Best Practices

1. run_in_background Rule

Agent calls (Task):
  run_in_background: false  → Synchronous, get result immediately

CLI calls (Bash + ccw cli):
  run_in_background: true   → Asynchronous, run in background

2. Tool Selection

Analysis tasks: gemini > qwen
Generation tasks: codex > gemini > qwen
Code modification: codex > gemini

3. Session Management

• Use --resume for related tasks to maintain context
• Do not use --resume for independent tasks

4. Prompt Specification

• Always use PURPOSE/TASK/MODE/CONTEXT/EXPECTED/CONSTRAINTS structure
• Use --rule <template> to auto-append protocol + template to prompt
• Template name format: category-function (e.g., analysis-code-patterns)

5. Result Processing

• Persist important results to workDir
• Brief returns: path + summary, avoid context overflow
• JSON format convenient for downstream processing