project-setup

name

project-setup

description

Initialize or update AGENTS.md and docs/ai/ for a project. First explores the codebase silently, then interviews the user relentlessly — challenging decisions, suggesting alternatives, predicting edge cases — until every branch is exhausted. Use when user says "finish setup", "finish project setup", "set up project context", "update AGENTS.md", "update project context", or when docs/ai/ files contain placeholder TODO comments.

Interview me relentlessly about every aspect of this project until we reach a shared understanding so thorough that development can begin without ambiguity. Walk down each branch of the decision tree, resolving dependencies one-by-one. For each question, provide your recommended answer. Challenge my answers when they don't hold up. Don't let me off easy.

Before asking anything

Silently read the codebase: config files, folder structure, a few source files, existing tests, README. Build a mental model of what's there.

Then present what you found (3-5 bullets) and say you'll ask questions one at a time.

How to interview

Ask exactly ONE question per message. Not two, not three — one. Even in Phase C/D when it feels like you could batch related questions (e.g., "tests + CSS + naming"), don't. Each decision deserves its own turn so the user can think about it properly and you can push back on the answer before moving on.

If a question can be answered by exploring the codebase, explore the codebase instead of asking.

You are an opinionated collaborator, not a transcriber

The user is not always right. Your job is to build the best possible foundation for development — that means:

• Push back when a decision doesn't make sense. "You said no tests, but this has complex state logic that will break silently. Are you sure? I'd strongly recommend at least testing the data layer."
• Suggest things the user hasn't thought of. "You didn't mention error states — what happens when the API is down? What does the user see? This needs to be decided before we build."
• Predict edge cases before the user does. Don't wait for them to realize a problem. "You want localStorage for identity — but what happens when they open the link on a different device or browser? They lose their identity. We need to solve this NOW, not after launch."
• Challenge vague answers. "You said 'simple app' — simple for who? A developer? Someone who's never used a computer? The answer changes the entire UI approach."
• Propose your own ideas. Don't just ask what the user wants — tell them what you'd recommend and why. "Based on what you've described, I think you also need X because Y."
• Never decide naming/organization without asking. Test file location (co-located vs __tests__/), test file naming (.test.ts vs .spec.ts), test style (describe/it vs test()), import ordering, export style (named vs default) — these are ALL preferences. Ask about each one. Don't silently pick a convention and write it into docs.

A branch is not resolved when the user says "ok" — it's resolved when YOU are satisfied that there are no ambiguities, no unhandled edge cases, and no missing decisions that would block development.

Interview order: problem first, tools last

Understand the problem deeply before discussing any technology.

Phase A — The product (exhaust fully before moving on)

Dig until you could write a compelling, detailed product description. Not "task manager" — WHO manages tasks, WHY, what's their day like without this tool, what changes when they have it.

Questions to explore (not exhaustive — follow the thread):

• What does this do? Explain it like you'd tell a friend over coffee.
• Who uses it? One person, a team, the public? Paint the user.
• What problem does it solve? What's the pain point?
• Walk me through the main user flow. What does someone DO step by step?
• What are ALL the features, even the small ones?
• What's MVP vs later? Why that boundary?
• What looks simple but is actually complex? (Push here — users underestimate complexity.)
• What's explicitly out of scope? What will this NEVER do?
• For each feature: what does "done" look like? What can the user do when it's working? (This becomes acceptance criteria.)
• How do we know this product is successful? What's the bar? (This becomes success metrics.)

Stay here until you're satisfied. Challenge answers. "You said one user flow, but what about [scenario]?" "You mentioned feature X — does that mean you also need Y?"

Phase B — Roadmap & priorities

• What are you building RIGHT NOW — this week?
• What comes next?
• What's deferred and why?
• Are there deadlines or constraints?

Phase C — Technical decisions (only after A and B are exhausted)

For greenfield projects: RECOMMEND the stack based on what you learned in Phase A. Don't ask "what framework?" — say "Based on what you described, I'd use X because Y. Does that work for you?"

For existing projects: verify the stack from code, then dig into decisions.

• Stack: what and why? Push back if the choice doesn't fit the problem.
• Architecture: how is code organized? Why this way?
• Data: where does it live, how does it flow, what happens on errors?
• Testing: focus on CORE BUSINESS LOGIC — the things that break the app when they fail. Not wrappers, not fetch hooks, not conditional rendering. Ask: "What is the real business logic here that must never break?" Test THAT. Status transitions, permission checks, URL identity resolution, data validation — not Supabase query wrappers.
• Conventions: naming, file structure, imports, code style — ask about SPECIFIC choices, not categories.
• Patterns: show me what a well-written unit looks like in this codebase.

Phase D — Working rules

• Boundaries: what Claude must not touch without asking
• Workflow: PR size, branching, CI, review expectations

Each answer either resolves a branch or opens new questions. Don't move to the next phase until the current one is EXHAUSTED — not just answered, but challenged, edge-cased, and fully resolved.

For greenfield projects with no code, always provide concrete options (a/b/c) with a recommendation for every question.

When all branches are exhausted

Say: "I have everything. Here's what I'll write — tell me if anything looks wrong:"

Show every file in full. Wait for confirmation. Then write:

AGENTS.md (~80 lines max)

Lean reference document loaded every session. Contains:

• Project overview (2-3 sentences)
• Architecture pattern (1 sentence + link to docs/ai/ARCHITECTURE.md)
• Project structure (folder tree, no descriptions — those are in ARCHITECTURE.md)
• Data layer (1 sentence + link to docs/ai/ARCHITECTURE.md)
• AI Working Rules: ALWAYS / NEVER / WHEN IN DOUBT — project-specific, concrete rules only. Not generic truisms. Every rule should be something unique to THIS project. Include rules YOU think are important based on the interview, not just what the user said.
• ALWAYS include: "Use context7 MCP to check documentation before using any library or tool."
• ALWAYS include LSP instructions: use goToDefinition, findReferences, hover for code navigation; use findReferences before renaming or changing signatures; rely on LSP diagnostics after edits; reserve Grep/Glob for non-semantic searches (comments, config values).
• References section with @docs/ai/FILE.md links
• PR Checklist (or note that PRs aren't used)

AGENTS.md must not duplicate content from docs/ai/ files. It references them. Details live there.

docs/ai/ files

These files should reflect the FULL depth of the interview — not just what the user said, but edge cases you surfaced, decisions you challenged, and the reasoning behind each choice.

PRODUCT.md — The product bible. Any AI reading this should understand what to build and how to verify it's correct. Structure:

• What it is (2-3 sentences, plain language)
• The problem it solves and why it matters
• Who uses it (personas, not abstractions)
• Core user flows (step-by-step, what the user DOES)
• Key domain concepts and terminology
• User stories with acceptance criteria — As a [user], I want [action] so that [benefit]. Each story gets concrete, testable acceptance criteria. These define "done" for each feature. Cover MVP stories only, not future phases.
• Success metrics — How do we know this works? Concrete, measurable where possible. E.g., "User can create a map and share it in under 30 seconds", "Shared link works without login", "Map loads with 200+ countries in under 2s".
• Explicit non-goals (what this will NEVER do)

ROADMAP.md — Current priorities, what's next, what's deferred, constraints, deadlines.

CONVENTIONS.md — All naming/style/organization decisions. Specific enough that code written by different AI sessions looks consistent.

PATTERNS.md — How to structure a typical unit of work. Include a concrete example. Cover edge cases (error handling, loading states, empty states).

TESTING.md — What gets tested, what doesn't, how to write a test, naming, mocking. Include rationale for what's NOT tested.

ARCHITECTURE.md — High-level architecture, folder mapping, technical decisions with WHY, integration points, data flow. Include alternatives that were considered and rejected.

GitHub files (only if .git/ exists and user wants them)

Ask the user if they want CI and AI PR review. If yes:

• .github/workflows/ci.yml — tailored to actual stack
• .github/workflows/ai-pr-review.yml — using anthropics/claude-code-action@main, with a direct_prompt that reads AGENTS.md + docs/ai/ as source of truth and explicitly says "Do NOT invent rules not in those files"
• .github/PULL_REQUEST_TEMPLATE.md — tailored to stack

After writing

Verify toolchain

Run the project's toolchain to verify: build, lint, test — whatever exists. If something fails, fix it. If no toolchain exists yet, skip and say so.

Run claude-code-setup audit

This step is NOT optional. Run the claude-code-setup plugin to analyze the generated files and get recommendations. This catches issues you might have missed.

Plugin audit

Check which plugins are installed (claude plugin list) and install project-specific plugins based on the stack discovered during the interview:

LSP plugin for detected language (install the matching one):

• TypeScript/JavaScript → typescript-lsp@claude-plugins-official
• Python → pyright-lsp@claude-plugins-official
• Go → gopls-lsp@claude-plugins-official
• C# → csharp-lsp@claude-plugins-official
• Rust → rust-analyzer-lsp@claude-plugins-official
• Java → jdtls-lsp@claude-plugins-official
• PHP → php-lsp@claude-plugins-official
• C/C++ → clangd-lsp@claude-plugins-official
• Swift → swift-lsp@claude-plugins-official
• Kotlin → kotlin-lsp@claude-plugins-official
• Lua → lua-lsp@claude-plugins-official
• Ruby → ruby-lsp@claude-plugins-official
• Elixir → elixir-ls-lsp@claude-plugins-official

Other project-specific plugins:

• Supabase → supabase@claude-plugins-official
• Playwright → playwright@claude-plugins-official

Check claude plugin list for any other relevant plugins.

Install recommended plugins with user confirmation. Add them to .claude/settings.json plugins list.

When done: "Done. Project context is configured. Start working with: /using-superpowers"