Claude CLI Advanced Starter Pack (CCASP)

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

Table of Contents

• Overview
• What's New in v1.8.24
• 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.24

Major additions in v1.8.x:

Agent Orchestration System (v1.8.24) - NEW!

• 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 Management System (v1.8.23)

• Multi-phase Roadmaps: ROADMAP.json with dependency graphs
• GitHub Epic Hierarchy: Auto-create epic → child issue structure
• Complexity Detection: Recommends roadmaps for plans with 30+ tasks
• Auto Documentation: Generate architecture docs from roadmap 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

90+ components across 10 implementation phases:

Key Features

Core Capabilities

Hook Templates (26 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.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    CCASP ARCHITECTURE (v1.8.22)                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  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

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+)

Hook Templates

CCASP includes 12 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:

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