Claude CLI Advanced Starter Pack (CCASP)

╔═══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║   ╔═╗╦  ╔═╗╦ ╦╔╦╗╔═╗  ╔═╗╔╦╗╦  ╦╔═╗╔╗╔╔═╗╔═╗╔╦╗  ╔═╗╔╦╗╔═╗╦═╗╔╦╗╔═╗╦═╗       ║
║   ║  ║  ╠═╣║ ║ ║║║╣   ╠═╣ ║║╚╗╔╝╠═╣║║║║  ║╣  ║║  ╚═╗ ║ ╠═╣╠╦╝ ║ ║╣ ╠╦╝       ║
║   ╚═╝╩═╝╩ ╩╚═╝═╩╝╚═╝  ╩ ╩═╩╝ ╚╝ ╩ ╩╝╚╝╚═╝╚═╝═╩╝  ╚═╝ ╩ ╩ ╩╩╚═ ╩ ╚═╝╩╚═       ║
║                                                                               ║
║                          v1.8.30  •  Production Ready                         ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

Table of Contents

• Overview
• What's New in v1.8.30
• Agent Orchestration
• Key Features
• Refactoring System
• Project Scaffolding
• Auto-Generated Agents
• Architecture
• Quick Start
• Installation Options
• Commands Reference
• Hook Templates
• Agent Patterns
• Utility Scripts
• Configuration
• Template Engine
• API Reference
• Tech Stack Detection
• Feature Presets
• MCP Server Integration
• Troubleshooting
• Contributing

Overview

CCASP is a two-phase toolkit that extends Claude Code CLI capabilities:

What This Means for You

1. Terminal Commands (ccasp wizard, ccasp init) run without AI — they read your project files and generate configuration
2. Slash Commands (/menu, /deploy-full) run inside Claude Code CLI with full AI capabilities

What's New in v1.8.30

Major additions in v1.8.x:

Happy.engineering Mobile UI (v1.8.30) - NEW!

• Auto-Detection: Detects Happy CLI via environment variables (HAPPY_HOME_DIR, HAPPY_SERVER_URL, HAPPY_WEBAPP_URL, HAPPY_EXPERIMENTAL, HAPPY_SESSION)
• Mobile-Optimized Formatting: 40-character max width, card-based layouts
• Word-Aware Wrapping: Text wraps at word boundaries (no mid-word breaks)
• Box-Drawing Characters: Consistent UI with ┌─┐│├┤└┘
• Updated Commands: /menu, /pr-merge, /menu-issues-list, /ccasp-panel all support mobile formatting
• happy-mode-detector Hook: Runs on session start, caches detection for 4 hours

PR Merge Command (v1.8.29)

• /pr-merge: Interactive PR merge with 9-phase workflow
• Safety Checkpoint: Stashes changes, records state before any modifications
• Automatic Rollback: Reverts on any failure
• Blocker Resolution: Handles draft, outdated, conflicts, CI failures, pending reviews
• Contributor Messaging: Thank-you messages before merge
• Mobile Card Layout: PR selection with mobile-friendly cards

Smart Update System (v1.8.28)

• Smart Update Mode (A): Protects customizations while adding new features
• Full Overwrite Mode (B): Replaces all .claude/ assets (preserves config)
• Auto-Repair Hooks: Outdated hooks repaired during ccasp init
• /update-smart: New command for intelligent updates

Roadmap Orchestration Framework (v1.8.27)

• Manual Builder (Mode A): Natural language to structured phases
• GitHub Integration (Mode B): Issue import with table selection, epic hierarchy
• Commands: /roadmap-status, /roadmap-edit, /roadmap-track
• Storage: .claude/roadmaps/{slug}.json, .claude/phase-plans/{slug}/
• Auto-Advance: Dependency checking, progress tracking

Dev Mode & Utilities (v1.8.26)

• Dev Mode: ccasp init --dev for rapid template testing
• Project Backup: Automatic backup before overwrites (.ccasp-backup/)
• Configurable Co-Authors: commit.coAuthors in tech-stack.json

Agent Orchestration System (v1.8.24)

• Hierarchical Agent Execution: L1 Orchestrator → L2 Specialists → L3 Workers
• Automatic PROGRESS.json Updates: Agents report completion, state auto-updates
• GitHub Issue Sync: Progress comments pushed to linked issues
• Enforcement Hooks: 11 new hooks for hierarchy validation, error recovery, audit logging
• L2 Domain Specialists: Frontend, backend, testing, deployment experts
• L3 Worker Templates: Search, analyze, validate, lint workers (Haiku model for cost efficiency)
• Error Recovery: Retry/escalate/abort strategies with max retry limits
• Audit Logging: All agent actions logged to .claude/logs/orchestrator-audit.jsonl
• /orchestration-guide: Quick reference for spawning agents and completion formats

Roadmap Orchestration Framework (v1.8.27)

• Manual Builder (Mode A): Natural language to structured phases
• GitHub Integration (Mode B): Issue import with table selection, epic hierarchy
• Dependency Graphs: Automatic cycle detection, topological ordering
• Commands: /roadmap-status, /roadmap-edit, /roadmap-track
• Storage: .claude/roadmaps/{slug}.json, .claude/phase-plans/{slug}/
• Phase-Dev Integration: Auto-generate PROGRESS.json from roadmap phases
• Execution Tracking: Dependency checking, progress tracking, auto-advance
• GitHub Epic Hierarchy: Auto-create epic → child issue structure

Refactoring System (v1.8.19-1.8.22)

• /ralph: Ralph Loop - continuous test-fix cycles until all tests pass
• /refactor-workflow: Guided refactoring with branch, task list, GitHub issue, and specialist agent
• /refactor-analyze: Deep complexity analysis and code smell detection
• /golden-master: Characterization tests before refactoring
• /project-explorer: Fresh project scaffolding wizard for empty directories
• 4 new hooks: ralph-loop-enforcer, refactor-verify, refactor-audit, refactor-transaction
• 2 new skills: refactor-react, refactor-fastapi

Auto-Generated Agents (v1.8.16-1.8.18)

• Stack-specific agents: Auto-generate L1/L2/L3 agents from detected tech stack
• 18 agent templates: React, Vue, FastAPI, Express, Prisma, Playwright, and more
• Delegation hooks: task-classifier, agent-delegator, delegation-enforcer
• Agent-only mode: Enforce agent usage for complex tasks

Previous Features

• ccasp init --dev: Dev mode for rapid template testing
• Mobile-optimized menus: Single-char inputs for Happy.Engineering

100+ components across 11 implementation phases:

Key Features

Core Capabilities

Hook Templates (40 Total)

Token & Session Hooks

Deployment & Git Hooks

Refactoring Hooks (NEW)

Agent Delegation Hooks

Agent Orchestration Hooks (NEW v1.8.24)

Phase & Validation Hooks

Happy.Engineering Hooks

Agent Patterns (5 Patterns)

Skill Templates (5 Skills)

Utility Scripts (7 Scripts)

Agent Orchestration

The Agent Orchestration System (v1.8.24) enables hierarchical agent execution for phased development plans:

Hierarchy

L1 Orchestrator (You / Main Conversation)
├── L2 Frontend Specialist (Sonnet)
│   ├── L3 Component Search Worker (Haiku)
│   └── L3 Style Analyzer Worker (Haiku)
├── L2 Backend Specialist (Sonnet)
│   └── L3 API Discovery Worker (Haiku)
├── L2 Testing Specialist (Sonnet)
│   └── L3 Coverage Analyzer Worker (Haiku)
└── L2 Deployment Specialist (Sonnet)
    └── L3 Config Validator Worker (Haiku)

How It Works

1. Create an Orchestrated Plan: Use /phase-dev-plan and select "Orchestrated"
2. Orchestrator Initializes: State file created at .claude/orchestrator/state.json
3. Spawn L2 Specialists: Task tool with domain-specific prompts
4. L2 Spawns L3 Workers: For atomic subtasks (search, analyze, validate)
5. Completion Reports: Agents output TASK_COMPLETE: {taskId} format
6. Auto-Update Progress: progress-tracker hook updates PROGRESS.json
7. GitHub Sync: Progress comments pushed to linked issues

Completion Report Format

All agents must end with one of:

TASK_COMPLETE: P1.1
ARTIFACTS: src/Button.tsx, src/Button.test.tsx
SUMMARY: Created button component with tests

TASK_FAILED: P1.1
ERROR: Database connection refused

TASK_BLOCKED: P1.1
BLOCKER: Waiting for API credentials from admin

Enabling Orchestration

# Option 1: During init
ccasp init  # Select "Agent Orchestration System"

# Option 2: Add to existing project
ccasp update-check  # Select "agentOrchestration" feature

Key Files

Quick Reference

Use /orchestration-guide inside Claude Code for spawning syntax, error handling, and domain detection rules.

Happy.engineering Mobile UI

CCASP v1.8.30 includes comprehensive mobile UI support for Happy.engineering CLI wrapper.

Detection

Happy mode is auto-detected via environment variables:

# Any of these trigger mobile formatting:
HAPPY_HOME_DIR=/path/to/.happy
HAPPY_SERVER_URL=https://...
HAPPY_WEBAPP_URL=https://...
HAPPY_EXPERIMENTAL=true
HAPPY_SESSION=true

Mobile Formatting Rules

Box-Drawing Characters

┌────────────────────────────────────┐  Top border
│ Content line here                  │  Vertical
├────────────────────────────────────┤  Separator
│ More content                       │
└────────────────────────────────────┘  Bottom border

Supported Commands

Example: Desktop vs Mobile

Desktop (76 chars):

╔══════════════════════════════════════════════════════════════════════════╗
║  #   │ Issue        │ Status   │ Priority │ Assigned       │ Updated    ║
╠══════════════════════════════════════════════════════════════════════════╣
║  42  │ Add JWT auth │ Ready    │ High     │ @johndoe       │ 2h ago     ║
╚══════════════════════════════════════════════════════════════════════════╝

Mobile (40 chars):

┌────────────────────────────────────┐
│ [1] Issue #42                      │
│ Add JWT auth                       │
├────────────────────────────────────┤
│ Status: Ready                      │
│ Priority: High                     │
│ @johndoe • 2h ago                  │
└────────────────────────────────────┘

Enabling Happy Mode

Happy mode is auto-detected when running via Happy CLI. For testing:

# Set environment variable
export HAPPY_HOME_DIR=/path/to/.happy

# Run any CCASP command
/menu  # Will display mobile format

Key Files

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    CCASP ARCHITECTURE (v1.8.30)                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  PHASE 1: TERMINAL (No AI)                                                   │
│  ─────────────────────────                                                   │
│                                                                              │
│  npm install ──► postinstall ──► ccasp wizard                                │
│                                                                              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  │
│  │  Tech Stack  │──►│   Template   │──►│   Feature    │──►│    Agent     │  │
│  │  Detection   │   │   Engine     │   │  Selection   │   │  Generation  │  │
│  └──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘  │
│         │                  │                  │                  │           │
│         ▼                  ▼                  ▼                  ▼           │
│  ┌──────────────────────────────────────────────────────────────────┐       │
│  │                    YOUR PROJECT (.claude/)                        │       │
│  │  commands/ │ config/agents.json │ skills/ │ hooks/ │ scripts/    │       │
│  └──────────────────────────────────────────────────────────────────┘       │
│                                                                              │
│  PHASE 2: CLAUDE CODE CLI (AI-Powered)                                       │
│  ─────────────────────────────────────                                       │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────┐       │
│  │                     RESTART REQUIRED                              │       │
│  │                            ↓                                      │       │
│  │  /menu │ /ralph │ /refactor-workflow │ /project-explorer │ ...   │       │
│  │                                                                   │       │
│  │  ┌─────────────────────────────────────────────────────────────┐ │       │
│  │  │ REFACTORING SYSTEM                                          │ │       │
│  │  │ /ralph → ralph-loop-enforcer → test → fix → repeat          │ │       │
│  │  │ /golden-master → characterization tests → verify            │ │       │
│  │  │ refactor-transaction → savepoints → rollback                │ │       │
│  │  └─────────────────────────────────────────────────────────────┘ │       │
│  │                                                                   │       │
│  │  ┌─────────────────────────────────────────────────────────────┐ │       │
│  │  │ AGENT DELEGATION                                            │ │       │
│  │  │ task-classifier → agent-delegator → specialist agent        │ │       │
│  │  │ L1 Orchestrator ──► L2 Specialist ──► L3 Worker             │ │       │
│  │  └─────────────────────────────────────────────────────────────┘ │       │
│  │                                                                   │       │
│  │  Hooks: PreToolUse | PostToolUse | UserPromptSubmit              │       │
│  │  Skills: refactor-react | refactor-fastapi | agent-creator       │       │
│  └──────────────────────────────────────────────────────────────────┘       │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Directory Structure

After running ccasp init, your project gets:

.claude/
├── commands/              # Slash commands (markdown with YAML frontmatter)
│   ├── menu.md           # Interactive menu
│   ├── ccasp-setup.md    # Setup wizard
│   ├── deploy-full.md    # Deployment command
│   └── ...               # 25+ commands based on feature selection
├── agents/               # L1/L2/L3 agent definitions
├── skills/               # RAG-enhanced skill packages
│   └── skill-name/
│       ├── skill.md      # Definition
│       ├── context/      # Knowledge base
│       └── workflows/    # Procedures
├── hooks/                # Enforcement hooks (12 templates available)
│   ├── pre-tool-use/
│   ├── post-tool-use/
│   └── user-prompt-submit/
├── scripts/              # Utility scripts (7 available via install-scripts)
├── docs/                 # Generated documentation
├── phase-dev/            # Phased development projects
├── settings.json         # Hook configuration
└── tech-stack.json       # Detected/configured values

Quick Start

# Step 1: Install globally
npm install -g claude-cli-advanced-starter-pack

# Step 2: Run the setup wizard (terminal command - no AI needed)
ccasp wizard

# Step 3: IMPORTANT - Restart Claude Code CLI
#         Changes to .claude/ require a new session
claude .

# Step 4: Use slash commands inside Claude (AI-powered)
/menu

Post-Install Commands

# Install additional skills after init
ccasp install-skill

# Install utility scripts
ccasp install-scripts

# Explore MCP servers for your stack
ccasp explore-mcp --recommend

Installation Options

Option A: Global Installation (Recommended)

npm install -g claude-cli-advanced-starter-pack
ccasp wizard

Option B: Project-Local Installation

npm install --save-dev claude-cli-advanced-starter-pack
npx ccasp wizard

Option C: One-Time Use

npx claude-cli-advanced-starter-pack init

CLI Aliases

All aliases point to the same CLI:

ccasp                           # Short form (recommended)
ccasp w                         # Wizard shortcut
claude-advanced                 # Medium form
claude-cli-advanced-starter-pack # Full name

Dev Mode (v1.8.26+)

For template development and rapid testing:

# Enable dev mode - templates read directly from package
ccasp init --dev

# Changes to templates/ reflect immediately
# No need to reinstall package between edits

Project Backup (v1.8.26+)

Before overwriting .claude/, CCASP creates automatic backups:

# Backups stored in:
.ccasp-backup/
├── 2026-02-01T12-00-00/
│   └── .claude/          # Complete backup
└── 2026-02-01T14-30-00/
    └── .claude/          # Another backup

Configurable Co-Authors (v1.8.26+)

Configure commit co-author attribution in tech-stack.json:

{
  "commit": {
    "coAuthors": {
      "enabled": true,
      "authors": [
        { "name": "Claude", "email": "noreply@anthropic.com" },
        { "name": "Happy", "email": "yesreply@happy.engineering" }
      ]
    }
  }
}

When enabled: false (default), no co-authors are added to commits.

Commands Reference

Terminal Commands (Shell — No AI)

Slash Commands (Inside Claude Code CLI — AI-Powered)

Core Commands (Always Installed)

Feature-Specific Commands

Refactoring Commands (NEW in v1.8.19+)

Project Scaffolding Commands (NEW in v1.8.22+)

PR & Git Commands (NEW in v1.8.29+)

Roadmap Commands (NEW in v1.8.27+)

PR Merge Workflow

The /pr-merge command (v1.8.29) provides a safe, interactive PR merge workflow:

9-Phase Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                          /pr-merge WORKFLOW                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Phase 1: Identify PR (current branch or explicit number)                   │
│  Phase 2: Create safety checkpoint (stash, record state)                    │
│  Phase 3: Detect all blockers (draft, outdated, conflicts, CI, reviews)     │
│  Phase 4: Resolve blockers one-by-one with user choice                      │
│  Phase 5: Offer contributor thank-you message                               │
│  Phase 6: Select merge method (squash/merge/rebase)                         │
│  Phase 7: Execute merge with confirmation                                   │
│  Phase 8: Post-merge cleanup (checkout base, prune)                         │
│  Phase 9: Success summary with next steps                                   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Blocker Types & Resolution

Safety Features

• Automatic Stash: Uncommitted changes saved before operations
• State Recording: Original branch, HEAD, and status recorded
• Automatic Rollback: On any failure, reverts to original state
• Dry-Run Mode: Preview changes without executing (/pr-merge --dry-run)

Usage

# Merge PR for current branch
/pr-merge

# Merge specific PR by number
/pr-merge 123

# Preview without changes
/pr-merge --dry-run

Roadmap Orchestration

The Roadmap Orchestration Framework (v1.8.27) enables multi-phase project planning with GitHub integration.

Creation Modes

Roadmap Structure

{
  "slug": "my-feature",
  "phases": [
    {
      "id": "P1",
      "name": "Discovery",
      "tasks": ["Research existing implementation", "Document requirements"],
      "dependencies": [],
      "status": "completed"
    },
    {
      "id": "P2",
      "name": "Implementation",
      "tasks": ["Build core feature", "Write tests"],
      "dependencies": ["P1"],
      "status": "in_progress"
    }
  ]
}

Commands

GitHub Epic Integration

When creating from GitHub issues, the framework:

1. Groups Issues: By label, milestone, or project column
2. Creates Epic: Parent issue linking all child issues
3. Tracks Progress: Updates epic when children complete
4. Syncs Status: Bidirectional sync with Project Board

Storage

Hook Templates

CCASP includes 30+ production-ready hook templates:

Token & Session Management

// token-usage-monitor: Auto-respawn at 90% threshold
{
  event: "PostToolUse",
  trigger: async (context) => {
    const usage = context.tokenUsage;
    if (usage.percentage > 90) {
      await respawnSession();
    }
  }
}

Deployment Automation

// branch-merge-checker: Block deploy on diverged branches
{
  event: "PreToolUse",
  tools: ["mcp__railway-mcp-server__deployment_trigger"],
  check: async () => {
    const { stdout } = await exec('git status -sb');
    if (stdout.includes('ahead') || stdout.includes('behind')) {
      return { allow: false, reason: "Branch not synced with main" };
    }
  }
}

Installing Hooks

# Via init wizard
ccasp init  # Select 'advancedHooks' feature

# Manually copy templates
cp templates/hooks/*.template.js .claude/hooks/

Agent Patterns

L1→L2 Orchestration

For tasks requiring parallel specialist agents:

                    ┌─────────────────────┐
                    │   L1 Orchestrator   │
                    │   - Decompose task  │
                    │   - Dispatch L2s    │
                    │   - Aggregate       │
                    └─────────────────────┘
                             ↓
        ┌────────────────────┼────────────────────┐
        ↓                    ↓                    ↓
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│ L2 Specialist │    │ L2 Specialist │    │ L2 Specialist │
│   (Search)    │    │   (Analyze)   │    │   (Document)  │
└───────────────┘    └───────────────┘    └───────────────┘

Multi-Phase Orchestration

For complex projects with sequential phases:

const phases: Phase[] = [
  { id: 'discovery', parallel: true, tasks: [...] },
  { id: 'planning', parallel: false, tasks: [...] },
  { id: 'implementation', parallel: true, tasks: [...] },
  { id: 'testing', parallel: false, tasks: [...] }
];

// Execute with validation gates between phases
const result = await executePhases(phases);

See templates/patterns/ for complete documentation.

Refactoring System

CCASP v1.8.19+ includes a comprehensive refactoring system designed for 98%+ success rate:

Commands

Ralph Loop Pattern

Named after Ralph Wiggum ("I'm helping!"), this pattern runs tests continuously and fixes failures:

┌─────────────────────────────────────────────────────────────┐
│                       RALPH LOOP                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Run tests ──► 2. Parse failures ──► 3. Fix code         │
│       ↑                                      │               │
│       └──────────────────────────────────────┘               │
│                                                              │
│  Stops when: All tests pass OR max iterations (10)          │
│              OR same failure repeated 3 times                │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Refactoring Hooks

Golden Master Pattern

Capture current behavior as "characterization tests" before refactoring:

/golden-master src/utils/calculateTotal.ts
# Creates .claude/golden-master/calculateTotal.master.json
# Generates test inputs: edge cases, boundary values, typical cases
# Captures actual outputs (not expected - ACTUAL behavior)

# After refactoring, verify behavior unchanged:
/golden-master src/utils/calculateTotal.ts --verify

Project Scaffolding

For fresh/empty directories, CCASP provides /project-explorer - an interactive scaffolding wizard:

Supported Project Types

Workflow

ccasp wizard (in empty directory)
       ↓
"No codebase detected - scaffold new project?"
       ↓ [Yes]
/project-explorer triggers
       ↓
Interview: name, type, language, framework, database, features
       ↓
Generate: skeleton files, config, dependencies
       ↓
Install: npm install / pip install
       ↓
Deploy: CCASP commands to .claude/
       ↓
"Project scaffolded! Run /create-task-list to continue"

Auto-Generated Agents

CCASP v1.8.16+ auto-generates specialist agents from your detected tech stack:

Available Agent Templates (18)

How It Works

# During init, after tech stack detection:
ccasp init
# Detected: React, FastAPI, PostgreSQL, Playwright

# Auto-generates agents in .claude/config/agents.json:
{
  "frontend-react-specialist": { "model": "sonnet", "expertise": ["hooks", "components"] },
  "backend-fastapi-specialist": { "model": "sonnet", "expertise": ["routers", "pydantic"] },
  "database-postgresql-specialist": { "model": "sonnet", "expertise": ["migrations", "queries"] },
  "testing-playwright-specialist": { "model": "sonnet", "expertise": ["e2e", "selectors"] }
}

Delegation Hooks

Utility Scripts

Installation

ccasp install-scripts
# Interactive selection of 7 scripts

Usage Examples

# Pre-deployment validation
node .claude/scripts/validate-deployment.js --platform railway

# Poll deployment status
node .claude/scripts/poll-deployment-status.js \
  --platform railway \
  --deployment-id abc123 \
  --timeout 300

# Scan roadmaps for progress
node .claude/scripts/roadmap-scanner.js --output json

# Analyze Claude delegation logs
node .claude/scripts/analyze-delegation-log.js \
  ~/.claude/logs/delegation.jsonl --cost-estimate

# Security audit git history
python .claude/scripts/git-history-analyzer.py --patterns "password|secret"

Configuration

tech-stack.json

Auto-generated during init with detected and configured values:

{
  "version": "2.0.0",
  "project": {
    "name": "my-project",
    "type": "fullstack"
  },
  "frontend": {
    "framework": "react",
    "port": 5173,
    "buildCommand": "npm run build",
    "devCommand": "npm run dev",
    "distDir": "dist"
  },
  "backend": {
    "framework": "fastapi",
    "port": 8001,
    "language": "python",
    "healthEndpoint": "/health"
  },
  "database": {
    "type": "postgresql",
    "orm": "prisma"
  },
  "testing": {
    "unit": "vitest",
    "e2e": "playwright",
    "unitCommand": "npm test",
    "e2eCommand": "npm run test:e2e"
  },
  "deployment": {
    "frontend": {
      "platform": "cloudflare",
      "projectName": "my-app"
    },
    "backend": {
      "platform": "railway",
      "projectId": "{{DEPLOY_BACKEND_PROJECT_ID}}"
    }
  },
  "features": {
    "githubIntegration": true,
    "phasedDevelopment": true,
    "advancedHooks": true,
    "refactoring": true,
    "skillTemplates": true
  }
}

settings.json

Configure hooks and agent behavior:

{
  "hooks": {
    "enabled": true,
    "preToolUse": ["file-guard", "token-guardian", "branch-merge-checker"],
    "postToolUse": ["test-enforcer", "github-progress", "autonomous-decision-logger"],
    "userPromptSubmit": ["context-loader", "session-id-generator"]
  },
  "agents": {
    "defaultModel": "sonnet",
    "maxTokensPerTask": 8000
  }
}

Template Engine

CCASP uses a Handlebars-style template engine for platform-agnostic configuration.

Supported Syntax

Template Example

{{#if deployment.backend.platform}}
## Backend Deployment

{{#if (eq deployment.backend.platform "railway")}}
Using Railway MCP:

mcp__railway-mcp-server__deployment_trigger({ projectId: "{{deployment.backend.projectId}}", serviceId: "{{deployment.backend.serviceId}}" })

{{/if}}

{{#if (eq deployment.backend.platform "vercel")}}
Using Vercel:
```bash
vercel --prod

{{/if}} {{else}} ⚠️ Backend deployment not configured {{/if}}

---

## API Reference

### Programmatic Usage

```javascript
import {
  // Setup & Detection
  runSetupWizard,
  detectTechStack,
  runClaudeAudit,

  // Template Processing
  replacePlaceholders,
  processFile,
  processDirectory,
  generateTechStack,

  // GitHub Integration
  isAuthenticated,
  getCurrentUser,
  createIssue,
  addIssueToProject,

  // Codebase Analysis
  searchFiles,
  searchContent,
  findDefinitions,
  analyzeForIssue,

  // Scripts & Skills
  runInstallScripts,
  installSkillCommand,
} from 'claude-cli-advanced-starter-pack';

Key Functions

detectTechStack(projectPath: string): Promise<TechStack>

Detects project technology stack by reading configuration files:

const techStack = await detectTechStack(process.cwd());
console.log(techStack.frontend.framework); // "react"
console.log(techStack.backend.framework);  // "fastapi"

replacePlaceholders(content: string, values: object, options?: object)

Process templates with values:

const template = '{{project.name}} uses {{frontend.framework}}';
const { content, warnings } = replacePlaceholders(template, techStack);
// content: "my-app uses react"

Tech Stack Detection

CCASP detects 40+ frameworks and tools by reading project files (no AI required):

Detection Sources

Detected Categories

• Frontend: React, Vue, Angular, Svelte, Next.js, Nuxt, Astro
• Backend: FastAPI, Express, NestJS, Django, Flask, Rails, Gin
• Database: PostgreSQL, MySQL, MongoDB, SQLite, Redis
• ORM: Prisma, TypeORM, SQLAlchemy, Drizzle
• Testing: Jest, Vitest, Mocha, pytest, Playwright, Cypress
• Deployment: Railway, Vercel, Netlify, Cloudflare, Heroku, AWS

Feature Presets

During setup, choose a preset for quick configuration:

Update System

CCASP v1.8.28 includes a smart update system for managing project updates:

Update Modes

Smart Update Features

• Customization Protection: Detects modified files and prompts before overwriting
• Selective Updates: Choose which features to add or update
• Auto-Repair: Outdated hooks automatically repaired during ccasp init
• State Tracking: Update history stored in .claude/config/ccasp-state.json

Update Flow

/update-smart or /update-check
       ↓
Check npm registry for new version
       ↓
Compare installed vs latest
       ↓
   ┌───────────┴───────────┐
   │                       │
Up to date           Update available
   ↓                       ↓
"All good!"          Show highlights
                           ↓
                   ┌───────┴───────┐
                   │               │
              Smart (A)       Full (B)
                   │               │
                   ↓               ↓
            Merge changes    Overwrite all
            Keep customs     Fresh install

Auto-Repair

When running ccasp init, outdated hooks are detected and repaired:

# During init
[REPAIR] Found outdated hooks:
  • ccasp-update-check.js (v1.8.25 → v1.8.30)
  • happy-mode-detector.js (v1.8.24 → v1.8.30)

Auto-repairing... Done!

MCP Server Integration

CCASP helps discover and configure Model Context Protocol (MCP) servers:

ccasp explore-mcp              # Interactive menu
ccasp explore-mcp --recommend  # Auto-recommend based on codebase
ccasp explore-mcp --testing    # Quick install Playwright + Puppeteer

Supported MCP Servers (v1.7.0+)

Prerequisites

GitHub CLI Setup (for GitHub features)

gh auth login
gh auth status

Troubleshooting

Common Issues

Debug Commands

ccasp detect-stack --verbose    # See all detected values
ccasp install-scripts --list    # List available scripts
ccasp install-skill --list      # List available skills
ccasp claude-audit              # Audit CLAUDE.md quality

Contributing

Contributions welcome! Please read our contributing guidelines.

Development Setup

git clone https://github.com/evan043/claude-cli-advanced-starter-pack.git
cd claude-cli-advanced-starter-pack
npm install
npm run lint
npm test

Code Structure

src/
├── commands/           # 30+ command implementations
├── cli/               # Interactive menu system (desktop + mobile)
├── github/            # GitHub API wrapper
├── agents/            # Agent generator, registry, stack-mapping
│   ├── generator.js   # Auto-generate agents from tech stack
│   ├── registry.js    # Agent registry management
│   ├── schema.js      # Agent schema definitions
│   └── stack-mapping.js # Tech stack → agent mapping
├── hooks/             # Hook configuration
├── panel/             # Control panel system
├── utils/             # Template engine, validators, paths
└── index.js           # Main exports

templates/
├── commands/          # Slash command templates (30+)
├── hooks/             # Hook templates (26)
├── skills/            # Skill templates (5)
├── agents/            # Agent templates (18 framework-specific)
│   ├── frontend/      # React, Vue, Angular, Svelte, Next.js
│   ├── backend/       # FastAPI, Express, NestJS, Django
│   ├── database/      # PostgreSQL, Prisma
│   ├── state/         # Redux, Zustand, Pinia
│   ├── deployment/    # Railway, Cloudflare
│   └── testing/       # Playwright, Vitest
├── patterns/          # Agent patterns (5)
├── scripts/           # Utility scripts (7)
└── docs/              # Doc templates (5)

License

MIT © evan043