skillwiki 0.8.1-beta.5 → 0.8.1-beta.8

package/dist/cli.js

@@ -4268,21 +4268,21 @@ function checkVaultStructure(resolvedPath) {
 function checkSkillsInstalled(home, cwd) {
   const srcDir = cwd ? join26(cwd, "packages", "skills") : void 0;
   if (srcDir && existsSync8(srcDir)) {
-    const found = findSkillMd(srcDir);
+    const found = findInstalledSkillMd(srcDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (source)`);
     }
   }
   const plugin = findPlugin(home);
   if (plugin) {
-    const found = findSkillMd(plugin.installPath);
+    const found = findInstalledSkillMd(plugin.installPath);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (plugin v${plugin.version})`);
     }
   }
   const skillsDir = join26(home, ".claude", "skills");
   if (existsSync8(skillsDir)) {
-    const found = findSkillMd(skillsDir);
+    const found = findInstalledSkillMd(skillsDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (CLI install)`);
     }
@@ -5066,6 +5066,10 @@ function findSkillMd(dir) {
   }
   return results;
 }
+function findInstalledSkillMd(dir) {
+  const directSkills = findSkillNames(dir).map((name) => join26(dir, name, "SKILL.md"));
+  return directSkills.length > 0 ? directSkills : findSkillMd(dir);
+}
 function findSkillNames(dir) {
   const results = [];
   let entries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.5",
+  "version": "0.8.1-beta.8",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.5",
+  "version": "0.8.1-beta.8",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.5",
+  "version": "0.8.1-beta.8",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",
@@ -17,7 +17,7 @@
     "obsidian",
     "karpathy"
   ],
-  "skills": "./",
+  "skills": "./skills/",
   "interface": {
     "displayName": "SkillWiki",
     "shortDescription": "Project-aware wiki skills for Codex agents",

package/skills/README.md

@@ -7,4 +7,6 @@ Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`.
 | `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit` |
 | `proj-*` | `proj-init`, `proj-work`, `proj-distill`, `proj-decide` |
 
-Each subdirectory holds one `SKILL.md`. No build step.
+Each top-level skill subdirectory holds one canonical `SKILL.md`. The nested
+`skills/<skill>/SKILL.md` tree mirrors those files for Codex plugin discovery;
+keep it byte-for-byte in sync with the canonical top-level files.

package/skills/hooks/session-start

@@ -21,7 +21,7 @@ escape_for_json() {
 }
 
 skill_escaped=$(escape_for_json "$skill_content")
-session_context="<EXTREMELY_IMPORTANT>\nYou have skillwiki.\n\n**Below is the full content of your 'skillwiki:using-skillwiki' skill - your introduction to the skillwiki skills. For all other skills, use the 'Skill' tool:**\n\n${skill_escaped}\n</EXTREMELY_IMPORTANT>"
+session_context="### Skillwiki Activation\n\nSkillwiki is active for this workspace. Below are the capability guidelines for local reference:\n\n${skill_escaped}"
 
 # Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
 printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"

package/skills/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.1-beta.5",
+  "version": "0.8.1-beta.8",
   "private": true,
   "files": [
     "wiki-*",
     "proj-*",
     "using-skillwiki",
+    "skills",
     ".claude-plugin",
     ".codex-plugin",
     "hooks",

package/skills/skills/proj-decide/SKILL.md

@@ -0,0 +1,25 @@
+---
+version: 0.2.1
+name: proj-decide
+description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
+---
+
+# proj-decide
+
+## When to invoke
+- User commits to an architectural decision worth recording for future reference.
+
+## Pre-orientation reads
+Standard four + project context.
+
+## Steps
+1. Compose the ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`. Frontmatter: kind=decision, status=in-progress or completed, project link. If no project context exists, default to `playground`.
+2. `skillwiki validate <adr>`. If non-zero, STOP.
+3. **Generalization check.** If the decision applies beyond this project, create a `concepts/` page with `provenance: project` (or `mixed` if research-informed).
+4. Apply writes: ADR → (optional) concept page → vault `index.md` → vault `log.md` and project `log.md`.
+
+## Stop conditions
+- `validate` non-zero on either page.
+
+## Forbidden
+- Filing the concept page without explicit `provenance:`.

package/skills/skills/proj-distill/SKILL.md

@@ -0,0 +1,55 @@
+---
+version: 0.2.1
+name: proj-distill
+description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
+---
+
+# proj-distill
+
+## When to invoke
+- A project compound entry captures a pattern that generalizes beyond the project.
+
+## Pre-orientation reads
+Standard four + project context.
+
+## Steps (E4 — 2-step pattern)
+
+### Source selection
+
+Check `projects/{slug}/compound/` first. If no project context exists, default to `playground`. If empty, fall back to retro
+entries in vault `log.md` (lines matching `## [YYYY-MM-DD] retro`).
+
+When reading retros as source material:
+- Collect all retros for the project, focusing on entries with
+  `Generalize?: yes`.
+- Group by recurring theme (≥2 occurrences across cycles).
+- Each group becomes a candidate concept outline.
+
+1. **Step 1 — Analyze.** Read the source compound entry + linked work
+   items (or retro groups from log.md). Output a candidate concept
+   outline. STOP if no clear universal pattern is found — surface the
+   reasoning instead of forcing a page.
+2. **Step 2 — Generate.** Compose the vault concept page with
+   `provenance: project` and
+   `provenance_projects: ["[[slug]]"]`. Validate with
+   `skillwiki validate`.
+   - **Tag hygiene:** `tags:` must only contain entries from
+     `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
+     (lesson/evidence sections) — use only established taxonomy tags
+     (e.g., `dev-loop`, `lint`, `vault`). If no relevant taxonomy tag
+     exists, use `[dev-loop]` as the safe default rather than inventing
+     new tags. New tags must be added to SCHEMA.md first.
+3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source
+   compound entry. For retro-sourced distillation, skip backlink (log.md
+   entries are append-only) and instead add `sources:` citing the vault
+   log with date range.
+4. **Apply writes in order.** Vault concept page → backlink update →
+   project `log.md` → vault `index.md` → vault `log.md`.
+
+## Stop conditions
+- No clear universal pattern.
+- `validate` non-zero on either page.
+
+## Forbidden
+- Skipping Step 1 (no direct generation).
+- Updating index/logs before `validate` passes.

package/skills/skills/proj-init/SKILL.md

@@ -0,0 +1,30 @@
+---
+version: 0.2.1
+name: proj-init
+description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
+---
+
+# proj-init
+
+## When to invoke
+- User starts a new project that should live inside the vault.
+
+## Pre-orientation reads
+Standard four reads (vault SCHEMA, index, log) — no project context yet.
+
+## Inputs
+- Slug (lowercase, hyphenated).
+- One-line intent.
+
+## Steps
+1. Verify `projects/{slug}/` does not exist.
+2. Create folders: `projects/{slug}/{requirements,architecture,work,compound}/`.
+3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`. The template includes a `## Knowledge Pages` section with a placeholder; agents populate it on first ingest via `skillwiki project-index`.
+4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
+5. Append vault `log.md` entry: "Project {slug} initialized."
+
+## Stop conditions
+- `projects/{slug}/` already exists.
+
+## Forbidden
+- Modifying any other project's files.

package/skills/skills/proj-work/SKILL.md

@@ -0,0 +1,69 @@
+---
+version: 0.2.2
+name: proj-work
+description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
+---
+
+# proj-work
+
+## When to invoke
+- User starts a feature, issue, refactor, or decision inside an existing project.
+- User asks to "get work of X" or "run work item Y" to review/execute an existing item.
+- Brainstorming or writing-plans skills would otherwise default-write outside the project tree.
+- If no project context can be determined, default to the `playground` slug so redirect paths always emit and the PRD bridge chain works.
+
+## Pre-orientation reads
+Standard four + project context (project README, last ~5 work logs).
+
+## Executing an Existing Work Item
+
+When the user asks to "get work of X" or "run work item Y" for review, you are in EXECUTION mode — not creation mode. Steps:
+
+1. **Resolve the work folder** at `<vault>/projects/{slug}/work/{YYYY-MM-DD-<slug>}/`. If the vault root isn't obvious, run `skillwiki path`.
+2. **Read spec.md and tasks.md** in full. The spec defines scope; tasks define the review checklist.
+3. **Verify every "DONE" claim against disk.** This is critical — previous sessions routinely mark items DONE in the wiki without actually applying the fix. For each claimed-complete task:
+   - Check file existence, content, config values on disk
+   - Cross-reference crontab entries, script timeouts, Makefile targets
+   - Trust nothing in the wiki alone — validate
+4. **Apply missing fixes**, then update the work item with accurate post-fix status.
+5. **Set `status: complete`** when all fixes are verified.
+
+## Creating a New Work Item
+1. Determine `kind:` (feature | issue | refactor | decision) and slug.
+2. Create folder `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
+3. Override default output paths for any nested skill: `spec.md`, `plan.md`, and `log.md` are written here, not at vault root.
+4. Validate work-item frontmatter via `skillwiki validate <spec.md>`. If non-zero, STOP.
+5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
+6. Append vault `log.md` entry on creation and on each status transition.
+
+## Redirect Output
+
+After step 3 (output path override), emit redirect paths for the active PRD skill:
+
+> Work item created: projects/{slug}/work/YYYY-MM-DD-{work-slug}/
+>
+> Redirect paths for PRD skills:
+>   spec -> <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/spec.md
+>   plan -> <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/plan.md
+>
+> Pass these paths to your PRD skill (superpowers:brainstorming, superpowers:writing-plans,
+> CodeStable, or any other). Files land in the vault natively — no separate ingest needed.
+
+Rules:
+- Emit redirect paths as the first output after folder creation, before any PRD skill runs.
+- Resolve `<vault-root>` via `skillwiki path` (never hardcode).
+- proj-work does NOT invoke any PRD skill — it provides paths only.
+- If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+
+## Pitfalls
+- **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.
+- **Re-marking without doing**: do not simply re-write tasks.md to say DONE without applying the corresponding fix. The next session will find the same gap.
+
+## Stop conditions
+- `validate` non-zero.
+- Conflicting work folder name.
+
+## Forbidden
+- Writing spec/plan files outside the work folder.
+- Marking `status: completed` without a `completed:` date.
+- Accepting tasks.md status labels without independent disk verification.

package/skills/skills/using-skillwiki/SKILL.md

@@ -0,0 +1,157 @@
+---
+version: 0.2.2
+name: using-skillwiki
+description: Invoke at session start or when knowledge-base tasks arise — maps skillwiki skills, dev-loop alignment, and PRD/TDD routing with plan-mode gate checks
+---
+*Note: If executing as a background subagent, skip this skill section.*
+
+# using-skillwiki
+You have skillwiki — a project-aware Karpathy-style knowledge base for Claude Code.
+
+## Last Hook Gate (SessionStart)
+
+This skill is activated by the plugin during `startup|clear|compact` lifecycle events.
+Use this section as procedural planning guidelines:
+
+1. If the task requires spec/plan work, route through PRD skills (not built-in plan mode).
+2. If `prd_layer` is `superpowers` or `tdd`, ensure `EnterPlanMode` is gated (`wiki-gate-plan-mode on` or `status` if uncertain).
+3. If `prd_layer` is `manual` or `none`, do not force the gate; follow project policy.
+4. Always apply the PRD bridge: spec/plan outputs go to vault work-item paths, never `docs/superpowers/`.
+
+## When to Use These Skills
+Invoke a skillwiki skill when the user:
+- Wants to create, build, or start a vault/wiki/knowledge base
+- Mentions ingesting sources, reading URLs into notes, converting content
+- Asks to search, query, or find information in their vault
+- Wants a health check or lint on their vault
+- Mentions crystallizing a session into a note
+- Talks about project workspaces, ADRs, or distillation
+- Wants to quickly capture an idea, bug, task, or note without interrupting their workflow
+- Wants to archive or clean up old vault pages
+- Needs to detect source drift or re-ingest updated content
+- Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
+- Asks about their skillwiki configuration or setup health
+- Wants to sync vault changes to/from a git remote
+- Wants to visualize the vault graph as an Obsidian Canvas
+- Wants to run a research scan of repo and vault health
+
+## Vault Structure
+A skillwiki vault has three layers. The canonical architecture lives in `SCHEMA.md` at the vault root — read it before creating any new directories.
+**Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest. `raw/transcripts/` doubles as the ad-hoc capture point for meeting notes and unprocessed ideas.
+```
+raw/
+├── articles/    # Web articles, clippings
+├── papers/      # PDFs, arxiv papers
+├── transcripts/ # Meeting notes, interviews, ad-hoc captures
+└── assets/      # Images, diagrams referenced by sources
+```
+Raw frontmatter:
+```yaml
+---
+source_url: https://…
+ingested: YYYY-MM-DD
+sha256:          # computed by skillwiki hash over body bytes after closing ---
+---
+```
+**Layer 2 — Typed Knowledge:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`. Agent-owned pages with `^[raw/...]` citation markers at paragraph-end. Global scope — project association via `provenance_projects:` frontmatter, not directory nesting.
+**Layer 3 — Project Workspaces (`projects/{slug}/`):** Per-project lifecycle directories with `work/` (spec + plan + retro), `compound/` (distilled lessons/patterns), `architecture/` (ADRs), and `history/` (archived specs/plans).
+**No `inbox/` directory.** Ad-hoc captures go to `raw/transcripts/` or directly into a project work item via `proj-work`. Do not invent new top-level directories — extend Layer 2 via SCHEMA.md tag taxonomy if needed.
+### Ad-hoc capture: three entry points
+| Entry | When | What happens |
+|-------|------|-------------|
+| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
+| Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create/edit any `.md` file in `raw/transcripts/` — dev-loop discovers it on next cycle |
+| Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
+
+## Skill Map
+| Skill | When to Invoke |
+|-------|----------------|
+| `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
+| `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
+| `wiki-query` | Search the vault and synthesize an answer with ranked results |
+| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
+| `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
+| `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
+| `wiki-reingest` | Detect drift in raw sources (sha256 comparison) and re-ingest updated content |
+| `wiki-add-task` | Quick-capture ideas, bugs, tasks, notes into `raw/transcripts/` without leaving the current workflow |
+| `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) into vault pages |
+| `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
+| `proj-work` | Open or run a work item under a project's work/ directory |
+| `proj-distill` | Distill project compound entries into vault concept pages |
+| `wiki-sync` | Safely sync vault git repository — push/pull with lint guards and conflict resolution |
+| `wiki-canvas` | Generate Obsidian Canvas visualization from vault graph data |
+| `proj-decide` | Write an Architectural Decision Record (ADR) |
+| `wiki-gate-plan-mode` | Toggle EnterPlanMode gating — force superpowers planning instead of built-in plan mode |
+| `dev-loop:research` | Research agent for dev-loop IDLE — scans repo + vault health, outputs prioritized work-item recommendations (formerly `/dev-loop-research`) |
+
+## dev-loop Alignment
+
+Use these skills as the knowledge layer in dev-loop. The loop remains capability-based:
+branch on capabilities (`BACKEND_CAPS`, `PRD_CAPS`), not backend names.
+
+Typical sequence with PRD enabled:
+`REFRESH → QUERY → WORK → SPEC → PLAN → EXECUTE → SIMPLIFY → MERGE → SAVE → RETRO`.
+
+- `QUERY/WORK/SAVE/RETRO` map naturally to `wiki-query`, `proj-work`, `wiki-crystallize`, and vault logs.
+- `SIMPLIFY` is a quality gate before merge; keep it in the loop even for small changes.
+- For no-work cycles, run maintenance (`wiki-lint`, `wiki-audit`, `proj-distill`, `dev-loop:research`).
+
+## PRD/TDD Compatibility
+
+Use `prd_layer` + `prd_pipeline` from `.claude/dev-loop.config.md` as source of truth:
+
+- `superpowers` + `full`: brainstorming/spec/plan/execute/review; route spec+plan through `proj-work`.
+- `tdd` + `tdd-first`: plan-first then test-driven execute; still route artifacts through `proj-work`.
+- `single-pass` or `debug-only`: may skip formal spec/plan, but if generated they still belong in vault work items.
+- `manual` / `none`: no forced PRD skills; preserve skillwiki logging and provenance discipline.
+
+## CLI Backbone
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
+Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+
+## Typical Workflow
+1. **Init** (`wiki-init`) — create vault, set domain and taxonomy
+2. **Ingest** (`wiki-ingest`) — add sources, build pages
+3. **Query** (`wiki-query`) — search and synthesize answers
+4. **Lint** (`wiki-lint`) — periodic health checks
+5. **Crystallize** (`wiki-crystallize`) — save session insights as pages
+6. **Audit** (`wiki-audit`) — verify source integrity
+For longer-running project work, use `proj-init` → `proj-work` → `proj-distill` / `proj-decide`.
+Maintenance: **Archive** (`wiki-archive`) superseded pages, **Drift** (`wiki-reingest`) to detect stale sources, **Adapter** (`wiki-adapter-prd`) for foreign PRD format ingestion.
+
+## Troubleshooting Version Drift
+skillwiki has three distribution channels that can drift:
+| Channel | Location | Update Command |
+|---------|----------|----------------|
+| npm CLI | `/usr/local/bin/skillwiki` | `npm install -g skillwiki@latest` |
+| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` (copies to `~/.claude/skills/`) |
+| Claude plugin | `~/.claude/plugins/cache/llm-wiki/` | `claude plugin update skillwiki@llm-wiki` |
+| Local git dev | `~/.hermes/skills/llm-wiki/` | `npm link ./packages/cli` (from repo root) |
+**Check versions:** `skillwiki doctor` reports "Plugin/CLI version" mismatch warnings.
+**Common issue:** npm package ships SKILL.md files with older `version:` frontmatter than CLI code. This creates false-positive "version warnings" in `skillwiki doctor` — the CLI is newer but skills report older version.
+**Fix:** If developing locally, use `npm link` from the git repo. If using released versions, wait for maintainer to bump SKILL.md versions in source and republish.
+
+## Multi-Wiki Profiles
+skillwiki supports named wiki profiles for working with multiple vaults. Set `WIKI_DEFAULT` to control which wiki all skills target by default.
+**Manage profiles:**
+- `skillwiki config set wiki.<name>.path <dir>` — register a profile
+- `skillwiki config set default <name>` — set active profile
+- `skillwiki config list --profiles` — list all profiles
+- `skillwiki --wiki <name> lint` — override per-command
+**Project-local override:** Place a `./skillwiki/.env` in a project root to bind that project to a specific wiki. Skills will use it automatically when running from that directory.
+
+## PRD Bridge — Redirect Spec/Plan Output to Vault
+When skillwiki is installed, **all spec and plan documents must land in the vault**, not in repo-local directories like `docs/superpowers/`. This applies to PRD and TDD workflows (superpowers, codestable, AIDE, Hermes, manual templates).
+**Rule:** Before a PRD skill writes a spec or plan file, redirect its save path:
+1. Resolve the vault path: `skillwiki path`
+2. If the cwd is inside a project (check for `projects/{slug}/` via `skillwiki path --init-time` or look for `./skillwiki/.env`), use that project's work directory
+3. Create or locate the work item via `proj-work`, which emits redirect paths for `spec.md` and `plan.md`
+4. Pass those vault paths to the PRD/TDD skill as its save location
+**Concrete overrides for superpowers:**
+- `superpowers:brainstorming` step 6: override `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` → vault work-item `spec.md` path from `proj-work`
+- `superpowers:writing-plans` header: override `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` → vault work-item `plan.md` path from `proj-work`
+Both skills say "User preferences for spec location override this default" — the vault work-item path IS the override. Apply the same override pattern to any TDD-oriented planner that emits spec/plan artifacts.
+**If no project context exists** (standalone vault, not inside a project), default to the `playground` project slug. Invoke `proj-work` with `playground` as the slug so redirect paths are emitted normally and the PRD bridge chain works. The `playground` project is a pre-initialized catch-all workspace at `projects/playground/` for exploratory work, experiments, and unclassified features. Work items that mature can be moved to a real project later.
+**Never create `docs/superpowers/` in any repo.**

package/skills/skills/wiki-adapter-prd/SKILL.md

@@ -0,0 +1,88 @@
+---
+version: 0.2.1
+name: wiki-adapter-prd
+description: Map foreign PRD formats (CodeStable, RFCs, structured markdown) into skillwiki raw + typed-knowledge pages.
+---
+
+# wiki-adapter-prd
+
+## When This Skill Activates
+
+- User provides a document or URL in a non-skillwiki PRD format and wants it captured in the vault.
+- User mentions CodeStable, RFC, AIDE, or another structured design document format.
+- A foreign spec/plan needs to be normalized into the vault's raw + concept structure.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate page prose in the resolved language. Frontmatter keys, file names, and structural markers stay English.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Recognized PRD Formats
+
+| Format | Structural cues |
+|--------|----------------|
+| CodeStable | `REQ-NNN` requirement IDs, `## Requirements` / `## Architecture` headers |
+| RFC | `## Motivation` / `## Proposal` / `## Drawbacks` headers |
+| AIDE directives | Specific YAML frontmatter keys (`aide-*`) |
+| Hermes spec | `N1`–`N18` normative requirement markers |
+| Generic structured | Clear `##` section hierarchy with requirements, decisions, or designs |
+
+If the format is unrecognized, treat as generic structured markdown and map by section hierarchy.
+
+## Mapping Strategy
+
+### Raw capture (verbatim)
+
+- Write the full source document to `raw/articles/<slug>.md` with RawSourceSchema frontmatter (`sha256`, `source_url`, `ingested`, `ingested_by: "wiki-ingest"`).
+- If the source is a URL, run `skillwiki fetch-guard <url>` first.
+- Run `skillwiki hash <raw-file>` to compute sha256.
+
+### Knowledge extraction
+
+Map source sections to typed-knowledge pages:
+
+| Source section | Target type | Notes |
+|----------------|-------------|-------|
+| Requirements list | `concepts/` or `entities/` | Each major requirement becomes its own page or a section in a compound page |
+| Architecture decisions | `concepts/` | Map to concept pages with `tags: [architecture]` |
+| Motivation / context | `entities/` | Capture as entity pages describing the system or component |
+| Trade-offs / comparisons | `comparisons/` | Create comparison pages when the source weighs alternatives |
+| Action items / next steps | Skip | Not knowledge — track in project work items instead |
+
+### Cross-reference handling
+
+- Requirement IDs (`REQ-NNN`, `N1`–`N18`) → preserve as frontmatter tags or inline references.
+- Internal links within the source → convert to `[[wikilinks]]` where corresponding pages exist.
+- External URLs → keep as-is in body text.
+
+## Steps
+
+0. Resolve vault and language: `skillwiki path` and `skillwiki lang`.
+1. Classify the input format using the structural cues above.
+2. If URL source: run `skillwiki fetch-guard <url>`, then fetch.
+3. Write raw capture: frontmatter + full body → `raw/articles/<slug>.md`.
+4. Run `skillwiki hash <raw-file>`, embed sha256.
+5. Generate typed-knowledge pages following the mapping strategy.
+6. For each page: run `skillwiki validate <page>`. If any fails, STOP.
+7. Write pages, then update `index.md` and `log.md`.
+
+## Provenance defaults
+
+- `provenance: research` (external PRD sources).
+- `sources: ["^[raw/articles/<slug>.md]"]` on every generated page.
+
+## Stop conditions
+
+- `fetch-guard` non-zero.
+- `validate` non-zero on any page.
+- sha256 already exists for the same source (skip — already ingested).
+
+## Forbidden
+
+- Skipping `fetch-guard` for URL sources.
+- Writing index/log before all pages validate.
+- Modifying existing raw files (N9).
+- Auto-generating pages for action items, timelines, or process steps — those are project management, not knowledge.

package/skills/skills/wiki-add-task/SKILL.md

@@ -0,0 +1,102 @@
+---
+version: 0.2.2
+name: wiki-add-task
+description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault with ad-hoc capture frontmatter and descriptive filenames.
+---
+# wiki-add-task
+Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points depending on where you are:
+| Entry | When | What happens |
+|-------|------|-------------|
+| `/wiki-add-task <text>` | You're in a Claude Code session (NOT Hermes compact) | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
+| Filesystem drop | Hermes Agent compact mode (no slash commands available) | Same as above — create `.md` in `raw/transcripts/`, dev-loop discovers it |
+| Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create any `.md` file in `raw/transcripts/` using the vault template — dev-loop discovers it on next cycle |
+| Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
+**Path Rule:** Captures ALWAYS go to `$(skillwiki path)/raw/transcripts/` (Layer 1). Never under `projects/{slug}/raw/` — that violates SCHEMA.md Layer 1 immutability.
+### Exception: Explicit project task requests
+When the user explicitly says "raise task to project X", "add a task for X", "create a feature request for X", or uses a directive structure like "raise task to {project} {description}", the intent is a **work item**, not a capture:
+| User wording | Action | Target |
+|---|---|---|
+| "capture this", "note this", "remember this" | Use wiki-add-task (this skill) | `raw/transcripts/` |
+| "raise task to project X", "add task to X project" | Escalate to `proj-work` | `projects/{slug}/work/YYYY-MM-DD-{slug}/task.md` |
+| "save to wiki" + content | Use `wiki-ingest` | `concepts/`, `entities/`, etc. |
+This is NOT a violation of the "ALWAYS" rule below — explicit project task requests are a distinct user intent that bypasses raw capture and goes directly to a Layer 3 work item.
+## When This Skill Activates
+- User invokes `/wiki-add-task` with a description.
+- User says "add task", "capture this", "note this", "remember this", "log this idea", or similar.
+- User provides a short text description and optionally a type tag.
+- **Do NOT activate** when the user says "raise task to project X" or "add work item to project X" — escalate to `proj-work` instead.
+## Output language
+Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the resolved language. Frontmatter keys, file names, and structural markers stay English.
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. **Parse arguments.** Extract from the user's message:
+- `text` — the idea/bug/task/note content (required)
+- `type` — one of: `idea`, `bug`, `task`, `note` (default: `idea`)
+- `project` — optional project slug to cross-reference (e.g., `llm-wiki`)
+2. **Build filename.** Derive a slug from the first ~6 words of the text (lowercased, hyphens for spaces, non-alphanumeric stripped). The capture file is `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`. Each capture gets its own file — never append to an existing file.
+3. **Write frontmatter.** Create the file with ad-hoc capture frontmatter:
+```yaml
+---
+source_url:
+ingested: YYYY-MM-DD
+kind: {type}
+project: "[[{slug}]]"
+---
+```
+- Set `kind` to the parsed type (`idea`, `bug`, `task`, `note`).
+- If a `project` slug was provided, set `project: "[[slug]]"`.
+- If no project, omit the `project` field entirely.
+- `source_url` is null (these are locally originated captures).
+- No `sha256` — ad-hoc captures are mutable working notes, not immutable sources.
+4. **Write body.** Below the frontmatter, write:
+```markdown
+# {type}: {text}
+{text}
+```
+Use the resolved output language for any prose. The type label and frontmatter stay English.
+5. **Cross-reference (optional).** If a `project` slug was provided:
+- Check that `projects/{slug}/` exists in the vault.
+- Append a one-line reference to the project's compound notes:
+`- [YYYY-MM-DD] capture: [text (first 60 chars)] → raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`
+- Do NOT create a full work item (that's `proj-work`'s job).
+6. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
+7. **Confirm to user.** Report what was captured and where. Suggest next steps:
+- If `type: idea` → "Consider ingesting related sources to develop this idea."
+- If `type: bug` → "Use proj-work to create a bug-fix work item."
+- If `type: task` → "Use proj-work to track this task through the dev loop."
+- If `type: note` → "Will be available for future wiki-query searches."
+## Capture file format
+Each capture is a standalone file with ad-hoc capture frontmatter:
+```yaml
+---
+source_url:
+ingested: 2026-05-08
+kind: idea
+project: "[[llm-wiki]]"
+---
+# idea: Fix the template mismatch
+Fix the template mismatch between wiki-add-task and the vault template.
+```
+The `kind` field uses the capture type and must be one of: `idea`, `bug`, `task`, `note` (plus the existing `postmortem`, `session-log`, `meeting-notes`, `other` for non-capture raw sources).
+The `project` and `kind` fields can be set independently — they do not require `work_item`. The `work_item` field is only used when the raw source is directly tied to a project work item (set by `proj-work`).
+Ad-hoc captures omit `sha256` — they are mutable working notes, not immutable sources. The `sha256` field is reserved for ingested raw sources that require integrity verification.
+## Stop conditions
+- `skillwiki path` returns NO_VAULT_CONFIGURED.
+- No `text` provided (prompt user once, then stop).
+- Target file already exists (use a different slug or add a suffix).
+## Forbidden
+- Creating an `inbox/` directory. All captures go to `raw/transcripts/`.
+- Appending to existing capture files — each capture gets its own file.
+- Creating a work item — this is capture-only. Use `proj-work` for full work items.
+- Writing to any Layer 2 or Layer 3 location. Captures are Layer 1 (raw).
+## Filesystem drop (offline capture)
+When you're not in a Claude session, drop files directly into `raw/transcripts/`:
+1. Create a `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-08-idea-fix-template.md`)
+2. Use ad-hoc capture frontmatter: `source_url:`, `ingested:`, `kind:`, and optionally `project:`
+3. Write your idea/bug/task/note below the frontmatter
+No special format required — the dev-loop QUERY step will discover new files on the next cycle and surface them as claimable work. Mark the type with a heading like `## idea`, `## bug`, `## task`, or just write freeform.
+## Dev-loop discovery
+When the dev-loop QUERY step runs, it should scan `raw/transcripts/` for files with `ingested:` date newer than the last cycle. New files are surfaced as claimable work items. The agent then decides whether to:
+- Create a work item via `proj-work` (for tasks and bugs)
+- Ingest as a knowledge page via `wiki-ingest` (for ideas with sources)
+- Leave in place (for notes that don't need action yet)