Spec-anchored development with automatic parallel execution for Claude Code.
Write a spec → generate a plan → execute tasks in parallel → get stacked PRs.
Note
/spectacular:execute requires git-spice for PR stacking. Support for Graphite coming soon!
Inspired and powered by Superpowers.
| Problem | Without | With Spectacular |
|---|---|---|
| Context drift | "What was that pattern?" → makes something up | Every task gets a fresh subagent with anchored context |
| Sequential execution | 40 min of serial tasks (even independent ones) | Parallel tasks in isolated worktrees |
| Unmergeable PRs | 47 files, +2,847 lines—nobody reviews this | Stacked PRs, one per task |
| Pattern hallucination | AI invents plausible-sounding patterns | Constitutions define the rules |
Prerequisites:
# Install git-spice (macOS)
brew install git-spiceSee git-spice installation instructions for other platforms.
Install plugins:
# In Claude Code, install marketplaces and plugins
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
/plugin marketplace add arittr/spectacular
/plugin install spectacular@spectacularInitialize your project:
/spectacular:initReal example from developing spectacular itself:
/spectacular:spec I can't use my main repo while spectacular is running, it locks everything up. I want each run isolated in its own worktree so I can keep working manually and run multiple features concurrently.
Output: specs/dedf14-worktree-isolation/spec.md
# Feature: Worktree Isolation for Spectacular Runs
## Problem Statement
Spectacular commands operate directly in the main repository:
- Cannot perform manual work during a spectacular run
- Cannot run multiple sessions concurrently
- No isolation between spectacular work and manual work
## Requirements
- FR1: Worktree creation in spec command
- FR2: Plan command operates in worktree
- FR3: Execute command uses worktree as base
...
## Acceptance Criteria
- [ ] Worktree created immediately after RUN_ID generation
- [ ] Spec committed to worktree branch
- [ ] Main repo working directory unchanged
.../spectacular:plan @specs/dedf14-worktree-isolation/spec.md
Output: specs/dedf14-worktree-isolation/plan.md
## Execution Summary
- **Total Tasks**: 3
- **Total Phases**: 1
- **Sequential Time**: 12h
- **Parallel Time**: 5h
- **Time Savings**: 7h (58%)
## Phase 1: Command Worktree Integration
**Strategy**: parallel
**Reason**: All tasks modify different command files
### Task 1: Spec Command Worktree Integration
Files: commands/spec.md
Complexity: M (4h)
### Task 2: Plan Command Worktree Integration
Files: commands/plan.md
Complexity: M (3h)
### Task 3: Execute Command Worktree Integration
Files: commands/execute.md
Complexity: L (5h)/spectacular:execute @specs/dedf14-worktree-isolation/plan.md
Time savings: 58% faster—parallel execution runs tasks simultaneously instead of sequentially.
Orchestrator
|
|-- 1. Read plan, identify 3 parallel tasks
|-- 2. Create worktrees
| dedf14-task-1/
| dedf14-task-2/
| dedf14-task-3/
|
|-- 3. Spawn subagents IN PARALLEL
| |
| +-- Subagent 1 (spec.md) +-- Subagent 2 (plan.md) +-- Subagent 3 (execute.md)
| | * Fresh spec context | * Fresh spec context | * Fresh spec context
| | * Implement, test | * Implement, test | * Implement, test
| | * Commit to branch | * Commit to branch | * Commit to branch
| | | |
| +-----------------------------+----------------------------+
| |
|-- 4. Collect results, stack branches: task-1 -> task-2 -> task-3
|-- 5. Code review, cleanup worktrees
gs stack submit
Result: 3 focused PRs instead of one large diff.
┌── dedf14-task-3-execute-command
├── dedf14-task-2-plan-command
├── dedf14-task-1-spec-command
main
Validates environment and configures project:
- Checks superpowers and git-spice installed
- Verifies git repository
- Adds
.worktrees/to.gitignore
Generates feature specification from natural language.
/spectacular:spec "real-time chat with WebSocket and message history"- Brainstorms requirements and architecture
- Asks clarifying questions and proposes solutions
- Reads constitutions (if they exist)
- Creates
specs/{runId}-{feature-slug}/spec.md
Decomposes specification into executable plan.
- Breaks spec into concrete tasks with file paths
- Analyzes dependencies to find parallelization opportunities
- Groups tasks into sequential/parallel phases
- Creates
specs/{runId}-{feature}/plan.md
Executes plan with automatic orchestration.
Sequential phases:
- Tasks run in shared worktree
- Each task creates a git-spice branch
- Branches stack linearly
Parallel phases:
- Each task gets isolated worktree
- Subagents run simultaneously
- Branches stacked after completion
Quality gates after each phase:
- Tests pass
- Linting passes
- Code review approves
Define in your project's CLAUDE.md:
## Development Commands
### Setup
- **install**: `npm ci`
- **postinstall**: `npx prisma generate`
### Quality Checks
- **test**: `npm test`
- **lint**: `npm run lint`
- **build**: `npm run build`Each worktree needs dependencies installed. Spectacular reads these commands and runs them automatically.
Constitutions are immutable snapshots of your project's architectural rules. Specs reference them instead of duplicating rules—this prevents AI from hallucinating patterns.
docs/constitutions/
├── current → v2/ # Symlink to active version
├── v1/ # Original architecture
│ ├── meta.md # "Initial patterns, Feb 2024"
│ ├── architecture.md # "3-layer: API, domain, data"
│ ├── patterns.md # "All API routes use tRPC"
│ └── tech-stack.md # "React, tRPC, Prisma"
└── v2/ # Current architecture
├── meta.md # "Migrated to Server Actions, Mar 2024"
├── architecture.md # "Server/client components"
├── patterns.md # "Server actions, no tRPC"
└── tech-stack.md # "Next.js 14, Server Actions, Prisma"
Creating and versioning:
Ask Claude to create or update your constitution—spectacular uses the versioning-constitutions skill:
"Create a constitution for this project based on the existing patterns"
"We're migrating from tRPC to server actions, update the constitution"
Why constitutions matter:
- Prevents hallucination: AI can't make up patterns—they're documented
- Immutable history: Old versions preserved when rules change
- Explicit evolution: Architecture changes are deliberate, not drift
- Single source of truth: Specs reference constitutions, not duplicate rules
❌ Setup Commands Required
Add setup commands to your CLAUDE.md. See Project Setup.
# List and clean stale worktrees
git worktree list
git worktree prune
# Remove specific worktree
git worktree remove .worktrees/{runId}-task-1# Check current stack
gs log short
# Restack if needed
gs repo syncSpectacular stops and reports the issue. Fix in the worktree:
cd .worktrees/{runId}-phase-{id}
# Fix the issue
git add . && git commit --amend --no-editIf execution is interrupted, re-run the same command:
# Check current state
gs log short
git branch | grep {runId}
# Resume - spectacular detects completed phases and continues
/spectacular:execute @specs/{runId}-{feature}/plan.mdGood for:
- Complex features (>30 min, multiple independent pieces)
- Large refactors
- Migrations (REST→GraphQL, etc.)
- Projects with documented patterns
Skip for:
- Quick bug fixes (<10 min)
- Single-file changes
- Emergency hotfixes
Rule of thumb: If work can be split into 3+ independent tasks, spectacular saves time.
Why spec anchoring prevents context drift
Traditional AI-assisted development degrades over long sessions:
Hour 1: System prompt + spec + task 1 code
Hour 2: System prompt + spec + tasks 1-2 code ← Spec getting pushed out
Hour 3: System prompt + tasks 1-3 code ← Spec gone
Hour 4: System prompt + recent code only ← Making things up
Spectacular's solution: Fresh subagents with spec context.
Each task subagent starts with:
- Full specification (always present)
- Constitution rules (always present)
- This task's requirements
- Relevant code files
Every task starts with the same foundation. No degradation. No drift.
How automatic parallelization works
The planner analyzes file dependencies:
Task 1: "Add WebSocket server"
Files: src/server/websocket.ts, src/server/index.ts
Task 2: "Create notification schema"
Files: prisma/schema.prisma, src/db/types.ts
Task 3: "Build notification UI"
Files: src/components/Notifications.tsx
Conflict matrix:
T1 T2 T3
T1 - ✓ ✓
T2 ✓ - ✓
T3 ✓ ✓ -
No conflicts → all parallel.
If Task 4 also modified src/server/index.ts, it would conflict with Task 1 and run sequentially after it.
Git worktree isolation
Parallel tasks run in completely isolated directories:
/project/
├── src/ ← Main repo (untouched)
├── .git/
└── .worktrees/
├── abc123-task-1/ ← Task 1 worktree
│ └── node_modules/ ← Separate dependencies
├── abc123-task-2/ ← Task 2 worktree
│ └── node_modules/
└── abc123-task-3/
└── node_modules/
Each worktree is a full working directory. Changes in task-1 don't affect task-2. Tests and linting run independently.
Quality gates
After each phase, code review validates:
- All acceptance criteria met
- Constitution patterns followed
- No file conflicts
- Tests pass
Without quality gates:
Task 1: Bug introduced
Task 2: Builds on Task 1 ← bug persists
Task 3: Depends on Task 2 ← bug compounds
Task 4: Integration fails ← hours wasted
With quality gates:
Task 1: Bug introduced ← detected by review
→ Fix immediately
Task 2: Builds on fix ← clean foundation
./tests/run-tests.sh --allmake link # Symlink into ~/.claude
make unlink # Remove symlink./scripts/update-version.sh 1.2.3Codex support is in beta. See .codex/INSTALL.md.
Built on superpowers - consider contributing to both.
MIT
Drew Ritter - @arittr