Writing Specs

Workspace Detection

Before starting the spec workflow, detect the workspace mode:

# Detect workspace mode
REPO_COUNT=$(find . -maxdepth 2 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
if [ "$REPO_COUNT" -gt 1 ]; then
  echo "Multi-repo workspace detected ($REPO_COUNT repos)"
  WORKSPACE_MODE="multi-repo"
  WORKSPACE_ROOT=$(pwd)
  # List detected repos
  find . -maxdepth 2 -name ".git" -type d | xargs -I{} dirname {} | sed 's|^\./||'
else
  echo "Single-repo mode"
  WORKSPACE_MODE="single-repo"
fi

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

Constitution Adherence

All specifications MUST follow: @docs/constitutions/current/

• 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

The Process

Step 0: Generate Run ID

First action: Generate a unique run identifier for this spec.

# Generate 6-char hash from feature name + timestamp
TIMESTAMP=$(date +%s)
RUN_ID=$(echo "{feature-description}-$TIMESTAMP" | shasum -a 256 | head -c 6)
echo "RUN_ID: $RUN_ID"

CRITICAL: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution $(...) causes parse errors.

Store for use in:

• Spec directory name: specs/{run-id}-{feature-slug}/
• Spec frontmatter metadata
• Plan generation
• Branch naming during execution

Announce: "Generated RUN_ID: {run-id} for tracking this spec run"

Step 0.5: Create Isolated Worktree

Announce: "Creating isolated worktree for this spec run..."

Multi-repo mode: Skip worktree creation. Specs live at workspace root, not inside any repo.

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

Single-repo mode: Continue with worktree creation as normal.

Create worktree for isolated development:

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:

   # 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

Working directory context:

• All subsequent file operations happen in .worktrees/{runId}-main/
• Brainstorming and spec generation occur in the worktree context
• Main repository working directory remains unchanged

Announce: "Worktree created at .worktrees/{runId}-main/ - all work will happen in isolation"

Step 0.6: Install Dependencies in Worktree

REQUIRED: Each worktree needs dependencies installed before work begins.

1. Check CLAUDE.md for setup commands:

   Look for this pattern in the project's CLAUDE.md:

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

2. If setup commands found, run installation:

   # 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:

   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}
   

Announce: "Dependencies installed in worktree - ready for spec generation"

Step 1: Brainstorm Requirements

Context: All brainstorming happens in the context of the worktree (.worktrees/{runId}-main/)

Announce: "I'm brainstorming the design using Phases 1-3 (Understanding, Exploration, Design Presentation)."

Create TodoWrite checklist:

Brainstorming for Spec:
- [ ] Phase 1: Understanding (purpose, constraints, criteria)
- [ ] Phase 2: Exploration (2-3 approaches proposed)
- [ ] Phase 3: Design Presentation (design validated)
- [ ] Proceed to Step 2: Generate Specification

Phase 1: Understanding

Goal: Clarify scope, constraints, and success criteria.

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

Constitution compliance:

• 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

Phase 2: Exploration

Goal: Propose and evaluate 2-3 architectural approaches.

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

Phase 3: Design Presentation

Goal: Present detailed design incrementally and validate.

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

After Phase 3: Mark TodoWrite complete and proceed immediately to Step 2.

Step 2: Generate Specification

Announce: "Generating the specification document..."

Task:

• 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)

Spec frontmatter must include:

---
runId: {run-id}