mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: Add ccw-cli-tools skill specification with unified execution framework and configuration-driven tool selection
This commit is contained in:
catlog22
@@ -17,6 +17,8 @@ Enhanced evidence-based debugging with **documented exploration process**. Recor
|
||||
|
||||
**Core workflow**: Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
|
||||
|
||||
**Scope**: Adds temporary debug logging to observe program state; cleans up all instrumentation after resolution. Does NOT execute code injection, security testing, or modify program behavior.
|
||||
|
||||
**Key enhancements over /workflow:debug**:
|
||||
- **understanding.md**: Timeline of exploration and learning
|
||||
- **Gemini-assisted correction**: Validates and corrects hypotheses
|
||||
@@ -44,7 +46,7 @@ Explore Mode:
|
||||
├─ Locate error source in codebase
|
||||
├─ Document initial understanding in understanding.md
|
||||
├─ Generate testable hypotheses with Gemini validation
|
||||
├─ Add NDJSON logging instrumentation
|
||||
├─ Add NDJSON debug logging statements
|
||||
└─ Output: Hypothesis list + await user reproduction
|
||||
|
||||
Analyze Mode:
|
||||
@@ -216,9 +218,9 @@ Save Gemini output to `hypotheses.json`:
|
||||
}
|
||||
```
|
||||
|
||||
**Step 1.4: Add NDJSON Instrumentation**
|
||||
**Step 1.4: Add NDJSON Debug Logging**
|
||||
|
||||
For each hypothesis, add logging (same as original debug command).
|
||||
For each hypothesis, add temporary logging statements to observe program state at key execution points. Use NDJSON format for structured log parsing. These are read-only observations that do not modify program behavior.
|
||||
|
||||
**Step 1.5: Update understanding.md**
|
||||
|
||||
@@ -441,7 +443,7 @@ What we learned from this debugging session:
|
||||
|
||||
**Step 3.3: Cleanup**
|
||||
|
||||
Remove debug instrumentation (same as original command).
|
||||
Remove all temporary debug logging statements added during investigation. Verify no instrumentation code remains in production code.
|
||||
|
||||
---
|
||||
|
||||
@@ -647,7 +649,7 @@ Why is config value None during update?
|
||||
|
||||
| Feature | /workflow:debug | /workflow:debug-with-file |
|
||||
|---------|-----------------|---------------------------|
|
||||
| NDJSON logging | ✅ | ✅ |
|
||||
| NDJSON debug logging | ✅ | ✅ |
|
||||
| Hypothesis generation | Manual | Gemini-assisted |
|
||||
| Exploration documentation | ❌ | ✅ understanding.md |
|
||||
| Understanding evolution | ❌ | ✅ Timeline + corrections |
|
||||
|
||||
549
.codex/skills/ccw-cli-tools/SKILL.md
Normal file
549
.codex/skills/ccw-cli-tools/SKILL.md
Normal file
@@ -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
|
||||
@@ -917,6 +917,7 @@ export async function handleClaudeRoutes(ctx: RouteContext): Promise<boolean> {
|
||||
const userClaudePath = join(homedir(), '.claude', 'CLAUDE.md');
|
||||
const userCodexPath = join(homedir(), '.codex', 'AGENTS.md');
|
||||
const chineseRefPattern = /@.*chinese-response\.md/i;
|
||||
const chineseSectionPattern = /## 中文回复/; // For Codex direct content
|
||||
|
||||
let claudeEnabled = false;
|
||||
let codexEnabled = false;
|
||||
@@ -928,10 +929,11 @@ export async function handleClaudeRoutes(ctx: RouteContext): Promise<boolean> {
|
||||
claudeEnabled = chineseRefPattern.test(content);
|
||||
}
|
||||
|
||||
// Check if user AGENTS.md exists and contains Chinese response reference
|
||||
// Check if user AGENTS.md exists and contains Chinese response section
|
||||
// Codex uses direct content concatenation, not @ references
|
||||
if (existsSync(userCodexPath)) {
|
||||
const content = readFileSync(userCodexPath, 'utf8');
|
||||
codexEnabled = chineseRefPattern.test(content);
|
||||
codexEnabled = chineseSectionPattern.test(content);
|
||||
}
|
||||
|
||||
// Find guidelines file path - always use user-level path
|
||||
@@ -983,10 +985,6 @@ export async function handleClaudeRoutes(ctx: RouteContext): Promise<boolean> {
|
||||
const targetDir = isCodex ? join(homedir(), '.codex') : join(homedir(), '.claude');
|
||||
const targetFile = isCodex ? join(targetDir, 'AGENTS.md') : join(targetDir, 'CLAUDE.md');
|
||||
|
||||
const chineseRefLine = `- **中文回复准则**: @${guidelinesRef}`;
|
||||
const chineseRefPattern = /^- \*\*中文回复准则\*\*:.*chinese-response\.md.*$/gm;
|
||||
const chineseSectionPattern = /\n*## 中文回复\n+- \*\*中文回复准则\*\*:.*chinese-response\.md.*\n*/gm;
|
||||
|
||||
// Ensure target directory exists
|
||||
if (!existsSync(targetDir)) {
|
||||
mkdirSync(targetDir, { recursive: true });
|
||||
@@ -1001,19 +999,71 @@ export async function handleClaudeRoutes(ctx: RouteContext): Promise<boolean> {
|
||||
content = headerText;
|
||||
}
|
||||
|
||||
if (enabled) {
|
||||
// Check if reference already exists
|
||||
if (chineseRefPattern.test(content)) {
|
||||
return { success: true, message: 'Already enabled' };
|
||||
}
|
||||
if (isCodex) {
|
||||
// Codex: Direct content concatenation (does not support @ references)
|
||||
const chineseSectionPattern = /\n*## 中文回复\n[\s\S]*?(?=\n## |$)/;
|
||||
const cliToolsSectionPattern = /\n*## CLI \u5de5\u5177\u8c03\u7528\n[\s\S]*?(?=\n## |$)/;
|
||||
|
||||
// Add new section at the end of file
|
||||
const newSection = `\n## 中文回复\n\n${chineseRefLine}\n`;
|
||||
content = content.trimEnd() + '\n' + newSection;
|
||||
if (enabled) {
|
||||
// Check if section already exists
|
||||
if (chineseSectionPattern.test(content)) {
|
||||
return { success: true, message: 'Already enabled' };
|
||||
}
|
||||
|
||||
// Read chinese-response.md content
|
||||
const chineseResponseContent = readFileSync(userGuidelinesPath, 'utf8');
|
||||
|
||||
// Read cli-tools-usage.md content
|
||||
const cliToolsUsagePath = join(homedir(), '.claude', 'workflows', 'cli-tools-usage.md');
|
||||
let cliToolsUsageContent = '';
|
||||
if (existsSync(cliToolsUsagePath)) {
|
||||
cliToolsUsageContent = readFileSync(cliToolsUsagePath, 'utf8');
|
||||
}
|
||||
|
||||
// Read and format cli-tools.json
|
||||
const cliToolsJsonPath = join(homedir(), '.claude', 'cli-tools.json');
|
||||
let cliToolsJsonContent = '';
|
||||
if (existsSync(cliToolsJsonPath)) {
|
||||
const cliToolsJson = JSON.parse(readFileSync(cliToolsJsonPath, 'utf8'));
|
||||
cliToolsJsonContent = `\n### CLI Tools Configuration\n\n\`\`\`json\n${JSON.stringify(cliToolsJson, null, 2)}\n\`\`\`\n`;
|
||||
}
|
||||
|
||||
// Add Chinese response section
|
||||
let newSection = `\n## 中文回复\n\n${chineseResponseContent}\n`;
|
||||
|
||||
// Add CLI tools section if usage content exists
|
||||
if (cliToolsUsageContent) {
|
||||
newSection += `\n## CLI 工具调用\n\n${cliToolsUsageContent}\n${cliToolsJsonContent}`;
|
||||
}
|
||||
|
||||
content = content.trimEnd() + '\n' + newSection;
|
||||
} else {
|
||||
// Remove both sections
|
||||
content = content.replace(chineseSectionPattern, '\n');
|
||||
content = content.replace(cliToolsSectionPattern, '\n');
|
||||
content = content.replace(/\n{3,}/g, '\n\n').trim();
|
||||
if (content) content += '\n';
|
||||
}
|
||||
} else {
|
||||
// Remove the entire section
|
||||
content = content.replace(chineseSectionPattern, '\n').replace(/\n{3,}/g, '\n\n').trim();
|
||||
if (content) content += '\n';
|
||||
// Claude: Use @ reference (original behavior)
|
||||
const chineseRefLine = `- **中文回复准则**: @${guidelinesRef}`;
|
||||
const chineseRefPattern = /^- \*\*中文回复准则\*\*:.*chinese-response\.md.*$/gm;
|
||||
const chineseSectionPattern = /\n*## 中文回复\n+- \*\*中文回复准则\*\*:.*chinese-response\.md.*\n*/gm;
|
||||
|
||||
if (enabled) {
|
||||
// Check if reference already exists
|
||||
if (chineseRefPattern.test(content)) {
|
||||
return { success: true, message: 'Already enabled' };
|
||||
}
|
||||
|
||||
// Add new section at the end of file
|
||||
const newSection = `\n## 中文回复\n\n${chineseRefLine}\n`;
|
||||
content = content.trimEnd() + '\n' + newSection;
|
||||
} else {
|
||||
// Remove the entire section
|
||||
content = content.replace(chineseSectionPattern, '\n').replace(/\n{3,}/g, '\n\n').trim();
|
||||
if (content) content += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
writeFileSync(targetFile, content, 'utf8');
|
||||
|
||||
Reference in New Issue
Block a user