Ccw CLI Tools

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:

1. 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")

2. 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)

3. 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:

Expected Tools (Reference Only)

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

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

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:

1. Add --includeDirs parameter
2. 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