@zosmaai/pi-llm-wiki 0.6.4 → 0.6.6

package/docs/plans/auto-bootstrap-plan.md

@@ -0,0 +1,46 @@
+# Auto-Bootstrap Plan
+
+## Changes (3 files)
+
+### 1. `extensions/llm-wiki/index.ts`
+
+**session_start hook** — Show correct status based on vault existence:
+```typescript
+pi.on("session_start", async (_event, ctx) => {
+  const paths = resolveVaultPaths(process.cwd());
+  if (!existsSync(join(paths.dotWiki, "config.json"))) {
+    ctx.ui.setStatus("llm-wiki", "📝 No wiki — call wiki_bootstrap to enable");
+    return;
+  }
+  ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (12 tools, auto-recall active)");
+});
+```
+
+**before_agent_start hook** — When no wiki exists on first turn, inject a system prompt hint so the LLM knows to suggest bootstrapping:
+```typescript
+pi.on("before_agent_start", async (event, _ctx) => {
+  const paths = resolveVaultPaths(process.cwd());
+  if (!existsSync(join(paths.dotWiki, "config.json"))) {
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n📝 No LLM Wiki found in this directory. On your first response, use ask_user to offer the user creating one via wiki_bootstrap. After suggesting once, do not repeat.`
+    };
+  }
+  // ... existing recall logic unchanged
+});
+```
+
+### 2. `extensions/llm-wiki/lib/recall.ts`
+
+**wiki_recall tool** — Improve error message when no vault exists to hint at bootstrap:
+```typescript
+// Current: "No wiki vault found at this location. Initialize one with wiki_bootstrap first."
+// Keep as-is but add isError flag for model to react
+```
+
+### 3. `skills/llm-wiki/SKILL.md`
+
+Add a section about what to do when no wiki exists — tell the model to proactively suggest bootstrapping using `ask_user`.
+
+## Not in scope (separate issue)
+
+- Migration script shipping — bcdiaconu's feedback from #22, needs its own focused PR

package/extensions/llm-wiki/index.ts

@@ -34,6 +34,9 @@ import { resolveVaultPaths } from "./lib/utils.js";
  * - wiki_recall tool available for explicit deep searches
  */
 
+// Track whether we already suggested bootstrapping this session
+let bootstrapSuggested = false;
+
 export default function (pi: ExtensionAPI) {
   registerWikiBootstrap(pi);
   registerWikiCaptureSource(pi);
@@ -51,6 +54,12 @@ export default function (pi: ExtensionAPI) {
   installGuardrails(pi);
 
   pi.on("session_start", async (_event, ctx) => {
+    bootstrapSuggested = false;
+    const paths = resolveVaultPaths(process.cwd());
+    if (!existsSync(join(paths.dotWiki, "config.json"))) {
+      ctx.ui.setStatus("llm-wiki", "📝 No wiki — call wiki_bootstrap to enable");
+      return;
+    }
     ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (12 tools, auto-recall active)");
   });
 
@@ -60,7 +69,14 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, _ctx) => {
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
-      return; // No wiki vault — nothing to recall
+      // No wiki — suggest bootstrap on first turn only
+      if (!bootstrapSuggested) {
+        bootstrapSuggested = true;
+        return {
+          systemPrompt: `${event.systemPrompt}\n\n📝 No LLM Wiki found in this directory. On your first response, use ask_user to offer the user creating one via wiki_bootstrap. After suggesting once, do not repeat.`,
+        };
+      }
+      return;
     }
 
     const prompt = event.prompt || "";

package/extensions/llm-wiki/lib/tools.ts

@@ -102,6 +102,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
         "- **concept** — ideas, patterns, frameworks",
         "- **synthesis** — cross-source theses and tensions",
         "- **analysis** — durable filed answers from queries",
+        "- **requirement** — atomic requirements with status, priority, and traceability",
         "",
         "## Linking Style",
         "",
@@ -368,7 +369,9 @@ export function registerWikiEnsurePage(pi: ExtensionAPI): void {
       "Search existing pages first with wiki_search.",
     ],
     parameters: Type.Object({
-      type: Type.String({ description: "Page type: entity | concept | synthesis | analysis" }),
+      type: Type.String({
+        description: "Page type: entity | concept | synthesis | analysis | requirement",
+      }),
       title: Type.String({ description: "Page title" }),
       content: Type.Optional(
         Type.String({ description: "Optional initial content (otherwise uses template)" }),
@@ -398,6 +401,7 @@ export function registerWikiEnsurePage(pi: ExtensionAPI): void {
         concept: "concepts",
         synthesis: "syntheses",
         analysis: "analyses",
+        requirement: "requirements",
       };
       const folder = folderMap[type] || "concepts";
       const pagePath = join(paths.wiki, folder, `${slug}.md`);
@@ -466,6 +470,43 @@ function buildPageTemplate(
       "Durable answer from a query.\n\n## Question\n\n[Original question]",
     );
   }
+  if (type === "requirement") {
+    return [
+      "---",
+      "type: requirement",
+      `created: ${date}`,
+      `updated: ${date}`,
+      "status: draft",
+      "priority: p2",
+      "source_id: ",
+      "depends_on: []",
+      "---",
+      "",
+      `# ${title}`,
+      "",
+      "## Description",
+      "",
+      "[Clear description of what this requirement entails]",
+      "",
+      "## Acceptance Criteria",
+      "",
+      "- [ ] [Criterion 1]",
+      "- [ ] [Criterion 2]",
+      "",
+      "## Dependencies",
+      "",
+      "_Pages this requirement depends on._",
+      "",
+      "## Implementation Notes",
+      "",
+      "[Optional notes]",
+      "",
+      "## Sources",
+      "",
+      "- [[sources/SRC-...]] — original concept capture",
+      "",
+    ].join("\n");
+  }
   return base;
 }
 

package/extensions/llm-wiki/lib/utils.ts

@@ -97,6 +97,7 @@ export function ensureVaultStructure(paths: VaultPaths): void {
     join(paths.wiki, "concepts"),
     join(paths.wiki, "syntheses"),
     join(paths.wiki, "analyses"),
+    join(paths.wiki, "requirements"),
     paths.meta,
     paths.dotWiki,
     paths.outputs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",

package/prompts/wiki-req.md

@@ -0,0 +1,55 @@
+---
+description: Capture and decompose a concept into atomic, traceable wiki requirements. Clarifies ambiguous requirements, splits them into atomic pieces, and persists them as wiki/requirements/ pages with status tracking.
+argument-hint: "<concept description>"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-req
+
+Capture a concept and decompose it into atomic, traceable requirements in the wiki.
+
+Transforms natural language descriptions into structured `wiki/requirements/` pages, preserving the original clarified concept as an immutable source packet in `raw/sources/`.
+
+## User Arguments
+
+$ARGUMENTS
+
+Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the wiki conventions, architecture, and page type rules.
+
+## Steps
+
+1. **Clarify the concept**
+   - Discuss with the user: unpack ambiguous terms, surfaces implicit assumptions, identify scope boundaries
+   - Ask targeted questions to resolve unknowns (e.g., "Which providers?", "What's the fallback behavior?", "Who are the actors?")
+   - Reach mutual clarity before proceeding
+
+2. **Capture the clarified concept**
+   - Call `wiki_capture_source(text=...)` with the clarified conversation as markdown
+   - This creates an immutable record in `raw/sources/SRC-YYYY-MM-DD-NNN/`
+   - The source captures the original intent verbatim — no interpretation, no decomposition
+
+3. **Decompose into atomic requirements**
+   - Break the clarified concept into the smallest meaningful units of functionality
+   - Each requirement should represent one independently verifiable behavior
+   - For each atomic requirement, call `wiki_ensure_page(type="requirement", title="...", content="...")` where content includes:
+     - `type: requirement` and `status: draft` in frontmatter
+     - A clear `## Description` section
+     - `## Acceptance Criteria` as a checkbox list (the threshold for "done")
+     - `source_id` linking back to the source capture
+     - `depends_on` linking to any prerequisite requirements
+     - `[[wikilinks]]` to relevant entities, concepts, and other wiki pages
+   - Set priority based on user input: `p0` (blocking), `p1` (critical), `p2` (important), `p3` (nice-to-have)
+
+4. **Cross-link and finalize**
+   - Ensure each requirement page has bidirectional wikilinks to related pages
+   - Update any existing entity or concept pages that these requirements reference
+   - Report the results: how many requirements created, their priorities, and the source capture ID
+
+**Rules:**
+- One atomic requirement per `wiki_ensure_page` call — each must be independently testable
+- Always capture the clarified concept first via `wiki_capture_source` before decomposing
+- Requirements live in `wiki/requirements/` — they are editable wiki pages, not immutable sources
+- Use status values: `draft` → `clarified` → `active` → `implemented` → `deferred` → `rejected`
+- Use priority values: `p0` (blocking), `p1` (critical), `p2` (important), `p3` (nice-to-have)
+- Do not create requirements in `raw/` — that layer is for external source artifacts only

package/skills/llm-wiki/SKILL.md

@@ -81,6 +81,14 @@ wiki_recall(query="specific terms...", max_results=10)
 
 This gives you more control over the search terms and returns content previews.
 
+### No Wiki Yet
+
+If the extension injects a "No LLM Wiki found" hint, use `ask_user` to offer creating one:
+
+> "No LLM Wiki found in this directory. Would you like to create one? It gives you a linked knowledge base with automatic recall."
+
+If the user agrees, call `wiki_bootstrap(topic="...", mode="personal")`. Suggest only once per session.
+
 ## Available Tools
 
 Use these directly — they handle scaffolding, bookkeeping, recall, and capture: