claude-pre-dev-setup

A portable, project-agnostic system that bootstraps any new Claude Code project with production-grade infrastructure: CLAUDE.md, rules, skills, sub-agents, commands, hooks, and an evolution protocol that grows with the project.

Quick Start

1. Install (one-time)

git clone https://github.com/YOUR_ORG/claude-pre-dev-setup.git ~/.claude-templates/pre-dev-setup
echo 'alias claude-init="~/.claude-templates/pre-dev-setup/bootstrap.sh"' >> ~/.zshrc
source ~/.zshrc

2. Bootstrap a Project

cd ~/Projects/my-new-project
claude-init .

This copies the scaffold into your project's .claude/ directory.

3. Run Setup

Open Claude Code in your project and run:

/pre-dev-setup

Claude will interview you about your project (tech stack, deployment target, preferences) and generate a customized CLAUDE.md with all conventions and rules.

What You Get

Rules (always-loaded, ~450 tokens)

Rule	Purpose
coding-style	Immutability, file <800 lines, functions <50 lines
git-workflow	Conventional commits, PR process, co-author
testing	TDD principles, coverage thresholds
security	OWASP awareness, input validation, no secrets
output-format	Structured file/architecture update format
agents	Auto-delegation criteria
performance	Model selection, context management
parallel-dispatch	When/how to dispatch parallel agents

Agents (6 core, ~600 tokens idle)

Agent	Purpose
planner	4-phase planning with bite-sized execution steps
code-architect	Architecture design + deep codebase exploration
code-reviewer	Dual-target review with confidence scoring
security-reviewer	OWASP Top 10 + 9 code pattern checks
work-verifier	Comprehensive verification (tests, quality, requirements)
tester	E2E + unit tests + coverage reporting

Skills (9 total, ~900 tokens idle)

Skill	Invocation	Purpose
Systematic Debugging	/systematic-debugging	6-phase debugging methodology
TDD	/tdd	RED-GREEN-REFACTOR cycle enforcement
Frontend Design	/frontend-design	Distinctive UI creation workflow
10/10 Frontend	/10-10-frontend	Screenshot loop until design scores 10/10
Webapp Testing	/webapp-testing	Write Playwright E2E test suites
E2E Testing Loop	/e2e-loop	Automated exploratory testing via Claude + Ralph loop
Feature Development	/feature-dev	7-phase feature development lifecycle
Create New Skill	/new-skill	CSO-optimized skill creation wizard
Create New Agent	/new-agent	Agent creation with on-demand catalog

Commands

Command	Purpose
/commit	Conventional commit with co-author
/pr	PR creation with template compliance
/plan	Architecture-first planning
/code-review	Parallel code + security review
/prd-init	Initialize JSON-based PRD
/ralph-loop	Iterative development loop

Hooks

• PreToolUse: Security pattern detection (9 vulnerability patterns)
• PostToolUse: Auto-formatting, type checking (configured per stack)
• Stop: Work verification prompt before session exit

E2E Testing Loop (/e2e-loop)

Automated exploratory E2E testing — Claude becomes the tester, navigating your running web app with Playwright, clicking through every workflow, and documenting bugs in a structured FINDINGS.md report.

How it works:

1. Recon — scans your codebase for routes, groups them into test phases
2. Setup — installs Playwright, saves auth state, generates test infrastructure
3. Execute — runs a Ralph Wiggum loop where each iteration tests one phase deeply
4. Review — summarizes findings with severity counts

What it generates in e2e-results/:

• loop-prompt.md — per-iteration instructions with quality rules
• phase-tracker.md — checkbox tracker for test progress
• FINDINGS.md — structured bug report (severity, screenshots, repro steps)
• playwright-helper.ts — reusable browser automation utilities
• test-data-helper.ts — mock data insertion for Supabase projects

Quality rules baked in (learned from real testing failures):

• "Page loads" is NOT testing — must click buttons, fill forms, verify outcomes
• Empty pages need mock data — insert before testing, don't report "no data" as a bug
• User reports are TRUTH — never dismiss as "design decisions"
• Write .ts files, not inline bash — avoids escaping issues

Complementary to /webapp-testing: webapp-testing writes deterministic test suites for CI. e2e-loop is exploratory — Claude discovers unknown unknowns.

Idle Context Budget

~1,950 tokens total (8 rules + 9 skill descriptions + 6 agent descriptions). Full content loads only on invocation.

Evolution Protocol

The system ships lean and grows with your project:

• Capability Gap Detection: Claude suggests new agents/skills when it detects a need
• Institutional Learning: Mistakes get added to CLAUDE.md, patterns become rules
• On-Demand Creation: Use /new-skill and /new-agent to extend the system

Supported Stacks

Pre-built profiles for:

• TypeScript + Node.js
• Python + FastAPI
• Next.js + React
• Generic (any stack — customized during setup)

Customization

See docs/CUSTOMIZATION.md for how to adapt the system to your needs.

See docs/ADDING-SKILLS.md for creating project-specific skills.

Re-running Setup

Running /pre-dev-setup again will:

1. Back up existing CLAUDE.md to CLAUDE.md.backup
2. Re-interview you
3. Regenerate everything

Merging into Existing Projects

claude-init /path/to/existing-project
# Choose [m] for merge — adds missing files without overwriting existing ones

License

MIT