Repo Setup

You are setting up this repository for agentic coding with Claude Code.

Step 0: Check Existing Setup & Context

First, check what's already configured in this repo:

ls -la CLAUDE.md .cursorrules 2>/dev/null
ls -la .claude/ 2>/dev/null
ls -la docs/ specs/ 2>/dev/null
cat .claude/settings.json 2>/dev/null

If things are already set up, ask the user:

"I see you already have [X] configured. Would you like me to:
- Add missing pieces only?
- Replace/update existing config?
- Skip certain parts?"

If you don't have enough context about the project:

Check for package.json, pyproject.toml, Cargo.toml, go.mod to detect project type
Read any existing CLAUDE.md or .cursorrules
If still unclear, say: "Tell me more about this project and what you're trying to build here. Or if you'd like, we can plan the project first before setting up—would you prefer that?"

Step 1: Interview the User

Ask about these if not already clear from context:

Project basics:
- What type of project? (web app, API, CLI, library, monorepo)
- Primary language/framework?
- New repo or existing codebase?
- If monorepo: what packages/apps?
Tooling preferences:
- Ralph for autonomous development loops?
- Code quality tools? (knip, jscpd)
- If frontend: ESLint rules for component discipline?
Project specifics:
- Non-standard patterns or architecture?
- Testing strategy? (interface tests > unit tests)
- Database/ORM? (Prisma for JS/TS, SQLAlchemy for Python)
- Existing CLAUDE.md or .cursorrules to migrate?

Step 2: Create CLAUDE.md

Note: The /init command can generate a starter CLAUDE.md automatically. This setup goes further with best practices.

Generate a concise CLAUDE.md (<300 lines). Include all relevant sections:

# Project Name

[1-2 sentence description]

## Quick Reference

- Dev: `npm run dev` / `uv run uvicorn app:app --reload`
- Test: `npm test` / `uv run pytest`
- Build: `npm run build` / `uv run build`
- Lint: `npm run lint` / `uv run ruff check`

## Directory Structure

[Tree of main directories with brief descriptions]

## Tech Stack

- Framework: [e.g., Next.js 15, FastAPI]
- Database: [e.g., Postgres + Prisma, SQLite + SQLAlchemy]
- Key deps: [list major ones]

## Conventions

- [File naming patterns]
- [Component/module patterns]
- [State management approach]
- Keep file/function names discrete and unique
- Add comments only on code that's referenced elsewhere or would be hard to understand without context (Chesterton's fence)

## What NOT to Do

- NEVER edit .env or environment files
- NEVER run destructive git ops (reset --hard, rm -rf) unless explicitly instructed
- NEVER add eslint-disable comments - fix the actual issue
- NEVER create abstractions I didn't ask for
- NEVER silence linter errors

## Philosophy

This codebase will outlive you. Every shortcut becomes someone else's burden. Every hack compounds into technical debt that slows the whole team down.

You are not just writing code. You are shaping the future of this project. The patterns you establish will be copied. The corners you cut will be cut again.

Fight entropy. Leave the codebase better than you found it.

## Testing

[Strategy and commands - prefer interface tests over unit tests]

## Commit Rules

Run `/commit` after completing tasks.

## Context Tips

- One chat = one task
- Reference docs/*.md for subsystem docs

Domain-Specific Additions

For backends, add:

## Backend Conventions
- Use an ORM for schema-as-context (Prisma, SQLAlchemy, Drizzle)
- Invest in realistic seed data so agents can self-verify
- Generate API docs and Postman workspaces for easy testing

For Python backends, also add:

## Python Conventions
- SQLAlchemy models in `models/`, Pydantic schemas in `schemas/`
- Async everywhere (aiosqlite, httpx)
- Type hints required on all functions

For JavaScript/TypeScript frontends, add:

## Frontend Conventions
- Leaf components are presentational (no business logic)
- Business logic lives in parent components
- Design tokens only (no custom colors/spacing values)
- Responsiveness matters - remind Claude from the start
- Create styling reference docs and configure tailwind.config with main colors/spacing
- Install Vercel's React best practices skill and frontend-design plugin

For monorepos, add:

## Monorepo Rules
- Claude is worse at monorepos - be extra explicit
- Always be explicit about which package you're working in
- Use full paths from repo root
- Check package.json in the specific package for scripts

Step 3: Create Directory Structure

mkdir -p docs specs scripts .claude

Create these files:

docs/README.md - Index of documentation
docs/schema.sql - DB schema if applicable (can be generated)
specs/requirements.md - Project requirements

Step 4: Set Up Tooling (If Requested)

Code Quality Tools (knip + jscpd)

# knip - find dead code and unused exports
npm install -D knip
npx knip init

# jscpd - find code duplication
npm install -D jscpd

Add to package.json:

{
  "scripts": {
    "lint:dead": "knip",
    "lint:dupes": "jscpd src/",
    "lint:quality": "npm run lint:dupes && npm run lint:dead"
  }
}

ESLint Rules for Frontend

For frontend projects with component discipline:

Add to .eslintrc.js or eslint.config.js:

// Prevent eslint-disable abuse
'eslint-comments/no-restricted-disable': ['error'],

// Prevent useState in view/presentational components
// Apply to files in components/views/ or similar
'no-restricted-syntax': [
  'error',
  {
    selector: 'CallExpression[callee.name="useState"]',
    message: 'View components should not manage state. Move state to parent.',
  },
],

Install required plugin:

npm install -D eslint-plugin-eslint-comments

Step 5: Set Up Ralph (If Requested)

Ralph enables autonomous development loops. Only set up if user wants it.

Check Installation

which ralph || echo "Not installed - see https://github.com/frankbria/ralph-claude-code"

Ralph File Structure

Ralph requires 3 files from you:

PROMPT.md - Instructions piped to Claude each loop
@fix_plan.md - Task list (Ralph checks - [x] for completion)
specs/requirements.md - Project requirements

Ralph auto-creates these (don't create manually):

.exit_signals, .ralph_session, progress.json

Create PROMPT.md

# [Project Name] Development

You are Ralph, an autonomous AI agent. YOU write code. YOU create files. Do not describe what you would do—DO IT.

## Context
Read these files for full context:
- `CLAUDE.md` - Project conventions
- `specs/` - Requirements and specifications
- `@fix_plan.md` - Current task priorities

## How to Work
1. Read `@fix_plan.md` to see current priorities
2. Implement the highest priority unchecked `- [ ]` item
3. Run tests after implementation
4. Mark task complete with `- [x]` in @fix_plan.md
5. Move to next task

## Key Principles
- ONE task per loop - focus completely
- Search codebase before assuming something doesn't exist
- Write tests for new functionality
- Update @fix_plan.md with progress

## Status Block (REQUIRED at end of every response)

\`\`\`
---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line summary>
---END_RALPH_STATUS---
\`\`\`

Set EXIT_SIGNAL: true ONLY when ALL @fix_plan.md items are [x] AND tests pass.

## Exit Conditions
Stop and report when:
- All current phase tasks complete
- Blocker requiring user input
- Tests failing and can't determine fix

Create @fix_plan.md

# Fix Plan

## High Priority (Current Sprint)
- [ ] **[1.1]** First task title
  - Files: `path/to/file.py`
  - Acceptance: [how to verify done]
  - Dependencies: none

- [ ] **[1.2]** Second task
  - Dependencies: 1.1

## Medium Priority
- [ ] **[2.1]** Future tasks...

## Completed
- [x] **[0.1]** Project initialization

Create specs/requirements.md

# Project Requirements

## Overview
[What the project does - 2-3 sentences]

## Core Requirements
- [Functional requirement 1]
- [Functional requirement 2]

## Technical Requirements
- [Non-functional requirements]
- [Performance, security, etc.]

## Out of Scope (V1)
- [Explicitly not doing this]
- [Or this]

Ralph Tips

CRITICAL - Claude acts as observer: Claude may respond with "Let Ralph continue working" instead of actually implementing. Your PROMPT.md must explicitly say: "YOU are the agent. YOU write code. Do not describe—DO IT."

Completion keyword exits: Ralph exits when it detects "done", "complete", "finished" in progress files. Use PASSED/PENDING status terms instead.

Keep accompanying chat open: Ralph runs in background; you steer from a separate chat. Check on progress, adjust @fix_plan.md, guide when stuck.

Reset if stuck:

rm .exit_signals .ralph_session progress.json
ralph --monitor

Run Ralph

cd /path/to/project
ralph --monitor    # With tmux monitoring (recommended)
ralph              # Without tmux
ralph --status     # Check current status

tmux controls (with --monitor):

Ctrl+B then D - Detach (Ralph keeps running)
Ctrl+B then ←/→ - Switch panes
tmux attach -t ralph-[project] - Reattach

Step 6: Install Dependencies

# JavaScript/TypeScript
npm install

# Python
uv sync

Step 7: Verification Checklist

Run through and confirm:

CLAUDE.md exists and is <300 lines
docs/ folder exists with README.md
Dependencies installed and working
Test commands work
If tooling: knip/jscpd configured
If Ralph: PROMPT.md, @fix_plan.md, specs/requirements.md created

Step 8: Report to User

Tell the user:

What files were created
What they should customize (CLAUDE.md conventions, @fix_plan.md tasks)
How to run Ralph if set up (ralph --monitor)
Tooling commands available (npm run lint:quality, npm run lint:dead, etc.)
Any next steps or recommendations

SilenNaihin/setup-repo.md

Select an option

No results found