@kaitranntt/ccs 3.5.0 → 4.1.1

package/.claude/agents/ccs-delegator.md

@@ -0,0 +1,117 @@
+---
+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

package/.claude/commands/ccs/glm/continue.md

@@ -0,0 +1,22 @@
+---
+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.
+
+**Workflow:**
+- Review what was accomplished in previous session
+- Analyze the follow-up instruction in `$ARGUMENTS`
+- Enhance prompt with context (reference files, incomplete tasks, next steps)
+- Execute continuation via `ccs glm:continue -p "$ENHANCED_PROMPT"`
+
+**Note:** `$ENHANCED_PROMPT` is an enhanced version that references previous work, highlights incomplete tasks, and adds specific validation criteria. If the follow-up contains a slash command (e.g., /commit), keep it at the start of the enhanced prompt.
+
+**Usage:**
+```
+/ccs:glm "fix typo in README"
+/ccs:glm:continue "also update the examples section"
+/ccs:glm:continue "/commit with descriptive message"
+```

package/.claude/commands/ccs/glm.md

@@ -0,0 +1,22 @@
+---
+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.
+
+**Workflow:**
+- Analyze the task description in `$ARGUMENTS`
+- Gather context if needed (read files, check structure)
+- Enhance prompt with specific details (file paths, context, success criteria)
+- Execute delegation via `ccs glm -p "$ENHANCED_PROMPT"`
+
+**Note:** `$ENHANCED_PROMPT` is an enhanced version that adds specifics like file paths, current implementation context, expected behavior, and success criteria. If the task contains a slash command (e.g., /cook, /plan), keep it at the start of the enhanced prompt.
+
+**Usage:**
+```
+/ccs:glm "refactor auth.js to use async/await"
+/ccs:glm "add tests for UserService"
+/ccs:glm "/cook create a landing page"
+```

package/.claude/commands/ccs/kimi/continue.md

@@ -0,0 +1,22 @@
+---
+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.
+
+**Workflow:**
+- Review analysis/work from previous session
+- Analyze the follow-up instruction in `$ARGUMENTS`
+- Enhance prompt with comprehensive context (findings, scope, deliverables, priority)
+- Execute continuation via `ccs kimi:continue -p "$ENHANCED_PROMPT"`
+
+**Note:** `$ENHANCED_PROMPT` is an enhanced version that references previous findings, specifies next scope, and adds actionable deliverables with priorities. If the follow-up contains a slash command (e.g., /plan), keep it at the start of the enhanced prompt.
+
+**Usage:**
+```
+/ccs:kimi "analyze all files in src/"
+/ccs:kimi:continue "suggest architectural improvements"
+/ccs:kimi:continue "/plan for refactoring with phases"
+```

package/.claude/commands/ccs/kimi.md

@@ -0,0 +1,22 @@
+---
+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.
+
+**Workflow:**
+- Analyze the task description in `$ARGUMENTS`
+- Gather context across multiple files/directories
+- Enhance prompt with comprehensive details (structure, relationships, scope)
+- Execute delegation via `ccs kimi -p "$ENHANCED_PROMPT"`
+
+**Note:** `$ENHANCED_PROMPT` is an enhanced version that adds directory structures, cross-file relationships, architecture context, and deliverables. If the task contains a slash command (e.g., /plan, /commit), keep it at the start of the enhanced prompt.
+
+**Usage:**
+```
+/ccs:kimi "analyze all files in src/ and document architecture"
+/ccs:kimi "find all deprecated API usages across codebase"
+/ccs:kimi "/plan for authentication system"
+```

package/.claude/skills/ccs-delegation/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ccs-delegation
+description: Delegate simple tasks to alternative models (GLM, Kimi) via CCS CLI for token optimization
+version: 2.2.0
+---
+
+# CCS Delegation
+
+Delegate deterministic tasks to cost-optimized models via CCS CLI.
+
+## Core Concept
+
+Execute tasks via alternative models using `ccs {profile} -p "task"` equivalent to `claude --settings ~/.ccs/{profile}.settings -p "task"`
+
+**Profiles:** GLM (cost-optimized), Kimi (long-context)
+
+## 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
+
+- **GLM**: Simple tasks (<5 files, clear scope, cost-optimized)
+- **Kimi**: Long-context (multi-file analysis, architecture docs)
+
+## Execution
+
+User invocation via slash commands:
+```
+/ccs:glm "task"
+/ccs:glm:continue "follow-up"
+```
+
+Agent execution via Bash tool:
+```bash
+ccs glm -p "task"
+ccs glm:continue -p "follow-up"
+```
+
+## References
+
+Technical details: `references/headless-workflow.md`
+Decision guide: `references/delegation-guidelines.md`
+Troubleshooting: `references/troubleshooting.md`

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

@@ -0,0 +1,24 @@
+# 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`

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

@@ -0,0 +1,99 @@
+# 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)

package/.claude/skills/ccs-delegation/references/headless-workflow.md

@@ -0,0 +1,174 @@
+# Headless Workflow
+
+**Last Updated**: 2025-11-15
+
+CCS delegation uses Claude Code headless mode with enhanced features for token optimization.
+
+## Core Concept
+
+CCS delegation executes tasks via alternative models using enhanced Claude Code headless mode with stream-JSON output, session management, and cost tracking.
+
+**Actual Command:**
+```bash
+ccs {profile} -p "prompt"
+```
+
+Internally executes:
+```bash
+claude -p "prompt" --settings ~/.ccs/{profile}.settings.json --output-format stream-json --permission-mode acceptEdits
+```
+
+**Docs:** https://code.claude.com/docs/en/headless.md
+
+## How It Works
+
+**Workflow:**
+1. User: `/ccs:glm "task"` in Claude Code session
+2. CCS detects `-p` flag and routes to HeadlessExecutor
+3. HeadlessExecutor spawns: `claude -p "task" --settings ~/.ccs/glm.settings.json --output-format stream-json --permission-mode acceptEdits`
+4. Claude Code runs headless with GLM profile + enhanced flags
+5. Returns stream-JSON with session_id, cost, turns
+6. Real-time tool use visibility in TTY
+7. ResultFormatter displays formatted results with metadata
+
+**Enhanced Features:**
+- Stream-JSON output parsing (`--output-format stream-json`)
+- Real-time tool use visibility (e.g., `[Tool Use: Bash]`)
+- Session persistence (`~/.ccs/delegation-sessions.json`)
+- Cost tracking (displays USD cost per execution)
+- Time-based limits (10 min default timeout with graceful termination)
+- Multi-turn session management (resume via session_id)
+- Formatted ASCII box output
+
+## Profile Settings
+
+**Location:** `~/.ccs/{profile}.settings.json`
+
+**Examples:**
+- GLM: `~/.ccs/glm.settings.json`
+- Kimi: `~/.ccs/kimi.settings.json`
+
+**Example content:**
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "ANTHROPIC_AUTH_TOKEN": "your-glm-api-key",
+    "ANTHROPIC_MODEL": "glm-4.6"
+  }
+}
+```
+
+## Output Format
+
+**Stream-JSON Mode** (automatically enabled):
+Each message is a separate JSON object (jsonl format):
+```json
+{"type":"init","session_id":"abc123def456"}
+{"type":"user","message":{"role":"user","content":"Task description"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash"}]}}
+{"type":"result","subtype":"success","total_cost_usd":0.0025,"num_turns":3,"session_id":"abc123def456","result":"Task completed"}
+```
+
+**Real-time Progress** (TTY only):
+```
+[i] Delegating to GLM-4.6...
+[Tool Use: Write]
+[Tool Use: Write]
+[Tool Use: Bash]
+[i] Execution completed in 1.5s
+```
+
+**Formatted Output** (displayed to user):
+```
+╔══════════════════════════════════════════════════════╗
+║ Working Directory: /path/to/project                 ║
+║ Model: GLM-4.6                                       ║
+║ Duration: 1.5s                                       ║
+║ Exit Code: 0                                         ║
+║ Session ID: abc123de                                 ║
+║ Cost: $0.0025                                        ║
+║ Turns: 3                                             ║
+╚══════════════════════════════════════════════════════╝
+```
+
+**Extracted Fields:**
+- `session_id` - For multi-turn (--resume)
+- `total_cost_usd` - Cost per execution
+- `num_turns` - Turn count
+- `is_error` - Error flag
+- `result` - Task output
+
+**Exit codes:** 0 = success, non-zero = error
+
+## Multi-Turn Sessions
+
+**Start session:**
+```bash
+ccs glm -p "implement feature"
+```
+
+**Continue session:**
+```bash
+ccs glm:continue -p "add tests"
+ccs glm:continue -p "run tests"
+```
+
+Via slash commands:
+```
+/ccs:glm "implement feature"
+/ccs:glm:continue "add tests"
+```
+
+**Session Storage:** `~/.ccs/delegation-sessions.json`
+
+**Metadata:**
+- Session ID
+- Total cost (aggregated across turns)
+- Turn count
+- Last turn timestamp
+- Working directory
+
+**Expiration:** ~30 days, auto-cleanup
+
+## Usage Patterns
+
+**Single execution:**
+```bash
+ccs glm -p "task description"
+```
+
+**With options:**
+```bash
+ccs glm -p "task" --permission-mode plan
+```
+
+**Continue session:**
+```bash
+ccs glm:continue -p "follow-up task"
+```
+
+All standard Claude Code headless flags are supported. See: https://code.claude.com/docs/en/headless.md
+
+## Error Handling
+
+**Common errors:**
+- `Settings file not found` - Profile not configured (`ccs doctor` to diagnose)
+- `Claude CLI not found` - Install Claude Code
+- `Invalid API key` - Check profile settings in `~/.ccs/{profile}.settings.json`
+
+**Diagnostics:**
+```bash
+ccs doctor          # Check configuration
+ccs --version       # Show delegation status
+```
+
+---
+
+## Related Documentation
+
+**Entry Point**: `../SKILL.md` - Quick start and decision framework
+**Decision Guide**: `delegation-guidelines.md` - When to delegate
+**Error Recovery**: `troubleshooting.md` - Common issues
+
+**Official Docs**: https://code.claude.com/docs/en/headless.md