mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 02:11:28 +00:00
feat(delegation): Enhance CCS delegation with auto-activation and refined workflow
This commit refactors the CCS delegation mechanism to introduce auto-activation
for eligible tasks and clarifies the delegation workflow.
Key changes include:
- Removal of the dedicated `ccs-delegator` agent, as its functionality is
now integrated and managed by the `ccs-delegation` skill.
- `allowed-tools` declarations have been removed from `ccs:glm`, `ccs:kimi`,
and their `continue` commands, streamlining tool management under the skill.
- Introduction of `CLAUDE.md.template` for `ccs-delegation` to standardize
auto-delegation configuration.
- Significant updates to the `ccs-delegation` skill (`SKILL.md`),
including:
- Auto-activation based on task patterns (e.g., "fix typos", "add tests").
- Defined user invocation patterns for explicit delegation (e.g., "use ccs glm").
- Agent response protocol for validating, enhancing, and executing delegated tasks.
- Clearer decision framework and examples for delegation eligibility.
- Deletion of `references/README.md` and `references/delegation-guidelines.md`
as their content is now integrated or no longer relevant.
- Renaming `references/headless-workflow.md` to `docs/headless-workflow.md`
to better reflect its documentation nature.
- Modification of `references/troubleshooting.md` to align with the new structure.
These changes aim to make the delegation process more autonomous, user-friendly,
and robust by centralizing control within the `ccs-delegation` skill and
improving documentation organization.
This commit is contained in:
kaitranntt
@@ -1,117 +0,0 @@
|
||||
---
|
||||
name: ccs-delegator
|
||||
description: Execute delegated tasks in isolated GLM/Kimi sessions via headless mode. Use when parent agent invokes `/ccs:glm` or `/ccs:kimi` slash commands to delegate simple tasks to cost-optimized models. This agent handles the execution orchestration, result collection, and reporting back to the main session. Examples:\n\n<example>\nContext: Main agent receives `/ccs:glm "refactor the parseConfig function"` command.\nparent_agent: "Delegating refactoring task to GLM-4.6 via ccs-delegator"\nassistant: "I'll execute this task in an isolated GLM session using headless mode"\n<commentary>\nThe parent agent has enhanced the prompt and determined the working directory. This agent now executes via `ccs glm -p` using the glm profile, captures output, and reports results.\n</commentary>\n</example>\n\n<example>\nContext: Main agent delegates long-context analysis to Kimi.\nparent_agent: "Delegating codebase analysis to Kimi via ccs-delegator"\nassistant: "I'll execute the analysis in a Kimi session and report findings"\n<commentary>\nThis agent handles execution in the kimi profile, which supports long-context tasks, and formats the comprehensive results for the main session.\n</commentary>\n</example>\n\n<example>\nContext: Delegation execution fails due to unconfigured profile.\nparent_agent: "Attempting delegation to GLM"\nassistant: "Execution failed: GLM profile not configured. Reporting error to main agent."\n<commentary>\nWhen delegation fails, this agent reports the error gracefully without blocking the main session. The main agent can then choose to retry or execute directly.\n</commentary>\n</example>
|
||||
allowed-tools: Bash, Read, Grep, Glob
|
||||
default-model: sonnet
|
||||
---
|
||||
|
||||
You are a Delegation Executor, a specialized subagent that orchestrates task execution in isolated Claude sessions using alternative models (GLM-4.6, Kimi) via headless mode.
|
||||
|
||||
**CRITICAL RULES:**
|
||||
|
||||
1. **YOU MUST DELEGATE** - Your ONLY job is to execute `ccs` commands via Bash. You MUST NOT edit or write files yourself.
|
||||
2. **ACTIVATE SKILL FIRST** - Always activate the `ccs-delegation` skill before any delegation.
|
||||
3. **READ-ONLY ANALYSIS** - You can read files to understand context, but ALL actual work must be done via `ccs` delegation.
|
||||
|
||||
## Your Mission
|
||||
|
||||
Execute tasks by delegating to alternative models via `ccs` CLI, then report results back to the main session.
|
||||
|
||||
## Workflow (MANDATORY)
|
||||
|
||||
1. **Activate Skill** - Load `ccs-delegation` skill for delegation guidelines
|
||||
2. **Analyze Task** - Read files if needed to understand context
|
||||
3. **Select Profile** - Choose GLM (simple/cost-optimized) or Kimi (long-context)
|
||||
4. **Delegate** - Execute via `ccs {profile} -p "enhanced task description"`
|
||||
5. **Report Results** - Parse output and report to main session
|
||||
|
||||
## Delegation Methodology
|
||||
|
||||
When delegating tasks, you will:
|
||||
|
||||
1. **Task Analysis**
|
||||
- Read `ccs-delegation` skill for decision framework
|
||||
- Determine if task is delegation-appropriate
|
||||
- Estimate time needed: Quick (<2 min) / Medium (<10 min) / Complex (>10 min)
|
||||
- Identify scope: Single file vs multiple files
|
||||
|
||||
2. **Profile Selection**
|
||||
- GLM: Simple, cost-optimized (refactoring, tests, typos)
|
||||
- Kimi: Long-context (multi-file analysis, architecture docs)
|
||||
|
||||
3. **Session Strategy**
|
||||
- **New session** (`ccs {profile} -p "task"`): Use when:
|
||||
- Starting a new, unrelated task
|
||||
- Previous session >30 days old
|
||||
- Different files/scope than last delegation
|
||||
|
||||
- **Continue session** (`ccs {profile}:continue -p "task"`): Use when:
|
||||
- Completing work from previous delegation
|
||||
- Fixing issues from last attempt
|
||||
- Adding to previously created files
|
||||
- Iterative refinement of same task
|
||||
- **CRITICAL**: Check delegation output for session ID before continuing
|
||||
|
||||
4. **Execution**
|
||||
- **New delegation**: `ccs {profile} -p "enhanced task description"`
|
||||
- **Continue delegation**: `ccs {profile}:continue -p "enhanced follow-up"`
|
||||
- **Note**: If task contains a slash command (/cook, /plan, /commit), keep it at the start when enhancing
|
||||
- Parse output for results
|
||||
- Report success/failure with file changes
|
||||
|
||||
5. **Batch Operations**
|
||||
- For multiple similar tasks, delegate each separately
|
||||
- Aggregate results
|
||||
- Report combined outcome
|
||||
|
||||
## Tools and Techniques
|
||||
|
||||
You will utilize:
|
||||
- **CCS CLI**: `ccs glm -p`, `ccs kimi -p` for delegation
|
||||
- **Bash Tool**: Execute CCS commands
|
||||
- **Read Tool**: Understand project context when needed
|
||||
- **ccs-delegation Skill**: Core knowledge base for delegation decisions
|
||||
|
||||
## Integration Components
|
||||
|
||||
CCS delegation uses these internal components:
|
||||
- **DelegationHandler**: Routes `-p` flag to HeadlessExecutor
|
||||
- **HeadlessExecutor**: Spawns `claude -p` with enhanced flags (--output-format stream-json, --permission-mode acceptEdits)
|
||||
- **SessionManager**: Persists sessions to `~/.ccs/delegation-sessions.json`
|
||||
- **ResultFormatter**: Displays ASCII box output with session ID, cost, turns
|
||||
|
||||
Results include metadata parsed from stream-json output with real-time tool visibility.
|
||||
|
||||
## Execution Pattern
|
||||
|
||||
**Standard delegation** (new task):
|
||||
```bash
|
||||
ccs glm -p "Refactor auth.js to use async/await"
|
||||
```
|
||||
|
||||
**Session continuation** (same task, iterative):
|
||||
```bash
|
||||
# First delegation creates landing page but misses JavaScript
|
||||
ccs glm -p "Create landing page in HTML/CSS"
|
||||
|
||||
# Output shows: Files Created: index.html, styles.css
|
||||
# You notice JavaScript file is missing
|
||||
|
||||
# Continue the SAME session to add missing JavaScript
|
||||
ccs glm:continue -p "Create the missing JavaScript file script.js"
|
||||
```
|
||||
|
||||
**Batch delegation** (multiple unrelated tasks):
|
||||
```bash
|
||||
# Each is a separate new session (different files)
|
||||
ccs glm -p "Add tests for UserService"
|
||||
ccs glm -p "Add tests for AuthService"
|
||||
ccs glm -p "Add tests for OrderService"
|
||||
```
|
||||
|
||||
## Remember
|
||||
|
||||
- **NEVER edit/write files yourself** - You lack Edit/Write tools for a reason
|
||||
- **ALWAYS delegate via `ccs`** - That's your only purpose
|
||||
- **ALWAYS activate `ccs-delegation` skill first** - It contains critical decision framework
|
||||
- Parse the delegation output and report results concisely to the main session
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
description: Delegate task to GLM-4.6 (cost-optimized model) [AUTO ENHANCE]
|
||||
argument-hint: [task description]
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
Delegate simple, deterministic tasks to GLM-4.6 for token optimization.
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
description: Continue last GLM delegation session [AUTO ENHANCE]
|
||||
argument-hint: [follow-up instruction]
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
Continue last GLM delegation session for iterative refinement.
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
description: Delegate task to Kimi (long-context model) [AUTO ENHANCE]
|
||||
argument-hint: [task description]
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
Delegate long-context, multi-file tasks to Kimi for comprehensive analysis.
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
description: Continue last Kimi delegation session [AUTO ENHANCE]
|
||||
argument-hint: [follow-up instruction]
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
Continue last Kimi delegation session for multi-turn analysis.
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
# CCS Auto-Delegation
|
||||
|
||||
Activate `ccs-delegation` skill for automatic delegation of eligible tasks.
|
||||
|
||||
**Auto-delegates:** typo fixes, test additions, refactoring, JSDoc, docs updates
|
||||
**Override:** Say "don't delegate" to bypass automation
|
||||
**Commands:** `/ccs:glm "task"` or `/ccs:kimi "task"` for explicit delegation
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: ccs-delegation
|
||||
description: Delegate simple tasks to alternative models (GLM, Kimi) via CCS CLI for token optimization
|
||||
version: 2.2.0
|
||||
description: AUTO-ACTIVATE for delegation-eligible tasks. Triggers on patterns like "fix typos", "add tests", "refactor to use", "add JSDoc", "analyze architecture". Also activates when user says "use ccs glm/kimi". Handles task validation, prompt enhancement, and execution via CCS CLI headless mode.
|
||||
version: 2.6.0
|
||||
---
|
||||
|
||||
# CCS Delegation
|
||||
@@ -14,6 +14,47 @@ Execute tasks via alternative models using `ccs {profile} -p "task"` equivalent
|
||||
|
||||
**Profiles:** GLM (cost-optimized), Kimi (long-context)
|
||||
|
||||
## User Invocation Patterns
|
||||
|
||||
Users trigger delegation naturally:
|
||||
- "use ccs glm [task]" - Delegate to GLM (cost-optimized)
|
||||
- "use ccs kimi [task]" - Delegate to Kimi (long-context)
|
||||
- "use ccs glm:continue [task]" - Continue GLM session
|
||||
- "use ccs kimi:continue [task]" - Continue Kimi session
|
||||
|
||||
**Examples:**
|
||||
- "use ccs glm to fix typos in README.md"
|
||||
- "use ccs kimi to analyze the entire architecture"
|
||||
- "use ccs glm:continue to add unit tests"
|
||||
|
||||
## Agent Response Protocol
|
||||
|
||||
When user says "use ccs {profile} [task]":
|
||||
|
||||
1. **Validate eligibility** against Decision Framework
|
||||
- Check: Simple, mechanical, <5 files
|
||||
- Check: No design decisions required
|
||||
- Check: Clear acceptance criteria exists
|
||||
|
||||
2. **Enhance prompt** with context:
|
||||
- Add file paths if mentioned
|
||||
- Include working directory
|
||||
- Specify success criteria
|
||||
- Add relevant constraints
|
||||
|
||||
3. **Execute via Bash tool**:
|
||||
```bash
|
||||
ccs {profile} -p "enhanced prompt"
|
||||
```
|
||||
|
||||
4. **Report results** to user:
|
||||
- Cost (USD)
|
||||
- Duration (seconds)
|
||||
- Session ID (for continuation)
|
||||
- Exit code/status
|
||||
|
||||
**If ineligible:** Explain why and handle in main session.
|
||||
|
||||
## Decision Framework
|
||||
|
||||
**Delegate when:**
|
||||
@@ -33,22 +74,26 @@ Execute tasks via alternative models using `ccs {profile} -p "task"` equivalent
|
||||
- **GLM**: Simple tasks (<5 files, clear scope, cost-optimized)
|
||||
- **Kimi**: Long-context (multi-file analysis, architecture docs)
|
||||
|
||||
## Example Delegation Tasks
|
||||
|
||||
**Good candidates:**
|
||||
- "add unit tests for UserService using Jest"
|
||||
- "fix typos in README.md"
|
||||
- "refactor parseConfig to use destructuring"
|
||||
- "add JSDoc comments to auth.js"
|
||||
|
||||
**Bad candidates (keep in main):**
|
||||
- "implement OAuth" (too complex, needs design)
|
||||
- "improve performance" (requires profiling)
|
||||
- "fix the bug" (needs investigation)
|
||||
|
||||
## Execution
|
||||
|
||||
User invocation via slash commands:
|
||||
```
|
||||
/ccs:glm "task"
|
||||
/ccs:glm:continue "follow-up"
|
||||
```
|
||||
Slash commands: `/ccs:glm "task"` or `/ccs:glm:continue "follow-up"`
|
||||
|
||||
Agent execution via Bash tool:
|
||||
```bash
|
||||
ccs glm -p "task"
|
||||
ccs glm:continue -p "follow-up"
|
||||
```
|
||||
Agent via Bash: `ccs glm -p "task"` or `ccs glm:continue -p "follow-up"`
|
||||
|
||||
## References
|
||||
|
||||
Technical details: `references/headless-workflow.md`
|
||||
Decision guide: `references/delegation-guidelines.md`
|
||||
Template: `CLAUDE.md.template` - Copy to user's CLAUDE.md for auto-delegation config
|
||||
Troubleshooting: `references/troubleshooting.md`
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
# CCS Delegation References
|
||||
|
||||
## Reading Order
|
||||
|
||||
1. **Start here**: `../SKILL.md` - Entry point, quick start
|
||||
2. `headless-workflow.md` - Technical details (command syntax, features, config)
|
||||
3. **As needed**:
|
||||
- `delegation-guidelines.md` - Decision framework
|
||||
- `troubleshooting.md` - Error recovery
|
||||
|
||||
## File Hierarchy
|
||||
|
||||
**PRIMARY (Authoritative Source)**
|
||||
- `headless-workflow.md` - Technical implementation details
|
||||
|
||||
**SUPPORTING (Reference Primary)**
|
||||
- `delegation-guidelines.md` - When to delegate
|
||||
- `troubleshooting.md` - Error patterns
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
**Need command syntax?** → `headless-workflow.md`
|
||||
**Need to decide if delegate?** → `delegation-guidelines.md`
|
||||
**Got an error?** → `troubleshooting.md`
|
||||
@@ -1,99 +0,0 @@
|
||||
# Delegation Guidelines
|
||||
|
||||
AI decision framework for when to delegate tasks vs keep in main session.
|
||||
|
||||
## Task Classification Rules
|
||||
|
||||
**Delegate if ALL criteria match:**
|
||||
- Task scope: Single concern, < 5 files
|
||||
- Complexity: Mechanical transformation, established pattern
|
||||
- Ambiguity: Zero decisions required, clear acceptance criteria
|
||||
- Context: Existing patterns to follow, no architecture changes
|
||||
|
||||
**Keep in main if ANY criteria match:**
|
||||
- Requires design decisions or tradeoff analysis
|
||||
- Security-critical (auth, encryption, permissions)
|
||||
- Performance-sensitive requiring profiling/measurement
|
||||
- Breaking changes or API migrations
|
||||
- User discussion/clarification needed
|
||||
- Coordinated changes across multiple subsystems
|
||||
|
||||
## Delegation Pattern Matching
|
||||
|
||||
**High-confidence delegation patterns:**
|
||||
```
|
||||
Task patterns to delegate:
|
||||
- refactor .* to use (async/await|destructuring|arrow functions)
|
||||
- add (unit|integration) tests for .*
|
||||
- fix (typos?|formatting|linting errors?) in .*
|
||||
- add JSDoc comments to .*
|
||||
- extract .* into (function|method|util) .*
|
||||
- rename (variable|function) .* to .*
|
||||
- add DELETE endpoint for .*
|
||||
- update README to document .*
|
||||
```
|
||||
|
||||
**Anti-patterns (never delegate):**
|
||||
```
|
||||
Task patterns to avoid:
|
||||
- implement .* (too vague, needs design)
|
||||
- improve .* (subjective, needs discussion)
|
||||
- fix bug .* (requires investigation)
|
||||
- optimize .* (requires profiling)
|
||||
- migrate .* to .* (breaking change)
|
||||
- design .* (architecture decision)
|
||||
- whatever .* you think (requires judgment)
|
||||
```
|
||||
|
||||
## Prompt Quality Criteria
|
||||
|
||||
**Well-formed delegation prompt:**
|
||||
- Specifies exact file paths: `in src/auth.js, ...`
|
||||
- Defines success criteria: `covering positive, zero, negative cases`
|
||||
- Single atomic task: One verb, one target
|
||||
- Uses imperative mood: "add tests" not "adding tests"
|
||||
|
||||
**Malformed delegation prompt:**
|
||||
- Multiple tasks: "add tests, update docs, fix linting"
|
||||
- Vague scope: "improve the code"
|
||||
- Requires decisions: "use whatever library you want"
|
||||
- No file context: "fix the bug" (which file?)
|
||||
|
||||
## Token Efficiency Model
|
||||
|
||||
**Delegation cost model:**
|
||||
- Main session overhead: ~2000 tokens (context, discussion)
|
||||
- Delegation overhead: ~500 tokens (focused execution)
|
||||
- Net savings: ~1500 tokens per delegated task
|
||||
|
||||
**When to batch delegate:**
|
||||
- User requests N similar tasks (e.g., "add tests for all services")
|
||||
- Each task follows identical pattern
|
||||
- Tasks are independent (no coordination needed)
|
||||
|
||||
**Execution pattern:**
|
||||
```
|
||||
for each service in [UserService, AuthService, OrderService]:
|
||||
ccs glm -p "add unit tests for {service} using Jest"
|
||||
```
|
||||
|
||||
## Monorepo Handling
|
||||
|
||||
**Workspace specification required:**
|
||||
- Pattern: `in packages/{workspace}, {task}`
|
||||
- Example: `in packages/api, add validation middleware`
|
||||
- Without workspace: Task may target wrong package
|
||||
|
||||
## Scope Limits
|
||||
|
||||
**Absolute limits (reject delegation):**
|
||||
- Estimated time > 30 minutes
|
||||
- File count > 5 files
|
||||
- Requires external research
|
||||
- Breaking changes to public APIs
|
||||
- User explicitly requests discussion
|
||||
|
||||
**Examples of over-scoped tasks:**
|
||||
- "Migrate from SQLite to PostgreSQL" (breaking change)
|
||||
- "Implement OAuth2 authentication" (too complex)
|
||||
- "Analyze entire codebase for security issues" (research task)
|
||||
@@ -2,267 +2,205 @@
|
||||
|
||||
AI-oriented error resolution guide for CCS delegation issues.
|
||||
|
||||
## Error Pattern Matching
|
||||
**Structure**: Quick Reference → Error Catalog → Common Resolutions → Diagnostics → Recovery
|
||||
|
||||
### Profile Configuration Errors
|
||||
**Cross-references**:
|
||||
- Technical details: `headless-workflow.md`
|
||||
- Decision framework: `delegation-guidelines.md`
|
||||
|
||||
**Pattern:** `Profile 'X' is not configured for delegation`
|
||||
```
|
||||
Root cause: Missing ~/.ccs/{profile}.settings.json
|
||||
Resolution:
|
||||
1. Check file exists: ls ~/.ccs/{profile}.settings.json
|
||||
2. Run diagnostics: ccs doctor
|
||||
3. If missing, user must configure profile manually
|
||||
```
|
||||
## Quick Reference
|
||||
|
||||
**Pattern:** `Invalid API key` (401 error)
|
||||
```
|
||||
Root cause: API token expired or invalid
|
||||
Resolution:
|
||||
1. Verify token exists in settings.json
|
||||
2. Test with simple command: ccs {profile} "test"
|
||||
3. If fails, user must regenerate token from provider
|
||||
```
|
||||
**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`
|
||||
|
||||
**Pattern:** `Settings file not found`
|
||||
```
|
||||
Root cause: ~/.ccs/{profile}.settings.json doesn't exist
|
||||
Resolution:
|
||||
1. Run: ccs doctor
|
||||
2. Shows missing profiles
|
||||
3. User must configure manually
|
||||
**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
|
||||
|
||||
**Pattern:** `No previous session found for {profile}`
|
||||
```
|
||||
Root cause: Using :continue without initial session
|
||||
Resolution:
|
||||
- Cannot use ccs {profile}:continue without prior session
|
||||
- Must run: ccs {profile} -p "initial task" first
|
||||
- Then can continue with: ccs {profile}:continue -p "follow-up"
|
||||
Example:
|
||||
[X] ccs glm:continue -p "task" # ERROR: no session
|
||||
[OK] ccs glm -p "task" # Creates session
|
||||
[OK] ccs glm:continue -p "more" # Uses session
|
||||
```
|
||||
| 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 |
|
||||
|
||||
**Pattern:** `Missing prompt after -p flag`
|
||||
```
|
||||
Root cause: No argument provided after -p
|
||||
Resolution:
|
||||
- Syntax: ccs {profile} -p "prompt text"
|
||||
- Quote prompt if contains spaces
|
||||
Example:
|
||||
[X] ccs glm -p # ERROR
|
||||
[OK] ccs glm -p "add tests" # Correct
|
||||
```
|
||||
|
||||
**Pattern:** `No profile specified`
|
||||
```
|
||||
Root cause: Command missing profile name
|
||||
Resolution:
|
||||
- Syntax: ccs <profile> -p "task"
|
||||
- Available profiles: glm, kimi
|
||||
Example:
|
||||
[X] ccs -p "task" # ERROR: no profile
|
||||
[OK] ccs glm -p "task" # Correct
|
||||
```
|
||||
|
||||
**Pattern:** Exit code 1 with JSON parse error
|
||||
```
|
||||
Root cause: Claude CLI returned non-stream-JSON output
|
||||
Resolution:
|
||||
1. Check if --output-format stream-json is supported
|
||||
2. Verify Claude CLI version (need recent version with stream-json support)
|
||||
3. Test manually: claude -p "test" --output-format stream-json
|
||||
4. If not supported, delegation won't work
|
||||
**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
|
||||
|
||||
**Pattern:** Session file corrupted
|
||||
```
|
||||
Root cause: ~/.ccs/delegation-sessions.json malformed
|
||||
Resolution:
|
||||
1. Backup file: cp ~/.ccs/delegation-sessions.json ~/.ccs/delegation-sessions.json.bak
|
||||
2. Delete corrupted file: rm ~/.ccs/delegation-sessions.json
|
||||
3. New file created on next delegation
|
||||
4. Previous sessions lost but fresh start
|
||||
```
|
||||
| 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) |
|
||||
|
||||
**Pattern:** Session expired
|
||||
```
|
||||
Root cause: Session older than 30 days
|
||||
Resolution:
|
||||
- Sessions auto-expire after 30 days
|
||||
- Start new session: ccs {profile} -p "task"
|
||||
- Cannot resume expired sessions
|
||||
```
|
||||
### Network/API Errors
|
||||
|
||||
### Network & API Errors
|
||||
|
||||
**Pattern:** Connection timeout
|
||||
```
|
||||
Root cause: Network issue or API endpoint unreachable
|
||||
Resolution:
|
||||
1. Check internet: ping 8.8.8.8
|
||||
2. Verify API endpoint in settings.json
|
||||
3. Check firewall/proxy settings
|
||||
4. Retry delegation
|
||||
```
|
||||
|
||||
**Pattern:** Rate limiting (429)
|
||||
```
|
||||
Root cause: Too many API requests
|
||||
Resolution:
|
||||
1. Wait 60 seconds before retry
|
||||
2. Reduce concurrent delegations
|
||||
3. Check API quota limits
|
||||
```
|
||||
| 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
|
||||
|
||||
**Pattern:** File not found during delegation
|
||||
```
|
||||
Root cause: Path doesn't exist or wrong working directory
|
||||
Resolution:
|
||||
1. Delegation runs in cwd where command executed
|
||||
2. Verify file exists: ls <file>
|
||||
3. Use absolute paths in prompt if needed
|
||||
Example:
|
||||
Prompt: "refactor src/auth.js"
|
||||
Check: ls src/auth.js # Must exist in cwd
|
||||
```
|
||||
| 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}" |
|
||||
|
||||
**Pattern:** Permission denied writing files
|
||||
```
|
||||
Root cause: Insufficient permissions in target directory
|
||||
Resolution:
|
||||
1. Check directory permissions: ls -la
|
||||
2. Verify cwd is writable
|
||||
3. Don't delegate in read-only directories
|
||||
```
|
||||
|
||||
## Diagnostic Commands
|
||||
|
||||
**Profile validation:**
|
||||
**Example:**
|
||||
```bash
|
||||
ccs doctor # Check all profiles
|
||||
cat ~/.ccs/glm.settings.json # Verify settings
|
||||
ccs glm "echo test" 2>&1 # Test execution
|
||||
# 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
|
||||
cat ~/.ccs/delegation-sessions.json # View sessions
|
||||
jq '.glm' ~/.ccs/delegation-sessions.json # Check specific profile
|
||||
```
|
||||
|
||||
**Delegation test:**
|
||||
```bash
|
||||
ccs glm -p "create test.txt file with 'hello'" # Simple test
|
||||
cat test.txt # Verify result
|
||||
```
|
||||
|
||||
**Debug mode:**
|
||||
```bash
|
||||
export CCS_DEBUG=1
|
||||
ccs glm -p "task" 2>&1 | tee debug.log # Capture full output
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Delegation fails?
|
||||
│
|
||||
├─→ "Profile not configured"
|
||||
│ └─→ Run: ccs doctor
|
||||
│ └─→ Configure missing profile
|
||||
│
|
||||
├─→ "No previous session"
|
||||
│ └─→ Using :continue?
|
||||
│ ├─→ YES: Run initial task first
|
||||
│ └─→ NO: Different error
|
||||
│
|
||||
├─→ "Missing prompt"
|
||||
│ └─→ Check syntax: ccs {profile} -p "prompt"
|
||||
│
|
||||
├─→ Exit code 1
|
||||
│ └─→ Check error message
|
||||
│ ├─→ JSON parse: Claude CLI version issue
|
||||
│ ├─→ File not found: Verify paths
|
||||
│ └─→ API error: Check network/token
|
||||
│
|
||||
└─→ Silent failure
|
||||
└─→ Enable debug: export CCS_DEBUG=1
|
||||
```
|
||||
|
||||
## Common Patterns to Avoid
|
||||
|
||||
**Anti-pattern:** Delegating without profile validation
|
||||
```
|
||||
[X] Assume profile exists
|
||||
[OK] Run ccs doctor first to verify
|
||||
```
|
||||
|
||||
**Anti-pattern:** Using :continue immediately
|
||||
```
|
||||
[X] ccs glm:continue -p "task" # No initial session
|
||||
[OK] ccs glm -p "task" && ccs glm:continue -p "more"
|
||||
```
|
||||
|
||||
**Anti-pattern:** Delegating complex tasks
|
||||
```
|
||||
[X] ccs glm -p "implement OAuth2" # Too complex
|
||||
[OK] ccs glm -p "add tests for login function"
|
||||
```
|
||||
|
||||
**Anti-pattern:** Vague prompts
|
||||
```
|
||||
[X] ccs glm -p "fix the bug" # No context
|
||||
[OK] ccs glm -p "fix typo in src/auth.js line 42"
|
||||
```
|
||||
|
||||
## Recovery Procedures
|
||||
|
||||
**Reset session state:**
|
||||
```bash
|
||||
rm ~/.ccs/delegation-sessions.json
|
||||
# Fresh start, all sessions lost
|
||||
```
|
||||
|
||||
**Reconfigure profile:**
|
||||
```bash
|
||||
ccs doctor # Shows issues
|
||||
# Edit ~/.ccs/{profile}.settings.json manually
|
||||
# Verify: ccs {profile} "test"
|
||||
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 content 'hello'"
|
||||
ccs glm -p "create test.txt with 'hello'"
|
||||
|
||||
# 2. Verify session created
|
||||
cat ~/.ccs/delegation-sessions.json | jq '.glm.sessionId'
|
||||
# 2. Verify session
|
||||
jq '.glm.sessionId' ~/.ccs/delegation-sessions.json
|
||||
|
||||
# 3. Test continue
|
||||
# 3. Continue
|
||||
ccs glm:continue -p "append 'world' to test.txt"
|
||||
|
||||
# 4. Verify aggregation
|
||||
cat ~/.ccs/delegation-sessions.json | jq '.glm.turns'
|
||||
# 4. Check aggregation
|
||||
jq '.glm.turns' ~/.ccs/delegation-sessions.json
|
||||
```
|
||||
|
||||
## Emergency Fallback
|
||||
## Emergency Recovery
|
||||
|
||||
If delegation completely broken:
|
||||
**Reset session state:**
|
||||
```bash
|
||||
# Use Claude CLI directly
|
||||
claude -p "task" --settings ~/.ccs/glm.settings.json
|
||||
rm ~/.ccs/delegation-sessions.json # Fresh start (loses all sessions)
|
||||
```
|
||||
|
||||
# Bypass delegation (no -p flag)
|
||||
ccs glm
|
||||
# Then work interactively
|
||||
**Bypass delegation (use CLI directly):**
|
||||
```bash
|
||||
claude -p "task" --settings ~/.ccs/{profile}.settings.json
|
||||
```
|
||||
|
||||
**Interactive mode (no -p flag):**
|
||||
```bash
|
||||
ccs {profile} # Opens interactive session
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user