# Brief: `/setup` Command — Project Initialization > **Catalyst Brief** — Read [AGENTS.md](../../AGENTS.md) and [BRIEFS.md](../BRIEFS.md) before implementing. ## Summary Create a `/setup` slash command that initializes a fresh Catalyst project. This command transforms the generic Catalyst kit into the user's own project by collecting essential information, updating configuration, clearing example content, and preparing the project for POC development. **Primary users:** Developers starting a new project with the Catalyst kit **Core outcome:** A clean, personalized project ready for development with no "Catalyst bleeding through" --- ## Context: What is Catalyst? Before implementing, understand the Catalyst system: ### The Kit Structure Catalyst is a **method + kit** for AI-assisted development: ``` catalyst/ # Method artifacts ├── project-state.md # Current stage, focus, health, goals ├── specs/ # Foundational documents │ ├── project-vision.md # North star, success criteria │ ├── project-experience.md # Users, journeys, features │ ├── project-brand.md # Voice, visuals, style │ └── project-architecture.md # Tech stack, patterns ├── briefs/ # Work items (PRDs) │ ├── approved-*.md # Ready to implement │ ├── active-*.md # In progress │ └── complete/ # Finished work ├── commands/ # Slash commands ├── CHANGELOG.md # Release history ├── FEEDBACK.md # Ideas and feedback └── prompts/ # AI prompts app/ # Next.js surfaces ├── (web)/ # Marketing/landing ├── (app)/ # Main application ├── (docs)/ # Documentation ├── (catalyst)/ # Catalyst dashboard (internal) ├── (examples)/ # Reference implementations ├── (present)/ # Presentations └── (auth)/ # Authentication lib/ ├── config.ts # Central configuration ├── navigation.ts # Navigation items └── ... ``` ### Delivery Stages Projects progress through stages: | Stage | Purpose | Exit Criteria | |-------|---------|---------------| | **INIT** | Project setup, no code yet | Config + state ready | | **POC** | Validate the idea works | Working proof, rough is fine | | **MVP** | Real users, real data | Core flows work end-to-end | | **MMP** | Market-ready product | Polished, paying customers | | **PROD** | Enterprise-grade | Fully hardened, scalable | ### Two Setup Approaches 1. **Intent-first:** Define the project clearly before building - More upfront questions - Populates spec documents with real content - Best when clarity is needed 2. **Proof-first:** Start building, capture decisions as you go - Minimal questions - Blank spec templates - Best when exploring/prototyping --- ## Objectives & Success Criteria 1. **Detect existing setup** — Warn if project appears already configured 2. **Collect project information** — Name, description, users, goals 3. **Update configuration** — Personalize the project 4. **Clear example content** — Remove Catalyst-specific artifacts 5. **Prepare for development** — Stage transitions from INIT → POC --- ## Scope Definition ### In Scope (Must Deliver) **1. Create `/setup` command** File: `catalyst/commands/setup.md` (+ pointers in `.claude/commands/` and `.github/prompts/`) **2. Detection logic** Check if already configured: ```typescript // Primary signal: app name changed from default const isConfigured = config.app.name !== "Catalyst" // Secondary signals (for stronger warning): // - project-state.md stage !== "init" // - Non-example briefs exist // - Specs have real content (not templates) ``` If configured, show warning: > "This project appears to be already configured (name: 'MyApp'). Running setup will reset configuration. Continue anyway? (yes/no)" **3. Conversation flow** Stage 1: Detection ``` /setup > Checking project state... > [Fresh kit detected] OR [Already configured - warn] ``` Stage 2: Set INIT stage ``` > Setting project stage to INIT... ``` Stage 3: Approach selection ``` > How would you like to start? > > 1. **Intent-first** — Define the project clearly, then build > Best when you need alignment before coding > > 2. **Proof-first** — Start building, capture decisions as you go > Best when exploring or prototyping ``` Stage 4: Core questions (both paths) ``` > Project name? (e.g., "Acme Dashboard") > One-line description? (e.g., "Team feedback and insights tool") > Primary users? (e.g., "Product managers and team leads") > Initial goal/focus? (e.g., "Validate the feedback collection flow") ``` Stage 5: Intent-first additional questions ``` > What problem does this solve? (2-3 sentences) > What does success look like? (2-3 bullets) > Any key constraints or principles? (optional) ``` Stage 6: Confirmation ``` > Ready to configure "Acme Dashboard": > > ✓ Update lib/config.ts with project name and description > ✓ Update catalyst/project-state.md (stage: poc, focus, goals) > ✓ Update README.md with project info > ✓ [Intent] Populate specs with your input / [Proof] Create blank templates > ✓ Clear landing page to minimal template > ✓ Archive example briefs > ✓ Reset CHANGELOG and FEEDBACK > > Proceed? (yes/no) ``` Stage 7: Apply changes ``` > Applying configuration... > > ✓ Updated lib/config.ts > ✓ Updated catalyst/project-state.md (stage: POC) > ✓ Updated README.md > ✓ Prepared spec documents > ✓ Cleared landing page > ✓ Archived 3 example briefs > ✓ Reset CHANGELOG.md > ✓ Reset FEEDBACK.md > > 🚀 Setup complete! Your project "Acme Dashboard" is ready. > > Next steps: > - Run /code to start a coding session > - Run /brief to create your first work item > - Edit catalyst/specs/ to refine your project definition ``` **4. File updates** | File | Action | Details | |------|--------|---------| | `lib/config.ts` | Update | `app.name`, `app.description` | | `catalyst/project-state.md` | Update | `stage: poc`, `focus`, `goals`, `target` | | `README.md` | Update | Project name, description, getting started | | `catalyst/specs/project-vision.md` | Update | Blank template OR populated | | `catalyst/specs/project-experience.md` | Update | Blank template OR populated | | `catalyst/specs/project-brand.md` | Update | Blank template OR populated | | `catalyst/specs/project-architecture.md` | Update | Blank template (keep tech defaults) | | `app/(web)/page.tsx` | Update | Clear to minimal "Welcome to [Project]" | | `catalyst/CHANGELOG.md` | Reset | Fresh with `[0.1.0] - Initial setup` | | `catalyst/FEEDBACK.md` | Reset | Empty with format guide only | | `catalyst/briefs/*.md` | Archive | Move to `archive/` with `archive-` prefix | **5. Command file structure** Create in `catalyst/commands/setup.md`: ```markdown --- description: Initialize a new Catalyst project --- [Full command instructions here - conversational flow, file updates, etc.] ``` Create pointer files: - `.claude/commands/setup.md` → `@catalyst/commands/setup.md` - `.github/prompts/setup.prompt.md` → `@catalyst/commands/setup.md` ### Out of Scope (Must NOT Deliver) - Surface deletion (defer to manual or future `/cleanup`) - Design token customization (colors, fonts) - Auth configuration - Navigation customization - Module setup - Dependency changes --- ## Technical Requirements ### T1: Config Update Pattern The `lib/config.ts` file has this structure: ```typescript export const config = { app: { name: "Catalyst", description: "AI-powered development kit", // ... }, // ... } ``` Update `app.name` and `app.description` with user input. ### T2: Project State Update The `catalyst/project-state.md` has YAML frontmatter: ```yaml --- stage: init focus: "Setting up the project" target: "Complete setup" health: green goals: - "Configure project basics" lead: "" support: [] blockers: [] updated: 2026-01-08 --- ``` Update with user's input: - `stage: poc` - `focus: [user's initial goal]` - `goals: [derived from user input]` - `updated: [today's date]` ### T3: Spec Templates **Blank template pattern (Proof-first):** ```markdown # Project Vision ## Problem Statement ## Success Criteria ## Decision Principles ``` **Populated pattern (Intent-first):** ```markdown # Project Vision ## Problem Statement [User's input about the problem] ## Success Criteria [User's input about success, formatted as bullets] ## Decision Principles ``` ### T4: Landing Page Reset Replace the current `app/(web)/page.tsx` content with a minimal template: ```tsx export default function HomePage() { return (

{config.app.name}

{config.app.description}

) } ``` Or a slightly more polished version using the existing component patterns. ### T5: Brief Archival Move all briefs from `catalyst/briefs/` (except subfolders) to `catalyst/briefs/archive/`: - Rename with `archive-` prefix - Preserve the rest of the filename Example: `approved-20260108_roadmap-page.md` → `archive/archive-20260108_roadmap-page.md` ### T6: README Update Update the README.md header section: ```markdown # [Project Name] [Project description] ## Getting Started 1. Install dependencies: `pnpm install` 2. Start development: `pnpm dev` 3. Open http://localhost:3000 ## Project Structure This project uses [Catalyst](https://github.com/...) for AI-assisted development. See `catalyst/` for project artifacts and `AGENTS.md` for AI agent instructions. ``` --- ## Edge Cases ### E1: User cancels mid-flow If user types "cancel" or "quit" at any point, abort gracefully: > "Setup cancelled. No changes were made." ### E2: Already configured + user proceeds If user confirms they want to re-run setup on a configured project: - Proceed normally - Previous config is overwritten - Stage resets to INIT then POC ### E3: Missing files If expected files don't exist (e.g., someone deleted specs): - Create them fresh with templates - Note in output: "Created missing file: project-vision.md" ### E4: Invalid input If user provides empty or invalid input: - Re-prompt with guidance - Don't proceed until valid input received --- ## Validation Checklist - [ ] Command file created: `catalyst/commands/setup.md` - [ ] Pointer files created: `.claude/commands/setup.md`, `.github/prompts/setup.prompt.md` - [ ] Detection logic correctly identifies fresh vs configured projects - [ ] Warning shown for already-configured projects - [ ] Both Intent-first and Proof-first paths work - [ ] `lib/config.ts` updated correctly - [ ] `catalyst/project-state.md` updated (stage: init → poc) - [ ] README.md updated with project info - [ ] All 4 spec files updated (blank or populated) - [ ] Landing page cleared to minimal template - [ ] Example briefs archived - [ ] CHANGELOG.md reset to fresh state - [ ] FEEDBACK.md reset to fresh state - [ ] Confirmation shown before destructive changes - [ ] Success message with next steps - [ ] Graceful handling of cancellation - [ ] No TypeScript errors after changes --- ## Handoff Notes (For Implementation Agent) **Before starting:** 1. Read `AGENTS.md` thoroughly — understand repo conventions 2. Read `catalyst/CATALYST.md` — understand the methodology 3. Read `catalyst/PLAYBOOK.md` — understand agent workflow 4. Review existing commands in `catalyst/commands/` for patterns **Key files to study:** - `lib/config.ts` — see current structure - `catalyst/project-state.md` — see current format - `catalyst/specs/*.md` — see current content to know what to clear - `app/(web)/page.tsx` — see current landing page - `catalyst/commands/code.md` — example of a well-structured command **Critical principles:** 1. **Conversational flow** — Don't dump all questions at once 2. **Confirm before changes** — Show what will happen, get explicit yes 3. **Clear feedback** — Show each change as it's applied 4. **Graceful errors** — Handle edge cases without crashing 5. **No partial states** — If something fails, provide clear recovery path **Testing approach:** 1. Run on a fresh Catalyst clone — should work smoothly 2. Run again on same project — should detect + warn 3. Test both Intent-first and Proof-first paths 4. Verify all files are correctly updated 5. Run `pnpm build` to ensure no TypeScript errors introduced **The goal:** After running `/setup`, the project should feel like *the user's project*, not a Catalyst demo. No example briefs, no "Catalyst" branding, no placeholder content — just a clean starting point for their POC.

Briefs