Claude Starter Kit

Autonomous AI-driven development agents for Claude Code. One command to scaffold, then let Claude build your TypeScript project.

Framework-agnostic: Supports Angular, React, Vue, Svelte via frontend profiles. Optimized for Nx monorepo but works with standalone projects too.

Quick Start

npx create-claude-workspace

This scaffolds the .claude/ folder (agents, scripts, templates, Docker config) into your project.

Then initialize your project:

claude --agent project-initializer

Answer the discovery questions (non-technical). Claude generates the full pipeline:

• CLAUDE.md — architecture & conventions
• PRODUCT.md — product strategy & monetization (via product-owner agent)
• TODO.md — phased development plan (via technical-planner agent)
• MEMORY.md — progress tracking

Start Autonomous Development

Pick one:

• Unattended (recommended): npx create-claude-workspace run — clean context per task, survives rate limits
• Docker (fully isolated): npx create-claude-workspace docker — container sandbox, safe --skip-permissions
• Interactive: claude --agent orchestrator, then /ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md

npx Options

npx create-claude-workspace [directory]    # scaffold into a specific directory
npx create-claude-workspace --update       # overwrite agents with latest version
npx create-claude-workspace --run          # scaffold + start autonomous loop
npx create-claude-workspace --docker       # scaffold + run in Docker
npx create-claude-workspace validate       # check prerequisites (Claude CLI, auth, git)

Docker Options

npx create-claude-workspace docker --max-iterations 20     # limit iterations
npx create-claude-workspace docker --max-turns 80          # more turns per invocation
npx create-claude-workspace docker --shell                 # interactive shell
npx create-claude-workspace docker --rebuild               # force rebuild image
npx create-claude-workspace docker --login                 # run 'claude auth login' on host first
npx create-claude-workspace docker --resume-session <id>   # resume a previous session
ANTHROPIC_API_KEY=sk-... npx create-claude-workspace docker  # API key

Authentication: The Docker container uses your host machine's Claude auth automatically. Authenticate on your host first (claude auth login), or pass an API key.

Agents

| Agent | Purpose | |---|---| | project-initializer | Orchestrates full setup pipeline | | product-owner | Product strategy, features, monetization, prioritization | | technical-planner | Translates PRODUCT.md into phased TODO.md (with quality validation) | | devops-integrator | GitLab/GitHub: milestones, issues, branches, MRs/PRs, post-merge cleanup | | deployment-engineer | CI/CD pipelines, deploys, rollbacks, smoke tests, DB migrations | | orchestrator | Development cycle: 12-step workflow with error recovery | | ui-engineer | Frontend: components, styling, state, a11y (any framework) | | backend-ts-architect | Backend: API, DB, business logic, DI, services | | senior-code-reviewer | Code review: security, performance, architecture, duplication | | test-engineer | Write and run tests: Vitest/Jest auto-detect + Playwright E2E |

Pipeline

project-initializer
  |-> Discovery Conversation   -> CLAUDE.md
  |-> product-owner            -> PRODUCT.md (features, monetization, MVP)
  |-> technical-planner        -> TODO.md (phases, tasks, dependencies)
  |-> devops-integrator (opt)  -> GitLab/GitHub milestones + issues
  |-> deployment-engineer (opt) -> CI/CD config + ## Deployment in CLAUDE.md
  |-> MEMORY.md

ralph-loop -> orchestrator agent (autonomous development)
  |-> Health check (track iterations, validate agents, sync main, ingest issues)
  |-> Pick task from TODO.md (+ dependency check, phase re-evaluation)
  |-> Create branch (devops-integrator)
  |-> Plan (backend-ts-architect first for fullstack, then ui-engineer)
  |-> Implement (+ DB migrations via deployment-engineer)
  |-> Write tests (test-engineer: auto-detects Vitest/Jest + Playwright E2E)
  |-> Build, lint & test (nx affected or explicit projects)
  |-> Visual verification (Playwright, UI tasks only)
  |-> Review (senior-code-reviewer, with TESTING context)
  |-> Rework -> Re-review (max 5 cycles, then escalate/skip)
  |-> Commit (source + tracking) + push + MR/PR (devops-integrator)
  |-> Post-merge (solo: merge to main / team: continue on next branch)
  |-> Next task

Autonomous Mode (Unattended)

The autonomous loop runs Claude Code in separate invocations with clean context per task. MEMORY.md maintains continuity between invocations.

# Unattended (--skip-permissions is added automatically)
npx create-claude-workspace run

# Resume after Ctrl+C (continues from checkpoint + resumes last Claude session)
npx create-claude-workspace run --resume

# Custom options
npx create-claude-workspace run --max-iterations 20 --delay 10000

# All options:
#   --max-iterations <n>         Safety limit (default: 50)
#   --max-turns <n>              Max turns per Claude invocation (default: 50)
#   --delay <ms>                 Pause between tasks (default: 5000)
#   --cooldown <ms>              Wait after error (default: 60000)
#   --process-timeout <ms>       Max time per invocation (default: 1800000 = 30min)
#   --activity-timeout <ms>      Max silence before kill (default: 300000 = 5min)
#   --resume                     Resume from checkpoint state
#   --resume-session <id>        Resume specific Claude session
#   --notify-command <cmd>       Shell command on critical events
#   --log-file <path>            Log file (default: .claude/autonomous.log)
#   --project-dir <path>         Target project (default: cwd)
#   --no-lock                    Disable lock file
#   --no-pull                    Skip auto git pull
#   --dry-run                    Validate prerequisites only
#   --help                       Show help

How it works:

• Each iteration = fresh claude -p call = clean context (no context overflow)
• Checkpoint state (.claude/autonomous-state.json) tracks progress between invocations
• Rate limits handled with exponential backoff (up to 30 min between retries)
• --resume continues from last checkpoint and auto-resumes the interrupted Claude session
• Graceful shutdown: Ctrl+C stops after current iteration completes (Ctrl+C again to force)
• Stops when all TODO.md tasks complete or max iterations reached
• Pre-flight checks: Claude CLI, auth, git identity, filesystem, git state

vs ralph-loop: Ralph-loop runs within one conversation (context fills up). This script runs separate conversations (unlimited iterations).

Fully Unattended Setup (PLAN.md)

For server/CI environments where no human interaction is possible, create a PLAN.md file in the project root before starting the autonomous loop. The project-initializer reads it and skips the discovery conversation.

# 1. Copy the template
cp .claude/templates/PLAN.md PLAN.md

# 2. Fill in your project details, credentials, and preferences

# 3. Start — no interaction needed
npx create-claude-workspace run
# or in Docker:
npx create-claude-workspace docker

The template covers: project info, product vision, tech stack, credentials (API keys, git tokens, npm auth), workflow mode, and runtime constraints.

Required Plugins

Install before starting:

# Core (required for interactive mode / ralph-loop)
claude plugin add ralph-loop
claude plugin add @anthropic/plugin-playwright

# Recommended
claude plugin add frontend-design        # UI generation without Figma
claude plugin add claude-md-management   # CLAUDE.md maintenance
claude plugin add commit-commands        # git workflow shortcuts

# Git integration (optional, pick one)
# GitHub: install gh CLI + run: gh auth login
# GitLab: install glab CLI + run: glab auth login

# Optional MCP Servers
# Figma MCP — configure in Claude Code MCP settings with API token

Frontend Profiles

Framework-specific best practices are stored in .claude/profiles/. During project initialization, the correct profile is detected and copied to .claude/profiles/frontend.md in the target project.

Shipped profiles:

• angular.md — Angular (signals, standalone, zoneless, SSR, TestBed, theme system)
• react.md — React (hooks, server components, Testing Library)
• vue.md — Vue (Composition API, Pinia, Vue Test Utils)
• svelte.md — Svelte (runes, $state, SvelteKit)

Only ui-engineer, senior-code-reviewer, and test-engineer read the frontend profile. Backend and infrastructure agents are unaffected — they don't receive framework-specific context.

Limitations

• Requires Claude Code with Agent tool support (subagent_type parameter)
• ralph-loop and other plugins are Claude Code community plugins — install via claude plugin add <name>
• Git integration requires gh (GitHub) or glab (GitLab) CLI to be installed and authenticated
• Shell commands assume bash (Unix syntax) — works via Git Bash or WSL on Windows
• Dev server cleanup uses npx kill-port — requires npm/npx to be available

What Gets Generated

| File | Content | |------|---------| | CLAUDE.md | Architecture, coding standards, DI, workflow mode (solo/team), autonomous workflow | | PRODUCT.md | Vision, target users, features (MVP/v1.1/future), monetization, metrics | | TODO.md | Phased tasks with type/dependencies/complexity/acceptance criteria, checkboxes ([ ] / [x] / [~]) | | MEMORY.md | Session state: current task/step, iterations, complexity tracking, done, next, decisions, blockers |