openclew 0.2.1 → 0.3.0

package/lib/status.js

@@ -0,0 +1,151 @@
+/**
+ * openclew status — documentation health dashboard.
+ *
+ * Shows stats, docs missing doc_brief, stale docs, and distribution.
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { collectDocs, parseFile } = require("./search");
+const { parseLegacyDoc } = require("./migrate");
+
+function run() {
+  const projectRoot = process.cwd();
+  const docDir = path.join(projectRoot, "doc");
+
+  if (!fs.existsSync(docDir)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  const docs = collectDocs(docDir);
+  const refdocs = docs.filter((d) => d.kind === "refdoc");
+  const logs = docs.filter((d) => d.kind === "log");
+
+  // ── Overview ──────────────────────────────────────────────────
+  console.log("openclew status\n");
+  console.log(`  Refdocs: ${refdocs.length}`);
+  console.log(`  Logs:    ${logs.length}`);
+  console.log(`  Total:   ${docs.length}`);
+  console.log("");
+
+  // ── Legacy format detection ──────────────────────────────────
+  let legacyCount = 0;
+  for (const d of docs) {
+    try {
+      const content = fs.readFileSync(d.filepath, "utf-8");
+      const parsed = parseLegacyDoc(content);
+      if (parsed.isLegacy) legacyCount++;
+    } catch {}
+  }
+  if (legacyCount > 0) {
+    console.log(`Legacy format: ${legacyCount} docs need migration`);
+    console.log(`  Run 'openclew migrate' to preview, 'openclew migrate --write' to apply.\n`);
+  }
+
+  // ── Missing doc_brief ─────────────────────────────────────────
+  const missingBrief = docs.filter(
+    (d) => !d.meta.doc_brief || d.meta.doc_brief === ""
+  );
+  if (missingBrief.length) {
+    console.log(`Missing doc_brief (${missingBrief.length}):`);
+    for (const d of missingBrief) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      const subject = d.meta.subject || d.filename;
+      console.log(`  - ${relPath}  (${subject})`);
+    }
+    console.log("");
+  }
+
+  // ── Missing subject ───────────────────────────────────────────
+  const missingSubject = docs.filter(
+    (d) => !d.meta.subject || d.meta.subject === ""
+  );
+  if (missingSubject.length) {
+    console.log(`Missing subject (${missingSubject.length}):`);
+    for (const d of missingSubject) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      console.log(`  - ${relPath}`);
+    }
+    console.log("");
+  }
+
+  // ── Stale refdocs (updated > 30 days ago) ─────────────────────
+  const now = new Date();
+  const staleThresholdMs = 30 * 24 * 60 * 60 * 1000;
+  const staleRefdocs = refdocs.filter((d) => {
+    const updated = d.meta.updated || d.meta.created;
+    if (!updated) return true; // No date = stale
+    const docDate = new Date(updated);
+    return !isNaN(docDate.getTime()) && now - docDate > staleThresholdMs;
+  });
+  if (staleRefdocs.length) {
+    console.log(`Stale refdocs (not updated in 30+ days): ${staleRefdocs.length}`);
+    for (const d of staleRefdocs) {
+      const relPath = path.relative(projectRoot, d.filepath);
+      const updated = d.meta.updated || d.meta.created || "no date";
+      const subject = d.meta.subject || d.filename;
+      console.log(`  - ${relPath}  (${subject}, last: ${updated})`);
+    }
+    console.log("");
+  }
+
+  // ── Status distribution ───────────────────────────────────────
+  const statusCounts = {};
+  for (const d of docs) {
+    const st = d.meta.status || "—";
+    statusCounts[st] = (statusCounts[st] || 0) + 1;
+  }
+  const statusEntries = Object.entries(statusCounts).sort((a, b) => b[1] - a[1]);
+  if (statusEntries.length) {
+    console.log("Status distribution:");
+    for (const [status, count] of statusEntries) {
+      console.log(`  ${status}: ${count}`);
+    }
+    console.log("");
+  }
+
+  // ── Category distribution ─────────────────────────────────────
+  const catCounts = {};
+  for (const d of docs) {
+    const cat = d.meta.category || "—";
+    if (cat && cat !== "—") catCounts[cat] = (catCounts[cat] || 0) + 1;
+  }
+  const catEntries = Object.entries(catCounts).sort((a, b) => b[1] - a[1]);
+  if (catEntries.length) {
+    console.log("Category distribution:");
+    for (const [cat, count] of catEntries) {
+      console.log(`  ${cat}: ${count}`);
+    }
+    console.log("");
+  }
+
+  // ── Health score ──────────────────────────────────────────────
+  const total = docs.length;
+  if (total === 0) {
+    console.log("Health: no docs yet. Run 'openclew new' to create one.");
+    return;
+  }
+
+  const withBrief = total - missingBrief.length;
+  const withSubject = total - missingSubject.length;
+  const freshRefdocs = refdocs.length - staleRefdocs.length;
+  const healthPct = Math.round(
+    ((withBrief + withSubject + freshRefdocs) /
+      (total + total + Math.max(refdocs.length, 1))) *
+      100
+  );
+
+  console.log(`Health: ${healthPct}%`);
+  if (healthPct === 100) {
+    console.log("  All docs have subject + doc_brief, no stale refdocs.");
+  }
+}
+
+module.exports = { run };
+
+const calledAsStatus = process.argv.includes("status");
+if (require.main === module || calledAsStatus) {
+  run();
+}

package/lib/templates.js

@@ -163,6 +163,17 @@ Every doc has a metadata line + 3 levels. Read only what you need:
 
 \`doc/_INDEX.md\` is auto-generated from L1 metadata on every git commit (via a pre-commit hook).
 Never edit it manually. To force a rebuild: \`openclew index\`
+
+## Using with OpenClaw (or any agent framework)
+
+openclew handles **project knowledge** — what your project knows, what was decided, what happened.
+Agent frameworks (OpenClaw, Claude Code, Cursor, etc.) handle **agent behavior** — identity, tools, memory.
+
+They work together:
+- Your framework's workspace memory (\`MEMORY.md\`, \`SOUL.md\`, etc.) = agent-level, cross-project
+- openclew's \`doc/\` = project-level, shared across all agents and sessions
+
+openclew injects into your project's instruction file (AGENTS.md, CLAUDE.md, .cursorrules, etc.) — it doesn't replace or conflict with your framework's configuration.
 <!-- L2_END -->
 
 ---
@@ -264,15 +275,35 @@ The index (\`doc/_INDEX.md\`) auto-regenerates on every git commit. To force a r
 /**
  * Example refdoc — shows what a filled-in doc looks like.
  */
-function exampleRefdocContent() {
+function exampleRefdocContent(existingInstructions) {
   const date = today();
   const ver = ocVersion();
+
+  // Strip openclew block from existing instructions to avoid duplication
+  let seedContent = "";
+  if (existingInstructions) {
+    seedContent = existingInstructions
+      .replace(/<!--\s*openclew_START\s*-->[\s\S]*?<!--\s*openclew_END\s*-->/g, "")
+      .trim();
+  }
+
+  const seedSection = seedContent
+    ? `## From existing project instructions
+
+${seedContent}
+
+## What to do next
+<!-- Review the above (imported from your instruction file) and reorganize into the sections below. Then delete this section. -->
+
+`
+    : "";
+
   return `openclew@${ver} · created: ${date} · updated: ${date} · type: Reference · status: Active · category: Architecture · keywords: [architecture, overview, components]
 
 <!-- L1_START -->
 **subject:** Architecture overview
 
-**doc_brief:** High-level architecture of the project — components, data flow, key decisions.
+**doc_brief:** <!-- ONE LINE: What does this project do, what's the main stack, how is it deployed? -->
 <!-- L1_END -->
 
 ---
@@ -280,13 +311,25 @@ function exampleRefdocContent() {
 <!-- L2_START -->
 # L2 - Summary
 
-## Objective
-Document the high-level architecture so new contributors and AI agents understand the system quickly.
-
-## Key points
-- Replace this with your actual architecture
-- Describe the main components and how they interact
-- Note key technical decisions and their rationale
+${seedSection}## What this project does
+<!-- 1-2 sentences. What problem does it solve? Who uses it? -->
+
+## Stack
+<!-- List the main technologies: language, framework, database, key libraries. -->
+
+## How it's organized
+<!-- Describe the main directories and what lives where. e.g.:
+- src/routes/ — API endpoints
+- src/services/ — business logic
+- src/models/ — database models
+-->
+
+## Key decisions
+<!-- List 2-5 architectural choices that someone new needs to know. e.g.:
+- Auth via JWT (not sessions) because the API is stateless
+- PostgreSQL over MongoDB because we need relational queries
+- All validation happens in middleware, not in route handlers
+-->
 <!-- L2_END -->
 
 ---
@@ -294,10 +337,21 @@ Document the high-level architecture so new contributors and AI agents understan
 <!-- L3_START -->
 # L3 - Details
 
-<!-- Replace this with your actual architecture details -->
+## Data flow
+<!-- How does a request travel through the system? e.g.:
+Client → route → middleware (auth, validation) → service → repository → DB
+-->
+
+## External dependencies
+<!-- APIs, services, or systems this project talks to. -->
+
+## How to run
+<!-- Commands to start the project locally. e.g.:
+npm install && npm run dev
+-->
 
-This is an example refdoc created by \`openclew init\`.
-Edit it to document your project's architecture, or delete it and create your own.
+## Known constraints
+<!-- Limits, technical debt, or things that don't scale. -->
 
 ---
 
@@ -305,7 +359,7 @@ Edit it to document your project's architecture, or delete it and create your ow
 
 | Date | Change |
 |------|--------|
-| ${date} | Created by openclew init (example) |
+| ${date} | Created by openclew init — fill this in! |
 <!-- L3_END -->
 `;
 }
@@ -352,10 +406,136 @@ For evolving knowledge, use refdocs (\`doc/_*.md\`).
 `;
 }
 
+/**
+ * Framework integration guide — created by init alongside the main guide.
+ * Explains how openclew works with workflow frameworks (BMAD, Spec Kit, Kiro...).
+ */
+function frameworkIntegrationContent() {
+  const date = today();
+  const ver = ocVersion();
+  return `openclew@${ver} · created: ${date} · updated: ${date} · type: Guide · status: Active · category: Integration · keywords: [BMAD, Spec Kit, Kiro, workflow, framework, integration]
+
+<!-- L1_START -->
+**subject:** How to use openclew with workflow frameworks (BMAD, Spec Kit, Kiro...)
+
+**doc_brief:** openclew handles knowledge, your framework handles process. Covers concrete use cases, integration patterns, and what goes where. Works with any spec-driven methodology.
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## The split
+
+Workflow frameworks (BMAD, Spec Kit, Kiro...) solve: *"my agent doesn't follow a process."*
+openclew solves: *"my agent forgets everything between sessions."*
+
+They're complementary. Use both.
+
+| Your framework does | openclew does |
+|---------------------|---------------|
+| Structures the workflow (who does what, in what order) | Structures the knowledge (what to remember, where to find it) |
+| Produces artifacts (PRD, architecture, stories, retro) | Persists them so they're found automatically next session |
+| Scoped to one sprint/feature | Scoped to the lifetime of the codebase |
+
+## Use cases
+
+### UC1 — PRD forgotten after creation
+
+You create a PRD with your framework. Two weeks later, a new session starts. The agent doesn't know the PRD exists.
+
+**With openclew:** The PRD is persisted as \`doc/_PRD_AUTH.md\` (L1 scannable). The agent scans the index at session start and finds it automatically.
+
+### UC2 — Sprint decisions lost
+
+Three stories completed in a sprint. Decisions were made (API design, tradeoffs, rejected approaches). They live in chat history — gone.
+
+**With openclew:** Each completed story produces a log (\`doc/log/YYYY-MM-DD_story-auth-flow.md\`). Immutable. When the project resumes, the agent sees what was decided and why.
+
+### UC3 — Retrospective lessons not reused
+
+Your framework runs a retro. Lessons are identified. They go into an output file that nobody reads again.
+
+**With openclew:** Lessons go into \`doc/_LESSONS_LEARNED.md\` — a living refdoc, updated after each retro. Future sprints consult it automatically via the index.
+
+### UC4 — New teammate onboarding
+
+A new developer (or a new agent session) joins mid-project. No context.
+
+**With openclew:** Read \`doc/_INDEX.md\` → scan L1s → read L2s of relevant docs → full context in minutes. Same docs for humans and agents.
+
+### UC5 — Framework needs project context
+
+Your framework's agents (PM, Architect, Dev) start from generic prompts. They don't know your project's conventions, architecture, or past decisions.
+
+**With openclew:** Point your framework's knowledge config at \`doc/\`. Agents read refdocs as context before producing artifacts.
+
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+## Integration pattern
+
+\`\`\`
+Framework (process)              openclew (knowledge)
+───────────────────              ────────────────────
+Create PRD            →          Save as doc/_PRD_FEATURE.md
+Architecture design   →          Save as doc/_ARCHITECTURE.md
+Sprint planning       →          Log as doc/log/YYYY-MM-DD_sprint-N.md
+Story completed       →          Log as doc/log/YYYY-MM-DD_story-ID.md
+Retrospective         →          Update doc/_LESSONS_LEARNED.md
+───────────────────              ────────────────────
+Next sprint starts    ←          Agent reads index, finds all of the above
+\`\`\`
+
+## Mapping: framework artifacts → openclew docs
+
+| Framework artifact | openclew type | Naming | Mutability |
+|--------------------|---------------|--------|------------|
+| PRD | Refdoc | \`doc/_PRD_FEATURE.md\` | Updated as requirements evolve |
+| Architecture decision | Refdoc | \`doc/_ARCHITECTURE.md\` | Updated as design evolves |
+| Sprint plan | Log | \`doc/log/YYYY-MM-DD_sprint-N.md\` | Frozen (snapshot of the plan) |
+| Completed story | Log | \`doc/log/YYYY-MM-DD_story-ID.md\` | Frozen (what was done) |
+| Retrospective | Log + Refdoc | Log for the session, refdoc for accumulated lessons | Log frozen, refdoc updated |
+| Tech spec | Refdoc | \`doc/_SPEC_FEATURE.md\` | Updated until implemented |
+
+## BMAD-specific integration
+
+BMAD uses a \`project_knowledge\` config that points agents to project context. Point it at \`doc/\`:
+
+\`\`\`yaml
+# _bmad/bmm/config.yaml
+project_knowledge: doc/
+\`\`\`
+
+BMAD agents (PM, Architect, Dev, QA) will read openclew docs as context before producing artifacts.
+
+## What openclew does NOT do
+
+- Does not replace your framework's workflow or personas
+- Does not impose a development process
+- Does not require any specific framework — works standalone
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init |
+<!-- L3_END -->
+`;
+}
+
 module.exports = {
   refdocContent,
   logContent,
   guideContent,
+  frameworkIntegrationContent,
   exampleRefdocContent,
   exampleLogContent,
   slugify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclew",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "MIT",
   "bin": {
@@ -8,10 +8,22 @@
   },
   "files": [
     "bin/",
-    "lib/",
+    "lib/checkout.js",
+    "lib/config.js",
+    "lib/detect.js",
+    "lib/index-gen.js",
+    "lib/init.js",
+    "lib/inject.js",
+    "lib/mcp-server.js",
+    "lib/new-doc.js",
+    "lib/new-log.js",
+    "lib/search.js",
+    "lib/status.js",
+    "lib/templates.js",
     "templates/",
-    "hooks/",
+    "skills/",
     "README.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "keywords": [
@@ -29,6 +41,15 @@
     "type": "git",
     "url": "https://github.com/openclew/openclew"
   },
+  "author": "Raphaël Flambard <raphael@ralpha.fr>",
+  "contributors": [
+    "Adrien Cocuaud <adrien@ralpha.fr>",
+    "Victor Ripplinger"
+  ],
+  "homepage": "https://github.com/openclew/openclew#readme",
+  "bugs": {
+    "url": "https://github.com/openclew/openclew/issues"
+  },
   "engines": {
     "node": ">=16"
   }

package/skills/openclew-checkpoint/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: openclew-checkpoint
+description: End-of-session checkpoint. Summarizes git activity, creates a session log, and regenerates the doc index. Use at the end of a work session to persist what was done.
+user-invocable: true
+---
+
+# openclew checkpoint — End-of-session summary
+
+Run this at the end of a work session to capture what happened.
+
+## Command
+
+```bash
+npx openclew checkout
+```
+
+## What it does
+
+1. Collects today's git activity (commits, changed files, uncommitted changes)
+2. Displays a summary table
+3. Creates a session log in `doc/log/YYYY-MM-DD_<topic>.md`
+4. Regenerates `doc/_INDEX.md`
+
+## When to use
+
+- End of a coding session
+- After completing a feature or bug fix
+- Before switching to a different project
+- When you want to leave a trace for the next session (yours or someone else's)
+
+## Other useful commands
+
+- `npx openclew add ref "Title"` — Create a reference doc for lasting knowledge
+- `npx openclew add log "Title"` — Create a log manually (for mid-session notes)
+- `npx openclew status` — Health dashboard (missing briefs, stale docs)
+- `npx openclew search "query"` — Find docs by keyword

package/skills/openclew-init/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: openclew-init
+description: Set up openclew structured documentation in the current project. Creates doc/ with L1/L2/L3 knowledge base, auto-generated index, and injects context into your instruction file.
+user-invocable: true
+---
+
+# openclew init — Set up project knowledge
+
+Run this to add structured documentation to your project.
+
+## What it does
+
+1. Creates `doc/` and `doc/log/` directories
+2. Detects your existing instruction file (AGENTS.md, CLAUDE.md, .cursorrules, etc.)
+3. Injects a knowledge block so agents automatically consult project docs
+4. Creates starter docs: guide, architecture template, example log
+5. Generates `doc/_INDEX.md` (auto-rebuilt on every commit)
+6. Installs a git pre-commit hook for index regeneration
+
+## Command
+
+```bash
+npx openclew init
+```
+
+## Options
+
+- `--no-inject` — Skip injection into instruction file
+- `--no-hook` — Skip git hook installation
+
+## After setup
+
+Your agent will now read `doc/_INDEX.md` before starting tasks. To add knowledge:
+
+- `npx openclew add ref "Title"` — Create a reference doc (architecture, conventions, decisions)
+- `npx openclew add log "Title"` — Create a session log (frozen facts)
+- `npx openclew search "query"` — Search existing docs
+- `npx openclew checkout` — End-of-session summary
+
+## How it works with OpenClaw
+
+openclew handles **project knowledge** (what your project knows, what was decided, what happened).
+OpenClaw handles **agent identity** (personality, memory, tools, messaging).
+
+They're complementary:
+- OpenClaw's `MEMORY.md` = your agent's personal memory across all projects
+- openclew's `doc/` = this project's shared knowledge across all agents and sessions
+
+openclew injects into your project's `AGENTS.md` (or any instruction file). This doesn't conflict with OpenClaw's workspace `AGENTS.md` — they live in different locations.

package/skills/openclew-search/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: openclew-search
+description: Search project documentation by keyword. Searches L1 metadata (subject, doc_brief, category, keywords) across all refdocs and logs. Returns results sorted by relevance.
+user-invocable: true
+---
+
+# openclew search — Find relevant docs
+
+Search your project's knowledge base by keyword.
+
+## Command
+
+```bash
+npx openclew search "<query>"
+```
+
+## Examples
+
+```bash
+npx openclew search "auth"           # Find docs about authentication
+npx openclew search "API design"     # Multi-word search
+npx openclew search "bug"            # Find bug-related logs
+```
+
+## What it searches
+
+- **subject** (weight: 3×) — document title
+- **doc_brief** (weight: 2×) — one-line summary
+- **keywords** (weight: 2×) — tags
+- **category** (weight: 1.5×) — domain
+- **type** (weight: 1×) — Reference, Guide, Bug, Feature...
+- **status** (weight: 0.5×) — Active, Done, Archived...
+
+## Reading results
+
+Each result shows:
+- Icon: 📘 refdoc or 📝 log
+- Subject and status
+- File path (relative)
+- Brief description
+
+After finding a doc, read it at the level you need:
+- **L1** (between `L1_START`/`L1_END`) — subject + brief, ~40 tokens
+- **L2** (between `L2_START`/`L2_END`) — summary, essential context
+- **L3** (between `L3_START`/`L3_END`) — full details, only when deep-diving