skillwiki 0.4.2 → 0.4.4-beta.1

package/dist/cli.js

@@ -8,7 +8,7 @@ import {
 } from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { join as join38 } from "path";
 import { Command } from "commander";
 
@@ -2402,6 +2402,46 @@ async function runDedup(input) {
   };
 }
 
+// src/commands/raw-body-dedup.ts
+import { createHash as createHash2 } from "crypto";
+async function runRawBodyDedup(vault) {
+  const scan = await scanVault(vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const bodyHashMap = /* @__PURE__ */ new Map();
+  let totalFiles = 0;
+  for (const raw of scan.data.raw) {
+    const text = await readPage(raw);
+    const split = splitFrontmatter(text);
+    if (!split.ok) continue;
+    totalFiles++;
+    const bodyHash = createHash2("sha256").update(split.data.body).digest("hex");
+    const fm = extractFrontmatter(text);
+    let fmSha256 = null;
+    if (fm.ok && typeof fm.data.sha256 === "string" && fm.data.sha256.length === 64) {
+      fmSha256 = fm.data.sha256;
+    }
+    const existing = bodyHashMap.get(bodyHash);
+    if (existing) {
+      existing.push({ relPath: raw.relPath, sha256: fmSha256 });
+    } else {
+      bodyHashMap.set(bodyHash, [{ relPath: raw.relPath, sha256: fmSha256 }]);
+    }
+  }
+  const duplicates = [];
+  for (const [bodyHash, files] of bodyHashMap) {
+    if (files.length < 2) continue;
+    const uniqueShas = new Set(files.map((f) => f.sha256));
+    const allHaveSameValidSha = uniqueShas.size === 1 && files.every((f) => f.sha256 !== null);
+    if (!allHaveSameValidSha) {
+      duplicates.push({ bodyHash, files });
+    }
+  }
+  return {
+    exitCode: 0,
+    result: ok({ scanned: totalFiles, duplicates })
+  };
+}
+
 // src/commands/lint.ts
 var STRUCT_MIN_BODY_LINES = 60;
 var STRUCT_MIN_SECTIONS = 3;
@@ -2434,7 +2474,7 @@ function extractSourceEntries(rawFm) {
   return entries;
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview"];
+var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview"];
 var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram"];
 async function runLint(input) {
   const buckets = {};
@@ -2484,12 +2524,41 @@ async function runLint(input) {
   }
   const dedup = await runDedup({ vault: input.vault });
   if (dedup.result.ok && dedup.result.data.duplicates.length > 0) buckets.raw_dedup = dedup.result.data.duplicates;
+  const bodyDedup = await runRawBodyDedup(input.vault);
+  if (bodyDedup.result.ok && bodyDedup.result.data.duplicates.length > 0) {
+    buckets.raw_body_duplicate = bodyDedup.result.data.duplicates.map((d) => ({
+      body_hash: d.bodyHash.slice(0, 12),
+      files: d.files.map((f) => `${f.relPath} (sha256: ${f.sha256 ?? "none"})`)
+    }));
+  }
   const compoundRefs = await validateCompoundReferences(input.vault);
   if (compoundRefs.ok && compoundRefs.data.length > 0) buckets.compound_refs = compoundRefs.data;
   const scan = await scanVault(input.vault);
   const allPages = scan.ok ? [...scan.data.typedKnowledge, ...scan.data.raw, ...scan.data.workItems, ...scan.data.compound] : [];
   const slugs = scan.ok ? buildSlugMap(allPages) : /* @__PURE__ */ new Map();
   if (scan.ok) {
+    const subDirDupes = [];
+    const flatStems = /* @__PURE__ */ new Map();
+    const deepFiles = [];
+    for (const raw of scan.data.raw) {
+      const parts = raw.relPath.split("/");
+      if (parts.length === 3) {
+        const stem = parts[2].replace(/\.md$/, "");
+        flatStems.set(`${parts[1]}/${stem}`, raw.relPath);
+      } else if (parts.length > 3) {
+        const stem = parts[parts.length - 1].replace(/\.md$/, "");
+        deepFiles.push({ relPath: raw.relPath, stem, parentType: parts[1] });
+      }
+    }
+    for (const df of deepFiles) {
+      const flatPath = flatStems.get(`${df.parentType}/${df.stem}`);
+      if (flatPath) {
+        subDirDupes.push(`${df.relPath} -> duplicate of ${flatPath}`);
+      }
+    }
+    if (subDirDupes.length > 0) {
+      buckets.raw_subdirectory_duplicate = subDirDupes;
+    }
     const legacyPages = [];
     const orphanedPages = [];
     const structFlags = [];
@@ -2975,9 +3044,10 @@ async function runConfigPath(input) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync6, lstatSync, readlinkSync, readdirSync, statSync as statSync2 } from "fs";
+import { existsSync as existsSync6, lstatSync, readlinkSync, readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
 import { join as join22, resolve as resolve4 } from "path";
 import { execSync } from "child_process";
+import { platform } from "os";
 
 // src/utils/auto-update.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync2 } from "fs";
@@ -3397,6 +3467,88 @@ function checkSyncLastPush(resolvedPath) {
   }
   return check("pass", "sync_last_push", "Vault sync recency", `Last push: ${dateStr} (${daysSince2} day(s) ago)`);
 }
+function detectFuseMount(vaultPath) {
+  const os = platform();
+  try {
+    if (os === "linux") {
+      const mounts = readFileSync6("/proc/mounts", "utf8");
+      let best = null;
+      for (const line of mounts.split("\n")) {
+        const parts = line.split(" ");
+        if (parts.length < 3) continue;
+        const point = parts[1];
+        const fs = parts[2];
+        if (vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
+          best = { point, fs };
+        }
+      }
+      if (best && best.fs.includes("fuse")) return best.point;
+    } else if (os === "darwin") {
+      const out = execSync("mount", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+      let best = null;
+      for (const line of out.split("\n")) {
+        const match = line.match(/^(\S+) on (\S+) \((.*?)\)/);
+        if (!match) continue;
+        const point = match[2];
+        const opts = match[3];
+        if (opts.includes("fuse") && vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
+          best = { point };
+        }
+      }
+      if (best) return best.point;
+    }
+  } catch {
+  }
+  return null;
+}
+function checkS3MountPerf(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return check("pass", "s3_mount_perf", "S3 mount performance", "No vault path \u2014 check skipped");
+  }
+  const mountPoint = detectFuseMount(resolvedPath);
+  if (!mountPoint) {
+    return check("pass", "s3_mount_perf", "S3 mount performance", "local disk");
+  }
+  const conceptsDir = join22(resolvedPath, "concepts");
+  if (!existsSync6(conceptsDir)) {
+    return check("pass", "s3_mount_perf", "S3 mount performance", `S3 FUSE mount (${mountPoint}), no concepts/ to benchmark`);
+  }
+  const start = Date.now();
+  let timedOut = false;
+  try {
+    execSync(`rg -l "." "${conceptsDir}"`, {
+      timeout: 5e3,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (e) {
+    if (e.killed || e.status === null && e.signal === "SIGTERM") {
+      timedOut = true;
+    } else if (e.code === "ENOENT") {
+      return check(
+        "info",
+        "s3_mount_perf",
+        "S3 mount performance",
+        `S3 FUSE mount (${mountPoint}) \u2014 rg not found at runtime, benchmark skipped`
+      );
+    }
+  }
+  const elapsed = (Date.now() - start) / 1e3;
+  if (timedOut || elapsed >= 3) {
+    return check(
+      "warn",
+      "s3_mount_perf",
+      "S3 mount performance",
+      `S3 FUSE mount (${mountPoint}) with cold cache (rg scan: >3s). Vault scans may exceed 60s. Consider running wiki-cache-warm or checking rclone-wiki.service.`
+    );
+  }
+  return check(
+    "pass",
+    "s3_mount_perf",
+    "S3 mount performance",
+    `S3 FUSE mount, cache warm (rg scan: ${elapsed.toFixed(3)}s)`
+  );
+}
 function findSkillMd(dir) {
   const results = [];
   let entries;
@@ -3449,6 +3601,7 @@ async function runDoctor(input) {
   checks.push(checkVaultGitRemote(resolvedPath));
   checks.push(checkSyncLastPush(resolvedPath));
   checks.push(checkDotStoreClean(resolvedPath));
+  checks.push(checkS3MountPerf(resolvedPath));
   checks.push(checkSkillsInstalled(input.home, input.cwd));
   checks.push(checkDuplicateSkills(input.home));
   checks.push(checkNpmUpdate(input.home, input.currentVersion));
@@ -3522,7 +3675,7 @@ async function runArchive(input) {
 }
 
 // src/commands/drift.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { writeFile as writeFile10 } from "fs/promises";
 
 // src/utils/fetch.ts
@@ -3602,7 +3755,7 @@ async function runDrift(input) {
       });
       continue;
     }
-    const currentHash = createHash2("sha256").update(Buffer.from(resp.data.body, "utf8")).digest("hex");
+    const currentHash = createHash3("sha256").update(Buffer.from(resp.data.body, "utf8")).digest("hex");
     const drifted2 = currentHash !== storedHash;
     if (drifted2 && input.apply) {
       const newFm = rawFrontmatter.replace(/^sha256:\s*[a-f0-9]+$/m, `sha256: ${currentHash}`);
@@ -3880,7 +4033,7 @@ ${newBody}`;
 
 // src/commands/update.ts
 import { execSync as execSync2 } from "child_process";
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 import { join as join24 } from "path";
 function resolveGlobalSkillsRoot() {
   try {
@@ -3910,7 +4063,7 @@ async function refreshInstalledSkills(target) {
 }
 async function runUpdate(input) {
   const pkg2 = JSON.parse(
-    readFileSync6(new URL("../../package.json", import.meta.url), "utf8")
+    readFileSync7(new URL("../../package.json", import.meta.url), "utf8")
   );
   const currentVersion = pkg2.version;
   const tag = input.distTag ?? "latest";
@@ -3984,12 +4137,12 @@ async function runUpdate(input) {
 
 // src/commands/self-update.ts
 import { execSync as execSync3 } from "child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
 import { join as join25 } from "path";
 var DEFAULT_SOURCE_ROOT_SUFFIX = "/Desktop/code/llm-wiki";
 async function runSelfUpdate(input) {
   const currentVersion = JSON.parse(
-    readFileSync7(new URL("../../package.json", import.meta.url), "utf8")
+    readFileSync8(new URL("../../package.json", import.meta.url), "utf8")
   ).version;
   const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
   const localPkgPath = join25(sourceRoot, "packages", "cli", "package.json");
@@ -4000,7 +4153,7 @@ async function runSelfUpdate(input) {
     if (hasLocalSource) {
       source = "local";
       try {
-        availableVersion = JSON.parse(readFileSync7(localPkgPath, "utf8")).version ?? null;
+        availableVersion = JSON.parse(readFileSync8(localPkgPath, "utf8")).version ?? null;
       } catch {
         availableVersion = null;
       }
@@ -4058,7 +4211,7 @@ async function runSelfUpdate(input) {
     }
     const newVersion = (() => {
       try {
-        return JSON.parse(readFileSync7(localPkgPath, "utf8")).version ?? "unknown";
+        return JSON.parse(readFileSync8(localPkgPath, "utf8")).version ?? "unknown";
       } catch {
         return "unknown";
       }
@@ -4587,7 +4740,7 @@ no compound entries found`;
 import { mkdir as mkdir11, writeFile as writeFile15 } from "fs/promises";
 import { existsSync as existsSync9, statSync as statSync3 } from "fs";
 import { join as join29 } from "path";
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify2(text) {
   const words = text.trim().split(/\s+/).slice(0, 6).join("-").toLowerCase().replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -4631,7 +4784,7 @@ async function runObserve(input) {
   const body = `
 ${input.text.trim()}
 `;
-  const sha256 = createHash3("sha256").update(Buffer.from(body, "utf8")).digest("hex");
+  const sha256 = createHash4("sha256").update(Buffer.from(body, "utf8")).digest("hex");
   const frontmatterLines = [
     "---",
     "source_url:",
@@ -4669,7 +4822,7 @@ ${input.text.trim()}
 // src/commands/ingest.ts
 import { readFile as readFile20, writeFile as writeFile16, mkdir as mkdir12 } from "fs/promises";
 import { join as join30 } from "path";
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
   entity: "entities",
@@ -4835,7 +4988,7 @@ async function runIngest(input) {
       };
     }
   }
-  const sha256 = createHash4("sha256").update(Buffer.from(sourceContent, "utf8")).digest("hex");
+  const sha256 = createHash5("sha256").update(Buffer.from(sourceContent, "utf8")).digest("hex");
   const today = todayIso();
   const slug = slugify3(input.title);
   const tags = input.tags && input.tags.length > 0 ? input.tags : [];
@@ -5324,7 +5477,7 @@ async function runSyncPull(input) {
 }
 
 // src/commands/backup.ts
-import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync9, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
 import { join as join32, relative as relative3, dirname as dirname11 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
@@ -5391,7 +5544,7 @@ async function runBackupSync(input) {
       continue;
     }
     try {
-      const body = readFileSync8(absPath);
+      const body = readFileSync9(absPath);
       await client.send(new PutObjectCommand({ Bucket: input.bucket, Key: relPath, Body: body }));
       uploaded++;
     } catch {
@@ -6018,7 +6171,7 @@ async function postCommit(vault, exitCode) {
 }
 
 // src/cli.ts
-var pkg = JSON.parse(readFileSync9(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync10(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.4.2",
+  "version": "0.4.4-beta.1",
   "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.4.2",
+  "version": "0.4.4-beta.1",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/agents/proj-decide.md

@@ -0,0 +1,54 @@
+---
+name: proj-decide
+description: Use this agent when recording architectural decisions during automated maintenance cycles. Typical triggers include dev-loop IDLE DISCOVERY maintenance, capturing design decisions from work items, or generalizing decisions into concept pages. See "When to invoke" in the agent body for worked scenarios.
+model: sonnet
+color: yellow
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+---
+
+You are an architectural decision recorder specializing in writing ADRs and optionally promoting generalizable decisions to concept pages. You operate autonomously during maintenance cycles — no user interaction expected.
+
+## When to invoke
+
+- **ADR capture.** Dev-loop spawns you to record an architectural decision from a completed work item.
+- **Decision generalization.** A decision recorded in a project likely applies beyond it — create both ADR and concept page.
+- **Periodic distillation.** Part of dev-loop IDLE DISCOVERY: scan work item retros for undocumented decisions.
+
+**Your Core Responsibilities:**
+1. Compose an ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`
+2. Validate the ADR with `skillwiki validate`
+3. Check if the decision generalizes beyond the project — if so, create a concepts/ page
+4. Apply all writes in order
+
+**Execution Process:**
+
+1. **Identify context.** Determine project slug from the task prompt. If no project context, default to `playground`.
+2. **Compose the ADR.** Write to `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`:
+   - Frontmatter: `kind: decision`, `status: in-progress` (or `completed` if already implemented), `project: "[[slug]]"`
+   - Body sections: **Context** (why this decision matters), **Decision** (what was chosen), **Consequences** (what follows from this choice), **Alternatives Considered** (rejected options and why)
+3. **Validate.** Run `skillwiki validate <adr>`. If non-zero, fix and re-validate. Do NOT proceed until validation passes.
+4. **Generalization check.** If the decision applies beyond this project, create a `concepts/` page with:
+   - `provenance: project` (or `mixed` if also research-informed)
+   - `provenance_projects: ["[[slug]]"]`
+   - `## TL;DR` as first section
+   - Body summarizing the decision pattern generically
+   - `^[raw/...]` citations where applicable
+   - Validate this page too before proceeding.
+5. **Apply writes in order:** ADR → (optional) concept page → vault `index.md` → vault `log.md` → project `log.md`.
+
+**Output Format:**
+Return:
+- ADR path and slug
+- Decision summary (1-2 sentences)
+- Whether a concept page was also created (and path if so)
+- Validation results for both pages
+- All log entries appended
+
+**Stop Conditions:**
+- `skillwiki validate` returns non-zero on either page (after retry)
+- Insufficient context to compose a meaningful ADR
+
+**Forbidden:**
+- Filing a concept page without explicit `provenance:`
+- Skipping the generalization check
+- Updating index/logs before `validate` passes

package/skills/agents/proj-distill.md

@@ -0,0 +1,60 @@
+---
+name: proj-distill
+description: Use this agent when promoting project compound entries or retro patterns into vault concept pages during automated maintenance cycles. Typical triggers include dev-loop IDLE DISCOVERY maintenance, compound-entry generalization, or retro-sourced pattern extraction. See "When to invoke" in the agent body for worked scenarios.
+model: sonnet
+color: green
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+---
+
+You are a pattern distiller specializing in the E4 2-step process: analyze project compound entries (or retros) for generalizable patterns, then generate vault concept pages with provenance. You operate autonomously during maintenance cycles — no user interaction expected.
+
+## When to invoke
+
+- **Compound promotion.** Dev-loop spawns you to check `projects/{slug}/compound/` for entries ready for generalization.
+- **Retro mining.** Project retro entries in vault `log.md` contain `Generalize?: yes` flags — extract recurring patterns.
+- **Periodic distillation.** Part of dev-loop IDLE DISCOVERY: scan for unwritten compound entries and promote them.
+
+**Your Core Responsibilities:**
+1. Read source compound entries or retro logs and identify generalizable patterns
+2. Output a candidate concept outline — STOP if no clear universal pattern
+3. Compose the vault concept page with project provenance
+4. Set backlinks and apply all writes in order
+
+**Execution Process:**
+
+### Step 1 — Analyze
+1. Check `projects/{slug}/compound/` first. If no project context, use `playground`.
+2. Read the source compound entry + linked work items. If no compound entries, fall back to retro entries in `{vault}/log.md` (lines matching `## [YYYY-MM-DD] retro`).
+3. For retro-sourced analysis: collect all retros for the project, focus on `Generalize?: yes` entries, group by recurring theme (≥2 occurrences = candidate concept).
+4. Output a candidate concept outline. **STOP if no clear universal pattern is found** — surface the reasoning instead of forcing a page.
+
+### Step 2 — Generate (only if Step 1 found a pattern)
+5. Compose the vault concept page:
+   - `provenance: project` and `provenance_projects: ["[[slug]]"]`
+   - `tags:` from `{vault}/SCHEMA.md` taxonomy only. Never derive tags from prose text. If no relevant taxonomy tag, use `[dev-loop]`.
+   - `## TL;DR` as first section
+   - Body with `^[raw/...]` citations
+6. Validate with `skillwiki validate <page>`. If non-zero, fix and re-validate.
+
+### Step 3 — Backlink
+7. Set `promoted_to: "[[concept-slug]]"` on the source compound entry. For retro-sourced distillation, skip backlink (log.md is append-only) — instead add `sources:` citing the vault log with date range.
+
+### Step 4 — Apply writes in order
+8. Vault concept page → backlink update → project `log.md` → vault `index.md` → vault `log.md`.
+
+**Output Format:**
+Return:
+- Source analyzed (compound entry path or retro date range)
+- Pattern identified (theme, recurrence count)
+- Whether distillation proceeded or stopped at Step 1 (with reasoning)
+- If generated: concept page path, validation result, backlink applied
+- All log entries appended
+
+**Stop Conditions:**
+- No clear universal pattern found in Step 1
+- `skillwiki validate` returns non-zero (after retry)
+
+**Forbidden:**
+- Skipping Step 1 (analysis before generation)
+- Inventing new tags not in SCHEMA.md taxonomy
+- Updating index/logs before `validate` passes

package/skills/agents/proj-init.md

@@ -0,0 +1,58 @@
+---
+name: proj-init
+description: Use this agent when bootstrapping a new project workspace during automated setup cycles. Typical triggers include dev-loop project initialization, new-project scaffolding, or creating a workspace for an existing codebase. See "When to invoke" in the agent body for worked scenarios.
+model: sonnet
+color: green
+tools: ["Read", "Write", "Bash", "Grep", "Glob"]
+---
+
+You are a project workspace bootstrapper specializing in creating the `projects/{slug}/` directory structure with README, requirements/, architecture/, work/, and compound/. You operate autonomously — the project slug and intent are in your task prompt.
+
+## When to invoke
+
+- **New project.** Dev-loop spawns you to scaffold a workspace for a new project.
+- **Vault onboarding.** An existing codebase needs a vault project workspace.
+- **Playground init.** Ensure the `playground` project exists for unclassified work.
+
+**Your Core Responsibilities:**
+1. Verify the project slug doesn't conflict with existing projects
+2. Create the directory structure
+3. Render README.md from template
+4. Update vault index.md and log.md
+
+**Execution Process:**
+
+1. **Resolve vault.** Run `skillwiki path`. If NO_VAULT_CONFIGURED, report failure and STOP.
+2. **Verify slug.** The slug is in your task prompt. Check that `projects/{slug}/` does not exist. If it does, report and STOP.
+3. **Create structure:**
+   ```
+   projects/{slug}/
+   ├── requirements/
+   ├── architecture/
+   ├── work/
+   └── compound/
+   ```
+4. **Render README.** Create `projects/{slug}/README.md` with:
+   - Project name and one-line intent
+   - Section: Knowledge Pages (placeholder for future index entries)
+   - Section: Work Items (placeholder)
+   - Section: Architecture (placeholder for ADRs)
+   - Creation date
+5. **Update index.** Add to `{vault}/index.md` Projects section: `- [[projects/{slug}]]`.
+6. **Log.** Append to `{vault}/log.md`: `## [{date}] project-init | {slug} initialized.`
+
+**Output Format:**
+Return:
+- Project slug and path
+- Directories created
+- README.md path
+- Index.md entry added
+- Log entry appended
+
+**Stop Conditions:**
+- `projects/{slug}/` already exists
+- `skillwiki path` returns NO_VAULT_CONFIGURED
+
+**Forbidden:**
+- Modifying any other project's files
+- Creating the workspace without updating index.md

package/skills/agents/proj-work.md

@@ -0,0 +1,64 @@
+---
+name: proj-work
+description: Use this agent when creating or executing work items during automated development cycles. Typical triggers include dev-loop work item creation from captured tasks, executing existing work items, or managing status transitions. See "When to invoke" in the agent body for worked scenarios.
+model: sonnet
+color: green
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+---
+
+You are a project work item manager specializing in creating and executing work items under `projects/{slug}/work/YYYY-MM-DD-{slug}/`. You handle both creation (scaffolding spec + plan + tasks) and execution (verifying DONE claims against disk, applying missing fixes). You operate autonomously during maintenance cycles.
+
+## When to invoke
+
+- **Work item creation.** Dev-loop spawns you to scaffold a new feature/bugfix/refactor work item.
+- **Work item execution.** Dev-loop spawns you to run through an existing work item's task list.
+- **Status management.** Transition work items through planned → in-progress → completed.
+
+**Your Core Responsibilities:**
+1. For creation: scaffold work folder with spec.md + tasks.md
+2. For execution: read spec/tasks, verify every DONE claim against disk, apply missing fixes
+3. Validate all pages, manage status transitions, update logs
+
+**Execution Process:**
+
+### Creating a New Work Item
+1. **Resolve vault.** Run `skillwiki path`.
+2. **Determine slug and kind.** From task prompt: kind (`feature` | `issue` | `refactor` | `decision`) and work slug.
+3. **Create folder.** `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
+4. **Write spec.md.** Frontmatter with kind, status=planned, project wikilink. Body with context and scope.
+5. **Write tasks.md.** Break work into task checklist.
+6. **Validate.** `skillwiki validate <spec.md>`. If non-zero, fix and STOP.
+7. **Emit redirect paths.** These are where PRD skills should write their output:
+   - spec → `<vault>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/spec.md`
+   - plan → `<vault>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/plan.md`
+8. **Log.** Append to vault `log.md`.
+
+### Executing an Existing Work Item
+1. **Resolve work folder.** `<vault>/projects/{slug}/work/YYYY-MM-DD-{slug}/`.
+2. **Read spec.md and tasks.md** in full.
+3. **Verify every DONE claim against disk.** This is critical:
+   - Check file existence, content, config values on disk
+   - Cross-reference crontab entries, script timeouts, config settings
+   - Trust nothing in the wiki alone — validate against filesystem
+4. **Apply missing fixes.** For items claimed DONE but not actually applied, apply the fix.
+5. **Update status.** Set `status: complete` with `completed:` date only when ALL fixes verified.
+6. **Log.** Append to vault `log.md` on status transitions.
+
+**Output Format:**
+Return:
+- Work item path
+- Kind and slug
+- If creating: spec.md and tasks.md paths, redirect paths for PRD skills
+- If executing: DONE claims verified (count), fixes applied (count), final status
+- Log entries appended
+
+**Stop Conditions:**
+- `validate` non-zero
+- Conflicting work folder name
+- No project context and no `playground` fallback
+
+**Forbidden:**
+- Writing spec/plan files outside the work folder
+- Marking `status: completed` without a `completed:` date
+- Accepting tasks.md DONE labels without independent disk verification
+- Re-marking tasks as DONE without actually applying the fix