ccs-delegation

Original source / Raw SKILL.md

---
name: ccs-delegation
description: >-
  Auto-activate CCS CLI delegation for deterministic tasks. Parses user input,
  auto-selects optimal profile (glm/kimi/custom) from ~/.ccs/config.json,
  enhances prompts with context, executes via `ccs {profile} -p "task"` or
  `ccs {profile}:continue`, and reports results. Triggers on "use ccs [task]"
  patterns, typo/test/refactor keywords. Excludes complex architecture,
  security-critical code, performance optimization, breaking changes.
version: 3.0.0
user-invocable: true
---

# CCS Delegation

Delegate deterministic tasks to cost-optimized models via CCS CLI.

## Core Concept

Execute tasks via alternative models using:
- **Initial delegation**: `ccs {profile} -p "task"`
- **Session continuation**: `ccs {profile}:continue -p "follow-up"`

**Profile Selection:**
- Auto-select from `~/.ccs/config.json` via task analysis
- Profiles: glm (cost-optimized), kimi (long-context/reasoning), custom profiles
- Override: `--{profile}` flag forces specific profile

## User Invocation Patterns

Users trigger delegation naturally:
- "use ccs [task]" - Auto-select best profile
- "use ccs --glm [task]" - Force GLM profile
- "use ccs --kimi [task]" - Force Kimi profile
- "use ccs:continue [task]" - Continue last session

**Examples:**
- "use ccs to fix typos in README.md"
- "use ccs to analyze the entire architecture"
- "use ccs --glm to add unit tests"
- "use ccs:continue to commit the changes"

## Agent Response Protocol

**For `/ccs [task]`:**

1. **Parse override flag**
   - Scan task for pattern: `--(\w+)`
   - If match: `profile = match[1]`, remove flag from task, skip to step 5
   - If no match: continue to step 2

2. **Discover profiles**
   - Read `~/.ccs/config.json` using Read tool
   - Extract `Object.keys(config.profiles)` → `availableProfiles[]`
   - If file missing → Error: "CCS not configured. Run: ccs doctor"
   - If empty → Error: "No profiles in config.json"

3. **Analyze task requirements**
   - Scan task for keywords:
     - `/(think|analyze|reason|debug|investigate|evaluate)/i` → `needsReasoning = true`
     - `/(architecture|entire|all files|codebase|analyze all)/i` → `needsLongContext = true`
     - `/(typo|test|refactor|update|fix)/i` → `preferCostOptimized = true`

4. **Select profile**
   - For each profile in `availableProfiles`: classify by name pattern (see Profile Characteristic Inference table)
   - If `needsReasoning`: filter profiles where `reasoning=true` → prefer kimi
   - Else if `needsLongContext`: filter profiles where `context=long` → prefer kimi
   - Else: filter profiles where `cost=low` → prefer glm
   - `selectedProfile = filteredProfiles[0]`
   - If `filteredProfiles.length === 0`: fallback to `glm` if exists, else first available
   - If no profiles: Error

5. **Enhance prompt**
   - If task mentions files: gather context using Read tool
   - Add: file paths, current implementation, expected behavior, success criteria
   - Preserve slash commands at task start (e.g., `/cook`, `/commit`)

6. **Execute delegation**
   - Run: `ccs {selectedProfile} -p "$enhancedPrompt"` via Bash tool

7. **Report results**
   - Log: "Selected {profile} (reason: {reasoning/long-context/cost-optimized})"
   - Report: Cost (USD), Duration (sec), Session ID, Exit code

**For `/ccs:continue [follow-up]`:**

1. **Detect profile**
   - Read `~/.ccs/delegation-sessions.json` using Read tool
   - Find most recent session (latest timestamp)
   - Extract profile name from session data
   - If no sessions → Error: "No previous delegation. Use /ccs first"

2. **Parse override flag**
   - Scan follow-up for pattern: `--(\w+)`
   - If match: `profile = match[1]`, remove flag from follow-up, log profile switch
   - If no match: use detected profile from step 1

3. **Enhance prompt**
   - Review previous work (check what was accomplished)
   - Add: previous context, incomplete tasks, validation criteria
   - Preserve slash commands at start

4. **Execute continuation**
   - Run: `ccs {profile}:continue -p "$enhancedPrompt"` via Bash tool

5. **Report results**
   - Report: Profile, Session #, Incremental cost, Total cost, Duration, Exit code

## Decision Framework

**Delegate when:**
- Simple refactoring, tests, typos, documentation
- Deterministic, well-defined scope
- No discussion/decisions needed

**Keep in main when:**
- Architecture/design decisions
- Security-critical code
- Complex debugging requiring investigation
- Performance optimization
- Breaking changes/migrations

## Profile Selection Logic

**Task Analysis Keywords** (scan task string with regex):

| Pattern | Variable | Example |
|---------|----------|---------|
| `/(think\|analyze\|reason\|debug\|investigate\|evaluate)/i` | `needsReasoning = true` | "think about caching" |
| `/(architecture\|entire\|all files\|codebase\|analyze all)/i` | `needsLongContext = true` | "analyze all files" |
| `/(typo\|test\|refactor\|update\|fix)/i` | `preferCostOptimized = true` | "fix typo in README" |

**Profile Characteristic Inference** (classify by name pattern):

| Profile Pattern | Cost | Context | Reasoning |
|----------------|------|---------|-----------|
| `/^glm/i` | low | standard | false |
| `/^kimi/i` | medium | long | true |
| `/^claude/i` | high | standard | false |
| others | low | standard | false |

**Selection Algorithm** (apply filters sequentially):

```
profiles = Object.keys(config.profiles)
classified = profiles.map(p => ({name: p, ...inferCharacteristics(p)}))

if (needsReasoning):
  filtered = classified.filter(p => p.reasoning === true).sort(['kimi'])
else if (needsLongContext):
  filtered = classified.filter(p => p.context === 'long').sort(['kimi'])
else:
  filtered = classified.filter(p => p.cost === 'low').sort(['glm', ...])

selected = filtered[0] || profiles.find(p => p === 'glm') || profiles[0]
if (!selected): throw Error("No profiles configured")

log("Selected {selected} (reason: {reasoning|long-context|cost-optimized})")
```

**Override Logic**:
- Parse task for `/--(\w+)/`. If match: `profile = match[1]`, remove from task, skip selection

## Example Delegation Tasks

**Good candidates:**
- "/ccs add unit tests for UserService using Jest"
  → Auto-selects: glm (simple task)
- "/ccs analyze entire architecture in src/"
  → Auto-selects: kimi (long-context)
- "/ccs think about the best database schema design"
  → Auto-selects: kimi (reasoning)
- "/ccs --glm refactor parseConfig to use destructuring"
  → Forces: glm (override)

**Bad candidates (keep in main):**
- "implement OAuth" (too complex, needs design)
- "improve performance" (requires profiling)
- "fix the bug" (needs investigation)

## Execution

**Commands:**
- `/ccs "task"` - Intelligent delegation (auto-select profile)
- `/ccs --{profile} "task"` - Force specific profile
- `/ccs:continue "follow-up"` - Continue last session (auto-detect profile)
- `/ccs:continue --{profile} "follow-up"` - Continue with profile switch

**Agent via Bash:**
- Auto: `ccs {auto-selected} -p "task"`
- Continue: `ccs {detected}:continue -p "follow-up"`

## References

Template: `CLAUDE.md.template` - Copy to user's CLAUDE.md for auto-delegation config
Troubleshooting: `references/troubleshooting.md`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/troubleshooting.md

```markdown
# Troubleshooting

AI-oriented error resolution guide for CCS delegation issues.

**Structure**: Quick Reference → Error Catalog → Common Resolutions → Diagnostics → Recovery

**Cross-references**:
- Technical details: `headless-workflow.md`
- Decision framework: `delegation-guidelines.md`

## Quick Reference

**Profile/Config Issues:**
- E-001: "Profile 'X' not configured" → `ccs doctor`
- E-002: "Invalid API key" (401) → Check `~/.ccs/{profile}.settings.json`
- E-003: "Settings file not found" → `ccs doctor` to configure
- E-004: JSON parse error (settings) → Validate with `jq . ~/.ccs/{profile}.settings.json`

**Delegation Issues:**
- D-001: "No previous session" → Run `ccs {profile} -p "task"` first
- D-002: "Missing prompt" → Syntax: `ccs {profile} -p "prompt"`
- D-003: "No profile specified" → Syntax: `ccs <profile> -p "task"`
- D-005: File not found → Verify CWD (delegation runs in current directory)

**Session Issues:**
- S-001: Session corrupted → `rm ~/.ccs/delegation-sessions.json`
- S-002: Session expired → Start new: `ccs {profile} -p "task"`

**Network Issues:**
- N-001: Connection timeout → Check internet/endpoint → Retry
- N-002: Rate limit (429) → Wait 60s → Retry

**CLI Issues:**
- C-001: Claude CLI not found → Install from code.claude.com
- C-002: Outdated version → Update: `ccs sync` or `ccs update`

**See Error Catalog below for detailed troubleshooting.**

## Error Catalog

### Environment/Config Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| E-001 | Profile 'X' not configured | Missing settings file | `ccs doctor` → configure manually |
| E-002 | Invalid API key (401) | Token expired/invalid | Verify token in settings.json → regenerate if needed |
| E-003 | Settings file not found | File doesn't exist | `ccs doctor` → shows missing profiles |
| E-004 | JSON parse error (settings) | Malformed JSON | Validate: `jq . ~/.ccs/{profile}.settings.json` |

**Examples:**
```bash
[X] ccs glm -p "task"  # E-001: Profile not configured
[OK] ccs doctor        # Shows: glm.settings.json missing
```

### Delegation Execution Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| D-001 | No previous session | Using :continue without init | Run `ccs {profile} -p "init"` first |
| D-002 | Missing prompt after -p | No argument provided | Quote prompt: `ccs {profile} -p "text"` |
| D-003 | No profile specified | Missing profile name | Syntax: `ccs <profile> -p "task"` |
| D-004 | Invalid profile name | Profile doesn't exist | Check: `ccs doctor` for available profiles |
| D-005 | File not found | CWD mismatch | Verify: delegation runs in current directory |

**Examples:**
```bash
[X] ccs glm:continue -p "task"     # D-001: No session
[OK] ccs glm -p "task"             # Creates session
[OK] ccs glm:continue -p "more"    # Uses session
```

### Session Management Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| S-001 | Session file corrupted | Malformed JSON | `rm ~/.ccs/delegation-sessions.json` → fresh start |
| S-002 | Session expired | >30 days old | Start new: `ccs {profile} -p "task"` |
| S-003 | Session ID mismatch | ID not found | Check: `jq '.{profile}' ~/.ccs/delegation-sessions.json` |
| S-004 | Cost aggregation error | Calculation failure | Reset session or ignore (doesn't affect execution) |

### Network/API Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| N-001 | Connection timeout | Network/API unreachable | Check: internet, endpoint, firewall → Retry |
| N-002 | Rate limiting (429) | Too many requests | Wait 60s → Retry |
| N-003 | API endpoint unreachable | Wrong URL in settings | Verify ANTHROPIC_BASE_URL in settings.json |
| N-004 | SSL/TLS error | Certificate issue | Check system certs, firewall SSL inspection |

### File Operation Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| F-001 | File not found during delegation | Path doesn't exist in CWD | Verify: `ls <file>` from current directory |
| F-002 | Permission denied (write) | Insufficient permissions | Check: `ls -la` directory permissions |
| F-003 | Relative path failure | Path resolution issue | Use absolute paths in prompts if needed |
| F-004 | Workspace confusion (monorepo) | Wrong package targeted | Specify workspace: "in packages/{name}, {task}" |

**Example:**
```bash
# Delegation runs in CWD where command executed
ccs glm -p "refactor src/auth.js"
# Verify: ls src/auth.js  # Must exist in current directory
```

### Claude CLI Compatibility Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| C-001 | Claude CLI not found | Not installed | Install from code.claude.com |
| C-002 | Outdated CLI version | Old version | Update: `ccs sync` or `ccs update` |
| C-003 | stream-json not supported | Version < required | Upgrade CLI: check `claude --version` |
| C-004 | Permission mode unsupported | Old CLI version | Upgrade to support --permission-mode |

**Check version:**
```bash
claude --version  # Need recent version with --output-format stream-json
```

### Timeout/Resource Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| T-001 | Execution timeout (10 min) | Task too complex/slow | Simplify task or split into smaller tasks |
| T-002 | Memory limit exceeded | Large file processing | Reduce scope, process in batches |
| T-003 | Process killed (SIGTERM) | External termination | Check system resources, retry |

### Output Format Errors

| Code | Pattern | Root Cause | Resolution |
|------|---------|------------|------------|
| O-001 | JSON parse error (exit 1) | Non-stream-JSON output | Verify: `claude -p "test" --output-format stream-json` |
| O-002 | Malformed JSONL | Corrupted stream | Enable debug: `export CCS_DEBUG=1` → check logs |
| O-003 | Missing session_id | Incomplete response | Check CLI version, retry delegation |
| O-004 | Type mismatch in response | Unexpected data type | Enable debug mode, report issue |

## Common Resolution Patterns

**Profile Validation:**
```bash
ccs doctor                          # Check all profiles
cat ~/.ccs/{profile}.settings.json  # Verify settings
ccs {profile} "test" 2>&1           # Test execution
```

**Session Management:**
```bash
jq . ~/.ccs/delegation-sessions.json              # View all sessions
jq '.{profile}' ~/.ccs/delegation-sessions.json   # Check specific profile
rm ~/.ccs/delegation-sessions.json                # Reset (loses all sessions)
```

**Debug Mode:**
```bash
export CCS_DEBUG=1
ccs {profile} -p "task" 2>&1 | tee debug.log  # Capture full output
```

## Diagnostic Toolkit

**Profile diagnostics:**
````bash
ccs doctor        # All profiles status
ccs --version     # CCS version + delegation status
claude --version  # CLI version (check stream-json support)
```

**Session inspection:**
```bash
jq . ~/.ccs/delegation-sessions.json                    # All sessions
jq '.glm.sessionId' ~/.ccs/delegation-sessions.json     # GLM session ID
jq '.glm.totalCost' ~/.ccs/delegation-sessions.json     # Total cost
```

**Test delegation flow:**
```bash
# 1. Simple task
ccs glm -p "create test.txt with 'hello'"

# 2. Verify session
jq '.glm.sessionId' ~/.ccs/delegation-sessions.json

# 3. Continue
ccs glm:continue -p "append 'world' to test.txt"

# 4. Check aggregation
jq '.glm.turns' ~/.ccs/delegation-sessions.json
```

## Emergency Recovery

**Reset session state:**
```bash
rm ~/.ccs/delegation-sessions.json  # Fresh start (loses all sessions)
```

**Interactive mode (no -p flag):**
```bash
ccs {profile}  # Opens interactive session
```

```