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:
  bash
```
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

bash

# 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

bash

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

bash

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

bash

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

bash

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)

bash

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)

bash

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

bash

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)

bash

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

bash

# 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

ccw-cli-tools

NPX Install

Tags

SKILL.md Content

CLI Tools - Unified Execution Framework

Initialization (Required First Step)

Process Flow

Configuration Reference

Configuration File Location

Reading Configuration

Configuration Structure

Expected Tools (Reference Only)

Configuration Fields

Universal Prompt Template

Field Specifications

PURPOSE (Goal Definition)

TASK (Action Steps)

MODE (Permission Level)

CONTEXT (File Scope + Memory)

EXPECTED (Output Specification)

CONSTRAINTS (Domain Boundaries)

CLI Execution Modes

MODE: analysis

MODE: write

MODE: review

Command Structure

Basic Command

Command Options

Advanced Directory Configuration

Working Directory (--cd)

Include Directories (--includeDirs)

Session Resume

Available Rule Templates

Template System

Universal Templates

Analysis Templates

Planning Templates

Development Templates

Task-Type Specific Examples

Example 1: Security Analysis (Read-Only)

Example 2: Feature Implementation (Write Mode)

Example 3: Bug Root Cause Analysis

Example 4: Code Review (Codex Review Mode)

Tool Selection Strategy

Selection Algorithm

Selection Decision Tree

Common Tag Routing

Fallback Chain

Permission Framework

Auto-Invoke Triggers

Execution Principles for Auto-Invoke

Best Practices

Core Principles

Workflow Principles

Planning Checklist

Integration with CLAUDE.md Instructions

Working Directory (
`--cd`
)

Include Directories (
`--includeDirs`
)