skillwiki 0.2.1-beta.21 → 0.2.1-beta.23

package/dist/cli.js

@@ -1212,7 +1212,7 @@ async function createSymlink(src, dst) {
 async function runInstall(input) {
   let entries;
   try {
-    entries = (await readdir2(input.skillsRoot, { withFileTypes: true })).filter((d) => d.isDirectory() && (d.name.startsWith("wiki-") || d.name.startsWith("proj-"))).map((d) => d.name);
+    entries = (await readdir2(input.skillsRoot, { withFileTypes: true })).filter((d) => d.isDirectory() && (d.name.startsWith("wiki-") || d.name.startsWith("proj-") || d.name === "dev-loop-research" || d.name === "using-skillwiki")).map((d) => d.name);
   } catch (e) {
     return { exitCode: ExitCode.PREFLIGHT_FAILED, result: err("PREFLIGHT_FAILED", { message: String(e) }) };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.21",
+  "version": "0.2.1-beta.23",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

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

@@ -1,8 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.21",
+  "version": "0.2.1-beta.23",
   "skills": "./",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 17 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
+  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 prompt-only skills (wiki-*, proj-*, dev-loop-research, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/dev-loop-research/SKILL.md

@@ -0,0 +1,176 @@
+---
+version: 0.2.1
+name: dev-loop-research
+description: Standalone research agent — scans repo health and vault health, outputs prioritized work-item recommendations. Pass "high" for aggressive mode.
+---
+
+# dev-loop-research
+
+Standalone invocable research agent. Scans two parallel tracks — code health
+and vault health — cross-references findings, and outputs a prioritized
+work-item recommendation list.
+
+## When This Skill Activates
+
+- User runs `/dev-loop-research` or `/dev-loop-research high`
+- User wants a one-shot research scan of repo and vault health
+- User schedules recurring background scans: `/loop 1h dev-loop-research`
+- Dev-loop idle path delegates here (same logic, different trigger)
+
+## Intensity
+
+Parse arguments for `high` (case-insensitive). If present,
+**intensity = high**; otherwise **intensity = normal**.
+
+- **normal**: Output top-3 items. Suppress recurring findings that haven't
+  changed since last pass. Respect priority gates.
+- **high**: Output top-5 items. Never suppress recurring findings. Every
+  finding is actionable regardless of priority tier. P4+ items are
+  first-class.
+
+## Prerequisites
+
+1. **Project config** — load `./.claude/dev-loop.config.md`. Required
+   fields: `slug`. Optional: `vault`, `cli_src`, `cli_test`,
+   `skills_glob`. If missing, prompt user to bootstrap via dev-loop.
+2. **Resolve BACKEND_CAPS** from `knowledge_layer` config field (default:
+   `skillwiki` if vault exists, `none` otherwise).
+3. **Resolve VAULT_TYPES** from `{vault}/SCHEMA.md` `## Layers` section —
+   extract backtick-wrapped directory names ending in `/`, exclude `raw`
+   and `project`. Store for Track B.
+4. Read `CLAUDE.md` and user `MEMORY.md` fresh.
+
+## Single-Pass Cycle
+
+```
+┌───────────────────────────────────────────────────────────┐
+│ 0. REFRESH                                                │
+│    Load project config + read CLAUDE.md/MEMORY.md fresh   │
+├─────────────────────────┬─────────────────────────────────┤
+│ TRACK A: CODE HEALTH    │ TRACK B: VAULT HEALTH           │
+│                         │                                 │
+│ A1. CLI COVERAGE GAPS   │ B1. RAW-TO-PAGE COVERAGE        │
+│ A2. SKILLS AUDIT        │ B2. CROSS-LINK DENSITY          │
+│ A3. SPEC DRIFT          │ B3. PAGE QUALITY                 │
+│ A4. UNPUSHED COMMITS    │ B4. TYPE COVERAGE                │
+├─────────────────────────┴─────────────────────────────────┤
+│ 1. VAULT RETROS (cross-cutting)                           │
+│ 2. SYNTHESIZE — merge + score (P0–P3, +P4 in high)       │
+│ 3. SAVE & EXIT                                            │
+└───────────────────────────────────────────────────────────┘
+```
+
+Skip Track B entirely when `query_vault` not in BACKEND_CAPS or vault
+is empty. Skip Track A when `cli_src` is empty.
+
+## Track A: Code Health
+
+### A1. CLI Coverage Gaps
+- List `{cli_src}/*.ts`. For each: test file in `{cli_test}/`? `--human`
+  flag? Stable exit codes? `TODO/FIXME/HACK` markers?
+- Compare counts against CLAUDE.md documented counts. Flag drift.
+
+### A2. Skills Audit
+- List SKILL.md files from `skills_glob`. Check: CLI subcommand
+  references exist? Description matches current behavior? Skill maps
+  list all skills correctly?
+
+### A3. Spec Drift
+- If canonical spec is declared, verify scope fields against current
+  code. New commands not in spec? Changed counts? New schema changes?
+
+### A4. Unpushed Commits
+- `git log origin/$RELEASE_BRANCH..HEAD --oneline`. Priority:
+  ≥10→P1, 5-9→P2, 1-4→P4+.
+
+## Track B: Vault Health
+
+### B1. Raw-to-Page Coverage
+- Run `skillwiki lint` for `wikilink_citation` warnings.
+- Count raw files vs typed pages vs cited sources. Flag:
+  normal: uncited >50%→P1; high: uncited >20%→P1.
+- Single-source pages: normal→P2, high→P2 always.
+
+### B2. Cross-Link Density
+- Count outbound `[[wikilink]]` in body region per page.
+- normal: <2 links→P2; high: <3 links→P2.
+- Orphan and overlap detection via `skillwiki orphans`/`overlap`.
+
+### B3. Page Quality
+- Count non-blank body lines (exclude headings and `---`).
+- normal: <40 lines→thin; high: <60 lines→thin.
+- Flag missing Overview or Related sections.
+
+### B4. Type Coverage
+- Page counts per type directory. Flag: entities <3, empty comparisons,
+  empty queries when >30 pages exist, empty meta when 2+ projects active.
+- High: flag any empty type dir.
+
+## Vault Retros (Track 1)
+
+Scan `{vault}/log.md` for recent `Improve:` and `Generalize?: yes` entries.
+Check `{vault}/projects/{slug}/compound/` for pending distillation work.
+A retro's `Improve:` field that names a concrete action is a direct
+work-item candidate.
+
+## Synthesize (Track 2)
+
+Score each finding:
+
+| Score | Impact | Effort |
+|-------|--------|--------|
+| P0 | Spec violation or regression | Any |
+| P1 | High — untested command, raw-to-page gap >50%, isolated pages | S/M |
+| P2 | Medium — thin pages, skill map drift, single-source, empty type dirs | S/M |
+| P3 | Low — code quality, cross-link improvement, section completeness | Any |
+| P4+ | Speculative — proactive improvements, future-proofing, polish | Any |
+
+**normal**: top-3, P0–P3 only, suppress unchanged recurring.
+**high**: top-5, P0–P4+, never suppress recurring.
+
+Output format per item:
+
+```markdown
+### #N: [title] (Px)
+
+**Source**: [track source]
+**What**: One-paragraph spec.
+**Acceptance**: Bullet list of verifiable outcomes.
+**Files**: Likely files to touch (omit for vault-only items).
+```
+
+## Save & Exit (Track 3)
+
+1. Append research observation to `{vault}/log.md`:
+   ```
+   ## [YYYY-MM-DD HH:MM] research | dev-loop-research cycle [normal|high]
+   - Findings: [N] new, [N] recurring
+   - Vault health: raw=[N] pages=[N] cited=[N]% isolated=[N] thin=[N]
+   - Top-N: [titles]
+   ```
+2. If ranked list changed since last cycle, update user MEMORY.md with
+   research-backlog entry.
+3. Exit with one-line summary.
+
+## Idle Fast-Path
+
+**Pre-idle gate (mandatory):** Before declaring idle, collect actual vault
+health metrics from B1–B4. If any metric exceeds thresholds below, do NOT
+report idle:
+
+| Metric | normal | high |
+|--------|--------|------|
+| Uncited raw | >50% | >20% |
+| Isolated pages | any | any (<3 links) |
+| Thin pages | any (<40L) | any (<60L) |
+| Empty type dirs | any (entities, comparisons) | any |
+
+Three exit states:
+1. **Truly idle** — zero new findings, all metrics healthy. Exit:
+   `"Research idle — no new findings."`
+2. **Steady backlog** — no new findings, but known gaps persist. Exit:
+   `"Research steady — [N] recurring: [titles]"`
+3. **High mode never idle** — always produce recommendations. If standard
+   checks find nothing, generate proactive suggestions.
+
+**NEVER report idle when vault health metrics show actionable gaps.**

package/skills/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.1-beta.21",
+  "version": "0.2.1-beta.23",
   "private": true,
   "files": [
     "wiki-*",
     "proj-*",
+    "dev-loop-research",
     "using-skillwiki",
     ".claude-plugin",
     "hooks",

package/skills/using-skillwiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 version: 0.2.1
 name: using-skillwiki
-description: Invoke at session start or when knowledge-base tasks arise — maps all wiki-*/proj-* skills and teaches the skillwiki CLI workflow
+description: Invoke at session start or when knowledge-base tasks arise — maps all skillwiki skills and teaches the skillwiki CLI workflow
 ---
 
 <SUBAGENT-STOP>
@@ -28,6 +28,7 @@ Invoke a skillwiki skill when the user:
 - 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
 
@@ -86,6 +87,8 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `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` | Standalone research agent — scans repo + vault health, outputs prioritized work-item recommendations |
 
 ## CLI Backbone
 

package/skills/wiki-gate-plan-mode/SKILL.md

@@ -0,0 +1,80 @@
+---
+version: 0.2.1
+name: wiki-gate-plan-mode
+description: Toggle EnterPlanMode gating — force superpowers planning skills instead of built-in plan mode
+---
+
+# wiki-gate-plan-mode
+
+Gate the agent away from Claude Code's built-in `EnterPlanMode` tool, forcing
+all planning through `superpowers:brainstorming` → `superpowers:writing-plans`
+(or a configurable pipeline). Uses `permissions.deny` for two-layer enforcement:
+the tool is removed from the model's context before it ever sees it.
+
+## When This Skill Activates
+
+- User says "gate plan mode", "disable EnterPlanMode", "force superpowers planning"
+- User asks to toggle, check, or configure plan-mode gating
+- User wants to enforce structured planning workflows in a project
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Parse arguments.** Accept one of:
+   - `on` — enable gating (add EnterPlanMode to deny)
+   - `off` — disable gating (remove EnterPlanMode from deny)
+   - `status` (default if no argument) — report current state
+
+1. **Locate settings file.** Check in this order:
+   - `~/.claude/settings.json` (user-level, global — primary target for plan-mode gating)
+   - `.claude/settings.json` (project-level, checked into repo — use if user specifies project scope)
+   If the target file does not exist, create it with `{ "permissions": { "deny": [] } }`.
+
+2. **Read current state.** Parse the settings JSON. Check whether `"EnterPlanMode"` is present in `permissions.deny[]`.
+
+3. **Apply the requested action:**
+
+   **`on`:**
+   - If `"EnterPlanMode"` is already in `permissions.deny`, report "already gated" and stop.
+   - Otherwise, add `"EnterPlanMode"` to `permissions.deny[]`. Create the array if absent.
+   - Write the updated JSON back, preserving formatting.
+   - Report: "EnterPlanMode gated — agent will use superpowers planning skills."
+
+   **`off`:**
+   - If `"EnterPlanMode"` is not in `permissions.deny`, report "already ungated" and stop.
+   - Otherwise, remove `"EnterPlanMode"` from `permissions.deny[]`. If the array is now empty, remove the `deny` key.
+   - Write the updated JSON back.
+   - Report: "EnterPlanMode ungated — built-in plan mode is available."
+
+   **`status`:**
+   - Check both `~/.claude/settings.json` and `.claude/settings.json`.
+   - Report whether EnterPlanMode is currently gated or ungated.
+   - If gated, list which settings file contains the deny entry.
+
+4. **Suggest CLAUDE.md directive (on action only).** After enabling gating, check whether the project's `CLAUDE.md` contains a planning directive (search for "EnterPlanMode" or "superpowers:brainstorming"). If not found, suggest adding:
+
+   ```
+   ## Planning
+
+   Use superpowers:brainstorming → superpowers:writing-plans for all planning. EnterPlanMode is disabled.
+   ```
+
+   Do NOT edit CLAUDE.md automatically — only suggest.
+
+## Schema Warning
+
+The JSON Schema Store's `claude-code-settings.json` schema has a closed regex for `permissions.deny` that includes `ExitPlanMode` but **omits `EnterPlanMode`**. IDEs (VS Code, JetBrains) will show a validation warning. This is a schema staleness issue, not a runtime issue — Claude Code's runtime accepts `EnterPlanMode` in `permissions.deny` and enforces it correctly. See `[[queries/claude-code-plan-mode-schema-validation]]` for full analysis.
+
+## Stop conditions
+
+- No project directory found (not inside a git repo or project).
+- Settings file exists but is not valid JSON and cannot be parsed.
+
+## Forbidden
+
+- Do not add any tool other than `EnterPlanMode` to the deny list.
+- Do not modify CLAUDE.md automatically — only suggest changes.
+- Do not remove other entries from `permissions.deny` when toggling off — only remove `EnterPlanMode`.