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. **Platform Detection**: Windows vs Unix
2. **Create directories**: `~/.ccs/`, `~/.local/bin`
3. **Clean old installs**: Remove old `/usr/local/bin` installations (if CCS symlinks)
4. **Install executables**:
   - Git mode: Symlink from repo
   - Standalone: Download from GitHub
5. **Install .claude folder**: Commands and skills
6. **Create config**: `config.json` if missing
7. **Create GLM profile**: `glm.settings.json` if missing
8. **Backup**: Single `config.json.backup` (overwrites)
9. **Validate**: Check JSON syntax
10. **Configure PATH**: Auto-detect shell, add to profile
11. **Display instructions**: Shell reload, GLM API key (if needed)

### Unified Install Location (v2.2.0+)

**All Unix Systems**: `~/.local/bin/ccs`
- User-writable, no sudo required
- Auto PATH configuration for bash, zsh, fish
- Idempotent setup (safe to run multiple times)

**Windows**: `%USERPROFILE%\.ccs\ccs.ps1`
- Auto-added to user PATH

### Shell Profile Management

**Auto-detection** (`detect_shell_profile()`):
- Extracts shell from `$SHELL` variable
- Returns appropriate profile file:
  - bash: `~/.bashrc` (Linux) or `~/.bash_profile` (macOS)
  - zsh: `~/.zshrc`
  - fish: `~/.config/fish/config.fish`
- Validates shell name (alphanumeric only)
- Defaults to `~/.bashrc` if unknown

**PATH checking** (`check_path_configured()`):
- Tests if `~/.local/bin` in current `$PATH`
- Returns true if already configured

**PATH addition** (`add_to_path()`):
- Creates profile file if missing
- Checks for existing CCS marker comment
- Adds shell-specific PATH export:
  - bash/zsh: `export PATH="$HOME/.local/bin:$PATH"`
  - fish: `set -gx PATH $HOME/.local/bin $PATH`
- Idempotent: skips if already added

**Configuration workflow** (`configure_shell_path()`):
- Checks if PATH already configured
- Detects shell profile
- Adds PATH entry
- Shows reload instructions
- Fallback to manual instructions if fails

### Files Created

**Executable Locations**:
- macOS / Linux: `~/.local/bin/ccs` (symlink to `~/.ccs/ccs`)
- Windows: `%USERPROFILE%\.ccs\ccs.ps1`

**Configuration Directory** (`~/.ccs/`):
```
~/.ccs/
├── ccs                     # Main executable (symlink target)
├── config.json             # Profile mappings
├── config.json.backup      # Single backup (no timestamp)
├── glm.settings.json       # GLM profile
├── VERSION                 # Version file
├── 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

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

### Settings File Format

**GLM Profile** (`~/.ccs/glm.settings.json`):
```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 |

---

## Terminal Output Standards

### Color Functions

**TTY Detection**: Colors only shown when output is to terminal (not piped/redirected)
```bash
if [[ -t 2 ]] && [[ -z "${NO_COLOR:-}" ]]; then
  # Enable colors
else
  # Disable colors
fi
```

**NO_COLOR Support**: Respects `NO_COLOR` environment variable
```bash
export NO_COLOR=1  # Disables all color output
```

### Message Types

**Error Messages** (red, boxed):
```
╔═════════════════════════════════════════════╗
║  ERROR                                      ║
╚═════════════════════════════════════════════╝
```

**Critical Messages** (red, boxed, "ACTION REQUIRED"):
```
╔═════════════════════════════════════════════╗
║  ACTION REQUIRED                            ║
╚═════════════════════════════════════════════╝
```

**Warning Messages** (yellow):
```
[!] WARNING
```

**Success Messages** (green):
```
[OK] Success message
```

**Info Messages** (plain):
```
[i] Information
```

### ASCII Symbols (No Emojis)

All output uses ASCII symbols for compatibility:
- `[OK]` - Success
- `[!]` - Warning
- `[X]` - Error/Failure
- `[i]` - Information

## Key Points

1. **Installation**: Unified location (`~/.local/bin`), auto PATH config, validates JSON
2. **Runtime**: Simple delegation to Claude CLI via `--settings` flag
3. **Cross-platform**: Unified Unix location, identical behavior
4. **Non-invasive**: Never touches `~/.claude/settings.json`
5. **Validation**: JSON syntax checking prevents errors
6. **Backup**: Single file, overwrites each install
7. **Terminal Output**: TTY detection, NO_COLOR support, ASCII symbols only
8. **Shell Support**: Auto-detects bash, zsh, fish

---

**Version**: v2.2.0
**Updated**: 2025-11-03