superspecs 0.1.0

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

@@ -0,0 +1,168 @@
+---
+name: execute-tdd
+description: Enforce RED-GREEN-REFACTOR for every implementation task. Write failing test, watch it fail, write minimal code, watch it pass, commit. Delete code written before tests. Activates during implementation. Triggers on /tdd, when a task starts, or when code is being written without a test.
+slash_command: tdd
+phase: "2.4 — Execute › TDD"
+---
+
+# Skill: execute-tdd
+
+You are enforcing test-driven development. This skill activates during every implementation task.
+
+## The Law
+
+```
+RED → GREEN → REFACTOR
+```
+
+This is not a suggestion. It is the only permitted order of operations.
+
+Code written before a failing test exists gets **deleted**.
+
+## Steps
+
+### RED Phase
+
+#### 1. Read the task's test requirement
+
+Every task in `tasks.md` has a `Test requirement:` field. Read it before touching any implementation file.
+
+#### 2. Write the test
+
+Write a test that:
+- Tests the **behavior** described in the task (not implementation details)
+- Is specific enough to fail for the right reason
+- Uses the same test framework as the rest of the project (detect from existing test files)
+
+The test should read like documentation: *given this setup, when I do this, I expect this outcome.*
+
+#### 3. Run the test — confirm RED
+
+```bash
+# Run ONLY the new test (not the full suite)
+<test-runner> <test-file> -t "<test-name>"
+```
+
+**Expected: FAIL**
+
+Check the failure reason:
+- ✅ Right reason: the feature doesn't exist yet → proceed
+- ❌ Wrong reason: import error, syntax error, test setup problem → fix the test, not the implementation
+- ❌ Passes immediately: the test is wrong — it's not testing anything new → rewrite it
+
+Do not proceed to GREEN until the test fails for the right reason.
+
+### GREEN Phase
+
+#### 4. Write the minimum implementation
+
+Write the smallest amount of code that makes the test pass. That's it.
+
+Rules:
+- No code that isn't needed for this test
+- No "I'll need this later" additions (YAGNI)
+- No refactoring yet (that's REFACTOR phase)
+- No changing the test to make it pass easier
+
+#### 5. Run the test — confirm GREEN
+
+```bash
+<test-runner> <test-file> -t "<test-name>"
+```
+
+**Expected: PASS**
+
+If it fails, fix the implementation. Do not touch the test.
+
+#### 6. Run the full suite — confirm no regressions
+
+```bash
+<test-runner>
+```
+
+**Expected: all previously-passing tests still pass**
+
+If regressions exist: fix them before proceeding. A new feature that breaks existing behavior is not done.
+
+### REFACTOR Phase
+
+#### 7. Improve without changing behavior
+
+Look for:
+- Duplication (same logic in 2+ places) → extract
+- Unclear naming → rename
+- Unnecessary complexity → simplify
+- Inconsistency with project patterns → align
+
+Rules:
+- Tests stay green throughout
+- No new functionality
+- No changes that aren't improvements
+
+Run the full suite after each refactor step.
+
+#### 8. Commit
+
+```bash
+git add <changed files>
+git commit -m "task <task-id>: <description>
+
+- test: <what the test verifies>
+- impl: <what was implemented>
+"
+```
+
+## Violations
+
+### Code before test
+
+If implementation code was written before the test:
+
+```
+⚠️ Code found without test coverage.
+
+Files affected: <list>
+Action required: Delete implementation, write test first.
+
+The RED-GREEN-REFACTOR cycle must start from RED.
+```
+
+Delete the untested code. Start from RED.
+
+### Skipped tests
+
+If a test is skipped (`xit`, `skip`, `@pytest.mark.skip`, etc.):
+
+```
+⚠️ Skipped test found: <test name>
+
+Skipped tests do not count. Either:
+1. Remove the skip and make it pass
+2. Delete the test if it's no longer relevant
+```
+
+### Pending tests (test written, no implementation)
+
+This is acceptable as a planning step, but a task is not DONE until the test passes green.
+
+## Progress Report Format
+
+After each completed task:
+
+```
+✅ Task <id> — RED-GREEN-REFACTOR complete
+
+RED:   <test name> — failed (reason: <right reason>)
+GREEN: <test name> — passing
+SUITE: X tests passing, 0 failing, 0 skipped
+
+Commit: <short SHA> — "task <id>: <description>"
+```
+
+## What NOT to do
+
+- Do not write `// TODO: add test later`
+- Do not mock away the behavior being tested
+- Do not test implementation details (private methods, internal state)
+- Do not mark a task done while any test is red or skipped
+- Do not proceed to the next task before committing the current one

package/.skills/plan-discuss/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: plan-discuss
+description: Capture implementation decisions BEFORE any spec is written. Triggers on /discuss, "what are we building", "let's plan", "I want to build X", "new feature". Always runs before /spec.
+slash_command: discuss
+phase: "1.1 — Plan › Discuss"
+---
+
+# Skill: plan-discuss
+
+You are opening the discussion phase. This happens **before any spec is written**.
+
+The goal is to capture every decision, assumption, constraint, and open question so the spec that follows is grounded — not guessed.
+
+## Why this step exists
+
+Decisions made during planning are cheap. Decisions discovered during implementation are expensive. This step makes the cheap ones explicit before they become expensive ones.
+
+## Steps
+
+### 1. Orient with the wiki
+
+Before asking anything, check `superspec/wiki/`:
+- Read `_index.md`
+- Scan domain folders relevant to what's being described
+- Note: existing patterns, past decisions, anything that should inform this discussion
+
+Report what you found (or "wiki is empty / nothing relevant").
+
+### 2. Understand the rough idea
+
+Ask the user to describe what they want to build. Keep it conversational. One question at a time. Cover:
+
+**What**
+- What does this feature do from the user's perspective?
+- What problem does it solve?
+
+**Why now**
+- What's the trigger for building this?
+- What happens if we don't build it?
+
+**Constraints**
+- Technical constraints (existing stack, performance requirements, etc.)
+- Scope constraints (what's explicitly NOT included?)
+- Time or complexity constraints?
+
+**Success**
+- How do we know this is done?
+- What does "working" look like?
+
+**Risks**
+- What could go wrong?
+- What are we uncertain about?
+
+Do not ask all questions at once. Read the answers and ask follow-ups. Stop when you have enough to write the discussion doc.
+
+### 3. Write DISCUSS.md
+
+Create `superspec/specs/<slug>/DISCUSS.md`:
+
+```markdown
+# Discussion: <Feature Name>
+
+Date: <today>
+Participants: human + AI
+
+## What We're Building
+
+<1-2 paragraph summary in plain language>
+
+## Goals
+- <Goal>
+- <Goal>
+
+## Non-Goals (explicitly out of scope)
+- <Non-goal>
+- <Non-goal>
+
+## Constraints
+- **Technical:** <constraint>
+- **Scope:** <constraint>
+- **Other:** <constraint>
+
+## Key Decisions Made
+
+### Decision: <Topic>
+**We will:** <chosen approach>
+**Because:** <reason>
+**We won't:** <rejected alternative>
+
+[Repeat for each significant decision]
+
+## Open Questions
+- [ ] <Question that needs resolution before or during implementation>
+
+## Success Criteria
+- [ ] <Measurable outcome>
+- [ ] <Measurable outcome>
+
+## Risks
+- **<Risk>:** <Mitigation or acceptance>
+
+## Wiki References
+<Links to relevant existing wiki pages, or "None">
+```
+
+### 4. Create the spec directory and status file
+
+Create `superspec/specs/<slug>/status.md`:
+
+```markdown
+# <Feature Name> — Status
+
+## Phase
+1.1 — Plan › Discuss ✅
+
+## Checklist
+- [x] Discussion complete (DISCUSS.md)
+- [ ] Spec written
+- [ ] Spec fits context window
+- [ ] Branch created
+- [ ] Subagent execution complete
+- [ ] All tests passing
+- [ ] Code review passed (no Critical findings)
+- [ ] Wiki imported
+- [ ] PR created
+- [ ] Archived
+
+## Slug
+<slug>
+
+## Started
+<date>
+```
+
+### 5. Confirm and hand off
+
+Show the DISCUSS.md. Say:
+
+> "Discussion captured. Ready to write the spec? → `/spec <slug>`"
+
+Do not write the spec automatically. The user confirms first.
+
+## Output
+
+- `superspec/specs/<slug>/DISCUSS.md`
+- `superspec/specs/<slug>/status.md`
+- A clear handoff prompt to `/spec`

package/.skills/plan-spec/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: plan-spec
+description: Write an OpenSpec-style spec from the discussion document. Triggers on /spec, "write the spec", "create spec". Requires DISCUSS.md to exist. The spec must fit a fresh 200k context window.
+slash_command: spec
+phase: "1.2 — Plan › Spec"
+---
+
+# Skill: plan-spec
+
+You are writing the feature spec. This is the contract between planning and execution.
+
+**Prerequisite:** `superspec/specs/<slug>/DISCUSS.md` must exist. If it doesn't, stop and say: *"Run `/discuss` first to capture decisions before writing the spec."*
+
+## What a spec is
+
+A spec is a precise description of system behavior — not implementation details. It answers: *what must the system do?* Not: *how does it do it?*
+
+It uses SHALL for requirements. It uses GIVEN/WHEN/THEN for scenarios. Every requirement is testable.
+
+## The 200k Context Window Constraint
+
+The complete spec — plus the implementation context — must fit in a fresh 200k-token context window. This is not optional. It's what makes parallel execution possible: each executor starts clean.
+
+**Target:** spec.md under ~3,000 words. If you find yourself writing more, the feature is too large. Decompose it.
+
+## Steps
+
+### 1. Read DISCUSS.md completely
+
+Read `superspec/specs/<slug>/DISCUSS.md`. Do not proceed without understanding it fully.
+
+### 2. Check for existing specs in this domain
+
+Read `superspec/wiki/_index.md` and any related specs in `superspec/specs/`. Note:
+- Patterns already established (naming, structure, error formats)
+- Decisions already made that this spec should be consistent with
+
+### 3. Write spec.md
+
+Create `superspec/specs/<slug>/spec.md`:
+
+```markdown
+# <Feature Name> Specification
+
+**Slug:** <slug>
+**Status:** draft
+**Depends on:** <other spec slugs, or "none">
+
+## Purpose
+
+One paragraph: what this feature does and why it exists. Written from the user/system perspective, not the implementation perspective.
+
+## Requirements
+
+### Requirement: <Requirement Name>
+The system SHALL <behavior>.
+
+#### Scenario: <Scenario Name>
+- GIVEN <precondition>
+- WHEN <action or event>
+- THEN <expected outcome>
+- AND <additional outcome> (if needed)
+
+#### Scenario: <Edge case>
+- GIVEN <setup>
+- WHEN <unusual input or condition>
+- THEN <expected safe behavior>
+
+[Each requirement gets at least one happy-path scenario and at least one edge/error scenario]
+
+## Error Behavior
+
+Explicit SHALL statements for error cases:
+- The system SHALL return <error format> when <condition>
+- The system SHALL NOT <prohibited behavior>
+
+## Non-Functional Requirements (if applicable)
+- Performance: The system SHALL <behavior> within <timeframe>
+- The system SHALL handle <load> without <failure mode>
+
+## Out of Scope
+- <Explicit exclusion>
+- <Explicit exclusion>
+
+## Glossary (if terms need definition)
+- **<Term>:** <Definition>
+```
+
+### 4. Write tasks.md
+
+Decompose into concrete implementation tasks. Each task is small enough for one subagent with a fresh context.
+
+Create `superspec/specs/<slug>/tasks.md`:
+
+```markdown
+# Implementation Tasks: <Feature Name>
+
+## Context Window Budget
+Estimated spec + task tokens: ~<N>k / 200k ✅
+
+## Wave 1 — Foundation
+Tasks that must complete before Wave 2 can start.
+
+### Task 1.1: <Name>
+**What:** <Precise description>
+**Files to create/modify:** <list>
+**Test requirement:** Write a test for <specific behavior> that fails before implementation
+**Done when:** Test passes, no regressions
+
+### Task 1.2: <Name>
+**What:** <Precise description>
+**Files to create/modify:** <list>
+**Test requirement:** <behavior to test>
+**Done when:** Test passes, no regressions
+
+## Wave 2 — Core Logic
+Tasks runnable in parallel once Wave 1 is complete.
+
+### Task 2.1: <Name>
+...
+
+### Task 2.2: <Name>
+...
+
+## Wave 3 — Integration
+Final integration tasks.
+
+### Task 3.1: <Name>
+...
+
+## Done Criteria
+The feature is DONE when:
+- [ ] All tasks complete
+- [ ] All tests passing (zero skipped, zero pending)
+- [ ] Every scenario in spec.md has a corresponding passing test
+- [ ] Code review passed with no Critical findings
+- [ ] No regressions in unrelated tests
+```
+
+### 5. Context window check
+
+Estimate the token count of spec.md + tasks.md combined.
+
+- Under 50k tokens: ✅ Excellent
+- 50k–100k tokens: ✅ Fine
+- 100k–150k tokens: ⚠️ Consider trimming
+- Over 150k tokens: ❌ Too large — decompose into sub-specs
+
+Report: `Context estimate: ~Xk tokens / 200k window ✅`
+
+If over 150k, stop and propose decomposition before proceeding.
+
+### 6. Update status.md
+
+```markdown
+## Phase
+1.2 — Plan › Spec ✅
+
+## Checklist
+- [x] Discussion complete (DISCUSS.md)
+- [x] Spec written
+- [x] Spec fits context window (~Xk / 200k)
+- [ ] Branch created
+...
+```
+
+### 7. Handoff
+
+Show spec summary:
+
+```
+Spec ready: <slug>
+
+Requirements: X
+Scenarios: Y
+Tasks: Z across W waves
+Context estimate: ~Xk / 200k ✅
+
+Next: /pick-spec <slug>
+```
+
+## Output
+
+- `superspec/specs/<slug>/spec.md`
+- `superspec/specs/<slug>/tasks.md`
+- Updated `superspec/specs/<slug>/status.md`
+
+## What NOT to do
+
+- Do not write implementation details in the spec (no code, no file paths, no library choices)
+- Do not write spec.md without reading DISCUSS.md first
+- Do not proceed if the spec exceeds the context window budget — decompose instead
+- Do not invent requirements not discussed in DISCUSS.md

package/.skills/ship/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: ship
+description: Create the PR, write the changelog entry, archive the phase directory, mark the spec complete, and trigger the next cycle. Triggers on /ship, "create PR", "ship it", "merge". Final step in the SuperSpecs lifecycle.
+slash_command: ship
+phase: "4 — Ship"
+---
+
+# Skill: ship
+
+You are shipping the feature. Final step.
+
+**Preconditions — verify before proceeding:**
+- [ ] All tests passing (Phase 3.1 complete)
+- [ ] Wiki imported (Phase 3.2 complete)
+- [ ] No open Critical review findings
+- [ ] Branch is on `superspec/<slug>` with all commits
+
+If any precondition fails, stop and name the missing step.
+
+## Steps
+
+### 1. Final diff review
+
+```bash
+git log main..superspec/<slug> --oneline
+git diff main..superspec/<slug> --stat
+```
+
+Show a summary: how many files changed, how many commits. No surprises.
+
+### 2. Write the PR description
+
+```markdown
+## <Feature Name>
+
+### What
+<1–2 paragraphs: what was built, from the user/system perspective>
+
+### Why
+<The problem this solves, from DISCUSS.md>
+
+### How it works
+<Brief technical summary — key decisions, architecture shape>
+
+### Tests
+- Suite: X tests, all passing
+- New tests: Y (covering N spec scenarios)
+
+### Spec
+`superspec/specs/<slug>/spec.md`
+
+### Wiki
+<links to new wiki pages>
+
+### Checklist
+- [x] Tests passing
+- [x] Spec scenarios covered
+- [x] Code review passed
+- [x] Wiki updated
+- [x] No regressions
+```
+
+### 3. Create the PR
+
+Instruct the user (or if gh CLI is available):
+
+```bash
+gh pr create \
+  --base main \
+  --head superspec/<slug> \
+  --title "<Feature Name>" \
+  --body-file /tmp/pr-body.md
+```
+
+Or: output the PR body and say *"Create the PR with this description."*
+
+### 4. Write changelog entry
+
+If the project has a `CHANGELOG.md`:
+
+```markdown
+## [Unreleased]
+
+### Added
+- <Feature description> (closes #<issue if applicable>)
+```
+
+### 5. Archive the phase directory
+
+```bash
+mkdir -p superspec/archive
+mv superspec/phases/<slug>-execute superspec/archive/<slug>-execute
+```
+
+### 6. Mark spec complete
+
+Update `superspec/specs/<slug>/status.md`:
+
+```markdown
+## Phase
+4 — Shipped ✅
+
+## Completed
+<date>
+
+## PR
+<PR URL or number>
+
+## Checklist
+- [x] Discussion complete (DISCUSS.md)
+- [x] Spec written
+- [x] Spec fits context window
+- [x] Branch created
+- [x] Subagent execution complete
+- [x] All tests passing
+- [x] Code review passed (no Critical findings)
+- [x] Wiki imported
+- [x] PR created
+- [x] Archived
+
+## Wiki Pages
+- [[superspec/wiki/<domain>/<page>]] — <description>
+```
+
+### 7. Trigger next cycle
+
+```
+Shipped: <slug> ✅
+
+PR: <url or "ready to create">
+Tests: X passing
+Wiki: Y pages
+Archive: superspec/archive/<slug>-execute/
+
+─────────────────────────────────
+What's next?
+
+Available specs ready to execute:
+<list specs in planning or proposed state>
+
+Or start a new feature: /discuss
+```
+
+## Output
+
+- PR created (or PR body ready)
+- `CHANGELOG.md` updated
+- `superspec/phases/<slug>-execute/` → `superspec/archive/<slug>-execute/`
+- `superspec/specs/<slug>/status.md` marked complete
+- Prompt to start next cycle

package/.skills/skill-creator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: skill-creator
+description: Create a new SuperSpecs skill. Use when the user wants to extend the framework with a new workflow step or tool.
+slash_command: skill-creator
+---
+
+# Skill: skill-creator
+
+Create a new SuperSpecs skill.
+
+## A skill is
+
+A markdown file in `.skills/<skill-name>/SKILL.md` that an AI agent reads when triggered. Skills are instruction sets, not code.
+
+## Structure
+
+```markdown
+---
+name: <skill-name>
+description: <One sentence: what this skill does and when it triggers. Include trigger phrases.>
+slash_command: <command:name>
+---
+
+# Skill: <skill-name>
+
+Brief intro: what you're doing in this phase.
+
+## Inputs
+What files or context the agent needs to read first.
+
+## Steps
+Numbered, concrete steps. Include:
+- What to read
+- What to write
+- What to verify
+- What to report to the user
+
+## Output
+What files are created/updated.
+
+## What NOT to do
+Explicit prohibitions.
+```
+
+## Good skill design
+
+- **Concrete steps, not vague instructions.** "Read `tasks.md` completely" not "understand the plan".
+- **Explicit output.** List every file created or modified.
+- **Stopping conditions.** When should the skill ask for input before proceeding?
+- **Verification steps.** What does "done" look like?
+- **Non-negotiables.** What must never be skipped?
+
+## After creating
+
+1. Place file in `.skills/<skill-name>/SKILL.md`
+2. Run `setup.sh` to symlink into agent directories
+3. Test: open your agent and say "tell me about <skill-name>"
+
+## Integration with SuperSpecs lifecycle
+
+If the new skill fits into the lifecycle, add it to:
+- `README.md` skill reference table
+- `CLAUDE.md` skills list
+- `AGENTS.md` lifecycle overview