Claude Starter Kit

A complete Claude Code environment for autonomous AI-driven development. One command scaffolds the .claude/ kit (agents, standards, templates) — then Claude Code itself runs the setup questionnaire and the development cycle.

Framework-agnostic: Supports Angular, React, Vue, Svelte via dedicated framework engineer agents. Optimized for Nx monorepo but works with standalone projects too.

Quick Start

npx create-claude-workspace

This scaffolds the .claude/ folder (agents, standards, templates) into your project and adds the needed .gitignore entries.

Then run the init agent — it interviews you and sets up the whole environment:

claude --agent project-initializer

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

• CLAUDE.md — project conventions, tech stack, workflow mode
• PRODUCT.md — product strategy & features (via product-owner agent)
• TODO.md or GitHub/GitLab/Forgejo issues — phased development plan (via technical-planner + it-analyst agents)

Start Autonomous Development

The orchestrator must run top-level (sub-agents cannot spawn other agents). Always use --dangerously-skip-permissions — autonomous development is impractical with permission prompts (every git/build/test command would block on you):

# Single task per run
claude --dangerously-skip-permissions --agent orchestrator

# Continuous (recommended) — start the orchestrator, then set a goal (built-in /goal:
# an external evaluator keeps triggering turns until the condition holds):
/goal The task queue is empty (no status::todo issues / unchecked TODO.md tasks) and all shipped work is merged or awaiting review

# Fallback without /goal: /ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md

Claude Code desktop app (no --agent flag there): open the project and start with the prompt "Act as the orchestrator agent: read .claude/agents/orchestrator.md and follow it exactly. Continue autonomous development according to CLAUDE.md." — desktop sessions are top-level, so delegation, /goal, and ultracode all work. Set the permission mode to skip prompts in session settings.

Each cycle runs: pick task → plan (architect) → implement (framework engineer / backend architect — incl. the Lighthouse audit for page changes) → QA (test-engineer: E2E + axe-core a11y + VRT) → visual verify + Lighthouse score check → review (senior-code-reviewer) → commit + PR → CI watch → merge. Post-deploy, deployment-engineer re-checks the live URL via the PageSpeed Insights API.

Ultracode Bulk Mode (opt-in)

Process several independent tasks in ONE invocation — parallel agents via the Claude Code Workflow tool, each task in its own worktree:

# inside an orchestrator session:
ultracode          # batch of up to 4 independent tasks
ultracode 6        # custom batch size (hard max 8)

• Opt-in only — the orchestrator never batches on its own
• Tasks qualify by: status::todo / unchecked, complexity S/M, satisfied dependencies, and concrete affected paths (it-analyst Affected Components / TODO.md Files:) — path-disjoint tasks run in parallel, everything else stays serial
• Per task: plan → implement → QA (unique dev-server port) → review/rework → ship (PR) → CI watch — then the orchestrator merges serially after green CI (solo) or leaves PRs for review (team)
• One failed task never sinks the batch — it returns to the queue and gets the full single-task treatment next time
• Local TODO.md mode: branches don't touch TODO.md; the orchestrator reconciles tracking in one commit after the batch

CLI Options

npx create-claude-workspace [directory]    # scaffold into a specific directory
npx create-claude-workspace --update       # overwrite kit files with latest version

Agents

| Agent | Purpose | |---|---| | project-initializer | Init agent: discovery questionnaire → full setup pipeline | | orchestrator | Development cycle: 10-step workflow, worktrees, PR/CI/merge, error recovery | | product-owner | Product strategy, features, monetization, phase re-evaluation | | technical-planner | Phased development plan → TODO.md or platform milestones + issues | | it-analyst | Detailed platform issues: acceptance criteria, edge cases, labels | | ui-engineer | Frontend architect — plans only, never implements | | angular-engineer | Angular implementation (signals, zoneless, SSR, Signal Forms) | | react-engineer | React implementation (React Compiler, RSC, Actions) | | vue-engineer | Vue implementation (Composition API, Pinia, Vapor Mode, Nuxt) | | svelte-engineer | Svelte implementation (runes, attachments, SvelteKit) | | backend-ts-architect | Backend: API, DB, business logic, DI, onion architecture | | senior-code-reviewer | Structured review: CRITICAL / WARN / NICE-TO-HAVE / GREEN | | test-engineer | QA: E2E (Playwright), integration tests, VRT, acceptance criteria | | devops-integrator | Git platform setup: remote, labels, milestones, releases, retro-sync | | deployment-engineer | CI/CD pipelines, deploys, rollbacks, smoke tests, DB migrations |

All agents declare model: inherit — they run with the session model (run sessions on Opus or better; sub-agents are never downgraded).

Pipeline

claude --agent project-initializer   (once)
  |-> Discovery questionnaire        -> CLAUDE.md
  |-> product-owner                  -> PRODUCT.md (features, monetization, MVP)
  |-> technical-planner              -> TODO.md (local) / milestones + issues (platform)
  |-> it-analyst (platform mode)     -> detailed issue specs (acceptance criteria, edge cases)
  |-> devops-integrator (optional)   -> remote, labels, CI secrets
  |-> deployment-engineer (optional) -> deployment interview -> ## Deployment in CLAUDE.md

claude --agent orchestrator          (every iteration; /goal for continuous)
  |-> Session-start recovery (state derived from worktrees, branches, PRs — no state files)
  |-> Health check (agents, auth, git sync, kit auto-upgrade, external issue intake)
  |-> Pick task (TODO.md or platform issues; dependency check, phase transitions)
  |-> Create worktree (.worktrees/feat/{id}-{slug})
  |-> Plan (backend-ts-architect first for fullstack, then ui-engineer)
  |-> Implement (framework engineer / backend-ts-architect + unit tests
  |             + Lighthouse audit for page changes: prod build, mobile + simulated throttling)
  |-> QA (test-engineer: E2E, integration, VRT, coverage >= 80%)
  |-> Visual verification (Playwright, UI tasks only) + Lighthouse score verification
  |-> Review (senior-code-reviewer) -> rework -> re-review (max 5 cycles)
  |-> Commit + push + PR (Closes #N) + file discovered issues
  |-> CI watch (diagnose + fix failures, max 3 attempts)
  |-> Merge (solo: auto-merge after green CI / team: leave PR for review)
  |-> Cleanup worktree -> EXIT (one task per invocation)

Task modes

| Mode | Source | Use case | |------|--------|----------| | local | TODO.md checkboxes | Solo development, no issue tracker | | platform | GitHub/GitLab/Forgejo issues + labels (status::todo → in-progress → in-review → done; Forgejo uses native scoped labels status/todo) | Issue-tracked workflows, teams |

Set during init (Task Platform in CLAUDE.md). In platform mode the orchestrator flips labels, creates PRs, watches CI, and merges — via gh/glab CLI on GitHub/GitLab, via the Gitea-compatible REST API (FORGEJO_TOKEN) on Forgejo/Codeberg/self-hosted instances. Forgejo CI runs on Forgejo Actions (.forgejo/workflows/, GitHub-Actions-compatible syntax; requires a registered forgejo-runner).

Discovered issues

Agents never dismiss problems as "pre-existing." Every agent reports out-of-scope findings in a structured DISCOVERED ISSUES section of its final message:

• Non-blocker: reported, agent continues its task
• Blocker: agent finishes what it can, then returns

The orchestrator collects the findings and files them — as detailed platform issues (via it-analyst) or TODO.md tasks — so they enter the queue in the next iteration.

Fully Unattended Setup (PLAN.md)

For server/CI environments where no human interaction is possible, create a PLAN.md file in the project root. The project-initializer reads it and skips the discovery conversation; the orchestrator detects later PLAN.md edits and propagates them into CLAUDE.md/PRODUCT.md/tasks.

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

# 2. Fill in project details, credentials (env vars), and preferences

# 3. Run the pipeline
claude --agent project-initializer
claude --agent orchestrator

Required Plugins

Install before starting:

# Core
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
claude plugin add ralph-loop             # fallback loop for Claude Code versions without built-in /goal

# 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 — configured by project-initializer with your API token

Frontend Frameworks

Framework-specific best practices live in dedicated engineer agents (.claude/agents/{framework}-engineer.md). The Frontend: field in the generated CLAUDE.md selects which engineer implements UI tasks; ui-engineer only plans.

• angular-engineer — Angular 22+: signals, zoneless, OnPush default, Signal Forms, httpResource, @Service(), SSR with incremental hydration
• react-engineer — React 19.2+: React Compiler (no manual memoization), Server Components, Actions, Next.js App Router
• vue-engineer — Vue 3.6+: Composition API, Pinia, Vapor Mode for perf-critical components, Nuxt 4
• svelte-engineer — Svelte 5: runes, attachments ({@attach}), SvelteKit

Kit Updates

The orchestrator checks npm for a newer create-claude-workspace on every iteration. When found, it runs --update, analyzes the diff, and creates migration tasks for your project when conventions changed. You can also update manually:

npx create-claude-workspace --update

Windows & WSL

Three supported setups, fastest last:

| Setup | How | Performance | |---|---|---| | Windows native | Default — commands run in Git Bash | OK | | WSL execution mode | Repo stays on C:\, agents run ALL git/build/test commands inside WSL (Execution: wsl in CLAUDE.md, set during init) | Slower IO (/mnt/c 9P mount), Linux toolchain | | Repo inside WSL (recommended for speed) | Repo in ~/dev/..., Claude Code runs INSIDE WSL (CLI in Windows Terminal, or desktop app via SSH environment into WSL) | Native ext4 — fastest; no special mode needed |

WSL execution mode prerequisites (the initializer's pre-flight checks all of them): git + node + package manager installed in WSL, shared Git Credential Manager for HTTPS pushes, npx playwright install --with-deps run once inside WSL for E2E. Key rule: in WSL mode there is exactly ONE git — WSL git; never run git or the package manager from the Windows shell against the repo (worktree metadata would corrupt). gh/glab and MCP servers (Playwright/Figma) stay on Windows; the WSL dev server is reachable via WSL2 localhost forwarding.

Performance Audits (Lighthouse)

Frontend tasks that add or change pages must pass a Lighthouse audit valid for weak devices: production build only (never the dev server), mobile form factor + simulated throttling (4× CPU + slow 4G — host-independent), 3 runs median. Thresholds: perf ≥ 90, a11y ≥ 95, best-practices ≥ 95, SEO ≥ 90.

The audit is run by the implementing framework engineer during development (same as build + lint — fix it while the context is fresh); the orchestrator only verifies the reported scores, with test-engineer as fallback auditor. Unfixable findings (max 2 fix cycles) are filed as tracked issues. Post-deploy, the deployment-engineer re-checks the live URL via the PageSpeed Insights API (Google-hosted Lighthouse + real-user CrUX data).

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; Forgejo needs no CLI — just FORGEJO_TOKEN in .env
• Shell commands assume bash (Unix syntax) — Git Bash on Windows, or WSL (see Windows & WSL above)
• Dev server cleanup uses npx kill-port scoped to the task's own port — requires npm/npx to be available
• /goal requires a recent Claude Code; older versions fall back to the ralph-loop plugin

What Gets Generated

| File | Content | |------|---------| | CLAUDE.md | Project conventions, tech stack (incl. Frontend: field), workflow mode (solo/team), task platform, autonomous workflow rules | | PRODUCT.md | Vision, target users, features (MVP/v1.1/future), monetization, metrics | | TODO.md | Local mode: phased tasks with type/dependencies/complexity, checkboxes ([ ] / [x] / [~]) | | Platform issues | Platform mode: milestones per phase + issues with acceptance criteria and status::/type::/complexity:: labels |