@kaitranntt/ccs 3.5.0 → 4.1.0

package/.claude/skills/ccs-delegation/references/troubleshooting.md

@@ -0,0 +1,268 @@
+# Troubleshooting
+
+AI-oriented error resolution guide for CCS delegation issues.
+
+## Error Pattern Matching
+
+### Profile Configuration Errors
+
+**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
+```
+
+**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
+```
+
+**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 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
+```
+
+**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
+```
+
+### 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
+```
+
+**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
+
+**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
+```
+
+### 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
+```
+
+**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:**
+```bash
+ccs doctor                              # Check all profiles
+cat ~/.ccs/glm.settings.json            # Verify settings
+ccs glm "echo test" 2>&1                # Test execution
+```
+
+**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"
+```
+
+**Test delegation flow:**
+```bash
+# 1. Simple task
+ccs glm -p "create test.txt with content 'hello'"
+
+# 2. Verify session created
+cat ~/.ccs/delegation-sessions.json | jq '.glm.sessionId'
+
+# 3. Test continue
+ccs glm:continue -p "append 'world' to test.txt"
+
+# 4. Verify aggregation
+cat ~/.ccs/delegation-sessions.json | jq '.glm.turns'
+```
+
+## Emergency Fallback
+
+If delegation completely broken:
+```bash
+# Use Claude CLI directly
+claude -p "task" --settings ~/.ccs/glm.settings.json
+
+# Bypass delegation (no -p flag)
+ccs glm
+# Then work interactively
+```

package/README.md

@@ -174,29 +174,51 @@ Then: 🔴 _"You've reached your usage limit."_
 <details>
 <summary><strong>❌ OLD WAY:</strong> Switch When You Hit Limits (Reactive)</summary>
 
-### Your Current Workflow:
-- **2pm:** Building features, in the zone
-- **3pm:** 🔴 Usage limit hit
-- **3:05pm:** Stop work, edit `~/.claude/settings.json`
-- **3:15pm:** Switch accounts, lose context
-- **3:30pm:** Try to get back in flow state
-- **4pm:** Finally productive again
+<br>
+
+```mermaid
+graph LR
+    A[2pm: Building features<br/>In the zone] --> B[3pm: Usage limit hit<br/>BLOCKED]
+    B --> C[3:05pm: Stop work<br/>Edit settings.json]
+    C --> D[3:15pm: Switch accounts<br/>Context lost]
+    D --> E[3:30pm: Restart<br/>Trying to focus]
+    E --> F[4pm: Finally productive<br/>Back in flow]
+
+    style A fill:#d4edda,stroke:#333,color:#000
+    style B fill:#f8d7da,stroke:#333,color:#000
+    style C fill:#fff3cd,stroke:#333,color:#000
+    style D fill:#f8d7da,stroke:#333,color:#000
+    style E fill:#fff3cd,stroke:#333,color:#000
+    style F fill:#d4edda,stroke:#333,color:#000
+```
 
-- **Result:** 1 hour lost, momentum destroyed, frustration builds
+**Result:** 1 hour lost, momentum destroyed, frustration builds
 
 </details>
 
 <details open>
 <summary><strong>✨ NEW WAY:</strong> Run Parallel From Start (Proactive) - <strong>RECOMMENDED</strong></summary>
 
-### Your New Workflow:
-- **2pm:** **Terminal 1:** `ccs "Plan the API architecture"` → Strategic thinking (Claude Pro)
-- **2pm:** **Terminal 2:** `ccs glm "Implement the endpoints"` → Code execution (GLM)
-- **3pm:** Still shipping, no interruptions
-- **4pm:** Flow state achieved, productivity spiking
-- **5pm:** Features shipped, context maintained
+<br>
 
-- **Result:** Zero downtime, continuous productivity, less frustration
+```mermaid
+graph LR
+    A[2pm: Start work] --> B[Terminal 1: Claude Pro<br/>Strategic planning]
+    A --> C[Terminal 2: GLM<br/>Code execution]
+    B --> D[3pm: Still shipping<br/>No interruptions]
+    C --> D
+    D --> E[4pm: Flow state<br/>Productivity peak]
+    E --> F[5pm: Features shipped<br/>Context maintained]
+
+    style A fill:#e7f3ff,stroke:#333,color:#000
+    style B fill:#cfe2ff,stroke:#333,color:#000
+    style C fill:#cfe2ff,stroke:#333,color:#000
+    style D fill:#d4edda,stroke:#333,color:#000
+    style E fill:#d4edda,stroke:#333,color:#000
+    style F fill:#d4edda,stroke:#333,color:#000
+```
+
+**Result:** Zero downtime, continuous productivity, less frustration
 
 ### 💰 **The Value Proposition:**
 - **Setup:** Your existing Claude Pro + GLM Lite (cost-effective add-on)
@@ -291,16 +313,22 @@ Then: 🔴 _"You've reached your usage limit."_
 - Uses `CLAUDE_CONFIG_DIR` for isolated instances
 - Create with `ccs auth create <profile>`
 
-### Shared Data (v3.1)
+### Shared Data (v3.1+)
+
+**CCS items (v4.1)**: Commands and skills symlinked from `~/.ccs/.claude/` to `~/.claude/` - **single source of truth with auto-propagation**.
 
-Commands and skills symlinked from `~/.ccs/shared/` - **no duplication across profiles**.
+**Profile access**: `~/.ccs/shared/` symlinks to `~/.claude/` - **no duplication across profiles**.
 
 ```plaintext
 ~/.ccs/
-├── shared/                  # Shared across all profiles
-│   ├── agents/
-│   ├── commands/
-│   └── skills/
+├── .claude/                 # CCS items (ships with package, v4.1)
+│   ├── commands/ccs/        # Delegation commands (/ccs:glm, /ccs:kimi)
+│   ├── skills/ccs-delegation/  # AI decision framework
+│   └── agents/ccs-delegator.md # Proactive delegation agent
+├── shared/                  # Symlinks to ~/.claude/ (for profiles)
+│   ├── agents@ → ~/.claude/agents/
+│   ├── commands@ → ~/.claude/commands/
+│   └── skills@ → ~/.claude/skills/
 ├── instances/               # Profile-specific data
 │   └── work/
 │       ├── agents@ → shared/agents/
@@ -309,15 +337,23 @@ Commands and skills symlinked from `~/.ccs/shared/` - **no duplication across pr
 │       ├── settings.json    # API keys, credentials
 │       ├── sessions/        # Conversation history
 │       └── ...
+
+~/.claude/                   # User's Claude directory
+├── commands/ccs@ → ~/.ccs/.claude/commands/ccs/  # Selective symlink
+├── skills/ccs-delegation@ → ~/.ccs/.claude/skills/ccs-delegation/
+└── agents/ccs-delegator.md@ → ~/.ccs/.claude/agents/ccs-delegator.md
 ```
 
+**Symlink Chain**: `work profile → ~/.ccs/shared/ → ~/.claude/ → ~/.ccs/.claude/` (CCS items)
+
 | Type | Files |
 |:-----|:------|
-| **Shared** | `commands/`, `skills/`, `agents/` |
+| **CCS items** | `~/.ccs/.claude/` (ships with package, selective symlinks to `~/.claude/`) |
+| **Shared** | `~/.ccs/shared/` (symlinks to `~/.claude/`) |
 | **Profile-specific** | `settings.json`, `sessions/`, `todolists/`, `logs/` |
 
 > [!NOTE]
-> **Windows**: Copies directories if symlinks unavailable (enable Developer Mode for true symlinks)
+> **Windows**: Symlink support requires Developer Mode (v4.2 will add copy fallback)
 
 <br>
 
@@ -358,6 +394,123 @@ ccs --help       # Show all commands and options
 
 <br>
 
+## AI-Powered Delegation
+
+> [!TIP]
+> **New in v4.0**: Delegate tasks to cost-optimized models (GLM, Kimi) directly from your main Claude session. Save 81% on simple tasks with real-time visibility.
+
+### What is Delegation?
+
+CCS Delegation lets you **send tasks to alternative models** (`glm`, `kimi`) **from your main Claude session** using the `-p` flag or slash commands (`/ccs:glm`, `/ccs:kimi`).
+
+**Why use it?**
+- **Token efficiency**: Simple tasks cost 81% less on GLM vs main Claude session
+- **Context preservation**: Main session stays clean, no pollution from mechanical tasks
+- **Real-time visibility**: See tool usage as tasks execute (`[Tool] Write: index.html`)
+- **Multi-turn support**: Resume sessions with `:continue` for iterative work
+
+### Quick Examples
+
+**Direct CLI:**
+```bash
+# Delegate simple task to GLM (cost-optimized)
+ccs glm -p "add tests for UserService"
+
+# Delegate long-context task to Kimi
+ccs kimi -p "analyze all files in src/ and document architecture"
+
+# Continue previous session
+ccs glm:continue -p "run the tests and fix any failures"
+```
+
+**Via Slash Commands** (inside Claude sessions):
+```bash
+# In your main Claude session:
+/ccs:glm "refactor auth.js to use async/await"
+/ccs:kimi "find all deprecated API usages across codebase"
+/ccs:glm:continue "also update the README examples"
+```
+
+**Via Natural Language** (Claude auto-delegates):
+```bash
+# Claude detects delegation patterns and auto-executes:
+"Use ccs glm to add tests for all *.service.js files"
+"Delegate to kimi: analyze project structure"
+```
+
+### Real-Time Output
+
+See exactly what's happening as tasks execute:
+
+```
+$ ccs glm -p "/cook create a landing page"
+[i] Delegating to GLM-4.6...
+[Tool] Write: /home/user/project/index.html
+[Tool] Write: /home/user/project/styles.css
+[Tool] Write: /home/user/project/script.js
+[Tool] Edit: /home/user/project/styles.css
+[i] Execution completed in 45.2s
+
+╔══════════════════════════════════════════════════════╗
+║ Working Directory: /home/user/project               ║
+║ Model: GLM-4.6                                       ║
+║ Duration: 45.2s                                      ║
+║ Exit Code: 0                                         ║
+║ Session ID: 3a4f8c21                                 ║
+║ Total Cost: $0.0015                                  ║
+║ Turns: 3                                             ║
+╚══════════════════════════════════════════════════════╝
+```
+
+### Advanced Features
+
+**Slash Command Support:**
+Delegation preserves custom slash commands in prompts:
+```bash
+ccs glm -p "/cook create responsive landing page"
+# Executes /cook command in delegated GLM session
+```
+
+**Signal Handling:**
+Ctrl+C or Esc properly kills delegated processes (no orphans):
+```bash
+# Hit Ctrl+C during delegation
+[!] Parent process terminating, killing delegated session...
+```
+
+**Time-Based Limits:**
+10-minute default timeout with graceful termination (supports `:continue`):
+```bash
+ccs glm -p "complex task"  # Auto-terminates after 10min if needed
+ccs glm:continue -p "pick up where we left off"
+```
+
+### Cost Savings Example
+
+**Traditional (Main Session):**
+```
+Context load: 2000 tokens
+Discussion:   1500 tokens
+Code gen:     4500 tokens
+─────────────────────────
+Total:        8000 tokens → $0.032
+```
+
+**Delegation (GLM):**
+```
+3x tasks via GLM: 1500 tokens → $0.0045
+─────────────────────────────────────────
+Savings:                        $0.0275 (86% reduction)
+```
+
+### Documentation
+
+- **Workflow Diagrams**: See [docs/ccs-delegation-diagrams.md](docs/ccs-delegation-diagrams.md) for visual architecture
+- **Skill Reference**: `.claude/skills/ccs-delegation/` for AI decision framework
+- **Agent Docs**: `.claude/agents/ccs-delegator.md` for orchestration patterns
+
+<br>
+
 ## GLM with Thinking (GLMT)
 
 > [!CAUTION]
@@ -568,6 +721,53 @@ cat ~/.ccs/logs/*response-openai.json | jq '.choices[0].message.reasoning_conten
 
 <br>
 
+## Maintenance
+
+### Health Check
+
+Run diagnostics to verify your CCS installation:
+
+```bash
+ccs doctor
+```
+
+**Checks performed**:
+- ✓ Claude CLI availability
+- ✓ Configuration files (config.json, profiles)
+- ✓ CCS symlinks to ~/.claude/
+- ✓ Delegation system
+- ✓ File permissions
+
+**Output**:
+```
+[?] Checking Claude CLI... [OK]
+[?] Checking ~/.ccs/ directory... [OK]
+[?] Checking config.json... [OK]
+[?] Checking CCS symlinks... [OK]
+...
+Status: Installation healthy
+```
+
+### Update CCS Items
+
+If you modify CCS items or need to re-install symlinks:
+
+```bash
+ccs update
+```
+
+**What it does**:
+- Re-creates selective symlinks from `~/.ccs/.claude/` to `~/.claude/`
+- Backs up existing files before replacing
+- Safe to run multiple times (idempotent)
+
+**When to use**:
+- After manual modifications to ~/.claude/
+- If `ccs doctor` reports symlink issues
+- After upgrading CCS to a new version
+
+<br>
+
 ## Uninstall
 
 <details>

package/VERSION

@@ -1 +1 @@
-3.5.0
+4.1.0

package/bin/ccs.js

@@ -73,6 +73,33 @@ function handleVersionCommand() {
   // Config path
   const configPath = getConfigPath();
   console.log(`  ${colored('Config:', 'cyan')} ${configPath}`);
+
+  // Delegation status
+  const delegationRulesPath = path.join(os.homedir(), '.ccs', 'delegation-rules.json');
+  const delegationEnabled = fs.existsSync(delegationRulesPath);
+
+  if (delegationEnabled) {
+    console.log(`  ${colored('Delegation:', 'cyan')} Enabled`);
+
+    // Check which profiles are delegation-ready
+    const readyProfiles = [];
+    const { DelegationValidator } = require('./utils/delegation-validator');
+
+    for (const profile of ['glm', 'kimi']) {
+      const validation = DelegationValidator.validate(profile);
+      if (validation.valid) {
+        readyProfiles.push(profile);
+      }
+    }
+
+    if (readyProfiles.length > 0) {
+      console.log(`  ${colored('Ready:', 'cyan')} ${readyProfiles.join(', ')}`);
+    } else {
+      console.log(`  ${colored('Ready:', 'cyan')} None (configure profiles first)`);
+    }
+  } else {
+    console.log(`  ${colored('Delegation:', 'cyan')} Not configured`);
+  }
   console.log('');
 
   // Documentation
@@ -121,9 +148,19 @@ function handleHelpCommand() {
   console.log(`  ${colored('ccs personal', 'yellow')}                Switch to personal account`);
   console.log('');
 
+  // Delegation (NEW)
+  console.log(colored('Delegation (Token Optimization):', 'cyan'));
+  console.log(`  ${colored('/ccs:glm "task"', 'yellow')}             Delegate to GLM-4.6 within Claude session`);
+  console.log(`  ${colored('/ccs:kimi "task"', 'yellow')}            Delegate to Kimi for long context`);
+  console.log(`  ${colored('/ccs:create m2', 'yellow')}              Create custom delegation command`);
+  console.log('  Use delegation to save tokens on simple tasks');
+  console.log('  Commands work inside Claude Code sessions only');
+  console.log('');
+
   // Diagnostics
   console.log(colored('Diagnostics:', 'cyan'));
   console.log(`  ${colored('ccs doctor', 'yellow')}                  Run health check and diagnostics`);
+  console.log(`  ${colored('ccs update', 'yellow')}                  Re-install CCS items to ~/.claude/`);
   console.log('');
 
   // Flags
@@ -217,6 +254,16 @@ async function handleDoctorCommand() {
   process.exit(doctor.results.isHealthy() ? 0 : 1);
 }
 
+async function handleUpdateCommand() {
+  const ClaudeSymlinkManager = require('./utils/claude-symlink-manager');
+  const manager = new ClaudeSymlinkManager();
+
+  console.log('[i] Updating CCS items in ~/.claude/...');
+  manager.update();
+
+  process.exit(0);
+}
+
 // Smart profile detection
 function detectProfile(args) {
   if (args.length === 0 || args[0].startsWith('-')) {
@@ -454,6 +501,12 @@ async function main() {
     return;
   }
 
+  // Special case: update command (re-install CCS symlinks)
+  if (firstArg === 'update' || firstArg === '--update') {
+    await handleUpdateCommand();
+    return;
+  }
+
   // Special case: auth command (multi-account management)
   if (firstArg === 'auth') {
     const AuthCommands = require('./auth/auth-commands');
@@ -462,6 +515,14 @@ async function main() {
     return;
   }
 
+  // Special case: headless delegation (-p flag)
+  if (args.includes('-p') || args.includes('--prompt')) {
+    const DelegationHandler = require('./delegation/delegation-handler');
+    const handler = new DelegationHandler();
+    await handler.route(args);
+    return;
+  }
+
   // Auto-recovery for missing configuration
   const recovery = new RecoveryManager();
   const recovered = recovery.recoverAll();