feat: Add ccw-cli-tools skill specification with unified execution framework and configuration-driven tool selection

2026-02-10 02:24:35 +08:00 · 2026-01-28 22:55:36 +08:00
parent a5d9e8ca87
commit 0a07138c27
3 changed files with 623 additions and 22 deletions
--- a/.codex/skills/ccw-cli-tools/SKILL.md
+++ b/.codex/skills/ccw-cli-tools/SKILL.md
@@ -0,0 +1,549 @@
+---
+name: ccw-cli-tools
+description: CLI tools execution specification (gemini/claude/codex/qwen/opencode) with unified prompt template, mode options, and auto-invoke triggers for code analysis and implementation tasks. Supports configurable CLI endpoints for analysis, write, and review modes.
+version: 1.0.0
+---
+
+# 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, ALWAYS**:
+
+1. 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.
+
+## Process Flow
+
+```
+┌─ USER REQUEST
+│
+├─ STEP 1: Read Configuration
+│  └─ 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**: Always read this file first before making tool selections or recommendations.
+
+### Reading Configuration
+
+```bash
+# Read the configuration file
+cat ~/.claude/cli-tools.json
+
+# Or use Read tool
+Read(file_path="~/.claude/cli-tools.json")
+```
+
+The configuration file defines all available tools with their settings.
+
+### 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. Always read `~/.claude/cli-tools.json` for current configuration.
+
+### 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
+
+## 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)**: Read `~/.claude/cli-tools.json` to get current configuration
+
+```bash
+# Always start with this
+Read(file_path="~/.claude/cli-tools.json")
+```
+
+Then proceed with selection:
+
+1. **Parse task intent** → Extract required capabilities
+2. **Load configuration** → Parse enabled tools with tags from JSON
+3. **Match tags** → Filter tools supporting required capabilities
+4. **Select tool** → Choose by priority (explicit > tag-match > default)
+5. **Select model** → Use primaryModel, fallback to secondaryModel
+
+### Selection Decision Tree
+
+```
+0. 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):
+
+1. Check `secondaryModel` for same tool (use `secondaryModel` from config)
+2. Try next enabled tool with matching tags (scan config for enabled tools)
+3. 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