superspecs 0.1.0 → 0.2.0

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

@@ -0,0 +1,209 @@
+---
+name: plan-grill
+description: Relentless interview to stress-test a spec before execution. Validates every decision against the wiki and techstack. Triggers on /grill, "grill me", "stress-test the spec", "challenge the plan". Always runs after /spec, before /pick-spec.
+slash_command: grill
+phase: "1.3 — Plan › Grill"
+---
+
+# Skill: plan-grill
+
+You are a relentless interviewer. Your job is to stress-test the spec before any code is written.
+
+A spec that survives the grill is a spec worth executing. A spec that collapses under questioning was never ready.
+
+**Prerequisite:** `superspec/specs/<slug>/spec.md` must exist. If it doesn't, stop and say: *"Run `/spec` first. There is nothing to grill."*
+
+## What grilling is
+
+Grilling walks every branch of the decision tree in the spec — one question at a time. For each question you provide your recommended answer. You wait for feedback before continuing.
+
+You are not looking for validation. You are looking for gaps, contradictions, unstated assumptions, and decisions that haven't been made yet.
+
+If a question can be answered by exploring the codebase or the wiki, explore them instead of asking.
+
+## Steps
+
+### 1. Load the context
+
+Read all of the following before asking a single question:
+
+- `superspec/specs/<slug>/DISCUSS.md` — the original decisions
+- `superspec/specs/<slug>/spec.md` — the spec under review
+- `superspec/wiki/techstack/profile.md` — the defined stack (if it exists)
+
+Then perform a tiered wiki scan for context relevant to this spec:
+
+**Tier 1 — Index scan:**
+- 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 for relevance to this feature's domain and requirements
+
+**Tier 2 — Deep read:**
+- Open the 3–5 most relevant pages in full
+- Follow `[[wikilinks]]` one level deep for directly related pages
+
+Report what you loaded. Flag any contradictions you already see before the interview begins.
+
+### 2. Surface pre-flight conflicts
+
+Before the interview, scan for immediate issues:
+
+**Wiki conflicts:** Does anything in the spec contradict established patterns, decisions, or interfaces documented in the wiki?
+
+**Techstack conflicts:** Does the spec assume libraries, patterns, or approaches that contradict the defined techstack?
+
+**Internal contradictions:** Does the spec contradict itself between requirements or scenarios?
+
+Report any conflicts found as blockers. These must be resolved before continuing. If none found: "No pre-flight conflicts found."
+
+### 3. Run the interview
+
+Interview relentlessly. One question at a time.
+
+**For each question:**
+1. State the question clearly
+2. Provide your recommended answer with reasoning
+3. Wait for feedback — do not proceed until the user responds
+
+**Question domains to cover (in order of criticality):**
+
+**Scope & Boundaries**
+- Is the "Out of Scope" section complete? What is likely to be assumed in-scope that isn't listed?
+- Are there adjacent features that will be broken or need changes?
+- What happens at the edges — empty state, maximum load, concurrent access?
+
+**Requirements completeness**
+- For each SHALL statement: is the success condition unambiguous? Could two developers implement it differently and both claim compliance?
+- Are there implicit SHALLs not written down?
+- What triggers each requirement — is the trigger explicit?
+
+**Scenario coverage**
+- For each scenario: does GIVEN capture all necessary preconditions?
+- Is there a scenario for every error path mentioned in "Error Behavior"?
+- What happens when the system is in an unexpected state?
+
+**Wiki alignment**
+- Does this spec reuse existing patterns, or introduce new ones? If new — is that intentional?
+- Are interfaces consistent with what the wiki documents?
+- Will this break any documented contract?
+
+**Techstack alignment**
+- Does every technical approach in the spec align with the defined stack?
+- Are there library choices implied but not validated against the techstack?
+- Will this require deviating from the stack? If so — is that decision documented?
+
+**Testability**
+- Can every scenario be tested with the current stack?
+- Are there scenarios that require external services, special fixtures, or are difficult to make deterministic?
+- Is "Done" defined precisely enough that a subagent can verify it without asking?
+
+**Task decomposition (if tasks.md exists)**
+- Can Wave 1 tasks truly complete independently?
+- Do any tasks assume shared state that isn't in the spec?
+- Is the context budget estimate realistic?
+
+Stop the interview when:
+- Every branch of the decision tree has been resolved, OR
+- The user says "enough" / "I'm done"
+
+### 4. Write GRILL.md
+
+After the interview, write `superspec/specs/<slug>/GRILL.md`:
+
+```markdown
+# Grill Session: <Feature Name>
+
+Date: <today>
+Spec reviewed: superspec/specs/<slug>/spec.md
+
+## Pre-flight
+
+### Wiki conflicts
+<conflicts found, or "None">
+
+### Techstack conflicts
+<conflicts found, or "None">
+
+### Internal contradictions
+<contradictions found, or "None">
+
+## Questions & Resolutions
+
+### Q1: <Question asked>
+**Recommended:** <what you suggested>
+**Resolved:** <what was decided>
+**Impact:** <spec change required / no change / deferred>
+
+### Q2: <Question asked>
+...
+
+## Spec Changes Required
+
+<List of changes to spec.md that emerged from the grill session>
+- <Requirement X: needs clarification on Y>
+- <Scenario Z: missing edge case for W>
+- <Out of Scope: add V>
+
+## Deferred Questions
+
+<Questions that were consciously deferred to implementation, with the rationale>
+- [ ] <Question> — deferred because <reason>
+
+## Verdict
+
+**READY** — All decision branches resolved. Proceed to `/pick-spec`.
+OR
+**NEEDS REVISION** — Spec must be updated before execution. Required changes listed above.
+```
+
+### 5. Apply spec changes
+
+If the grill session surfaced required changes to `spec.md`:
+- Apply them directly. Do not ask for permission on small clarifications.
+- For structural changes (adding requirements, removing scope), summarize what changed.
+
+### 6. Update status.md
+
+```markdown
+## Phase
+1.3 — Plan › Grill ✅
+
+## Checklist
+- [x] Discussion complete (DISCUSS.md)
+- [x] Spec written
+- [x] Spec grilled and stress-tested (GRILL.md)
+- [x] Wiki conflicts: none / resolved
+- [x] Techstack conflicts: none / resolved
+- [ ] Branch created
+...
+```
+
+### 7. Handoff
+
+```
+Grill complete: <slug>
+
+Questions asked: X
+Spec changes applied: Y
+Deferred questions: Z
+
+Verdict: READY / NEEDS REVISION
+
+Next: /pick-spec <slug>
+```
+
+If verdict is NEEDS REVISION, do not suggest `/pick-spec`. Say: *"Update the spec first, then re-run `/grill <slug>` to confirm."*
+
+## Output
+
+- `superspec/specs/<slug>/GRILL.md`
+- Updated `superspec/specs/<slug>/spec.md` (if changes required)
+- Updated `superspec/specs/<slug>/status.md`
+
+## Rules
+
+- One question at a time. Never ask two questions in the same message.
+- Always provide your recommended answer. A question without a recommendation is lazy.
+- If the codebase or wiki can answer the question — go read them. Do not ask the human what already exists.
+- Pre-flight conflicts block the interview. Resolve them first.
+- A NEEDS REVISION verdict blocks `/pick-spec`. No exceptions.

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

@@ -25,15 +25,40 @@ The complete spec — plus the implementation context — must fit in a fresh 20
 
 ## Steps
 
-### 1. Read DISCUSS.md completely
+### 1. Read DISCUSS.md and design-context.md
 
 Read `superspec/specs/<slug>/DISCUSS.md`. Do not proceed without understanding it fully.
 
-### 2. Check for existing specs in this domain
+Then check for `superspec/specs/<slug>/design-context.md`. If it exists, read it completely before writing the spec. It carries design constraints from a DesignOS export — treat them as fixed inputs, not decisions to re-make:
 
-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
+- **Design system constraints** → add to Non-Functional Requirements + Out of Scope
+- **Data contract types** → add an Interface/Contract section or enrich Requirements
+- **Milestone structure** → use as the wave structure in `tasks.md`
+- **Test scaffolding** → use as starting points for GIVEN/WHEN/THEN scenarios (adapt, don't copy verbatim)
+- **Open questions** → check if they were answered in `DISCUSS.md`; if not, surface them in the spec's Out of Scope or flag them
+
+DISCUSS.md carries the human decisions. design-context.md carries the design constraints. The spec merges both.
+
+### 2. Query the wiki for relevant patterns
+
+Perform a tiered wiki scan for patterns, interfaces, and decisions relevant to this feature:
+
+**Tier 1 — Index scan:**
+- 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 for relevance to this feature's domain
+
+**Tier 2 — Deep read:**
+- Open the 3–5 most relevant pages in full
+- Note:
+  - Existing patterns this spec should follow or extend
+  - Established interfaces this feature must be consistent with
+  - Past decisions that constrain what's being designed
+  - Open questions from previous features this spec might resolve
+
+Also scan `superspec/specs/` for related specs (any status).
+
+**Report before writing.** If established wiki patterns conflict with what's described in DISCUSS.md, flag the conflict explicitly — do not silently apply one over the other.
 
 ### 3. Write spec.md
 
@@ -160,6 +185,7 @@ If over 150k, stop and propose decomposition before proceeding.
 - [x] Discussion complete (DISCUSS.md)
 - [x] Spec written
 - [x] Spec fits context window (~Xk / 200k)
+- [ ] Spec grilled and stress-tested (GRILL.md)
 - [ ] Branch created
 ...
 ```
@@ -176,9 +202,11 @@ Scenarios: Y
 Tasks: Z across W waves
 Context estimate: ~Xk / 200k ✅
 
-Next: /pick-spec <slug>
+Next: /grill <slug>
 ```
 
+Do not suggest `/pick-spec` directly. The spec must survive a grill session first.
+
 ## Output
 
 - `superspec/specs/<slug>/spec.md`

package/.skills/tag-taxonomy/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: tag-taxonomy
+description: Maintain a controlled vocabulary of canonical tags for the wiki vault. Creates and updates _meta/taxonomy.md. Audits all wiki pages for non-canonical tags and normalizes them. Triggers on /tag-taxonomy, "fix tags", "normalize wiki tags", "audit tags".
+slash_command: tag-taxonomy
+phase: "3.2 — Verify › Wiki Taxonomy"
+---
+
+# Skill: tag-taxonomy
+
+You are maintaining tag consistency across the wiki vault.
+
+Tags are how the Obsidian graph clusters knowledge. Without a controlled vocabulary, tags drift: "auth" and "authentication" and "Authorization" end up meaning the same thing, fragmenting the graph. This skill enforces one canonical tag per concept.
+
+---
+
+## The Taxonomy File
+
+`superspec/wiki/_meta/taxonomy.md` is the source of truth for canonical tags.
+
+Format:
+```markdown
+---
+title: Tag Taxonomy
+updated: <YYYY-MM-DD>
+---
+
+# Tag Taxonomy
+
+Canonical tag vocabulary for this vault. All wiki pages must use tags from this list.
+Add new tags here before using them in pages.
+
+## Domain Tags
+<!-- One tag per domain folder -->
+- `auth` — authentication and authorization
+- `api` — API design and contracts
+- `data` — data models and storage
+- `ui` — frontend and interface
+- `infra` — infrastructure and deployment
+- `patterns` — reusable implementation patterns
+- `decisions` — architecture decision records
+
+## Topic Tags
+<!-- Cross-domain concept tags -->
+- `jwt` — JSON Web Tokens
+- `caching` — caching strategies and implementations
+- `error-handling` — error handling patterns
+- `testing` — test strategy and patterns
+- `performance` — performance considerations
+- `security` — security concerns
+
+## Meta Tags
+<!-- Reserved for wiki structure -->
+- `index` — index and home pages (do not use in content pages)
+- `log` — activity log (reserved)
+- `insights` — generated insights pages
+- `lint` — lint report pages
+- `query-derived` — pages created from wiki-query results
+- `capture` — pages created from wiki-capture
+
+## Aliases
+<!-- Non-canonical → canonical mappings -->
+- `authentication` → `auth`
+- `authorization` → `auth`
+- `Authorization` → `auth`
+- `caches` → `caching`
+- `errors` → `error-handling`
+```
+
+---
+
+## Steps
+
+### Mode A — Init (first run, no taxonomy yet)
+
+If `superspec/wiki/_meta/taxonomy.md` does not exist:
+
+1. Scan all wiki pages and collect every tag in use
+2. Group by apparent intent (cluster similar tags)
+3. For each cluster, pick the shortest, clearest, lowercase-hyphenated canonical form
+4. Write `_meta/taxonomy.md` with:
+   - Domain tags (one per domain folder)
+   - Topic tags (all unique concepts found)
+   - Alias map (non-canonical → canonical for each cluster)
+5. Report what was found and the proposed taxonomy — wait for confirmation before normalizing pages
+
+---
+
+### Mode B — Audit (taxonomy exists, check compliance)
+
+1. Read `_meta/taxonomy.md` — build canonical set + alias map
+2. Scan all wiki pages
+3. For each page, check `tags:` in frontmatter:
+   - Is every tag in the canonical set? → OK
+   - Is the tag an alias? → candidate for normalization
+   - Is the tag unknown (not canonical, not alias)? → flag for addition to taxonomy
+4. Report findings:
+
+```
+Tag Audit Report
+
+Canonical tags used: N
+Non-canonical tags found: M pages
+
+Aliases that can be auto-normalized:
+  "authentication" (4 pages) → "auth"
+  "Authorization" (2 pages) → "auth"
+  "caches" (1 page) → "caching"
+
+Unknown tags (not in taxonomy):
+  "websocket" (3 pages) — add to taxonomy as: `websocket` — WebSocket connections?
+  "rate-limit" (2 pages) — add to taxonomy as: `rate-limiting` — Rate limiting patterns?
+
+Auto-normalize aliases? [Y/N]
+Add unknown tags to taxonomy? [Y to review each / A for all / N to skip]
+```
+
+---
+
+### Mode C — Normalize (apply fixes after confirmation)
+
+For each alias normalization confirmed:
+1. Update `tags:` in each affected page's frontmatter
+2. Update `updated:` date
+3. Update alias map in `_meta/taxonomy.md` if not already there
+
+For each new tag added to taxonomy:
+1. Add to appropriate section in `_meta/taxonomy.md`
+
+Append to `log.md`:
+```markdown
+## [<YYYY-MM-DD>] taxonomy | normalized N tags across M pages
+```
+
+---
+
+## Output
+
+- `superspec/wiki/_meta/taxonomy.md` (created or updated)
+- Modified wiki pages (normalized tags)
+- Appended `superspec/wiki/log.md`
+- Audit report in response

package/.skills/techstack/SKILL.md

@@ -22,7 +22,7 @@ Work conversationally. One topic at a time. Never dump a wall of questions. Ask,
 
 Before asking anything, check for an existing tech stack profile:
 
-- Read `superspec/wiki/_index.md`
+- Read `superspec/wiki/Home.md` (if it exists)
 - Check for `superspec/wiki/techstack/profile.md`
 
 If a profile already exists:
@@ -456,15 +456,17 @@ _Browse all community skills: https://awesome-skills.com/_
 3. Reference this profile in every spec for consistency
 ```
 
-### 3.2 Update the wiki index
+### 3.2 Update the wiki Home page
 
-Add to `superspec/wiki/_index.md`:
+Update `superspec/wiki/Home.md` (create it if it doesn't exist) to include the techstack domain:
 
 ```markdown
 ## Domains
 
-- [[techstack/]] — Project tech stack, library choices, production checklists
-- ...existing domains...
+| Domain | Description |
+|--------|-------------|
+| [[techstack/]] | Project tech stack, library choices, production checklists |
+| _(further domains added as features ship)_ | |
 
 ## Recent Updates