---
name: project-setup
description: Bootstrap a new project with the full agentic layer — CLAUDE.md, AGENTS.md, docs/agents/, docs/project_notes/, and subproject overlays — using an opinionated 6-agent routing pattern.
argument-hint: [--force]
---

# project-setup

Bootstrap a new project with the complete Claude Code agentic layer in minutes.

Scans the codebase, asks a few targeted questions, then generates all configuration files from embedded templates.

Pass `--force` to overwrite existing files.

---

## What gets generated

| File | Purpose |
|---|---|
| `CLAUDE.md` | Project overlay — load order, skills, memory links |
| `AGENTS.md` | Agent routing, commands, shared rules |
| `docs/agents/README.md` | Agent index and attribution convention |
| `docs/agents/router.md` | Routing rules |
| `docs/agents/scope.md` | Scope agent prompt |
| `docs/agents/design.md` | Design agent prompt |
| `docs/agents/build.md` | Build agent prompt |
| `docs/agents/review.md` | Review agent prompt |
| `docs/agents/review-secperf.md` | Security & performance review prompt |
| `docs/agents/integration.md` | Integration / FE–BFF boundary prompt |
| `docs/project_notes/bugs.md` | Known bugs log |
| `docs/project_notes/decisions.md` | Architecture decision records |
| `docs/project_notes/key_facts.md` | Ports, URLs, env vars, package managers |
| `docs/project_notes/issues.md` | Completed work log |
| `{subproject}/AGENTS.md` | Per-subproject overlay (one per detected subproject) |

---

## Workflow

### Phase 1 — Scan

Inspect the project root silently. Detect:

**Package managers** (check lock files):
- `bun.lock` / `bun.lockb` → bun
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- `package-lock.json` → npm
- `Cargo.toml` → cargo
- `go.mod` → go
- `requirements.txt` / `pyproject.toml` → pip/uv

**Monorepo** — check for: `workspaces` in package.json, `turbo.json`, `nx.json`, `pnpm-workspace.yaml`

**Subprojects** — scan for nested `package.json` files (max depth 2), group by directory

**Frameworks** (parse dependencies):
- Frontend: `@tanstack/start`, `next`, `vite`, `nuxt`, `remix`, `astro`, `@sveltejs/kit`
- Backend: `@nestjs/core`, `express`, `fastify`, `hono`, `django`, `fastapi`, `flask`
- Mobile: `react-native`, `expo`

**Database/ORM**: `drizzle-orm`, `@prisma/client`, `typeorm`, `mongoose`, `sequelize`, `sqlalchemy`

**Auth**: `better-auth`, `next-auth`, `@auth/core`, `passport`, `supertokens`, `clerk`

**Testing**: `vitest`, `jest`, `@playwright/test`, `cypress`, `pytest`

**Linting**: `@biomejs/biome`, `eslint`, `prettier`, `ruff`

**i18n**: `@inlang/paraglide-js`, `i18next`, `react-i18next`, `next-intl`

**Existing files**: note which of CLAUDE.md, AGENTS.md, docs/agents/, docs/project_notes/ already exist.

---

### Phase 2 — Interview

Ask only what cannot be auto-detected. Keep this to a single message.

**Always ask:**
1. Project name?
2. One-line description of what it does?
3. Production URL (if known)?

**Ask if not auto-detected:**
4. List the subprojects and their roles (e.g. `web/` — React frontend, `bff/` — NestJS API)?
5. Any external services not visible in package.json? (Stripe, Resend, S3, OpenAI…)

**Ask once, branching:**
6. Do you use **Notion**, **Atlassian** (Jira/Confluence), or neither for PM work?
   - If Notion: mother page URL or ID?
   - If Atlassian: Jira URL + project key, Confluence space key?

Wait for all answers before writing any files.

---

### Phase 3 — Generate files

Skip any file that already exists unless `--force` was passed.

#### CLAUDE.md

```markdown
# CLAUDE.md

This file is the Claude Code overlay for this repository.

Load these in order:

1. [AGENTS.md](./AGENTS.md)
2. [{SUBPROJECT}/AGENTS.md](./{SUBPROJECT}/AGENTS.md) — for {SUBPROJECT} tasks  ← repeat per subproject

Use this file only for Claude-specific additions.

## Claude-Specific Skills

Available via slash commands:

- `/prioritizing-roadmap`
- `/product-strategy-session`
- `/pm-skills`

## Project Memory

Institutional knowledge lives in `docs/project_notes/`:

- `bugs.md` — known bugs and fixes
- `decisions.md` — architecture decision records
- `key_facts.md` — ports, URLs, env var names, package managers
- `issues.md` — completed work log

Before proposing architecture changes, check `decisions.md`.
When debugging, check `bugs.md`.
After significant work, update `issues.md` when appropriate.
```

Fill `{SUBPROJECT}` for each detected subproject.

---

#### AGENTS.md

```markdown
# AGENTS.md

This repository uses a compact agent system for Claude Code. Keep routing clear, avoid committee-mode reviews, and only load deep guidance when the task actually needs it.

## Repo Overview

{DESCRIPTION}

{SUBPROJECT_TABLE}  ← one bullet per subproject: name, framework, role
- Runtime flow: `user -> {FLOW}`.
- Read [{SUBPROJECT}/AGENTS.md](./{SUBPROJECT}/AGENTS.md) for {SUBPROJECT}-specific rules.  ← repeat per subproject

## Package Managers And Commands

{PACKAGE_MANAGER_SECTION}  ← per detected package manager and subproject

Common commands:
{COMMANDS}  ← filled from detected scripts in package.json

## Router

Choose one primary agent per task.

- Do not invoke all agents by default.
- Add a second agent only when the task crosses a real boundary.
- Allowed handoffs:
  - `scope -> design`
  - `scope -> build`
  - `build -> integration`
  - `integration -> build`
- Load at most `2` skills unless the user explicitly asks for broader analysis.
- `review` is read-only unless the user explicitly asks for fixes.

Route requests like this:

- New feature, vague ask, conflicting requirements, scope creep risk: `scope`
- UX flow, UI polish, CSS, component consistency: `design`
- Implementation, debugging, refactors, tests: `build`
- Review, audit, regression scan, PR feedback: `review`
- Security vulnerabilities, performance regressions, N+1 queries, bundle size, auth audit: `review-secperf`
- FE/BFF mismatch, auth/session flow, DTO drift, persistence ownership, query invalidation, route/search state bugs: `integration`

## Shared Prompts

The shared agent prompts live in `docs/agents/`.

- [docs/agents/README.md](./docs/agents/README.md)
- [docs/agents/router.md](./docs/agents/router.md)
- [docs/agents/scope.md](./docs/agents/scope.md)
- [docs/agents/design.md](./docs/agents/design.md)
- [docs/agents/build.md](./docs/agents/build.md)
- [docs/agents/review.md](./docs/agents/review.md)
- [docs/agents/review-secperf.md](./docs/agents/review-secperf.md)
- [docs/agents/integration.md](./docs/agents/integration.md)

## Skill Invocation Policy

- Never invoke a skill for configuration, meta-tasks, tooling, or one-shot operations.
- Only invoke skills when the task requires deep framework-specific knowledge during implementation, review, or discovery.
- When a skill must be loaded, prefer invoking it inside a subagent to protect the main context.
- Load at most `2` skills per task unless the user explicitly asks for broader analysis.
- Skills are on-demand: decide when to load them based on task complexity, not preemptively.

## Model And Effort Policy

Three tiers — pick the lowest that confidently handles the task:

| Tier | Model | Use when |
|---|---|---|
| Light | `haiku` | Mechanical search, file grep, formatting sweeps, single-file reads |
| Default | `sonnet` | Standard build, refactor, simple CRUD, styling, most sub-agents |
| Deep | `opus` | Multi-subsystem work, auth/routing/contracts/persistence, audit, review, root-cause analysis |

Rules:
- Default to `sonnet`. Omitting the model parameter inherits this.
- Use `haiku` for pure exploration or search sub-agents where no judgment is required.
- Escalate to `opus` only when: more than one subsystem is involved, auth/routing/caching/persistence/contracts are in play, the user explicitly asked for review/audit/root-cause, or the first pass did not produce a confident answer.
- Do not use `opus` for styling tweaks, formatting, simple CRUD, or mechanical refactors.

## Shared Working Rules

- Inspect code before editing.
- Prefer the smallest coherent slice.
- Add or update tests when behavior changes.
- Keep outputs compact and decision-oriented.
- Do not edit generated files unless the task explicitly requires regeneration.

## Memory Protocol

Before or during work:

- Check `docs/project_notes/decisions.md` before introducing new libraries or architecture changes.
- Check `docs/project_notes/bugs.md` when you hit a bug that may already be known.
- Check `docs/project_notes/key_facts.md` for ports, URLs, env var names, and package-manager facts.

After significant work:

- Add durable bug fixes to `docs/project_notes/bugs.md`.
- Log significant completed work in `docs/project_notes/issues.md`.
```

---

#### docs/agents/README.md

```markdown
# Shared Agent Prompts

> **Note:** These files are the shared source of truth for agent prompts. Claude Code's live agent definitions live in `.claude/agents/` — keep both in sync when updating agent behaviour.

- [router.md](./router.md): choose the primary agent and control token use
- [scope.md](./scope.md): feature discovery and scope control
- [design.md](./design.md): UX/UI, CSS, component systems
- [build.md](./build.md): implementation and testing
- [review.md](./review.md): read-only review and risk finding
- [review-secperf.md](./review-secperf.md): security and performance audit
- [integration.md](./integration.md): FE/BFF contracts and state-flow tracing

## Attribution convention

Whenever a skill, agent, or sub-agent is invoked, name it explicitly in the response — e.g. "using `prd` skill", "via `Explore` sub-agent", "handled directly (no delegation)". This lets the user audit and improve the agentic workflow.

---

Load the shared prompt for the relevant role, then the scope overlay:

- [AGENTS.md](../../AGENTS.md)
- [{SUBPROJECT}/AGENTS.md](../../{SUBPROJECT}/AGENTS.md) — {SUBPROJECT} tasks only  ← repeat per subproject

Do not load large project guides into subagent context. AGENTS.md and the scope overlays are sufficient.
```

---

#### docs/agents/router.md

```markdown
# Router

Use this prompt before any specialist.

## Goal

Pick one primary agent and keep token use low.

## Rules

- Choose one primary agent per task.
- Add a second agent only when the task crosses a real boundary.
- Allowed handoffs:
  - `scope -> design`
  - `scope -> build`
  - `build -> integration`
  - `integration -> build`
- Load at most `2` skills unless the user explicitly asks for broader analysis.
- `review` is read-only unless the user explicitly asks for fixes.

## Routing

- New feature, vague ask, scope risk, conflicting requirements: `scope`
- UX flow, UI polish, CSS, Tailwind, component consistency: `design`
- Implementation, debugging, refactors, tests: `build`
- Review, audit, regression scan, PR feedback: `review`
- FE/BFF mismatch, auth/session, DTO drift, persistence ownership, invalidation, route/search state bugs: `integration`

## Model And Effort

- Default: `fast + low`
- Escalate one tier when:
  - more than one subsystem is involved
  - auth, routing, caching, persistence, or contracts are in play
  - the user asked for review, audit, or root-cause analysis
  - the first pass is not confident

## Output

State:

- chosen primary agent
- optional second agent and why
- selected skills, if any
```

---

#### docs/agents/scope.md

```markdown
# Scope

Use when the task is not implementation-ready.

## Sub-agents

- `scope.discover`
- `scope.guard`

## Do

- clarify the user outcome
- identify the thinnest shippable slice
- define in-scope and out-of-scope
- list assumptions, constraints, and acceptance criteria

## Avoid

- broad implementation detail unless it reduces risk
- redesigning the full system when a narrower slice will ship

## Default Model And Effort

- `fast + low`

## Useful Skills

- `discovery-process`
- `user-story`
- `prd`
- `prioritizing-roadmap`
- `roadmap-planning`

## Handoff

- hand off to `design` for UX/system decisions
- hand off to `build` once the slice is implementation-ready
```

---

#### docs/agents/design.md

```markdown
# Design

Use for user-visible flow and surface quality.

## Sub-agents

- `design.flow`
- `design.system`

## Do

- improve interaction flow and clarity
- fix hierarchy, spacing, states, accessibility, and responsiveness
- prefer reusable primitives over one-off styling
- preserve the existing visual system unless a deliberate system change is needed

## Avoid

- backend or API changes unless they directly block the UX
- decorative styling that does not improve clarity or consistency

## Default Model And Effort

- `fast + low`

## Useful Skills

- `tailwind-ui-polish`
- `ui-design-system`

## Handoff

- hand off to `build` when the design decision is implementation-ready
```

---

#### docs/agents/build.md

```markdown
# Build

Use for implementation, debugging, refactors, and tests.

## Sub-agents

- `build.frontend`
- `build.backend`
- `build.test`

## Do

- inspect current code before editing
- implement the smallest coherent change
- add or update tests around the real state flow or contract
- verify with repo-native commands

## Avoid

- rewriting scope unless blocked by ambiguity
- pulling in a second agent unless the task crosses a real boundary

## Default Model And Effort

- `balanced + medium`

## Useful Skills

Load only the skill relevant to the layer being touched:

- frontend: `tanstack-start-best-practices`, `tanstack-router-best-practices`, `tanstack-query-best-practices`, `vercel-react-best-practices`
- backend: `nestjs-best-practices`
- either: `security-best-practices` when auth, input handling, or sensitive data are involved

## Handoff

- hand off to `integration` when the failure spans FE and BFF boundaries
```

---

#### docs/agents/review.md

```markdown
# Review

Use for review only.

## Sub-agents

- `review.risk`
- `review.secperf`

## Do

- report findings first
- prioritize bugs, regressions, contract mistakes, missing tests, and security/performance risks
- keep summaries short and secondary

## Avoid

- implementing fixes unless the user explicitly asks
- long architecture essays when concrete findings are available

## Default Model And Effort

- `deep + high`

## Useful Skills

Load skills from the relevant scope only — not both:

- frontend reviews: `tanstack-start-best-practices`, `tanstack-router-best-practices`, `tanstack-query-best-practices`
- backend reviews: `nestjs-best-practices`
- either: `security-best-practices` when auth, input handling, or sensitive data are in scope
```

---

#### docs/agents/review-secperf.md

```markdown
# Review — Security & Performance

Use when reviewing code for security vulnerabilities or performance regressions. Read-only unless the user explicitly asks for fixes.

## Sub-agents

- `review.secperf`

## Do

- audit auth, session, input validation, output encoding, and sensitive data handling
- flag N+1 queries, missing indexes, expensive re-renders, large bundle additions, and Core Web Vitals regressions
- report findings with file and line references
- prioritize by severity: critical blockers first, then high, then recommendations

## Avoid

- implementing fixes unless the user explicitly asks
- general architecture commentary unrelated to security or performance

## Default Model And Effort

- `deep + high`

## Useful Skills

- `security-best-practices`
- `nestjs-best-practices` when reviewing backend auth, guards, or input handling
- `tanstack-start-best-practices` when reviewing server functions, loaders, or SSR paths
- `tanstack-query-best-practices` when reviewing caching, stale time, or invalidation

## Handoff

- hand off to `build` once the fix point is identified and the user asks for changes
```

---

#### docs/agents/integration.md

```markdown
# Integration

Use when the failure or feature spans the FE/BFF boundary.

## Sub-agents

- `integration.contract`
- `integration.flow`

## Do

- trace request shape, response shape, auth/session, route/search state, mutation timing, persistence, and invalidation
- identify the source of truth
- choose the single clean fix point before editing

## Avoid

- drifting into broad styling or architecture work that does not affect the boundary
- fixing both sides blindly before the contract mismatch is identified

## Default Model And Effort

- `deep + high`

## Useful Skills

Load by side — not both at once:

- frontend side: `tanstack-start-best-practices`, `tanstack-router-best-practices`, `tanstack-query-best-practices`
- backend side: `nestjs-best-practices`
- either: `security-best-practices` when auth, session, or sensitive data flow is involved

## Handoff

- hand off to `build` once the fix point and ownership are clear
```

---

#### docs/project_notes/bugs.md

```markdown
# Bugs

Log of known bugs, root causes, and fixes.

## Format

```
## BUG-{NNN}: {title}
**Status**: Open | Fixed | Won't Fix
**Root cause**: {one-line explanation}
**Fix**: {what was done, or N/A}
**Files**: {relevant file paths}
```

---
```

---

#### docs/project_notes/decisions.md

```markdown
# Architecture Decisions

Log of key technical decisions (ADRs).

## Format

```
## ADR-{NNN}: {title}
**Status**: Active | Superseded | Deprecated
**Date**: {YYYY-MM-DD}
**Context**: {why this decision was needed}
**Decision**: {what was decided}
**Alternatives considered**: {what was rejected and why}
**Consequences**: {trade-offs accepted}
```

---
```

---

#### docs/project_notes/key_facts.md

```markdown
# Key Facts

## Project

- **Name**: {PROJECT_NAME}
- **Description**: {DESCRIPTION}
- **Production URL**: {PRODUCTION_URL}

## Package Managers

| Subproject | Package manager | Install | Dev |
|---|---|---|---|
{PACKAGE_MANAGER_TABLE}

## Ports

| Service | Port |
|---|---|
{PORT_TABLE}

## Environment Files

{ENV_FILE_LIST}

## Generated Files (never edit manually)

{GENERATED_FILES_LIST}

## External Services

{EXTERNAL_SERVICES_LIST}

{PM_SECTION}
```

Fill in detected values. Leave unknown fields as `TBD`.

PM section if Notion/Atlassian was provided:
```markdown
## Project Management

### Notion
- Mother page ID: {NOTION_MOTHER_PAGE_ID}
- Feature Ideas DB: {NOTION_FEATURE_IDEAS_ID}

### Atlassian
- Jira URL: {JIRA_BASE_URL}
- Jira project key: {JIRA_PROJECT_KEY}
- Confluence space key: {CONFLUENCE_SPACE_KEY}
```

---

#### docs/project_notes/issues.md

```markdown
# Issues Log

Log of significant completed work.

## Format

```
## {YYYY-MM-DD}: {title}
**Type**: Feature | Fix | Refactor | Infra
**Summary**: {what was done}
**Files changed**: {key paths}
**Notes**: {anything future-Claude should know}
```

---
```

---

#### Per-subproject AGENTS.md

Generate one per detected subproject (e.g. `web/AGENTS.md`, `bff/AGENTS.md`):

```markdown
# {SUBPROJECT} AGENTS.md

Overlay for `{SUBPROJECT}/`. Load after [AGENTS.md](../AGENTS.md).

## Stack

- Framework: {FRAMEWORK}
- Runtime: {RUNTIME}
- Package manager: {PACKAGE_MANAGER}
- Testing: {TEST_FRAMEWORK}

## Commands

```bash
# Dev
cd {SUBPROJECT} && {DEV_COMMAND}

# Test
cd {SUBPROJECT} && {TEST_COMMAND}

# Lint / type-check
cd {SUBPROJECT} && {CHECK_COMMAND}
```

## Key Patterns

{FRAMEWORK_SPECIFIC_NOTES}

## Generated Files (do not edit)

{GENERATED_FILES}

## Notes

- Data should generally flow through the API layer rather than direct DB access from the frontend.
```

---

### Phase 4 — Summary

Print:

```
Project setup complete.

Generated:
  ✓ CLAUDE.md
  ✓ AGENTS.md
  ✓ docs/agents/ (8 shared agent prompts)
{SUBPROJECT_AGENTS}
  ✓ docs/project_notes/bugs.md
  ✓ docs/project_notes/decisions.md
  ✓ docs/project_notes/key_facts.md
  ✓ docs/project_notes/issues.md

Skipped (already exist):
{SKIPPED_FILES}

Next steps:
  1. Review AGENTS.md — fill in any tech-specific rules for your stack
  2. Review docs/project_notes/decisions.md — add ADRs for key tech choices
  3. Fill in docs/project_notes/key_facts.md — add env var names and ports
  4. Add subproject-specific rules to each {SUBPROJECT}/AGENTS.md
  5. Run /prioritizing-roadmap or /product-strategy-session to start PM work
```

---

## Notes

- Never write actual secret values to any generated file — env var names only
- If a file already exists, skip it (print "Skipped") unless `--force` was passed
- This skill is safe to re-run — it will skip existing files by default
- The agent prompts in `docs/agents/` are project-agnostic and can be kept as-is; update them only if you add new agents or change routing rules