superspecs 0.1.0 → 0.2.0

package/.skills/cross-linker/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: cross-linker
+description: Scan the wiki vault for unlinked mentions of page titles and topics. Insert [[wikilinks]] automatically. Run after /wiki ingest or standalone. Triggers on /cross-linker, "cross-link the wiki", "add wikilinks", "link wiki pages".
+slash_command: cross-linker
+phase: "3.2 — Verify › Wiki Cross-link"
+---
+
+# Skill: cross-linker
+
+You are weaving the knowledge graph. After new pages are ingested, unlinked mentions of their topics exist across the vault — prose that says "JWT refresh" without linking to `[[auth/jwt-refresh]]`. You find those gaps and insert `[[wikilinks]]`.
+
+---
+
+## Steps
+
+### 1. Build the link target map
+
+Scan every `.md` file in `superspec/wiki/` (excluding `raw/`, `.obsidian/`, `_meta/`).
+
+For each page, collect:
+- The page path (e.g. `auth/jwt-refresh`)
+- The `title:` from frontmatter
+- Common aliases: derived from the title (e.g. "JWT Refresh", "jwt refresh", "JWT refresh token")
+- Any explicit `aliases:` field in frontmatter if present
+
+Build a lookup: `alias → [[domain/page]]`
+
+---
+
+### 2. Scan all pages for unlinked mentions
+
+For each wiki page, scan the body text for occurrences of any alias from the map that:
+1. Is **not already inside a `[[wikilink]]`**
+2. Is **not in a code block** (fenced ``` or inline `` ` ``)
+3. Is **not in a heading** (`#`, `##`, etc.)
+4. Is **not a self-reference** (page doesn't link to itself)
+5. Appears as a **standalone phrase** (not a substring of a longer word)
+
+Collect all candidates: `{page, line, alias, target}`.
+
+---
+
+### 3. Apply links — first occurrence per page only
+
+For each candidate:
+- Link only the **first occurrence** of each alias per page
+- Replace the plain text with `[[target|alias]]` if the alias differs from the page title, or `[[target]]` if it matches exactly
+- Preserve surrounding punctuation and capitalization
+
+Example:
+```
+Before: The system uses JWT refresh tokens to maintain sessions.
+After:  The system uses [[auth/jwt-refresh|JWT refresh tokens]] to maintain sessions.
+```
+
+Do **not** link:
+- Occurrences in frontmatter
+- Occurrences already inside `[[...]]`
+- Occurrences inside code blocks
+- Generic words that happen to match a title (use judgment — "data" should not auto-link to a page titled "Data")
+
+---
+
+### 4. Avoid over-linking
+
+Apply these guards:
+- Skip aliases shorter than 4 characters (too generic)
+- Skip aliases that are common English words unlikely to be intentional references (use judgment)
+- If uncertain: skip and note it in the report
+
+---
+
+### 5. Write changes
+
+For each modified page:
+- Apply all link insertions in a single write (don't write page multiple times)
+- Update the `updated:` date in frontmatter to today
+
+---
+
+### 6. Report
+
+```
+Cross-link complete
+
+Pages scanned: N
+Pages modified: M
+Links inserted: K
+
+Changes:
+- auth/session-management.md: 3 links inserted
+    - "JWT refresh" → [[auth/jwt-refresh]]
+    - "Redis" → [[infra/redis-cache]]
+    - "session TTL" → [[auth/session-management]] (self-link skipped)
+- patterns/error-handling.md: 1 link inserted
+    - "circuit breaker" → [[patterns/circuit-breaker]]
+
+Skipped (ambiguous):
+- data/pipeline.md: "data" matched [[data/Home]] — too generic, skipped
+
+Append to log.md: [YYYY-MM-DD] cross-link | K links inserted across M pages
+```
+
+---
+
+### 7. Append to log.md
+
+```markdown
+## [<YYYY-MM-DD>] cross-link | <K> links inserted across <M> pages
+```
+
+---
+
+## Output
+
+- Modified wiki pages with `[[wikilinks]]` inserted
+- Updated `updated:` dates in modified pages
+- Appended `superspec/wiki/log.md`
+- Cross-link report in response

package/.skills/design-import/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: design-import
+description: Import a DesignOS export as structured context for Phase 1 planning. Reads the export and creates a design-context.md that enriches /discuss and /spec with design constraints, data shapes, milestone structure, and test scaffolding. Optional — the normal /discuss + /spec flow still runs. Triggers on /design-import, "import design", "import DesignOS", "import from design export".
+slash_command: design-import
+phase: "1.x — Plan › Design Import (optional)"
+---
+
+# Skill: design-import
+
+You are enriching the Phase 1 planning process with a DesignOS export.
+
+This is an **optional step** — it does not replace `/discuss` or `/spec`. It reads a DesignOS export and extracts the design constraints, data shapes, milestone structure, and test scaffolding into a `design-context.md` file. The normal `/discuss` + `/spec` flow then uses both the discussion and the design context together.
+
+**Use it to integrate a DesignOS-built prototype into your planning — not to skip planning.**
+
+---
+
+## When to run it
+
+```
+# Run before /discuss — design context informs the conversation:
+/design-import <path> → /discuss → /spec → /grill
+
+# Run after /discuss — enrich discussion with design details before writing spec:
+/discuss → /design-import <path> → /spec → /grill
+
+# Run alongside /discuss — reference the context during discussion:
+/discuss (with design-context.md open as reference) + /design-import <path>
+```
+
+All paths still go through `/discuss`, `/spec`, and `/grill`. The design import adds structured input; it doesn't make those steps optional.
+
+---
+
+## Expected DesignOS Export Structure
+
+```
+<export-folder>/
+├── product-plan/
+│   ├── product-overview.md          ← product description, goals, non-goals
+│   ├── one-shot-instructions.md     ← (optional) full one-shot guide
+│   └── incremental/
+│       ├── 01-shell.md              ← milestone 1: design tokens + app shell
+│       ├── 02-<section>.md          ← milestone 2: first content section
+│       └── NN-<section>.md          ← milestone N: last section
+│
+├── design-system/
+│   ├── tokens.css                   ← CSS custom properties
+│   ├── tailwind.config.js           ← Tailwind configuration
+│   └── fonts.md                     ← font setup
+│
+├── data-shape/
+│   ├── types.ts                     ← TypeScript interfaces
+│   ├── sample-data.ts               ← sample data
+│   └── entities.md                  ← entity documentation
+│
+├── components/
+│   └── <section>/
+│       └── screenshots/             ← visual references
+│
+└── test-instructions/
+    ├── tests.md                     ← overall test specification
+    ├── user-flow-tests.md           ← (optional) end-to-end user flows
+    └── <section>-tests.md           ← per-section test specs
+```
+
+---
+
+## Steps
+
+### 1. Locate the export
+
+Ask the user for the path to the DesignOS export folder if not provided.
+
+Verify the folder exists and contains at minimum `product-plan/product-overview.md`.
+
+If the structure is partial (some files missing), proceed with what's available and note gaps.
+
+---
+
+### 2. Read the export
+
+Read in this order:
+
+1. `product-plan/product-overview.md` — product description, goals, constraints
+2. `product-plan/incremental/` — all milestone files, sorted numerically
+3. `test-instructions/tests.md` + per-section test files
+4. `data-shape/types.ts` + `entities.md`
+5. `design-system/tokens.css` — skim for token naming convention
+
+Do NOT read component `.tsx` files — they are reference material, not planning input.
+
+---
+
+### 3. Check for existing DISCUSS.md
+
+Check if `superspec/specs/<slug>/DISCUSS.md` already exists.
+
+- **If it does:** the design context will enrich it — merge relevant design decisions into the existing doc (Step 4b)
+- **If it doesn't:** create `design-context.md` as standalone context for the upcoming `/discuss` session (Step 4a)
+
+If no slug exists yet, derive one from the product name in `product-overview.md`.
+
+---
+
+### 4a. Create design-context.md (no DISCUSS.md yet)
+
+Create `superspec/specs/<slug>/design-context.md`:
+
+```markdown
+# Design Context: <Product Name>
+
+Source: DesignOS export — <export-folder-name>
+Imported: <today>
+
+> This file is input for `/discuss` and `/spec`. It captures the design constraints,
+> data contract, milestone plan, and test scaffolding from the DesignOS export.
+> Review it before running `/discuss` so these decisions inform the conversation.
+
+---
+
+## Product Overview
+
+<Summary from product-overview.md — what the product is and why it exists>
+
+## Design System (locked)
+
+The following are provided by the DesignOS export and should be treated as constraints, not decisions to re-make:
+
+- **CSS tokens:** `design-system/tokens.css` — all colors, spacing, typography
+- **Tailwind config:** `design-system/tailwind.config.js`
+- **Fonts:** see `design-system/fonts.md`
+
+No hardcoded color or spacing values. All styling via the token set.
+
+## Data Contract
+
+Types from `data-shape/types.ts` that are relevant to planning:
+
+```typescript
+<key interfaces — trimmed to what matters for behavior decisions>
+```
+
+Entity relationships: <summary from entities.md>
+
+## Build Order (Incremental Milestones)
+
+The DesignOS export defines N milestones. Each should become one execution wave:
+
+| Wave | Milestone | What it builds |
+|------|-----------|---------------|
+| 1 | 01-shell | Design tokens applied, app shell structure |
+| 2 | 02-<section> | <section description> |
+| … | … | … |
+
+**Shell (Wave 1) must complete before any section wave.** Each section wave depends on the shell having established design tokens and layout structure.
+
+## Test Scaffolding
+
+Key behaviors from `test-instructions/tests.md` to incorporate into spec scenarios:
+
+<Extracted test scenarios as bullet points — what needs to be verified>
+
+**User flows:**
+<From user-flow-tests.md if present>
+
+**Per-section tests:**
+<Summarized from section test files>
+
+## Open Questions for /discuss
+
+Based on the export, these decisions still need to be made in the discussion:
+
+- [ ] <Gap or ambiguity found in the export>
+- [ ] <Stack/framework choice if not specified>
+- [ ] <Integration points not covered by the design>
+
+## Visual References
+
+Screenshots preserved in `superspec/wiki/raw/design-system/screenshots/` for use during execution.
+```
+
+---
+
+### 4b. Enrich existing DISCUSS.md
+
+If DISCUSS.md already exists, add a `## Design Import` section to it:
+
+```markdown
+## Design Import
+
+Source: DesignOS export — <export-folder-name>
+Imported: <today>
+
+### Design System Constraints (locked)
+- CSS tokens: `design-system/tokens.css` — use as-is
+- Tailwind: `design-system/tailwind.config.js` — use as-is
+- No hardcoded styling values
+
+### Data Contract
+<Key types from types.ts relevant to this feature>
+
+### Milestone Structure → Waves
+| Wave | Milestone | What it builds |
+|------|-----------|---------------|
+| 1 | 01-shell | Design tokens + shell |
+| … | … | … |
+
+### Test Scaffolding
+<Key test scenarios to incorporate into spec>
+
+### Additional Open Questions
+- [ ] <Gaps found in the design export>
+```
+
+---
+
+### 5. Preserve design assets in wiki/raw/
+
+Copy to `superspec/wiki/raw/design-system/`:
+
+```
+superspec/wiki/raw/design-system/
+├── tokens.css
+├── tailwind.config.js
+├── fonts.md
+├── entities.md
+└── screenshots/
+    └── <section>/
+```
+
+Create `superspec/wiki/raw/design-system/README.md` with source info and link to spec slug.
+
+---
+
+### 6. Update status.md
+
+If status.md exists, add a line. If not, create it:
+
+```markdown
+## Design Import
+- [x] DesignOS export imported (design-context.md)
+- [x] Design assets preserved (wiki/raw/design-system/)
+```
+
+---
+
+### 7. Handoff
+
+```
+Design import complete: <slug>
+
+Created: superspec/specs/<slug>/design-context.md
+Preserved: superspec/wiki/raw/design-system/
+
+What was extracted:
+  - Design system constraints (tokens, Tailwind, fonts)
+  - Data contract (N TypeScript interfaces)
+  - N milestones → N execution waves (sequential)
+  - Test scaffolding (N scenarios)
+  - N open questions for /discuss
+
+Next steps:
+  /superspecs:discuss <slug>   Open the discussion (design-context.md is ready as input)
+  /superspecs:spec <slug>      Write the spec (reads DISCUSS.md + design-context.md)
+```
+
+---
+
+## How /spec uses design-context.md
+
+When `/spec` runs, it should check for `design-context.md` alongside `DISCUSS.md`:
+
+- Design system constraints → Non-Functional Requirements + Out of Scope section
+- Data contract types → Interface/Contract section
+- Milestone structure → waves in `tasks.md`
+- Test scaffolding → GIVEN/WHEN/THEN scenarios (starting points, not verbatim copy)
+- Open questions → open questions in DISCUSS.md (if not yet addressed)
+
+The spec writer merges both sources. DISCUSS.md carries the human decisions; design-context.md carries the design constraints.
+
+---
+
+## Output
+
+- `superspec/specs/<slug>/design-context.md` (if no DISCUSS.md exists)
+- OR enriched `superspec/specs/<slug>/DISCUSS.md` (if DISCUSS.md already exists)
+- `superspec/wiki/raw/design-system/` (design assets for later wiki ingest)
+- Updated `superspec/specs/<slug>/status.md`

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Dispatch fresh subagents per task for parallel execution. Each subagent runs RED-GREEN-REFACTOR TDD on their task. 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"
 ---
@@ -11,9 +11,12 @@ 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.
 
+**TDD is not a separate step after subagent development. TDD happens inside every subagent task.** Each task follows RED → GREEN → REFACTOR before it is considered done. The `/superspecs:tdd` skill defines the cycle; this skill embeds it into every task.
+
 ## Core Principles
 
 - **Fresh context per task.** Each subagent starts clean.
+- **TDD per task.** Every task: RED → GREEN → REFACTOR → commit. No exceptions.
 - **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.
@@ -46,11 +49,29 @@ For each task in this wave, assemble the context package. This is what each suba
 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>"
+## TDD — Non-Negotiable
+You follow RED → GREEN → REFACTOR for every piece of implementation code.
+
+**RED**
+1. Write a failing test for the behavior described in your task
+2. Run it — confirm it fails for the RIGHT reason (feature missing, not a syntax error)
+   - If it passes immediately: the test is wrong. Rewrite it.
+   - If it fails for the wrong reason: fix the test, not the implementation.
+
+**GREEN**
+3. Write the minimum code to make the test pass
+   - No YAGNI additions. No refactoring yet.
+4. Run the test — confirm PASS
+5. Run the full test suite — confirm no regressions
+
+**REFACTOR**
+6. Clean up: duplication, naming, complexity — keep tests green throughout
+7. Run the full suite after each refactor step
+
+**COMMIT**
+8. `git commit -m "task <task-id>: <description>"`
+
+**Code written before a failing test exists gets deleted. Start over from RED.**
 
 ## Done When
 <done criteria from tasks.md for this task>
@@ -59,11 +80,10 @@ Relevant files: <list files the task touches>
 ### 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.
+Execute task by task. For each task, the subagent follows the full TDD cycle (RED-GREEN-REFACTOR) as defined in the context package above. After TDD is complete:
+1. Run `/code-review` (see code-review skill)
+2. If Critical finding: STOP. Report. Wait for resolution.
+3. If no Critical finding: proceed to next task.
 
 #### Parallel tasks
 For tasks that can run in parallel (stated in plan.md):

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

@@ -1,13 +1,15 @@
 ---
 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.
+description: Enforce RED-GREEN-REFACTOR for every implementation task. This cycle runs inside each subagent task — not as a separate sequential step. Triggers on /tdd, when a task starts, or when code is being written without a failing test. Also used standalone when implementing outside of subagent mode.
 slash_command: tdd
-phase: "2.4 — Execute › TDD"
+phase: "2.3 — Execute › per task (TDD)"
 ---
 
 # Skill: execute-tdd
 
-You are enforcing test-driven development. This skill activates during every implementation task.
+You are enforcing test-driven development. **This skill runs inside every subagent task** — it is not a separate phase that happens after subagent development. Every implementation task, in every wave, follows this cycle.
+
+If you are implementing code outside of subagent mode (e.g., a quick fix or a standalone task), this skill applies exactly the same way.
 
 ## The Law
 

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

@@ -19,12 +19,21 @@ Decisions made during planning are cheap. Decisions discovered during implementa
 
 ### 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
+Before asking anything, scan the wiki for relevant context using tiered retrieval:
 
-Report what you found (or "wiki is empty / nothing relevant").
+**Tier 1 — Index scan (always):**
+- Read `superspec/wiki/Home.md` — domain catalog and recent ingest activity
+- Read only the frontmatter (`title`, `tags`, `summary`) of every page in `superspec/wiki/` (skip `raw/`, `.obsidian/`)
+- Score each page for relevance to the feature being described
+
+**Tier 2 — Deep read (targeted):**
+- Open the full body of the 3–5 most relevant pages
+- Follow `[[wikilinks]]` one level deep for directly related pages
+
+**Report before the first question:**
+- List relevant pages found with a one-line summary of what each contributes
+- Flag decisions, patterns, or interfaces that should inform or constrain this discussion
+- If the wiki is empty or nothing is relevant: say so explicitly — "Wiki has no relevant pages for this feature."
 
 ### 2. Understand the rough idea