From 53dc2ed8c8a48e5bf96a7705ab6289d67f441716 Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Tue, 18 Nov 2025 20:38:14 -0500 Subject: [PATCH] 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. --- .claude/agents/ccs-delegator.md | 117 ------ .claude/commands/ccs/glm.md | 1 - .claude/commands/ccs/glm/continue.md | 1 - .claude/commands/ccs/kimi.md | 1 - .claude/commands/ccs/kimi/continue.md | 1 - .../skills/ccs-delegation/CLAUDE.md.template | 7 + .claude/skills/ccs-delegation/SKILL.md | 73 +++- .../ccs-delegation/references/README.md | 24 -- .../references/delegation-guidelines.md | 99 ----- .../references/troubleshooting.md | 388 ++++++++---------- .../references => docs}/headless-workflow.md | 0 11 files changed, 229 insertions(+), 483 deletions(-) delete mode 100644 .claude/agents/ccs-delegator.md create mode 100644 .claude/skills/ccs-delegation/CLAUDE.md.template delete mode 100644 .claude/skills/ccs-delegation/references/README.md delete mode 100644 .claude/skills/ccs-delegation/references/delegation-guidelines.md rename {.claude/skills/ccs-delegation/references => docs}/headless-workflow.md (100%) diff --git a/.claude/agents/ccs-delegator.md b/.claude/agents/ccs-delegator.md deleted file mode 100644 index 885f038d..00000000 --- a/.claude/agents/ccs-delegator.md +++ /dev/null @@ -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\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\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\n\n\n\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\nThis agent handles execution in the kimi profile, which supports long-context tasks, and formats the comprehensive results for the main session.\n\n\n\n\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\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\n -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 diff --git a/.claude/commands/ccs/glm.md b/.claude/commands/ccs/glm.md index 8cde0cd7..e2906da0 100644 --- a/.claude/commands/ccs/glm.md +++ b/.claude/commands/ccs/glm.md @@ -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. diff --git a/.claude/commands/ccs/glm/continue.md b/.claude/commands/ccs/glm/continue.md index 3dc4c634..666fdd50 100644 --- a/.claude/commands/ccs/glm/continue.md +++ b/.claude/commands/ccs/glm/continue.md @@ -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. diff --git a/.claude/commands/ccs/kimi.md b/.claude/commands/ccs/kimi.md index db8a05ae..e1d24bb7 100644 --- a/.claude/commands/ccs/kimi.md +++ b/.claude/commands/ccs/kimi.md @@ -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. diff --git a/.claude/commands/ccs/kimi/continue.md b/.claude/commands/ccs/kimi/continue.md index 2e7f4713..21ed85c1 100644 --- a/.claude/commands/ccs/kimi/continue.md +++ b/.claude/commands/ccs/kimi/continue.md @@ -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. diff --git a/.claude/skills/ccs-delegation/CLAUDE.md.template b/.claude/skills/ccs-delegation/CLAUDE.md.template new file mode 100644 index 00000000..740ad39b --- /dev/null +++ b/.claude/skills/ccs-delegation/CLAUDE.md.template @@ -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 diff --git a/.claude/skills/ccs-delegation/SKILL.md b/.claude/skills/ccs-delegation/SKILL.md index 16a3035a..819c2d76 100644 --- a/.claude/skills/ccs-delegation/SKILL.md +++ b/.claude/skills/ccs-delegation/SKILL.md @@ -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` diff --git a/.claude/skills/ccs-delegation/references/README.md b/.claude/skills/ccs-delegation/references/README.md deleted file mode 100644 index cc5d7c67..00000000 --- a/.claude/skills/ccs-delegation/references/README.md +++ /dev/null @@ -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` diff --git a/.claude/skills/ccs-delegation/references/delegation-guidelines.md b/.claude/skills/ccs-delegation/references/delegation-guidelines.md deleted file mode 100644 index 9bcc54f4..00000000 --- a/.claude/skills/ccs-delegation/references/delegation-guidelines.md +++ /dev/null @@ -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) diff --git a/.claude/skills/ccs-delegation/references/troubleshooting.md b/.claude/skills/ccs-delegation/references/troubleshooting.md index 35f5aa01..f55719a6 100644 --- a/.claude/skills/ccs-delegation/references/troubleshooting.md +++ b/.claude/skills/ccs-delegation/references/troubleshooting.md @@ -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 -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 -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 -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 - 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 ` 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 ``` diff --git a/.claude/skills/ccs-delegation/references/headless-workflow.md b/docs/headless-workflow.md similarity index 100% rename from .claude/skills/ccs-delegation/references/headless-workflow.md rename to docs/headless-workflow.md