Refactor commands to thin wrappers invoking skills

CLAUDE.md

@@ -17,28 +17,33 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Plugin Structure
 
-This is a Claude Code plugin with a standard structure:
+This is a Claude Code plugin with a pure skills architecture (matching superpowers pattern):
 
 ```
 spectacular/
 ├── .claude-plugin/
 │   └── plugin.json              # Plugin metadata and configuration
-├── commands/                     # Slash commands (invoked with /spectacular:*)
-│   ├── init.md                  # Environment setup and dependency validation
-│   ├── spec.md                  # Feature specification generation
-│   ├── plan.md                  # Task decomposition with dependency analysis
-│   └── execute.md               # Parallel/sequential execution orchestration
-└── skills/                       # Reusable process documentation
-    ├── decomposing-tasks/       # Plan generation logic and quality rules
-    ├── writing-specs/           # Spec creation patterns and anti-patterns
+├── commands/                     # Thin wrappers (invoke skills)
+│   ├── init.md                  # → invokes validating-environment skill
+│   ├── spec.md                  # → invokes writing-specs skill
+│   ├── plan.md                  # → invokes decomposing-tasks skill
+│   └── execute.md               # → invokes executing-plan skill
+└── skills/                       # All logic lives here
+    ├── validating-environment/  # Environment validation
+    ├── writing-specs/           # Complete spec workflow
+    ├── decomposing-tasks/       # Complete plan workflow
+    ├── executing-plan/          # Execution orchestration
+    ├── executing-sequential-phase/
+    ├── executing-parallel-phase/
     ├── versioning-constitutions/ # Constitution evolution workflow
-    └── using-git-spice/         # Stacked branch management patterns
+    ├── using-git-spice/         # Stacked branch management patterns
+    └── ... (supporting skills)
 ```
 
-### Command vs Skill
+### Command vs Skill (Updated)
 
-- **Commands** (`commands/*.md`): Entry points that users invoke with `/spectacular:*` slash commands. These are user-facing workflows.
-- **Skills** (`skills/*/SKILL.md`): Reusable process documentation invoked programmatically by commands or other skills using the Skill tool. These define HOW to do things.
+- **Commands** (`commands/*.md`): Thin wrappers that invoke skills. Each command is ~5 lines that simply calls the appropriate skill.
+- **Skills** (`skills/*/SKILL.md`): Contain all orchestration logic. Self-contained workflows that define HOW to do things.
 
 ### Core Workflow
 
@@ -47,6 +52,85 @@ spectacular/
 3. **`/spectacular:plan`** → Decomposes spec into execution plan with automatic phase grouping
 4. **`/spectacular:execute`** → Orchestrates parallel/sequential implementation with git worktrees
 
+## Multi-Repo Support
+
+Spectacular supports features spanning multiple git repositories.
+
+### Workspace Structure
+
+```
+workspace/                      # Run Claude from here
+├── specs/                      # Specs at workspace root
+│   └── abc123-feature/
+│       ├── spec.md
+│       └── plan.md
+├── backend/                    # Repo 1 (has .git/)
+│   ├── .worktrees/            # Per-repo worktrees
+│   ├── CLAUDE.md              # Per-repo setup commands
+│   └── docs/constitutions/current/
+├── frontend/                   # Repo 2
+│   ├── .worktrees/
+│   ├── CLAUDE.md
+│   └── docs/constitutions/current/
+└── shared-lib/                 # Repo 3
+```
+
+### Auto-Detection
+
+Spectacular auto-detects multi-repo mode:
+- If current directory contains multiple subdirs with `.git/` → multi-repo mode
+- If current directory is a single git repo → single-repo mode (original behavior)
+
+### Multi-Repo Plan Format
+
+Tasks specify which repo they belong to:
+
+```markdown
+## Phase 1: Foundation
+- [ ] **Task 1.1**: Add shared types | repo: shared-lib | files: src/types.ts
+
+## Phase 2: Implementation (parallel)
+- [ ] **Task 2.1**: Add API endpoint | repo: backend | files: src/api.ts
+- [ ] **Task 2.2**: Add UI component | repo: frontend | files: src/App.tsx
+```
+
+### Per-Repo Requirements
+
+Each repo should have:
+- `CLAUDE.md` with setup commands (required for worktrees)
+- `docs/constitutions/current/` (optional but recommended)
+
+### Execution Behavior
+
+- **Parallel phases**: Tasks in different repos run simultaneously
+- **Sequential phases**: Tasks execute in order, switching repos as needed
+- **Stacking**: Each repo has its own git-spice stack (cannot stack across repos)
+- **PR submission**: Submit in phase order (foundation repos first)
+
+### Example Workflow
+
+```bash
+# From workspace root (parent of all repos)
+cd workspace
+
+# Initialize and check all repos
+/spectacular:init
+
+# Create spec for cross-repo feature
+/spectacular:spec "user preferences with shared types"
+
+# Create plan (will show per-repo tasks)
+/spectacular:plan @specs/{runId}-{feature}/spec.md
+
+# Execute (creates per-repo worktrees and branches)
+/spectacular:execute @specs/{runId}-{feature}/plan.md
+
+# Submit PRs (in phase order)
+cd shared-lib && gs stack submit && cd ..
+cd backend && gs stack submit && cd ..
+cd frontend && gs stack submit && cd ..
+```
+
 ### Codex-Specific Commands
 
 **IMPORTANT: Intentional Duplication for Codex Independence**
@@ -364,6 +448,11 @@ If not set, you'll be prompted to choose during execution.
   - Time estimates and parallelization savings
   - Generated by `decomposing-tasks` skill
 
+**Multi-repo considerations:**
+- Specs stored at workspace root in multi-repo mode
+- Plans include `repo:` field for each task
+- Constitutions referenced per-repo
+
 ### Constitutions
 
 **Constitutions** are immutable snapshots of architectural truth stored in `docs/constitutions/`:
@@ -528,6 +617,16 @@ If changing how constitutions work:
 2. Test changes don't break immutability guarantees
 3. Update documentation in README.md if user-facing
 
+### Multi-Repo Feature Development
+
+1. Set up workspace with repos as subdirectories
+2. Run `/spectacular:init` to validate all repos
+3. Run `/spectacular:spec` from workspace root
+4. Review spec with per-repo constitution references
+5. Run `/spectacular:plan` to get repo-tagged tasks
+6. Run `/spectacular:execute` for parallel execution across repos
+7. Submit PRs per-repo in phase order
+
 ## File Naming Conventions
 
 - Commands: Lowercase with hyphens: `init.md`, `execute.md`