superspecs 0.1.0

package/.skills/execute-branch/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: execute-branch
+description: Create a git branch or worktree for isolated spec execution. One branch per spec. Triggers on /branch, "create branch", "set up worktree". Run after /pick-spec.
+slash_command: branch
+phase: "2.2 — Execute › Branch"
+---
+
+# Skill: execute-branch
+
+You are creating an isolated execution environment for this spec.
+
+**One branch per spec. No exceptions.** Isolation prevents parallel workstreams from interfering with each other.
+
+## Steps
+
+### 1. Check git status
+
+```bash
+git status
+git branch --show-current
+```
+
+Verify:
+- The working directory is clean (no uncommitted changes)
+- We're on the correct base branch (usually `main` or `develop`)
+
+If there are uncommitted changes, stop: *"Commit or stash changes before creating a branch."*
+
+### 2. Determine branch name
+
+Convention: `superspec/<slug>`
+
+Examples:
+- `superspec/auth-jwt`
+- `superspec/export-csv`
+- `superspec/payment-stripe`
+
+### 3. Choose: branch or worktree
+
+**Standard branch** (default, single workstream):
+```bash
+git checkout -b superspec/<slug>
+```
+
+**Git worktree** (parallel workstreams, recommended when executing multiple specs simultaneously):
+```bash
+git worktree add ../project-<slug> -b superspec/<slug>
+```
+
+Ask the user: *"Use a worktree for parallel execution, or a standard branch?"*
+
+If worktree: note the path in `plan.md`.
+
+### 4. Verify branch was created
+
+```bash
+git branch --show-current
+# should output: superspec/<slug>
+```
+
+### 5. Update plan.md
+
+Add to `superspec/phases/<slug>-execute/plan.md`:
+
+```markdown
+## Branch
+
+Branch name: `superspec/<slug>`
+Type: [branch | worktree]
+Worktree path: <path if worktree, else N/A>
+Created from: <base branch> @ <short SHA>
+Created: <timestamp>
+```
+
+### 6. Update status.md
+
+```markdown
+## Phase
+2.2 — Execute › Branch ✅
+
+## Checklist
+...
+- [x] Branch created (superspec/<slug>)
+...
+```
+
+### 7. Handoff
+
+```
+Branch ready: superspec/<slug>
+
+Type: <branch/worktree>
+Base: <base-branch> @ <SHA>
+
+Next: /subagent <slug>   (to start Wave 1)
+```
+
+## Output
+
+- Git branch `superspec/<slug>` created
+- `superspec/phases/<slug>-execute/plan.md` updated with branch info
+- Updated `superspec/specs/<slug>/status.md`

package/.skills/execute-pick-spec/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: execute-pick-spec
+description: Choose and validate the next spec for execution. Verifies the spec is complete, dependencies are met, and it fits a clean 200k context window. Triggers on /pick-spec, "what should we build next", "start execution".
+slash_command: pick-spec
+phase: "2.1 — Execute › Pick Spec"
+---
+
+# Skill: execute-pick-spec
+
+You are selecting the next spec to execute. This is the gate between planning and execution.
+
+**Nothing is dispatched to subagents until this step passes.**
+
+## Steps
+
+### 1. List available specs
+
+Scan `superspec/specs/`. For each directory, read `status.md` and categorize:
+
+```
+Ready to execute (spec written, not yet started):
+  - <slug> — <purpose> — context: ~Xk
+
+In progress:
+  - <slug> — <phase>
+
+Complete:
+  - <slug>
+```
+
+If the user specified a slug, jump to step 3 with that slug.
+
+If multiple specs are ready, present the list and ask which to pick.
+
+### 2. Check dependencies
+
+Read the spec's `spec.md`. Look for the `Depends on:` field.
+
+For each dependency:
+- Is there a spec for it in `superspec/specs/`?
+- Is that spec complete (shipped)?
+
+If unmet dependencies exist:
+```
+Cannot execute <slug> yet.
+Depends on: <dep-slug> (status: <status>)
+
+Options:
+1. Execute <dep-slug> first
+2. Remove the dependency if it's not actually needed (update spec)
+```
+
+Do not proceed until dependencies are resolved.
+
+### 3. Validate the spec
+
+Read `spec.md` and `tasks.md` completely. Check:
+
+**Completeness**
+- [ ] Every requirement has at least one scenario
+- [ ] Every scenario is testable (concrete GIVEN/WHEN/THEN)
+- [ ] tasks.md exists with at least one task
+- [ ] Done criteria defined
+
+**Clarity**
+- [ ] No ambiguous SHALL statements
+- [ ] No tasks that say "implement X" without specifying the test requirement
+- [ ] No tasks that depend on unwritten decisions
+
+**Context window**
+- Estimate: `spec.md` (~Xk) + `tasks.md` (~Yk) + typical implementation context (~Zk)
+- Total must be under 200k
+- Report: `Context budget: ~<total>k / 200k`
+
+If validation fails, list specific issues and say: *"Fix these before execution begins."*
+
+### 4. Create the phase directory
+
+Create `superspec/phases/<slug>-execute/`:
+
+```
+superspec/phases/<slug>-execute/
+├── plan.md          ← execution plan (written here)
+├── review-log.md    ← code review findings (populated during execution)
+└── wave-1.md        ← populated when Wave 1 starts
+```
+
+### 5. Write plan.md
+
+```markdown
+# Execution Plan: <Feature Name>
+
+**Spec:** superspec/specs/<slug>/spec.md
+**Tasks:** superspec/specs/<slug>/tasks.md
+**Context estimate:** ~<N>k / 200k ✅
+**Started:** <date>
+
+## Execution Strategy
+
+Wave execution order: Wave 1 → Wave 2 → Wave 3
+Parallelism: [list tasks that can run in parallel within each wave]
+
+## Wave Summary
+
+### Wave 1 — <Name>
+Sequential / Parallel: <which>
+Tasks: 1.1, 1.2, ...
+Unblocks: Wave 2
+
+### Wave 2 — <Name>
+Sequential / Parallel: <which>
+Tasks: 2.1, 2.2, ...
+Unblocks: Wave 3
+
+### Wave 3 — <Name>
+Tasks: 3.1, ...
+
+## Executor Instructions
+
+Each subagent receives:
+1. spec.md (full)
+2. tasks.md (their task only)
+3. The codebase (branch: <branch-name>)
+4. No prior chat history
+
+## Human Checkpoints
+- After Wave 1: review and approve before Wave 2
+- After Wave 2: review and approve before Wave 3
+- After Wave 3: full verification before ship
+```
+
+### 6. Update status.md
+
+```markdown
+## Phase
+2.1 — Execute › Pick Spec ✅
+
+## Checklist
+...
+- [x] Spec fits context window (~Nk / 200k)
+- [ ] Branch created
+...
+```
+
+### 7. Handoff
+
+```
+Spec validated: <slug>
+
+Dependencies: ✅ met
+Context: ~<N>k / 200k ✅
+Tasks: X across Y waves
+Validation: ✅ complete
+
+Next: /branch <slug>
+```
+
+## Output
+
+- `superspec/phases/<slug>-execute/plan.md`
+- `superspec/phases/<slug>-execute/review-log.md` (empty template)
+- Updated `superspec/specs/<slug>/status.md`

package/.skills/execute-review/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: execute-review
+description: Review implementation against the spec between tasks. Two passes: spec compliance, then code quality. Critical findings BLOCK progress. Triggers on /code-review, between tasks, or when requested. Runs after each task in /subagent.
+slash_command: code-review
+phase: "2.5 — Execute › Code Review"
+---
+
+# Skill: execute-review
+
+You are reviewing implementation against the spec and for code quality.
+
+**This runs between tasks.** Not at the end — between each task, while changes are still small and fixable.
+
+**Critical findings block progress.** No task starts after a Critical finding until it's resolved.
+
+## Severity Levels
+
+| Level | Meaning | Action |
+|---|---|---|
+| **Critical** | Spec violation, security issue, data loss risk, test circumvented | **BLOCK. Stop all execution. Must be fixed before next task.** |
+| **High** | Logic error, wrong behavior, missing error handling | Must be resolved before wave ends |
+| **Medium** | Code quality issue, missed edge case, unclear abstraction | Should be resolved; note in review-log |
+| **Low** | Style, naming, minor improvement | Note in review-log; optional to fix |
+
+## Two-Pass Review
+
+### Pass 1: Spec Compliance
+
+Read `superspec/specs/<slug>/spec.md`. For every requirement in scope of the completed task:
+
+```markdown
+## Pass 1: Spec Compliance
+
+### ✅ Requirement: <Name>
+Scenario: <Name>
+Coverage: `<test-file>:<line>` — `<test name>`
+Verified: behavior matches spec ✅
+
+### ⚠️ Requirement: <Name>
+Scenario: <Name>
+Coverage: MISSING
+Severity: Critical
+Issue: This scenario has no test. The behavior is not verified.
+
+### ❌ Requirement: <Name>
+Scenario: <Name>
+Coverage: `<test-file>:<line>`
+Verified: FAILS — the implementation does X but spec says Y
+Severity: Critical
+```
+
+**If any Critical findings in Pass 1:** stop immediately. Report. Do not run Pass 2.
+
+### Pass 2: Code Quality
+
+Only run if Pass 1 is fully ✅ (or only Medium/Low findings).
+
+Review dimensions:
+
+**Logic correctness**
+- Are there cases where the code does the wrong thing?
+- Are error paths handled?
+- Are assumptions safe?
+
+**Test quality**
+- Do tests test behavior (not implementation)?
+- Are edge cases covered?
+- Are tests readable as documentation?
+
+**Structure**
+- DRY: is there duplication that should be extracted?
+- YAGNI: is there code that serves no current requirement?
+- Clarity: can this be read and understood without mental overhead?
+
+**Consistency**
+- Does this match patterns in the rest of the codebase?
+- Does naming follow existing conventions?
+
+```markdown
+## Pass 2: Code Quality
+
+### Strengths
+- <What's done well>
+
+### Findings
+
+#### [Critical] <Title>
+File: `<path>:<line>`
+Issue: <precise description>
+Why it matters: <impact>
+Fix: <concrete suggestion>
+
+#### [High] <Title>
+File: `<path>:<line>`
+Issue: <description>
+Fix: <suggestion>
+
+#### [Medium] <Title>
+...
+
+#### [Low] <Title>
+...
+```
+
+## After Review
+
+### Append to review-log.md
+
+Append to `superspec/phases/<slug>-execute/review-log.md`:
+
+```markdown
+## Review: Task <id> — <timestamp>
+
+### Pass 1: Spec Compliance
+Result: ✅ PASS / ❌ FAIL (N critical)
+
+### Pass 2: Code Quality
+Result: ✅ PASS / ⚠️ FINDINGS
+
+### Findings Summary
+| Severity | Count | Status |
+|----------|-------|--------|
+| Critical | 0 | — |
+| High     | 1 | resolved |
+| Medium   | 2 | noted |
+| Low      | 1 | noted |
+
+### Resolution
+<Critical findings resolved by: <description of fix>>
+```
+
+### Decision
+
+```
+Code Review: Task <id>
+
+Pass 1 (Spec): ✅ / ❌
+Pass 2 (Quality): ✅ / ⚠️ / ❌
+
+Critical findings: <N>
+
+→ APPROVED — proceed to next task
+→ BLOCKED — fix Critical findings before continuing
+```
+
+## Blocked State
+
+When blocked:
+
+```
+⛔ BLOCKED: Critical finding in Task <id>
+
+Finding: <description>
+File: <path>
+Fix required: <what needs to change>
+
+Execution paused. Resolve this before running the next task.
+When fixed, run /code-review again to clear the block.
+```
+
+Nothing proceeds until the block is cleared by a clean re-review.

package/.skills/execute-subagent/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: execute-subagent
+description: Dispatch fresh subagents per task for parallel execution. Two-stage review per task. Human checkpoints between waves. Triggers on /subagent, "start executing", "run the tasks", "dispatch agents". Run after /branch.
+slash_command: subagent
+phase: "2.3 — Execute › Subagent Development"
+---
+
+# Skill: execute-subagent
+
+You are orchestrating subagent-driven execution.
+
+Each subagent gets a **clean 200k-token context**: the spec, one task, and the codebase. Nothing else. No prior chat history. No shared state.
+
+## Core Principles
+
+- **Fresh context per task.** Each subagent starts clean.
+- **Two-stage review per task.** Every task gets reviewed for spec compliance first, then code quality.
+- **Human checkpoints between waves.** No wave starts without human approval.
+- **Critical findings block progress.** A Critical issue in code review stops the wave.
+
+## Steps
+
+### 1. Read the execution plan
+
+Read `superspec/phases/<slug>-execute/plan.md` and `superspec/specs/<slug>/tasks.md`.
+
+Identify:
+- The current wave (which one hasn't started yet)
+- Tasks in this wave
+- Whether they're sequential or parallel
+
+### 2. Prepare subagent context package
+
+For each task in this wave, assemble the context package. This is what each subagent receives — and ONLY this:
+
+```markdown
+# Subagent Context: <Task ID>
+
+## Spec
+<full contents of spec.md>
+
+## Your Task
+<single task block from tasks.md>
+
+## Codebase State
+Branch: superspec/<slug>
+Relevant files: <list files the task touches>
+
+## Rules
+1. Write the failing test first (see /tdd skill)
+2. Make it pass with minimum code
+3. Run all tests after your change
+4. Commit with message: "task <task-id>: <short description>"
+
+## Done When
+<done criteria from tasks.md for this task>
+```
+
+### 3. Execute the wave
+
+#### Sequential tasks
+Execute task by task. After each:
+1. Run `/tdd` enforcement (see tdd skill)
+2. Run `/code-review` (see code-review skill)
+3. If Critical finding: STOP. Report. Wait for resolution.
+4. If no Critical finding: proceed to next task.
+
+#### Parallel tasks
+For tasks that can run in parallel (stated in plan.md):
+
+Note: true parallel execution requires multiple worktrees or the user to manually run tasks in separate terminals. In single-agent mode, execute tasks sequentially but treat them as logically independent.
+
+Document in `wave-<N>.md` which tasks were parallelizable.
+
+### 4. Track progress in wave-N.md
+
+Create `superspec/phases/<slug>-execute/wave-<N>.md`:
+
+```markdown
+# Wave <N>: <Name>
+
+Started: <timestamp>
+
+## Task Status
+
+| Task | Status | Review | Notes |
+|------|--------|--------|-------|
+| 1.1 | ⏳ in progress | — | |
+| 1.2 | ✅ done | ✅ passed | |
+| 1.3 | ❌ blocked | ⚠️ critical finding | <issue> |
+
+## Review Log Summary
+(populated by /code-review)
+
+## Completed: <timestamp>
+```
+
+### 5. Human checkpoint
+
+After the wave completes (all tasks done, no Critical findings):
+
+```
+Wave <N> complete: <slug>
+
+Tasks: X/X ✅
+Review findings:
+  - Critical: 0
+  - High: <N> (resolved)
+  - Medium: <N> (noted)
+  - Low: <N> (noted)
+
+Tests: X passing
+
+Ready for Wave <N+1>?
+Show me the diff first, or type '/subagent <slug>' to continue.
+```
+
+**Wait for human approval before starting the next wave.**
+
+### 6. Final wave complete
+
+After all waves are done:
+
+```
+All waves complete: <slug>
+
+Total tasks: X
+Review findings resolved: Y
+Tests: X passing
+
+Next: /check-tests <slug>
+```
+
+Update `superspec/specs/<slug>/status.md`:
+```markdown
+## Phase
+2.3–2.5 — Execute ✅
+```
+
+## Batch Mode (alternative to wave mode)
+
+If the user says "batch mode", run all waves without human checkpoints between waves, but still run code review between tasks. Stop only on Critical findings.
+
+## Output
+
+- All task implementations committed to `superspec/<slug>` branch
+- `superspec/phases/<slug>-execute/wave-<N>.md` for each wave
+- `superspec/phases/<slug>-execute/review-log.md` populated
+- Updated status