CLI Tools - Unified Execution Framework

Purpose: Structured CLI tool usage with configuration-driven tool selection, unified prompt templates, and quality-gated execution.

Configuration: ~/.claude/cli-tools.json (Global, always read at initialization)

Initialization (Required First Step)

Before any tool selection or recommendation:

Check if configuration exists in memory:

• If configuration is already in conversation memory → Use it directly

• If NOT in memory → Read the configuration file: Read(file_path="~/.claude/cli-tools.json")

Parse the JSON to understand:

• Available tools and their enabled status

• Each tool's primaryModel and secondaryModel

• Tags defined for tag-based routing

• Tool types (builtin, cli-wrapper, api-endpoint)

Use configuration throughout the selection process

Why: Tools, models, and tags may change. Configuration file is the single source of truth. Optimization: Reuse in-memory configuration to avoid redundant file reads.

Process Flow

┌─ USER REQUEST │ ├─ STEP 1: Load Configuration │ ├─ Check if configuration exists in conversation memory │ └─ If NOT in memory → Read(file_path="~/.claude/cli-tools.json") │ ├─ STEP 2: Understand User Intent │ ├─ Parse task type (analysis, implementation, security, etc.) │ ├─ Extract required capabilities (tags) │ └─ Identify scope (files, modules) │ ├─ STEP 3: Select Tool (based on config) │ ├─ Explicit --tool specified? │ │ YES → Validate in config → Use it │ │ NO → Match tags with enabled tools → Select best match │ │ → No match → Use first enabled tool (default) │ └─ Get primaryModel from config │ ├─ STEP 4: Build Prompt │ └─ Use 6-field template: PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS │ ├─ STEP 5: Select Rule Template │ ├─ Determine rule from task type │ └─ Pass via --rule parameter │ ├─ STEP 6: Execute CLI Command │ └─ ccw cli -p "<PROMPT>" --tool <tool> --mode <mode> --rule <rule> │ └─ STEP 7: Handle Results ├─ On success → Deliver output to user └─ On failure → Check secondaryModel or fallback tool

Configuration Reference

Configuration File Location

Path: ~/.claude/cli-tools.json (Global configuration)

IMPORTANT: Check conversation memory first. Only read file if configuration is not in memory.

Reading Configuration

Priority: Check conversation memory first

Loading Options:

• Option 1 (Preferred): Use in-memory configuration if already loaded in conversation

• Option 2 (Fallback): Read from file when not in memory

Read configuration file

cat ~/.claude/cli-tools.json

The configuration defines all available tools with their enabled status, models, and tags.

Configuration Structure

The JSON file contains a tools object where each tool has these fields:

Field Type Description Example

enabled

boolean Tool availability status true or false

primaryModel

string Default model for execution "gemini-2.5-pro"

secondaryModel

string Fallback model on primary failure "gemini-2.5-flash"

tags

array Capability tags for routing ["分析", "Debug"]

type

string Tool type "builtin" , "cli-wrapper" , "api-endpoint"

Expected Tools (Reference Only)

Typical tools found in configuration (actual availability determined by reading the file):

Tool Typical Type Common Use

gemini

builtin Analysis, Debug (分析, Debug tags)

qwen

builtin General coding

codex

builtin Code review, implementation

claude

builtin General tasks

opencode

builtin Open-source model fallback

Note: Tool availability, models, and tags may differ. Use in-memory configuration or read ~/.claude/cli-tools.json if not cached.

Configuration Fields

• enabled : Tool availability (boolean)

• primaryModel : Default model for execution

• secondaryModel : Fallback model on primary failure

• tags : Capability tags for routing (分析, Debug, implementation, etc.)

• type : Tool type (builtin, cli-wrapper, api-endpoint)

Universal Prompt Template

Structure: Every CLI command follows this 6-field template

ccw cli -p "PURPOSE: [goal] + [why] + [success criteria] + [scope] TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action] MODE: [analysis|write|review] CONTEXT: @[file patterns] | Memory: [session/tech/module context] EXPECTED: [deliverable format] + [quality criteria] + [structure requirements] CONSTRAINTS: [domain constraints]" --tool <tool-id> --mode <mode> --rule <template>

Field Specifications

PURPOSE (Goal Definition)

What: Clear objective + motivation + success criteria + scope boundary

Components:

• What: Specific task goal

• Why: Business/technical motivation

• Success: Measurable success criteria

• Scope: Bounded context/files

Example - Good:

PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module to pass security audit; success = all critical/high issues documented with remediation; scope = src/auth/** only

Example - Bad:

PURPOSE: Analyze code

TASK (Action Steps)

What: Specific, actionable steps with clear verbs and targets

Format: Bullet list with concrete actions

Example - Good:

TASK: • Scan for SQL injection in query builders • Check XSS in template rendering • Verify CSRF token validation

Example - Bad:

TASK: Review code and find issues

MODE (Permission Level)

Options:

• analysis

• Read-only, safe for auto-execution

• write

• Create/Modify/Delete files, full operations

• review

• Git-aware code review (codex only)

Rules:

• Always specify explicitly

• Default to analysis for read-only tasks

• Require explicit --mode write for file modifications

• Use --mode review with --tool codex for git-aware review

CONTEXT (File Scope + Memory)

Format: CONTEXT: @[file patterns] | Memory: [memory context]

File Patterns:

• @**/*

• All files (default)

• @src/**/*.ts

• Specific pattern

• @../shared/**/*

• Parent/sibling (requires --includeDirs )

Memory Context (when building on previous work):

Memory: Building on auth refactoring (commit abc123), using JWT for sessions Memory: Integration with auth module, shared error patterns from @shared/utils/errors.ts

EXPECTED (Output Specification)

What: Output format + quality criteria + structure requirements

Example - Good:

EXPECTED: Markdown report with: severity levels (Critical/High/Medium/Low), file:line references, remediation code snippets, priority ranking

Example - Bad:

EXPECTED: Report

CONSTRAINTS (Domain Boundaries)

What: Scope limits, special requirements, focus areas

Example - Good:

CONSTRAINTS: Focus on authentication | Ignore test files | No breaking changes

Example - Bad:

CONSTRAINTS: (missing or too vague)

CLI Execution Modes

MODE: analysis

• Permission: Read-only

• Use For: Code review, architecture analysis, pattern discovery, exploration

• Safe: Yes - can auto-execute

• Default: When not specified

MODE: write

• Permission: Create/Modify/Delete files

• Use For: Feature implementation, bug fixes, documentation, code creation

• Safe: No - requires explicit --mode write

• Requirements: Must be explicitly requested by user

MODE: review

• Permission: Read-only (git-aware review output)

• Use For: Code review of uncommitted changes, branch diffs, specific commits

• Tool Support: codex only (others treat as analysis)

• Constraint: Target flags (--uncommitted , --base , --commit ) and prompt are mutually exclusive

Command Structure

Basic Command

ccw cli -p "<PROMPT>" --tool <tool-id> --mode <analysis|write|review>

Command Options

Option Description Example

--tool <tool>

Tool from config --tool gemini

--mode <mode>

REQUIRED: analysis/write/review --mode analysis

--model <model>

Model override --model gemini-2.5-flash

--cd <path>

Working directory --cd src/auth

--includeDirs <dirs>

Additional directories --includeDirs ../shared,../types

--rule <template>

Auto-load template --rule analysis-review-architecture

--resume [id]

Resume session --resume or --resume <id>

Advanced Directory Configuration

Working Directory (--cd )

When using --cd :

• @**/* = Files within working directory tree only

• Cannot reference parent/sibling without --includeDirs

• Reduces token usage by scoping context

Include Directories (--includeDirs )

Two-step requirement for external files:

• Add --includeDirs parameter

• Reference in CONTEXT with @ patterns

Single directory

ccw cli -p "CONTEXT: @/* @../shared//*"
--tool gemini --mode analysis
--cd src/auth --includeDirs ../shared

Multiple directories

ccw cli -p "..."
--tool gemini --mode analysis
--cd src/auth --includeDirs ../shared,../types,../utils

Session Resume

When to Use:

• Multi-round planning (analysis → planning → implementation)

• Multi-model collaboration (tool A → tool B on same topic)

• Topic continuity (building on previous findings)

Usage:

ccw cli -p "Continue analyzing" --tool <tool-id> --mode analysis --resume # Resume last ccw cli -p "Fix issues found" --tool <tool-id> --mode write --resume <id> # Resume specific ccw cli -p "Merge findings" --tool <tool-id> --mode analysis --resume <id1>,<id2> # Merge sessions

Available Rule Templates

Template System

Use --rule <template-name> to auto-load protocol + template appended to prompt

Universal Templates

• universal-rigorous-style

• Precise tasks (default)

• universal-creative-style

• Exploratory tasks

Analysis Templates

• analysis-trace-code-execution

• Execution tracing

• analysis-diagnose-bug-root-cause

• Bug diagnosis

• analysis-analyze-code-patterns

• Code patterns

• analysis-analyze-technical-document

• Document analysis

• analysis-review-architecture

• Architecture review

• analysis-review-code-quality

• Code review

• analysis-analyze-performance

• Performance analysis

• analysis-assess-security-risks

• Security assessment

Planning Templates

• planning-plan-architecture-design

• Architecture design

• planning-breakdown-task-steps

• Task breakdown

• planning-design-component-spec

• Component design

• planning-plan-migration-strategy

• Migration strategy

Development Templates

• development-implement-feature

• Feature implementation

• development-refactor-codebase

• Code refactoring

• development-generate-tests

• Test generation

• development-implement-component-ui

• UI component

• development-debug-runtime-issues

• Runtime debugging

Task-Type Specific Examples

Example 1: Security Analysis (Read-Only)

ccw cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure MODE: analysis CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk CONSTRAINTS: Focus on authentication | Ignore test files " --tool gemini --mode analysis --rule analysis-assess-security-risks --cd src/auth

Example 2: Feature Implementation (Write Mode)

ccw cli -p "PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services MODE: write CONTEXT: @src/middleware//* @src/config//* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide CONSTRAINTS: Follow existing middleware patterns | No breaking changes " --tool gemini --mode write --rule development-implement-feature

Example 3: Bug Root Cause Analysis

ccw cli -p "PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility MODE: analysis CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps CONSTRAINTS: Focus on resource cleanup " --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause --cd src

Example 4: Code Review (Codex Review Mode)

Option 1: Custom focus (reviews uncommitted by default)

ccw cli -p "Focus on security vulnerabilities and error handling" --tool codex --mode review

Option 2: Target flag only (no prompt with target flags)

ccw cli --tool codex --mode review --uncommitted ccw cli --tool codex --mode review --base main ccw cli --tool codex --mode review --commit abc123

Tool Selection Strategy

Selection Algorithm

STEP 0 (REQUIRED): Load configuration (memory-first strategy)

Check if configuration exists in conversation memory

If YES → Use in-memory configuration

If NO → Read(file_path="~/.claude/cli-tools.json")

Then proceed with selection:

• Parse task intent → Extract required capabilities

• Load configuration → Parse enabled tools with tags from JSON

• Match tags → Filter tools supporting required capabilities

• Select tool → Choose by priority (explicit > tag-match > default)

• Select model → Use primaryModel, fallback to secondaryModel

Selection Decision Tree

0. LOAD CONFIGURATION (memory-first) ├─ In memory? → Use it └─ Not in memory? → Read ~/.claude/cli-tools.json ↓
1. Explicit --tool specified? YES → Validate tool is enabled in config → Use it NO → Proceed to tag-based selection ├─ Extract task tags (security, analysis, implementation, etc.) │ ├─ Find tools with matching tags │ │ ├─ Multiple matches? Use first enabled │ │ └─ Single match? Use it │ └─ No tag match? Use default tool │ └─ Default: Use first enabled tool in config

Common Tag Routing

Note: Match task type to tags defined in ~/.claude/cli-tools.json

Task Type Common Tags to Match

Security audit 分析 , analysis , security

Bug diagnosis Debug , 分析 , analysis

Implementation implementation , (any enabled tool)

Testing testing , (any enabled tool)

Refactoring refactoring , (any enabled tool)

Documentation documentation , (any enabled tool)

Selection Logic: Find tools where tags array contains matching keywords, otherwise use first enabled tool.

Fallback Chain

When primary tool fails (based on ~/.claude/cli-tools.json configuration):

• Check secondaryModel for same tool (use secondaryModel from config)

• Try next enabled tool with matching tags (scan config for enabled tools)

• Fall back to default enabled tool (first enabled tool in config)

Example Fallback:

Tool1: primaryModel fails ↓ Try Tool1: secondaryModel ↓ (if fails) Try Tool2: primaryModel (next enabled with matching tags) ↓ (if fails) Try default: first enabled tool

Permission Framework

Single-Use Authorization: Each execution requires explicit user instruction. Previous authorization does NOT carry over.

Mode Hierarchy:

• analysis : Read-only, safe for auto-execution

• write : Create/Modify/Delete files - requires explicit --mode write

• review : Git-aware code review (codex only) - requires explicit --mode review

• Exception: User provides clear instructions like "modify", "create", "implement"

Auto-Invoke Triggers

Proactive CLI invocation - Auto-invoke ccw cli when encountering these scenarios:

Trigger Suggested Rule When

Self-repair fails analysis-diagnose-bug-root-cause

After 1+ failed fix attempts

Ambiguous requirements planning-breakdown-task-steps

Task description lacks clarity

Architecture decisions planning-plan-architecture-design

Complex feature needs design

Pattern uncertainty analysis-analyze-code-patterns

Unsure of existing conventions

Critical code paths analysis-assess-security-risks

Security/performance sensitive

Execution Principles for Auto-Invoke

• Default mode: --mode analysis (read-only, safe)

• No confirmation needed: Invoke proactively when triggers match

• Wait for results: Complete analysis before next action

• Tool selection: Use context-appropriate tool or fallback chain

• Rule flexibility: Suggested rules are guidelines, adapt as needed

Best Practices

Core Principles

• Configuration-driven - All tool selection from cli-tools.json

• Tag-based routing - Match task requirements to tool capabilities

• Use tools early and often - Tools are faster and more thorough than manual analysis

• Unified CLI - Always use ccw cli -p for consistent parameter handling

• Default to analysis - Omit --mode for read-only, explicitly use --mode write for modifications

• Use --rule for templates - Auto-loads protocol + template appended to prompt

• Write protection - Require EXPLICIT --mode write for file operations

Workflow Principles

• Use unified interface - Always ccw cli -p format

• Always include template - Use --rule <template-name> to load templates

• Be specific - Clear PURPOSE, TASK, EXPECTED fields

• Include constraints - File patterns, scope in CONSTRAINTS

• Leverage memory context - When building on previous work

• Discover patterns first - Use rg/MCP before CLI execution

• Default to full context - Use @**/* unless specific files needed

Planning Checklist

• Purpose defined - Clear goal and intent

• Mode selected - --mode analysis|write|review

• Context gathered - File references + memory (default @**/* )

• Directory navigation - --cd and/or --includeDirs if needed

• Tool selected - Explicit --tool or tag-based auto-selection

• Rule template - --rule <template-name> loads template

• Constraints - Domain constraints in CONSTRAINTS field

Integration with CLAUDE.md Instructions

From global CLAUDE.md:

• Always use run_in_background: false for Task tool agent calls

• Default: Use Bash run_in_background: true for CLI calls

• After CLI call: Stop output immediately, wait for hook callback

• Wait for results: MUST wait for CLI analysis before taking write actions

• Value every call: Never waste analysis results, aggregate before proposing solutions

From cli-tools-usage.md:

• Strict cli-tools.json configuration adherence

• Configuration-driven tool selection

• Template system with --rule auto-loading

• Permission framework with single-use authorization

• Auto-invoke triggers for common failure scenarios