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: ```bash 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 ```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**: 1. Add `--includeDirs` parameter 2. 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