• Invoked from

  /spectacular:spec

  slash command
• Creating a new feature specification from scratch
• Need the complete spec workflow (Run ID, worktree, brainstorm, spec, validation)

• Implementation plans with task breakdown - Use

  /spectacular:plan

  instead
• API documentation - Goes in code comments or separate docs
• Runbooks or operational guides - Different document type

List detected repos

**Single-repo mode (current behavior):**
- Specs stored in `specs/{runId}-{feature}/spec.md` at repo root
- Worktree created at `.worktrees/{runId}-main/`
- Constitution referenced from `@docs/constitutions/current/`

**Multi-repo mode (new behavior):**
- Specs stored in `./specs/{runId}-{feature}/spec.md` at WORKSPACE root
- NO worktree created (specs live at workspace level, not inside any repo)
- Each repo's constitution referenced separately

• architecture.md - Layer boundaries, project structure
• patterns.md - Mandatory patterns (next-safe-action, ts-pattern, etc.)
• schema-rules.md - Database design philosophy
• tech-stack.md - Approved libraries and versions
• testing.md - Testing requirements

if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  echo "Multi-repo mode: Specs stored at workspace root, no worktree needed"
  mkdir -p specs/${RUN_ID}-${FEATURE_SLUG}
  # Skip to Step 1 (brainstorming)
fi

1. Create branch using git-spice:
   • Use

     using-git-spice

     skill to create branch

     {runId}-main

     from current branch
   • Branch name format:

     {runId}-main

     (e.g.,

     abc123-main

     )
2. Create worktree:
   bash

   # Create worktree at .worktrees/{runId}-main/
   git worktree add .worktrees/${RUN_ID}-main ${RUN_ID}-main

3. Error handling:
   • If worktree already exists: "Worktree {runId}-main already exists. Remove it first with

     git worktree remove .worktrees/{runId}-main

     or use a different feature name."
   • If worktree creation fails: Report the git error details and exit

• All subsequent file operations happen in

  .worktrees/{runId}-main/

• Brainstorming and spec generation occur in the worktree context
• Main repository working directory remains unchanged

1. Check CLAUDE.md for setup commands:
   Look for this pattern in the project's CLAUDE.md:
   markdown

   ## Development Commands
   
   ### Setup
   
   - **install**: `bun install`
   - **postinstall**: `npx prisma generate`

2. If setup commands found, run installation:
   bash

   # Navigate to worktree
   cd .worktrees/${RUN_ID}-main
   
   # Check if dependencies already installed (handles resume)
   if [ ! -d node_modules ]; then
     echo "Installing dependencies..."
     {install-command}  # From CLAUDE.md (e.g., bun install)
   
     # Run postinstall if defined
     if [ -n "{postinstall-command}" ]; then
       echo "Running postinstall (codegen)..."
       {postinstall-command}  # From CLAUDE.md (e.g., npx prisma generate)
     fi
   else
     echo "Dependencies already installed"
   fi

3. If setup commands NOT found in CLAUDE.md:
   Error and instruct user:
   markdown

   Setup Commands Required
   
   Worktrees need dependencies installed to run quality checks and codegen.
   
   Please add to your project's CLAUDE.md:
   
   ## Development Commands
   
   ### Setup
   
   - **install**: `bun install` (or npm install, pnpm install, etc.)
   - **postinstall**: `npx prisma generate` (optional - for codegen)
   
   Then re-run: /spectacular:spec {feature-description}

1. Check current project state in working directory (note: we're in the worktree)
2. Read @docs/constitutions/current/ to understand constraints:
   • architecture.md - Layer boundaries
   • patterns.md - Mandatory patterns
   • tech-stack.md - Approved libraries
   • schema-rules.md - Database rules
3. Ask ONE question at a time to refine the idea
4. Use AskUserQuestion tool for multiple choice options
5. Gather: Purpose, constraints, success criteria

• All architectural decisions must follow @docs/constitutions/current/architecture.md
• All pattern choices must follow @docs/constitutions/current/patterns.md
• All library selections must follow @docs/constitutions/current/tech-stack.md

1. Propose 2-3 different approaches that follow constitutional constraints
2. For each approach explain:
   • Core architecture (layers, patterns)
   • Trade-offs (complexity vs features)
   • Constitution compliance (which patterns used)
3. Use AskUserQuestion tool to present approaches as structured choices
4. Ask partner which approach resonates

1. Present design in 200-300 word sections
2. Cover: Architecture, components, data flow, error handling, testing
3. After each section ask: "Does this look right so far?" (open-ended)
4. Use open-ended questions for freeform feedback
5. Adjust design based on feedback

• Feature: {feature-description}
• Design context: {summary from brainstorming}
• RUN_ID: {run-id from Step 0}
• Output location:

  .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md

• Constitution: All design decisions must follow @docs/constitutions/current/
• Analyze codebase for task-specific context:
  • Existing files to modify
  • New files to create (with exact paths per @docs/constitutions/current/architecture.md)
  • Dependencies needed (must be in @docs/constitutions/current/tech-stack.md)
  • Schema changes required (following @docs/constitutions/current/schema-rules.md)
• Follow all Iron Laws (see below):
  • Reference constitutions, don't duplicate
  • Link to SDK docs, don't embed examples
  • No implementation plans (that's

    /spectacular:plan

    's job)
  • Keep it lean (<300 lines)

---
runId: {run-id}
feature: {feature-slug}
created: {date}
status: draft
---

• Architecture: All components follow layer boundaries (@docs/constitutions/current/architecture.md)
  • Models - Services - Actions - UI (no layer violations)
  • Server/Client component boundaries respected
• Patterns: All mandatory patterns referenced (@docs/constitutions/current/patterns.md)
  • next-safe-action for server actions
  • ts-pattern for discriminated unions
  • Zod schemas for validation
  • routes.ts for navigation
• Schema: Database design follows rules (@docs/constitutions/current/schema-rules.md)
  • Proper indexing strategy
  • Naming conventions
  • Relationship patterns
• Tech Stack: All dependencies approved (@docs/constitutions/current/tech-stack.md)
  • No unapproved libraries
  • Correct versions specified
• Testing: Testing strategy defined (@docs/constitutions/current/testing.md)

• No Duplication: Constitution rules referenced, not recreated
• No Code Examples: External docs linked, not embedded
• No Implementation Plans: Focus on WHAT/WHY, not HOW/WHEN
• Lean: Spec < 300 lines (if longer, likely duplicating constitutions)

• Completeness: All FRs and NFRs defined, no missing scenarios
• Clarity: All requirements unambiguous and specific (no "fast", "good", "better")
• Measurability: All requirements have testable acceptance criteria
• Consistency: No conflicts between sections
• Edge Cases: Boundary conditions and error handling addressed
• Dependencies: External dependencies and assumptions documented

• File Paths: All new/modified files have exact paths per architecture.md
• Integration Points: How feature integrates with existing system clear
• Migration Impact: Schema changes and data migrations identified
• Security: Auth/authz requirements explicit

• A: {Option with trade-offs}
• B: {Option with trade-offs}
• Custom: {User provides alternative}

**Iteration limit**: Maximum 3 validation cycles. If issues remain after 3 iterations, escalate to user with clarifications.md.

Note: All features must follow @docs/constitutions/current/

• FR1: {specific requirement}
• FR2: {specific requirement}

• NFR1: {performance/security/DX requirement}
• NFR2: {performance/security/DX requirement}

Layer boundaries: @docs/constitutions/current/architecture.md Required patterns: @docs/constitutions/current/patterns.md

• src/lib/models/{name}.ts

  - {purpose}

• src/lib/services/{name}-service.ts

  - {purpose}

• src/lib/actions/{name}-actions.ts

  - {purpose}

• {path}

  - {what changes}

• {package}

  - {purpose}
• See: {link to official docs}

• {migration name} - {purpose}
• Rules: @docs/constitutions/current/schema-rules.md

• Auth: Uses existing Auth.js setup
• Database: Prisma client per @docs/constitutions/current/tech-stack.md
• Validation: Zod schemas per @docs/constitutions/current/patterns.md

• All patterns followed (@docs/constitutions/current/patterns.md)
• Architecture boundaries respected (@docs/constitutions/current/architecture.md)
• Testing requirements met (@docs/constitutions/current/testing.md)

• {criterion for this feature}
• {criterion for this feature}
• {criterion for this feature}

• All tests pass
• Linting passes
• Feature works end-to-end

• Architecture: @docs/constitutions/current/architecture.md
• Patterns: @docs/constitutions/current/patterns.md
• Schema Rules: @docs/constitutions/current/schema-rules.md
• Tech Stack: @docs/constitutions/current/tech-stack.md
• Testing: @docs/constitutions/current/testing.md
• {External SDK}: {link to official docs}

undefined

• architecture.md - Backend layer boundaries
• patterns.md - Backend patterns (next-safe-action, etc.)
• schema-rules.md - Database design rules

• architecture.md - Frontend component structure
• patterns.md - Frontend patterns (React Query, etc.)

• (if applicable)

When brainstorming in multi-repo mode:
- Read constitutions from ALL relevant repos
- Note which repo each architectural decision applies to
- Ensure cross-repo consistency (e.g., API contracts)

• Models: Data access with Prisma
• Services: Business logic
• Actions: Input validation with Zod

</Bad>

<Good>
```markdown

Layer boundaries: @docs/constitutions/current/architecture.md

</Good>

1. Create Prisma migration
2. Run migration
3. Verify indexes

• Migration:

  init_rooms

  - Add Room, RoomParticipant, WaitingListEntry models

/plan

</Good>

1. Adoption: 80% of users use feature within first month
2. Performance: Page loads in <500ms
3. Engagement: <5% churn rate

</Bad>

<Good>
```markdown

• NFR1: Page load performance <500ms (measured per @docs/constitutions/current/testing.md)
• NFR2: Support 1000 concurrent users

</Good>

• Full code examples from libraries (Zod, Prisma, Socket.io, etc.)
• Migration phases or implementation steps
• Success metrics or adoption targets
• Recreated architecture explanations
• Test implementation code
• Files in

  specs/{run-id}-{feature-slug}/notes/

  directory
• Spec > 300 lines (probably duplicating constitutions)

• Problem statement shows current - desired state gap
• All FRs and NFRs are testable/verifiable
• Architecture section lists files (not code examples)
• All constitution rules referenced (not recreated)
• All external libraries linked to docs (not copied)
• No implementation plan (saved for

  /spectacular:plan

  )
• No success metrics or timelines
• Single file at

  specs/{run-id}-{feature-slug}/spec.md

• Spec < 300 lines (if longer, check for duplication)

• Check

  .worktrees/

  is in

  .gitignore

• Run

  git worktree prune

  to clean stale entries
• Verify working directory is clean

• Run

  gs repo init

  to initialize repository
• Check

  gs ls

  to view current stack
• See

  using-git-spice

  skill for troubleshooting

• Project MUST define setup commands in CLAUDE.md
• See error message for required format
• Re-run spec command after adding commands

• Maximum 3 iteration cycles
• If issues persist, escalate via clarifications.md
• Do not skip validation - it catches real problems