ccs/docs/development-workflow.md

CCS Workflow Documentation

Workflow documentation for CCS v2.0.0 covering installation, runtime behavior, and troubleshooting.

---

Architecture Overview

User Command: ccs [profile] [claude-args...]
         │
         ▼
┌─────────────────┐
│  ccs (wrapper)  │  ← Bash (Unix) or PowerShell (Windows)
└────────┬────────┘
         │
         ├─ 1. Read ~/.ccs/config.json
         ├─ 2. Lookup profile → settings file
         ├─ 3. Validate settings file exists
         │
         ▼
    ┌────────────────┐
    │ Profile System │
    └───────┬────────┘
            │
            ├─ default: ~/.claude/settings.json
            └─ glm: ~/.ccs/glm.settings.json
            │
            ▼
    ┌──────────────────┐
    │   Claude CLI     │
    └──────────────────┘

Key Components

1. ccs wrapper: Lightweight script (bash/PowerShell)
2. Config file: ~/.ccs/config.json (profile → settings mappings)
3. Settings files: Claude CLI settings JSON format
4. Claude CLI: Official Anthropic CLI (unchanged)

Design Principles

• YAGNI: Only 2 profiles (default/glm)
• KISS: Simple delegation, no magic
• DRY: One source of truth (config.json)
• Non-invasive: Never modifies ~/.claude/settings.json

---

Installation Workflow

Process

1. Create directories: ~/.ccs/, ~/.local/bin/
2. Install executables:
   • Git mode: Symlink from repo
   • Standalone: Download from GitHub
3. Install .claude folder: Commands and skills
4. Create config: config.json if missing
5. Create GLM profile: glm.settings.json if missing
6. Backup: Single config.json.backup (overwrites)
7. Validate: Check JSON syntax

Files Created

~/.ccs/
├── ccs                     # Main executable
├── config.json             # Profile mappings
├── config.json.backup      # Single backup (no timestamp)
├── glm.settings.json       # GLM profile
├── uninstall.sh            # Uninstaller
└── .claude/                # Claude Code integration
    ├── commands/ccs.md
    └── skills/ccs-delegation/

---

Runtime Workflow

Unix/Linux/macOS

ccs [profile] [args]
  ↓
Read config.json
  ↓
Lookup profile → settings file path
  ↓
Validate file exists
  ↓
exec claude --settings <path> [args]

Windows

ccs [profile] [args]
  ↓
Read config.json
  ↓
Lookup profile → settings file path
  ↓
Validate file exists
  ↓
exec claude --settings <path> [args]

---

Profile System

Config Structure

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}

Settings File Format

GLM Profile (~/.ccs/glm.settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_api_key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.6"
  }
}

Claude (Default) (~/.claude/settings.json):

• User-managed, CCS never modifies it
• Referenced by default profile

---

Troubleshooting

Profile Not Found

Check	Fix
config.json exists?	Run installer
Valid JSON?	Fix syntax or restore from backup
Profile in config?	Add profile or use default/glm
Settings file exists?	Create from template

PowerShell Crash (Windows)

Error: SetEnvironmentVariable error

Fix:

1. Check settings format has {"env": {...}}
2. Ensure all values are strings (not booleans/objects)
3. Remove non-env fields from settings file

Installation Issues

Issue	Fix
404 Not Found	Check installers exist in GitHub
Permission denied	Check ~/.ccs/ permissions
jq not found	Install jq: brew install jq (Unix)
PATH warning	Add ~/.local/bin to PATH

---

Key Points

1. Installation: Creates 2 profiles (glm + default), validates JSON
2. Runtime: Simple delegation to Claude CLI via --settings flag
3. Cross-platform: Identical behavior on Unix/Linux/macOS/Windows
4. Non-invasive: Never touches ~/.claude/settings.json
5. Validation: JSON syntax checking prevents errors
6. Backup: Single file, overwrites each install

---

Version: v2.0.0 Updated: 2025-11-02