superspecs 0.1.0 → 0.2.0

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

@@ -0,0 +1,157 @@
+---
+name: wiki-query
+description: Query the compiled project wiki to answer a question. Uses tiered retrieval — summaries first, full pages only when needed. Synthesizes answers from existing wiki pages only, never from raw specs or the internet. Optionally files the answer back as a new wiki page. Triggers on /wiki-query, "search the wiki for...", "what does the wiki say about...", "ask the wiki".
+slash_command: wiki-query
+phase: "3.2 — Verify › Wiki Query"
+---
+
+# Skill: wiki-query
+
+You are answering a question using the compiled project wiki.
+
+The wiki at `superspec/wiki/` is a compiled knowledge base. It has already processed the raw specs, decisions, and review logs. **Read the wiki, not the raw sources.** This is the key efficiency of the LLM Wiki pattern: compile once, query fast.
+
+---
+
+## The 3-Layer Context
+
+```
+superspec/wiki/raw/     ← source material (ingest reads this; query does NOT)
+superspec/wiki/         ← compiled wiki (query reads this exclusively)
+.skills/wiki-query/     ← schema: these instructions
+```
+
+**Never read `raw/` to answer a query.** If the answer isn't in `wiki/`, the knowledge hasn't been compiled yet — that's a signal to run `/wiki` first.
+
+---
+
+## Tiered Retrieval
+
+Query in two phases to keep cost flat as the vault grows:
+
+### Phase 1 — Index scan (cheap)
+
+Read only the frontmatter of every wiki page (excluding `raw/`, `.obsidian/`):
+- `title`
+- `summary` (1–2 sentence preview)
+- `tags`
+
+Also read:
+- `superspec/wiki/Home.md` — domain table and recent updates
+- `superspec/wiki/log.md` — recent activity
+
+Score each page for relevance to the query. Select the top 3–5 candidates.
+
+**If the user says "quick answer" or "just scan":** answer from Phase 1 only — do not open page bodies.
+
+### Phase 2 — Deep read (targeted)
+
+Open the full body of the top 3–5 candidate pages only. Read:
+- All sections
+- Follow `[[wikilinks]]` to directly related pages (one level deep)
+
+Synthesize the answer from Phase 2 content.
+
+---
+
+## Steps
+
+### 1. Receive the question
+
+The user provides a question, topic, or keyword. Examples:
+- "What do we know about authentication?"
+- "What was the decision on database choice?"
+- "What patterns do we use for error handling?"
+- "Find everything about the payment integration"
+
+---
+
+### 2. Phase 1 — Index scan
+
+For each wiki page, read frontmatter only. Score relevance:
+- Title contains query keyword → high relevance
+- `tags:` overlap with query topic → medium relevance
+- `summary:` contains query concept → medium relevance
+
+Select top 3–5 by relevance score. If Phase 1 returns zero candidates → signal gap (Step 5).
+
+---
+
+### 3. Phase 2 — Deep read
+
+Open full body of top candidates. Follow `[[wikilinks]]` one level deep for directly linked pages.
+
+Collect all relevant content. Note provenance markers:
+- No marker = extracted from source
+- `^[inferred]` = agent synthesis
+- `^[ambiguous]` = sources disagree — flag this in the answer
+
+---
+
+### 4. Synthesize the answer
+
+Write a synthesized answer **in your response**:
+
+```
+## Answer: <query topic>
+
+<2–4 paragraph synthesis drawn from the wiki>
+
+### Sources
+- [[<domain>/<page>]] — <one-line summary of what it contributed>
+- [[<domain>/<page2>]] — <one-line summary>
+
+### Inferred content
+<If any part of the answer is marked ^[inferred] or ^[ambiguous], call it out:>
+"Note: the claim about X is inferred synthesis, not stated verbatim in sources."
+
+### Gaps
+<If the wiki doesn't have full coverage:>
+"The wiki has no pages about <X>. If this was covered in a spec, run /wiki to compile it first."
+```
+
+**Cite only wiki pages** — not raw spec files, not source code files.
+
+---
+
+### 5. Signal gaps clearly
+
+If Phase 1 returns no relevant pages:
+
+```
+The wiki doesn't have pages about "<X>" yet.
+
+This means either:
+  a) The feature hasn't been shipped yet (no spec/execution cycle completed)
+  b) The feature was shipped but not imported — run: /wiki <slug>
+  c) The knowledge lives only in raw/ — it hasn't been compiled yet
+
+I found partial coverage in: [[<related-page>]] (if any)
+```
+
+---
+
+### 6. Optionally file the answer back
+
+After answering, offer:
+
+```
+File this answer to the wiki?
+  [Y] Yes — create wiki/<domain>/<topic>.md
+  [U] Update an existing page instead
+  [N] No — one-off answer only
+```
+
+If the user confirms, write the page using the standard wiki page format including `summary:` and `provenance:` fields. Mark synthesized content as `^[inferred]`. Then:
+- Update the relevant domain `Home.md`
+- Append to `log.md`: `## [YYYY-MM-DD] query | <topic>`
+- Run `/cross-linker` to weave new page into the knowledge graph
+
+---
+
+## Output
+
+- Synthesized answer in the response
+- Optionally: new wiki page in `superspec/wiki/<domain>/<topic>.md`
+- Optionally: updated domain `Home.md`
+- Optionally: appended `superspec/wiki/log.md`

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

@@ -0,0 +1,163 @@
+---
+name: wiki-rebuild
+description: Archive the current wiki vault and rebuild it from scratch from raw source material and specs. Use when the wiki has drifted too far from its sources or accumulated too much drift. Also restores from a previous archive. Triggers on /wiki-rebuild, "rebuild the wiki", "archive and rebuild", "reset the wiki".
+slash_command: wiki-rebuild
+phase: "3.2 — Verify › Wiki Rebuild"
+---
+
+# Skill: wiki-rebuild
+
+You are managing the vault lifecycle — archiving and rebuilding when the wiki needs a clean slate.
+
+**When to rebuild:**
+- The wiki has accumulated too much drift (contradictions, stale content, structural mess)
+- A major architectural change makes existing pages misleading
+- The tag taxonomy was restructured and pages need a full re-pass
+
+**This is a destructive operation on the compiled wiki.** Raw source material in `raw/` and specs in `superspec/specs/` are never touched. The rebuild reconstructs from those sources.
+
+---
+
+## Modes
+
+### `archive` — Snapshot and preserve
+Create a timestamped archive of the current vault. No rebuild.
+
+### `rebuild` — Archive then reconstruct
+Archive the current vault, then compile all sources from scratch.
+
+### `restore <timestamp>` — Roll back
+Restore a previous archive by timestamp.
+
+### `list` — Show available archives
+List all archived snapshots.
+
+---
+
+## Steps
+
+### Archive
+
+1. Create `superspec/wiki/_archives/<YYYY-MM-DD-HH-MM>/`
+2. Copy the entire `superspec/wiki/` directory into it (excluding `raw/`, `_archives/`, `.obsidian/`)
+3. Write a manifest for the archive:
+
+```json
+// _archives/<timestamp>/archive-manifest.json
+{
+  "archived_at": "<ISO timestamp>",
+  "pages": N,
+  "domains": ["auth", "api", ...],
+  "reason": "<user-provided or 'manual'>",
+  "last_ingested_slug": "<slug>"
+}
+```
+
+4. Print:
+```
+Archive created: superspec/wiki/_archives/<timestamp>/
+Pages preserved: N
+```
+
+---
+
+### Rebuild
+
+After archiving:
+
+1. **Clear the compiled wiki** — delete all `.md` files and `_manifest.json` from `superspec/wiki/` except:
+   - `raw/` (source material — never touched)
+   - `.obsidian/` (vault config — never touched)
+   - `_archives/` (previous snapshots)
+   - `log.md` (append-only — preserve, add rebuild event)
+
+2. **Re-initialize vault structure:**
+   - New `Home.md` from template
+   - New `_manifest.json`: `{"sources": []}`
+   - Preserve `_meta/taxonomy.md` if it exists (tag vocabulary is still valid)
+
+3. **Recompile all sources in order:**
+
+   For each slug in `superspec/specs/` (ordered by `status.md` phase — shipped first):
+   - If spec has `## Phase ... ✅` in status.md → it was shipped → compile to wiki
+   - Follow the full `verify-wiki` ingest process for each slug
+
+   For each file in `superspec/wiki/raw/`:
+   - Compile to wiki pages
+
+4. **Post-rebuild:**
+   - Run cross-linker to weave all `[[wikilinks]]`
+   - Run tag-taxonomy audit
+   - Append to `log.md`:
+
+```markdown
+## [<YYYY-MM-DD>] rebuild | Vault rebuilt from scratch
+
+- Archive: _archives/<timestamp>/
+- Sources recompiled: N specs + M raw files
+- Pages created: K
+- Reason: <user-provided>
+```
+
+5. Print:
+```
+Rebuild complete
+
+Archive: superspec/wiki/_archives/<timestamp>/
+Pages rebuilt: K
+Specs compiled: N
+Raw files compiled: M
+
+Run /wiki-status to see the new vault state.
+Run /wiki-lint to verify health.
+```
+
+---
+
+### Restore
+
+1. Confirm with user: `Restore from <timestamp>? This will overwrite the current wiki. [Y/N]`
+2. Archive the current state first (auto-archive before restore)
+3. Copy `_archives/<timestamp>/` → `superspec/wiki/` (excluding `raw/`, `.obsidian/`, `_archives/`)
+4. Append to `log.md`:
+
+```markdown
+## [<YYYY-MM-DD>] restore | Restored from archive <timestamp>
+
+- Previous state auto-archived as: _archives/<auto-timestamp>/
+```
+
+---
+
+### List
+
+Print all available archives:
+
+```
+Available archives:
+
+  2026-06-15-14-30  (N pages, reason: "pre-refactor snapshot")
+  2026-05-20-09-15  (N pages, reason: "manual")
+  2026-04-10-16-00  (N pages, reason: "rebuild")
+
+To restore: /wiki-rebuild restore <timestamp>
+```
+
+---
+
+## Safety Rules
+
+- **Never delete `raw/`** — source material is immutable
+- **Never delete `.obsidian/`** — vault config must survive
+- **Never delete `log.md`** — append-only, always preserved
+- **Always archive before rebuild or restore** — no data loss
+- **Always confirm before destructive operations** — print what will happen and wait for [Y/N]
+
+---
+
+## Output
+
+- `superspec/wiki/_archives/<timestamp>/` (archive)
+- Rebuilt wiki pages (rebuild mode)
+- Appended `superspec/wiki/log.md`
+- Summary report in response

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

@@ -0,0 +1,156 @@
+---
+name: wiki-status
+description: Show a health and activity dashboard for the compiled wiki vault. Ingested pages, pending sources, hub pages with most backlinks, tag distribution, recent activity. Triggers on /wiki-status, "wiki dashboard", "wiki stats", "what's in the wiki".
+slash_command: wiki-status
+phase: "3.2 — Verify › Wiki Status"
+---
+
+# Skill: wiki-status
+
+You are producing a health and activity dashboard for `superspec/wiki/`.
+
+This is a read-only operation. No files are written except an optional `_insights.md`.
+
+---
+
+## Steps
+
+### 1. Inventory the vault
+
+Scan all `.md` files in `superspec/wiki/` (excluding `raw/`, `.obsidian/`).
+
+Collect for each page:
+- Path, title, domain
+- `created:` and `updated:` dates from frontmatter
+- `tags:` list
+- `summary:` (for preview)
+- All outbound `[[wikilinks]]`
+- Count of inbound `[[wikilinks]]` from other pages (backlinks)
+- Provenance block if present
+
+Also read:
+- `_manifest.json` — ingestion history
+- `log.md` — recent events
+
+---
+
+### 2. Compute metrics
+
+**Vault size**
+- Total pages (excluding Home indexes, log, manifest, lint report)
+- Pages by domain
+- Pages created this month / this quarter
+
+**Activity**
+- Last ingest: date + slug
+- Last query: date + topic
+- Last lint: date + issue count
+- Last cross-link run: date + links inserted
+
+**Hub pages** (most inbound backlinks)
+- Top 5 pages by backlink count
+- These are the most-referenced knowledge nodes
+
+**Orphaned pages** (no inbound backlinks, not an index)
+- Quick count — detail in `/wiki-lint`
+
+**Tag distribution**
+- Top 10 tags by frequency
+- Tags not in `_meta/taxonomy.md` (if taxonomy exists)
+
+**Provenance distribution** (across all pages with `provenance:` block)
+- Average extracted / inferred / ambiguous ratios
+- Pages with high inferred ratio (>50%) — flag for review
+
+**Pending sources**
+- Files in `superspec/wiki/raw/` not yet in `_manifest.json`
+- Specs in `superspec/specs/` whose slugs don't appear in `_manifest.json` ingestion history
+
+---
+
+### 3. Output dashboard
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Wiki Status — superspec/wiki/
+  Generated: <YYYY-MM-DD HH:MM>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+VAULT SIZE
+  Total pages:    N
+  Domains:        N (auth, api, data, ...)
+  Created this month: N
+
+RECENT ACTIVITY
+  Last ingest:    <YYYY-MM-DD> — <slug>: <title>
+  Last query:     <YYYY-MM-DD> — "<topic>"
+  Last lint:      <YYYY-MM-DD> — N issues
+  Last cross-link: <YYYY-MM-DD> — K links inserted
+
+HUB PAGES (most referenced)
+  N  [[auth/jwt-refresh]]
+  N  [[patterns/error-handling]]
+  N  [[api/rest-conventions]]
+  N  [[decisions/database-choice]]
+  N  [[infra/redis-cache]]
+
+TAG DISTRIBUTION (top 10)
+  auth (N)  api (N)  patterns (N)  ...
+
+PROVENANCE
+  Extracted:  ~X%   (directly from source material)
+  Inferred:   ~X%   (agent synthesis)
+  Ambiguous:  ~X%   (sources disagree)
+  ⚠ High-inferred pages: N (>50% inferred — verify accuracy)
+
+PENDING
+  raw/ files not yet ingested:  N
+  Specs not yet compiled:       N slugs
+    - <slug-1>
+    - <slug-2>
+
+HEALTH
+  Orphaned pages:    N  (run /wiki-lint for details)
+  Broken wikilinks:  N  (run /wiki-lint for details)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Suggested actions:
+  /wiki <slug>         Compile pending spec
+  /wiki-lint           Full health check
+  /cross-linker        Auto-weave missing [[wikilinks]]
+  /wiki-query          Ask the wiki anything
+```
+
+---
+
+### 4. Optionally write _insights.md
+
+If the user asks for a persistent record, write `superspec/wiki/_insights.md`:
+
+```markdown
+---
+title: Wiki Insights
+generated: <YYYY-MM-DD HH:MM>
+tags: [insights, status]
+---
+
+# Wiki Insights
+
+<Full dashboard content as markdown>
+
+## Hub Pages
+<Ranked list with backlink counts>
+
+## Domain Coverage
+<Table: domain | pages | last updated | pending>
+
+## Suggested Next Steps
+<Concrete actions based on pending sources and health>
+```
+
+---
+
+## Output
+
+- Dashboard printed in response (always)
+- Optionally: `superspec/wiki/_insights.md`

package/AGENTS.md

@@ -2,37 +2,66 @@
 
 SuperSpecs: spec-driven planning + parallel TDD execution + wiki memory.
 
+## Commands
+
+**Claude Code / Cursor:** `/superspecs:<cmd>`
+**OpenCode:** `/superspecs-<cmd>`
+
 ## Lifecycle (always in order)
 
 **Phase 0 — Setup**
-- `/techstack` — questionnaire: define stack, get skill & library recommendations, save to wiki
+- `/superspecs: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)
+- `/superspecs:design-import <path>` — (optional) import DesignOS export → design-context.md; enriches /discuss + /spec with design constraints, data shapes, milestone structure, and test scaffolding
+- `/superspecs:discuss` — capture decisions before planning
+- `/superspecs:spec` — write spec (fits 200k context window)
+- `/superspecs:grill` — stress-test spec against wiki + techstack before execution
 
 **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
+- `/superspecs:pick-spec` — validate spec, check context fit
+- `/superspecs:branch` — create branch/worktree
+- `/superspecs:subagent` — fresh subagent per task; RED→GREEN→REFACTOR TDD runs inside each task
+- `/superspecs:tdd` — invoke directly if writing code outside of subagent mode
+- `/superspecs:code-review` — critical issues block progress
 
 **Phase 3 — Verify**
-- `/check-tests` — full suite, every scenario covered
-- `/wiki` — distill to knowledge base
+- `/superspecs:check-tests` — full suite, every scenario covered
+- `/superspecs:wiki` — compile feature to wiki (ingest)
 
 **Phase 4 — Ship**
-- `/ship` — PR, archive, next cycle
+- `/superspecs:ship` — PR, archive, next cycle
+
+## Wiki Operations (run any time)
+- `/superspecs:wiki-query` — tiered retrieval query; answer stays in context or files back as a page
+- `/superspecs:wiki-lint` — health check: orphans, broken links, contradictions, stale refs
+- `/superspecs:cross-linker` — auto-insert `[[wikilinks]]` for unlinked mentions
+- `/superspecs:wiki-status` — vault dashboard: size, hubs, tags, provenance, pending sources
+- `/superspecs:wiki-capture` — save session findings to wiki (`--quick` or `--full`)
+- `/superspecs:tag-taxonomy` — canonical tag vocabulary; audit and normalize vault-wide
+- `/superspecs:wiki-rebuild` — archive + rebuild vault; restore from snapshot
+
+## Wiki Architecture (Karpathy LLM Wiki pattern)
+```
+superspec/wiki/raw/   ← immutable source material (agent reads, never edits)
+superspec/wiki/       ← compiled knowledge base (agent writes)
+superspec/wiki/log.md ← append-only activity log
+.skills/verify-wiki/  ← schema: how to ingest, link, and format
+```
+Compile once → query fast. The agent reads `wiki/`, not `raw/`, at query time.
 
 ## Rules
 - No implementation code before a failing test
 - Critical review findings block all progress
 - Spec must fit a fresh 200k context window
+- Spec must pass grill before execution
 - Every shipped feature → wiki page
+- Wiki query reads compiled `wiki/` only — never raw specs
 
 ## Paths
 - `superspec/specs/` — specs + DISCUSS.md files
 - `superspec/phases/` — execution working dirs
-- `superspec/wiki/` — knowledge base
-- `.skills/` — skill definitions
+- `superspec/wiki/raw/` — immutable source material
+- `superspec/wiki/` — compiled knowledge base (Obsidian vault)
+- `superspec/wiki/log.md` — append-only activity log
+- `.skills/` — skill definitions (schema layer)