gh-arittr-spectacular/commands/README.md

# Spectacular Commands

Spec-anchored development workflow with automatic sequential/parallel orchestration using superpowers skills and git-spice.

## Workflow

### Initialize → Specify → Plan → Execute

```bash
# 0. First time? Initialize your environment
/spectacular:init

# 1. Generate comprehensive spec from requirements (generates runId: a1b2c3)
/spectacular:spec "magic link authentication with Auth.js"

# 2. Decompose into execution plan with automatic phase analysis
/spectacular:plan @specs/a1b2c3-magic-link-auth/spec.md

# 3. Execute with automatic sequential/parallel orchestration
/spectacular:execute @specs/a1b2c3-magic-link-auth/plan.md
```

**Key Innovation**: Automatic parallelization based on file dependency analysis. You don't choose - Claude analyzes and orchestrates.

---

## Commands

### `/spectacular:init`

**Purpose**: Initialize spectacular environment and validate dependencies.

**Checks:**
- Superpowers plugin installed
- Git-spice installed and configured
- Gitignore configured for .worktrees/
- Git repository initialized
- Project structure (specs/ directory)

**Actions:**
- Installs missing .gitignore entries
- Creates specs/ directory if needed
- Reports missing dependencies with install instructions

**Example**:
```bash
/spectacular:init
```

**First-time setup:**
```
✅ Environment ready for spectacular workflows!

Next steps:
  1. Generate a spec: /spectacular:spec "your feature description"
  2. Create a plan: /spectacular:plan @specs/{run-id}-{feature-slug}/spec.md
  3. Execute: /spectacular:execute @specs/{run-id}-{feature-slug}/plan.md
```

---

### `/spectacular:spec {description}`

**Purpose**: Generate a complete feature specification from a brief description.

**Uses**:

- `brainstorming` skill to refine requirements
- Task tool to analyze codebase context
- Outputs comprehensive spec with task breakdown

**Output**: `specs/{run-id}-{feature-slug}/spec.md`

**Example**:

```bash
/spectacular:spec "user picks wizard with category navigation"
# Generates: specs/d4e5f6-user-picks-wizard/spec.md
```

**What it generates**:

- Requirements (functional + non-functional)
- Architecture (models, services, actions, UI)
- Implementation tasks with file paths
- Acceptance criteria per task
- Mandatory pattern reminders (next-safe-action, ts-pattern)

---

### `/spectacular:plan {spec-path}`

**Purpose**: Decompose spec into executable plan with automatic phase analysis.

**Uses**:

- `decomposing-tasks` skill (custom spectacular skill)
- Analyzes file dependencies between tasks
- Groups into sequential/parallel phases
- Validates task quality (no XL, explicit files, criteria)

**Output**: `{spec-directory}/plan.md`

**Example**:

```bash
/spectacular:plan @specs/a1b2c3-magic-link-auth/spec.md
```

**What it generates**:

- Phase grouping with strategies (sequential/parallel)
- Task dependencies based on file analysis
- Execution time estimates with parallelization savings
- Complete implementation details per task

**Automatic decisions**:

- **Sequential phase**: Tasks share files or have dependencies
- **Parallel phase**: Tasks are independent, can run simultaneously

**Quality validation**:

- ❌ XL tasks (>8h) → Must split
- ❌ Missing files → Must specify
- ❌ Missing criteria → Must add 3-5
- ❌ Wildcard patterns → Must be explicit

---

### `/spectacular:execute {plan-path}`

**Purpose**: Execute plan with automatic sequential/parallel orchestration.

**Uses**:

- `executing-sequential-phase` skill for sequential phase orchestration
- `executing-parallel-phase` skill for parallel phase orchestration
- `phase-task-verification` skill for shared branch creation/verification
- Fresh subagent per task with code review gates
- Git worktrees for parallel execution
- `finishing-a-development-branch` skill for completion
- Git-spice for branch management

**Flow**:

1. Extract run ID from plan path
2. For each phase:
   - **Sequential**: `executing-sequential-phase` orchestrates tasks in shared worktree
   - **Parallel**: `executing-parallel-phase` creates worktrees, spawns agents concurrently
3. Complete with `finishing-a-development-branch` skill

**Example**:

```bash
/spectacular:execute @specs/a1b2c3-magic-link-auth/plan.md
```

**Sequential phase execution**:

```
Phase 1 (sequential):
  Task 1 → fresh subagent → code review → commit
  Task 2 → fresh subagent → code review → commit
  Task 3 → fresh subagent → code review → commit
```

**Parallel phase execution**:

```
Phase 2 (parallel):
  Worktree A: Task 4 → fresh subagent → code review → commit
  Worktree B: Task 5 → fresh subagent → code review → commit
  Worktree C: Task 6 → fresh subagent → code review → commit
  ↓
  Merge all → feature branch → cleanup worktrees
```

**Quality Gates** (every task):

- Code review after each task
- Biome linting
- Tests pass
- Frequent commits

---

## Mandatory Patterns

All commands enforce these patterns from the constitution (see `@docs/constitutions/current/patterns.md`):

### 1. next-safe-action for ALL server actions

```typescript
// ✅ REQUIRED
export const submitPickAction = authenticatedAction
  .schema(pickSchema)
  .action(async ({ parsedInput, ctx }) => {
    return pickService.submitPick(ctx.userId, parsedInput);
  });

// ❌ FORBIDDEN
export async function submitPick(data: unknown) {
  // Raw server action
}
```

### 2. ts-pattern for ALL discriminated unions

```typescript
// ✅ REQUIRED
return match(event.status)
  .with("SETUP", () => false)
  .with("OPEN", () => true)
  .with("LIVE", () => false)
  .with("COMPLETED", () => false)
  .exhaustive(); // Compiler enforces completeness!

// ❌ FORBIDDEN
switch (event.status) {
  case "SETUP":
    return false;
  case "OPEN":
    return true;
  // Missing cases - no error!
}
```

### 3. Layer Boundaries

```
UI Components (src/components/)
    ↓ calls
Server Actions (src/lib/actions/) - next-safe-action only
    ↓ calls
Services (src/lib/services/) - business logic, no Prisma
    ↓ calls
Models (src/lib/models/) - Prisma only, no business logic
```

**Rules**:

- ✅ Actions call services
- ✅ Services call models
- ✅ Models use Prisma
- ❌ Services cannot import Prisma
- ❌ Actions cannot call models directly

---

## Tech Stack Reference

- **Framework**: Next.js 15 (App Router + Turbopack)
- **Language**: TypeScript (strict mode)
- **Database**: Prisma + PostgreSQL
- **Auth**: Auth.js v5 (magic links)
- **Real-time**: Socket.io
- **Validation**: Zod + next-safe-action
- **Pattern Matching**: ts-pattern
- **Linting**: Biome
- **VCS**: Git + git-spice

---

## Skills Used

### Spectacular Skills

- **`executing-sequential-phase`** - Orchestrates sequential phase execution with natural stacking
- **`executing-parallel-phase`** - Orchestrates parallel phase execution with worktree isolation
- **`phase-task-verification`** - Shared branch creation and verification logic
- **`decomposing-tasks`** - Analyzes dependencies and groups into phases
- **`writing-specs`** - Generates lean feature specifications
- **`validating-setup-commands`** - Validates CLAUDE.md setup commands
- **`understanding-cross-phase-stacking`** - Explains base branch inheritance
- **`using-git-spice`** - Git-spice command reference and patterns
- **`troubleshooting-execute`** - Error recovery for execution failures

### Superpowers Skills

- **`brainstorming`** - Refines requirements before spec generation
- **`requesting-code-review`** - Dispatches code review after each phase
- **`verification-before-completion`** - Evidence-based completion verification
- **`finishing-a-development-branch`** - Completes work and chooses next action

**Architecture**: Orchestrator skills manage workflow lifecycle and dispatch Task tool with embedded execution instructions. Subagents receive focused ~150-line instructions (80% cognitive load reduction vs original 750-line monolithic skills).

---

## Examples

### Example 1: Single Feature (Sequential)

```bash
# Initialize (first time only)
/spectacular:init

# Generate spec
/spectacular:spec "leaderboard with real-time updates via Socket.io"

# Review: specs/a1b2c3-leaderboard/spec.md

# Generate plan with phase analysis
/spectacular:plan @specs/a1b2c3-leaderboard/spec.md

# Review: specs/a1b2c3-leaderboard/plan.md
# Plan shows: 3 phases, all sequential (tasks share files)

# Execute
/spectacular:execute @specs/a1b2c3-leaderboard/plan.md

# Result: Sequential execution, no parallelization
```

### Example 2: Feature with Parallel Opportunities

```bash
# Generate spec
/spectacular:spec "user authentication with magic links"

# Generate plan
/spectacular:plan @specs/a1b2c3-auth/spec.md

# Review plan:
# - Phase 1 (sequential): Database + Models (share files)
# - Phase 2 (parallel): Magic link service + Email service (independent)
# - Phase 3 (sequential): Actions + UI (depend on Phase 2)

# Execute
/spectacular:execute @specs/a1b2c3-auth/plan.md

# Result:
# - Phase 1: Sequential execution
# - Phase 2: Parallel execution (significant time savings)
# - Phase 3: Sequential execution
# Overall: Faster than fully sequential execution
```

### Example 3: Large Feature Auto-Decomposed

```bash
# Generate spec for complex feature
/spectacular:spec "admin category management with drag-reorder and live preview"

# Generate plan
/spectacular:plan @specs/a1b2c3-admin-categories/spec.md

# Plan auto-detects:
# - Phase 1 (sequential): 3 tasks - Database schema + models
# - Phase 2 (parallel): 4 tasks - Services (independent domains)
# - Phase 3 (sequential): 2 tasks - Admin actions
# - Phase 4 (parallel): 3 tasks - UI components (independent pages)
# - Phase 5 (sequential): 1 task - Integration + E2E tests
# Multiple parallel phases provide significant time savings

# Execute automatically orchestrates all phases
/spectacular:execute @specs/a1b2c3-admin-categories/plan.md
```

---

## Troubleshooting

### "Superpowers plugin not installed"

**Cause**: The superpowers plugin is required but not installed.

**Fix**:
```bash
/plugin install superpowers@superpowers-marketplace
```

Then restart Claude Code and run `/spectacular:init` again.

### "Git-spice not installed"

**Cause**: Git-spice is required for stacked branch management.

**Fix**:
```bash
# macOS
brew install git-spice

# Linux
# See https://github.com/abhinav/git-spice for install instructions
```

Then run `/spectacular:init` again.

### "Plan validation failed"

**Cause**: Spec has quality issues (XL tasks, missing files, missing criteria).

**Fix**:

1. Review validation errors
2. Update spec at the indicated locations
3. Re-run `/spectacular:plan @spec-path`

### "Parallel phase failed - one agent blocked"

**Cause**: One task in parallel phase hit an issue.

**Fix**:

1. Other tasks already completed and merged
2. Fix failing task in its worktree: `cd {worktree-path}`
3. Debug and commit fix
4. Merge manually: `git merge {task-branch}`
5. Cleanup worktree: `git worktree remove {path}`

### "Merge conflict in parallel phase"

**Cause**: Tasks marked as independent actually modified same files.

**Fix**:

1. This indicates incorrect dependency analysis
2. Resolve conflict manually
3. Update plan to mark tasks as sequential
4. Report issue so task-decomposition skill can be improved

### "Tests failing after execution"

**Cause**: Implementation has bugs.

**Fix**: Code review runs after each phase, but bugs can slip through.

1. Review test failures
2. Use `systematic-debugging` skill to investigate
3. Fix issues
4. Commit fixes

---

## Design Philosophy

**Spec-Anchored Development**:

1. Comprehensive specs eliminate questions during implementation
2. Mandatory patterns ensure consistency
3. Layer boundaries prevent architectural drift
4. Quality gates catch issues early

**Automatic Orchestration**:

1. Dependency analysis determines sequential vs parallel
2. No manual decision needed - Claude optimizes
3. Worktrees provide true isolation for parallel work
4. Git-spice manages branch stacking

**Task-Level Autonomy**:

1. Fresh subagent per task (no context pollution)
2. Code review after each task (catch issues early)
3. Continuous commits (small, focused changes)
4. Quality gates every step

**Time Optimization**:

1. Automatic parallelization where safe
2. Time savings scale with feature size and parallelization opportunities
3. No coordination overhead (worktrees isolate)
4. Transparent - see exactly what's parallel vs sequential

---

## Performance Benefits

**Without this workflow**:

- Manual dependency tracking
- Conservative sequential execution
- No automatic parallelization

**With this workflow**:

- Automatic dependency analysis
- Optimal parallel/sequential orchestration
- Worktree isolation (no conflicts)
- Time savings scale with feature complexity and number of independent tasks