superspecs 0.1.0

package/.skills/verify-wiki/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: verify-wiki
+description: Distill a completed, verified feature into the project wiki. Architecture decisions, patterns, trade-offs, gotchas. The knowledge that should outlive this session. Triggers on /wiki, "import to wiki", "document the feature". Runs after /check-tests passes.
+slash_command: wiki
+phase: "3.2 — Verify › Wiki Import"
+---
+
+# Skill: verify-wiki
+
+You are distilling the completed feature into the living project wiki.
+
+The feature works. The tests pass. Now you extract the knowledge that should survive beyond this session — so future planning, future features, and future sessions start informed.
+
+## What to distill (and what not to)
+
+**Distill:**
+- Architecture decisions (what was chosen and why)
+- Patterns discovered or established
+- Trade-offs made (what was given up, what was gained)
+- Gotchas (things harder than expected + how they were solved)
+- Key interfaces / contracts / data shapes
+- Open questions deferred to future work
+
+**Do NOT copy:**
+- Full code listings (reference file paths instead)
+- Task checklists or execution logs
+- The full spec (it lives in `superspec/specs/`)
+
+## Steps
+
+### 1. Gather the source material
+
+Read:
+- `superspec/specs/<slug>/DISCUSS.md`
+- `superspec/specs/<slug>/spec.md`
+- `superspec/phases/<slug>-execute/review-log.md`
+- The implementation itself (key files touched)
+
+### 2. Determine wiki structure
+
+Check `superspec/wiki/_index.md`. Identify:
+- Which domain folder this belongs in (create one if needed)
+- Whether any existing pages should be updated vs. new pages created
+
+Domain examples: `auth/`, `api/`, `data/`, `ui/`, `infra/`, `patterns/`, `decisions/`
+
+### 3. Write wiki pages
+
+For each meaningful knowledge unit:
+
+```markdown
+---
+title: <Page Title>
+tags: [<domain>, <feature-slug>, <topic-tags>]
+spec: superspec/specs/<slug>/spec.md
+created: <date>
+updated: <date>
+sources: [<slug>]
+---
+
+# <Page Title>
+
+## Summary
+1–2 sentences: what this is and why it exists in the project.
+
+## Context
+When and why this was built. What problem it solves.
+
+## Key Decisions
+
+### <Decision Topic>
+**Chose:** <X>
+**Over:** <Y>
+**Because:** <reason>
+**Trade-off:** <what was given up>
+
+### <Decision Topic>
+...
+
+## Patterns
+
+### <Pattern Name>
+<Description>
+
+```<lang>
+// Short illustrative example
+<example>
+```
+
+## Gotchas
+
+- **<Problem>:** <how it manifested and what resolved it>
+
+## Interface / Contract (if applicable)
+
+<Key API shape, data model, event format — whatever future code needs to know>
+
+## Open Questions
+
+- [ ] <Unresolved question deferred to future work>
+
+## Related
+- [[<wikilink>]] — <what it covers>
+- `<path/to/key/file>` — <what it does>
+```
+
+### 4. Update the wiki index
+
+Update `superspec/wiki/_index.md`:
+
+```markdown
+## Domains
+
+- [[auth/]] — Authentication & authorization
+- [[<new-domain>/]] — <description>
+
+## Recent Updates
+
+- <date>: [[<domain>/<page>]] — <brief description> (from `<slug>`)
+```
+
+### 5. Update the manifest
+
+Update `superspec/wiki/_manifest.json`:
+
+```json
+{
+  "sources": [
+    {
+      "slug": "<slug>",
+      "ingested_at": "<ISO timestamp>",
+      "pages_created": ["<domain>/<page>"],
+      "pages_updated": ["<domain>/<existing-page>"]
+    }
+  ]
+}
+```
+
+### 6. Cross-link
+
+After writing all pages:
+- Scan existing wiki pages for unlinked mentions of new page topics
+- Add `[[wikilinks]]` where relevant
+- Ensure the new pages link back to related existing pages
+
+### 7. Update spec status
+
+Update `superspec/specs/<slug>/status.md`:
+
+```markdown
+## Wiki Pages
+- [[superspec/wiki/<domain>/<page>]] — <what it covers>
+
+## Phase
+3.2 — Verify › Wiki Import ✅
+```
+
+### 8. Handoff
+
+```
+Wiki import complete: <slug>
+
+Pages created: X
+Pages updated: Y
+
+superspec/wiki/
+├── <domain>/
+│   ├── <page1>.md  (new)
+│   └── <page2>.md  (updated)
+└── _index.md (updated)
+
+Next: /ship <slug>
+```
+
+## Output
+
+- New/updated pages in `superspec/wiki/<domain>/`
+- Updated `superspec/wiki/_index.md`
+- Updated `superspec/wiki/_manifest.json`
+- Updated `superspec/specs/<slug>/status.md`

package/AGENTS.md

@@ -0,0 +1,38 @@
+# SuperSpecs — Agent Bootstrap
+
+SuperSpecs: spec-driven planning + parallel TDD execution + wiki memory.
+
+## Lifecycle (always in order)
+
+**Phase 0 — Setup**
+- `/techstack` — questionnaire: define stack, get skill & library recommendations, save to wiki
+
+**Phase 1 — Plan**
+- `/discuss` — capture decisions before planning
+- `/spec` — write spec (fits 200k context window)
+
+**Phase 2 — Execute**
+- `/pick-spec` — validate spec, check context fit
+- `/branch` — create branch/worktree
+- `/subagent` — fresh subagent per task, two-stage review
+- `/tdd` — RED-GREEN-REFACTOR, no exceptions
+- `/code-review` — critical issues block progress
+
+**Phase 3 — Verify**
+- `/check-tests` — full suite, every scenario covered
+- `/wiki` — distill to knowledge base
+
+**Phase 4 — Ship**
+- `/ship` — PR, archive, next cycle
+
+## Rules
+- No implementation code before a failing test
+- Critical review findings block all progress
+- Spec must fit a fresh 200k context window
+- Every shipped feature → wiki page
+
+## Paths
+- `superspec/specs/` — specs + DISCUSS.md files
+- `superspec/phases/` — execution working dirs
+- `superspec/wiki/` — knowledge base
+- `.skills/` — skill definitions

package/CLAUDE.md

@@ -0,0 +1,44 @@
+# SuperSpecs — Claude Code
+
+You have SuperSpecs installed. Four phases, always in order.
+
+## The Lifecycle
+
+```
+PLAN → EXECUTE → VERIFY → SHIP
+```
+
+### Phase 1: Plan
+1. `/discuss` — Capture decisions, goals, non-goals, constraints BEFORE any spec is written
+2. `/spec` — Write the spec (SHALL requirements + GIVEN/WHEN/THEN scenarios)
+
+**Exit gate:** Spec + context fits a fresh 200k context window. Too big = decompose.
+
+### Phase 2: Execute
+3. `/pick-spec` — Confirm spec is complete and context-window-fit
+4. `/branch` — Create git branch or worktree (one per spec)
+5. `/subagent` — Dispatch fresh subagent per task; two-stage review per task
+6. `/tdd` — RED → GREEN → REFACTOR. Write failing test. Watch it fail. Write minimal code. Watch it pass. Commit. Delete any code written before tests.
+7. `/code-review` — Runs between tasks. Critical issues BLOCK progress.
+
+### Phase 3: Verify
+8. `/check-tests` — Full suite. Every spec scenario must have a passing test.
+9. `/wiki` — Distill to knowledge base.
+
+### Phase 4: Ship
+10. `/ship` — PR + changelog + archive + start next cycle.
+
+## Hard Rules
+
+- Never write implementation code before a failing test exists
+- Never proceed past a Critical code review finding
+- Never skip `/discuss` — decisions captured late are decisions lost
+- Never declare done without `/check-tests` passing
+- Every shipped feature gets a wiki page
+
+## Paths
+
+- `superspec/specs/` — Specs and discussion docs
+- `superspec/phases/` — Active execution working dirs
+- `superspec/wiki/` — Living knowledge base
+- `.skills/` — Skill definitions

package/GEMINI.md

@@ -0,0 +1,9 @@
+# SuperSpecs — Gemini CLI Bootstrap
+
+SuperSpecs is a unified development framework: spec-driven planning + TDD implementation + living wiki memory.
+
+Follow the SuperSpecs lifecycle for every feature. Skills are in `.skills/` and `~/.gemini/skills/superspecs/`.
+
+Lifecycle: `/spec:plan` → `/spec:propose` → `/spec:implement` → `/spec:review` → `/spec:wiki`
+
+Query before building: `/spec:query <topic>`

package/HOWITWORKS.md

@@ -0,0 +1,208 @@
+# How SuperSpecs Works
+
+An explanation of the mechanics behind the framework — how skills are discovered, how agents load instructions, and how the four-phase lifecycle runs.
+
+---
+
+## The Core Idea
+
+AI coding agents (Claude Code, Cursor, Copilot, OpenCode, Gemini CLI, Codex, Windsurf) are instruction-followers. They do not have an opinion about _how_ to develop software — they follow whatever guidance is in their context. SuperSpecs exploits this by injecting a structured, opinionated workflow into every agent's context before any development begins.
+
+The result: every agent on every project follows the same four-phase lifecycle — Plan, Execute, Verify, Ship — without any custom integration code.
+
+---
+
+## Skills
+
+A **skill** is a Markdown file (`SKILL.md`) that contains step-by-step instructions for one phase of the workflow. Skills are the only real source code in the framework.
+
+```
+.skills/
+└── execute-tdd/
+    └── SKILL.md        ← plain Markdown, no code
+```
+
+Each `SKILL.md` starts with a YAML frontmatter block:
+
+```yaml
+---
+name: TDD Execution
+description: Enforce RED → GREEN → REFACTOR with no exceptions
+slash_command: /tdd
+phase: "2.4"
+---
+```
+
+The rest of the file is a detailed, imperative instruction set written for the agent to follow when that slash command is invoked.
+
+---
+
+## Skill Discovery — How Agents Find Skills
+
+Each AI coding tool has a designated directory it scans for skills at startup. `setup.sh` symlinks every `SKILL.md` into each of those directories:
+
+```
+~/.claude/skills/execute-tdd.md   → .skills/execute-tdd/SKILL.md
+~/.agents/skills/execute-tdd.md   → .skills/execute-tdd/SKILL.md
+~/.codex/skills/execute-tdd.md    → .skills/execute-tdd/SKILL.md
+# ... same for every agent
+```
+
+When an agent starts, it reads its skills directory and registers each file as an available skill. The agent now knows about `/tdd`, `/spec`, `/ship`, and all the others — before any user message is sent.
+
+```
+Agent startup
+     │
+     ▼
+Read ~/.claude/skills/*.md
+     │
+     ▼
+Register skill: /discuss, /spec, /pick-spec, /branch,
+                /subagent, /tdd, /code-review,
+                /check-tests, /wiki, /ship
+     │
+     ▼
+Agent is ready — all commands available
+```
+
+---
+
+## Bootstrap Files
+
+Beyond skills, each agent also gets a **bootstrap file** that is loaded at the start of every session. These prime the agent with the lifecycle summary so it behaves correctly even before a slash command is issued.
+
+| File | Agent | Mechanism |
+|---|---|---|
+| `CLAUDE.md` | Claude Code | Auto-read at session start |
+| `AGENTS.md` | OpenCode / Aider / Codex | Auto-read at session start |
+| `GEMINI.md` | Gemini CLI | Auto-read at session start |
+| `.cursor/rules/superspecs.mdc` | Cursor | Always-on rule (`alwaysApply: true`) |
+| `.windsurf/rules/superspecs.md` | Windsurf | Always-on rule |
+| `.github/copilot-instructions.md` | GitHub Copilot | Workspace instructions |
+
+Bootstrap files are short — they contain the lifecycle diagram, the slash command table, the four hard rules, and the key directory paths. They fit comfortably in the initial context window and cost negligible tokens.
+
+---
+
+## The Four-Phase Lifecycle
+
+### Phase 1 — Plan
+
+**Goal:** Produce a spec that fits a fresh 200k-token context window.
+
+```
+/discuss  →  DISCUSS.md   (decisions, constraints, non-goals)
+/spec     →  spec.md      (SHALL requirements + GIVEN/WHEN/THEN scenarios)
+              tasks.md    (implementation task list)
+              status.md   (phase tracker)
+```
+
+The 200k window constraint is deliberate: any executor (subagent, fresh session, different agent) must be able to pick up the spec and work from it without needing prior chat history. If a spec is too large to fit, it is decomposed into smaller specs.
+
+### Phase 2 — Execute
+
+**Goal:** Implement the spec in parallel using isolated subagents, with TDD enforced at every step.
+
+```
+/pick-spec  →  Validates spec completeness; creates phases/<slug>-execute/plan.md
+/branch     →  git branch or worktree; one branch per spec
+/subagent   →  Fresh subagent per task; wave-based dispatch; human checkpoints
+/tdd        →  RED (failing test) → GREEN (minimal code) → REFACTOR → commit
+/code-review →  Spec compliance then code quality; Critical findings block progress
+```
+
+Each subagent receives: the spec, its task, and nothing else. No shared state. No reliance on context from other agents. This is what makes parallel execution safe.
+
+### Phase 3 — Verify
+
+**Goal:** Confirm the implementation matches the spec and the knowledge is preserved.
+
+```
+/check-tests  →  Full suite run; every spec scenario covered by a test; no skips
+/wiki         →  Distill to superspec/wiki/<domain>/<topic>.md
+```
+
+The wiki is a living knowledge base — architecture decisions, patterns, trade-offs, gotchas. It survives after the session ends and informs future planning.
+
+### Phase 4 — Ship
+
+**Goal:** Merge and close the loop.
+
+```
+/ship  →  PR creation; changelog entry; phase directory archived; spec marked complete
+```
+
+After `/ship`, the cycle resets: `/pick-spec` for the next item.
+
+---
+
+## The `superspec/` Directory
+
+All runtime artifacts live under `superspec/`:
+
+```
+superspec/
+├── specs/
+│   └── <slug>/
+│       ├── DISCUSS.md      ← pre-planning decisions
+│       ├── spec.md         ← SHALL requirements + scenarios
+│       ├── tasks.md        ← task list for /subagent
+│       └── status.md       ← phase tracker + checklist
+│
+├── phases/
+│   └── <slug>-execute/
+│       ├── plan.md         ← decomposed execution plan
+│       ├── review-log.md   ← code review history
+│       └── wave-*.md       ← parallel execution waves
+│
+├── archive/
+│   └── <slug>-execute/     ← moved here after /ship
+│
+└── wiki/
+    ├── _index.md           ← domain listing + recent updates
+    ├── _manifest.json      ← ingestion log
+    └── <domain>/
+        └── <topic>.md      ← one page per shipped feature
+```
+
+`specs/` is permanent — specifications are never deleted, only marked complete in `status.md`.
+
+`phases/` is ephemeral — working directories are moved to `archive/` after shipping.
+
+`wiki/` grows continuously — every shipped feature adds at least one page.
+
+---
+
+## The Four Hard Rules
+
+These are enforced by the skills and bootstrap files. Agents are instructed to refuse to continue if any rule is violated.
+
+| Rule | Enforcement |
+|---|---|
+| No implementation code before a failing test | `/tdd` deletes code written before tests |
+| Critical code-review findings block all progress | `/code-review` reports severity; Critical = hard stop |
+| Spec must fit a fresh 200k-token context window | `/spec` and `/pick-spec` both check this |
+| Every shipped feature → wiki page | `/ship` requires `/wiki` to have run first |
+
+---
+
+## The CLI
+
+`bin/superspecs.js` is a thin Node.js wrapper with a single command:
+
+```bash
+superspecs install   # runs setup.sh
+```
+
+It exists so the framework can be distributed and installed via npm. All real logic is in `setup.sh` and the `.skills/` Markdown files.
+
+---
+
+## Creating a New Skill
+
+The `skill-creator` meta-skill documents the process. In short:
+
+1. Create `.skills/<name>/SKILL.md` with YAML frontmatter (`name`, `description`, `slash_command`, `phase`)
+2. Write the step-by-step instructions in the body
+3. Run `bash setup.sh` to symlink the new skill into all agent directories
+4. Open your agent and invoke the new slash command to test it

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperSpecs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.