Initial commit
This commit is contained in:
Zhongwei Li
481
commands/README.md
Normal file
481
commands/README.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user