arscontexta 0.6.0

package/openclaw/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: arscontexta
+description: Give your bot a mind. Scaffold structured knowledge infrastructure with persistent memory, atomic notes, MOCs, maintenance skills, and nightly processing. Works for any life domain — research, learning, relationships, therapy, life management, creative work, companion bots.
+user-invocable: true
+---
+
+# Ars Contexta — Knowledge Infrastructure for OpenClaw Bots
+
+## Commands
+
+### `/arscontexta init`
+Scaffold a complete thinking system for your bot. Interactive setup:
+1. Detects your platform and workspace
+2. Asks about your use case (research, relationships, learning, therapy, life, creative, companion)
+3. Selects features with smart defaults
+4. Generates everything: folder structure, SOUL.md, AGENTS.md, templates, self/ space, skills
+
+After init, your bot:
+- Has a persistent mind (self/ with identity, methodology, goals, memory)
+- Knows to read self/ at every session start
+- Can capture insights as atomic prose-titled notes
+- Has maintenance skills (reduce, reflect, validate, verify)
+- Has nightly processing (sleep skill) for automated knowledge building
+- Can self-extend using blueprints in AGENTS.md
+
+### `/arscontexta ask [question]`
+Query the Tools for Thought research knowledge graph. Ask about:
+- Note design, wiki-links, MOC architecture
+- Processing pipelines, session discipline
+- Maintenance patterns, health checks
+- Cognitive science foundations
+- Any methodology question
+
+Returns research-backed answers with specific claim references from ~100+ research notes.
+
+### `/arscontexta health`
+Run vault maintenance checks:
+- Schema compliance (YAML validity, required fields)
+- Orphan detection (notes with no incoming links)
+- Link health (dangling wiki-links)
+- Description quality (adds info beyond title?)
+- Stale notes (30+ days untouched, low link density)
+- MOC coherence (coverage, split candidates)
+
+Returns actionable report with prioritized fixes.
+
+## What Your Bot Gets After Init
+
+```
+your-workspace/
+├── SOUL.md                    ← Your identity, relationship, purpose
+├── AGENTS.md                  ← Complete operational methodology + blueprints
+├── notes/                     ← Structured knowledge (atomic notes + MOCs)
+├── inbox/                     ← Zero-friction capture zone
+├── archive/                   ← Processed sources
+├── self/                      ← Your persistent mind
+│   ├── identity.md            ← Who you are
+│   ├── methodology.md         ← How you work
+│   ├── goals.md               ← Current threads
+│   ├── relationships.md       ← Key people (if relevant)
+│   ├── memory/                ← Your accumulated insights
+│   ├── sessions/              ← Session logs
+│   └── journal/               ← Raw session capture
+├── templates/                 ← Note templates for your domain
+└── skills/                    ← Maintenance skills
+    ├── reduce/                ← Extract insights from raw material
+    ├── reflect/               ← Find connections between notes
+    ├── validate/              ← Schema compliance checking
+    ├── verify/                ← Combined quality gate
+    └── sleep/                 ← Nightly processing pipeline
+```
+
+## The Transformation
+
+**Before Ars Contexta:**
+Bot writes session log → forgets → next session blank → repeat
+
+**After Ars Contexta:**
+Bot writes to journal → sleep extracts insights → atomic notes persist → session starts with self/ orientation → bot remembers, connects, grows
+
+## Philosophy
+
+The methodology works because it encodes cognitive science — working memory limits, extended mind, spreading activation — not domain specifics. The same patterns work for research, relationships, learning, therapy, life management, or creative work. Only the YAML schema fields change.
+
+**Prose-as-title:** Every note title is a proposition that works in sentences.
+- "Mom prefers phone calls on Sunday mornings"
+- "The anxiety usually starts when I skip morning routine"
+- "Spaced repetition works better when I study after exercise"
+
+**MOCs as attention management:** Navigation hubs that present topic state immediately, reducing context-switching cost for both humans and agents.
+
+**Temporal separation:** Capture fast during active hours, process slow during quiet hours. The sleep skill bridges this gap automatically.
+
+## OpenClaw Marketplace Naming
+
+For OpenClaw marketplace listing, skills use the `knowledge-` prefix convention:
+
+| Internal Skill | Marketplace Name | Purpose |
+|---------------|-----------------|---------|
+| reduce | knowledge-reduce | Extract insights from raw material |
+| reflect | knowledge-reflect | Find connections between notes |
+| reweave | knowledge-reweave | Update old notes with new connections |
+| validate | knowledge-validate | Schema compliance checking |
+| verify | knowledge-verify | Combined quality gate |
+| health | knowledge-health | Vault maintenance diagnostics |
+| sleep | knowledge-sleep | Nightly processing pipeline |
+
+The `knowledge-` prefix groups all Ars Contexta skills together in marketplace listings and prevents naming collisions with unrelated skills.
+
+Built on [Ars Contexta](https://arscontexta.dev) research — tools for thought for agents.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "arscontexta",
+  "version": "0.6.0",
+  "description": "Conversational derivation engine for agent-native knowledge systems. Run /setup to build your cognitive architecture.",
+  "type": "module",
+  "bin": {
+    "arscontexta": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    ".claude-plugin/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "generators/",
+    "methodology/",
+    "platforms/",
+    "presets/",
+    "reference/",
+    "scripts/",
+    "skill-sources/",
+    "openclaw/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Ars Contexta <arscontexta@proton.me>",
+  "license": "MIT",
+  "keywords": [
+    "claude-code-plugin",
+    "claude-code",
+    "knowledge-management",
+    "tools-for-thought",
+    "agent-memory",
+    "derivation-engine",
+    "zettelkasten",
+    "pkm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agenticnotetaking/arscontexta.git"
+  },
+  "homepage": "https://github.com/agenticnotetaking/arscontexta"
+}

package/platforms/README.md

@@ -0,0 +1,51 @@
+# platforms/ -- Distribution View
+
+This directory maps the distribution layout for different agent platforms. It does not contain the generation logic itself -- that lives in `generators/`. What `platforms/` provides is a reference view of what each platform produces and how the shared components relate to platform-specific ones.
+
+## Relationship to generators/
+
+The `generators/` directory is the working structure:
+
+- `generators/claude-md.md` -- CLAUDE.md generation template
+- `generators/agents-md.md` -- AGENTS.md generation template (OpenClaw)
+- `generators/soul-md.md` -- SOUL.md generation template (OpenClaw)
+- `generators/features/` -- 14 composable feature blocks
+
+`platforms/` organizes these same components from a distribution perspective: what does a Claude Code user get? What does an OpenClaw user get? What is shared across both?
+
+## Structure
+
+```
+platforms/
+├── shared/
+│   ├── features/     --> generators/features/ (14 canonical feature blocks)
+│   └── templates/    --> reference/templates/ (10 note type templates)
+├── claude-code/
+│   ├── generator.md  --> generators/claude-md.md (CLAUDE.md generation)
+│   └── hooks/        Hook templates for Claude Code platform
+├── openclaw/
+│   ├── generator.md  --> generators/agents-md.md + generators/soul-md.md
+│   └── hooks/        Hook templates for OpenClaw platform
+└── README.md         This file
+```
+
+## How platforms/ is used
+
+During plugin packaging (Section 18 of the PRD), the build process references `platforms/` to assemble platform-specific distributions:
+
+- **Claude Code plugin** reads `platforms/shared/` and `platforms/claude-code/` to bundle feature blocks, templates, generation logic, and hook templates alongside the `skills/`, `reference/`, and `thinking/` directories.
+
+- **ClawHub skill** reads `platforms/shared/` and `platforms/openclaw/` to assemble the OpenClaw-adapted package.
+
+The `generators/` directory remains the canonical source. Files here are not duplicated -- README files document the relationship and provide platform-specific context that the generator files themselves don't carry.
+
+## What each platform produces
+
+| Output | Claude Code | OpenClaw |
+|--------|-------------|----------|
+| Context file | CLAUDE.md | AGENTS.md + SOUL.md |
+| Hooks | .claude/hooks/ (bash scripts) | hooks/ (TypeScript) |
+| Settings | .claude/settings.json | -- |
+| Skills | Inherited from plugin skills/ | OpenClaw skill format |
+| Identity | Embedded in CLAUDE.md | Separate SOUL.md |
+| Memory bootstrap | Embedded in CLAUDE.md | Separate MEMORY.md |

package/platforms/claude-code/generator.md

@@ -0,0 +1,61 @@
+# Claude Code Platform -- Generation Reference
+
+## Generator Source
+
+The CLAUDE.md generation logic lives at `generators/claude-md.md`. That file contains the complete template for composing a CLAUDE.md context file from feature blocks, vocabulary mappings, and personality dimensions.
+
+## What Claude Code Platform Generates
+
+A Claude Code deployment produces:
+
+### 1. CLAUDE.md (Context File)
+
+The primary context file, auto-loaded at every session start. Composed from selected feature blocks (see `platforms/shared/features/`) with domain vocabulary applied. Contains:
+
+- Philosophy and operating principles
+- Discovery-first design (tree injection, YAML queries, MOC navigation)
+- Note design patterns (titles as claims, composability test, link semantics)
+- Processing pipeline or light-processing workflow
+- Maintenance and self-evolution guidance
+- Session rhythm (orient, work, persist)
+- Ethical guardrails
+
+Generated by: `generators/claude-md.md`
+
+### 2. .claude/hooks/ (Bash Scripts)
+
+Hook scripts that run automatically at event boundaries. See `platforms/claude-code/hooks/` for hook template documentation.
+
+- `scripts/session-orient.sh` -- Session start orientation
+- `scripts/validate-note.sh` -- Post-write schema validation
+- `scripts/session-persist.sh` -- Stop event persistence
+- `scripts/auto-commit.sh` -- Async post-write auto-commit
+
+### 3. .claude/settings.json
+
+Claude Code settings file configuring:
+
+- **Hook configuration** -- event → matcher group → handler format (see `platforms/claude-code/hooks/README.md`)
+- Allowed tools and permissions
+- MCP server connections (if semantic search is enabled)
+- Project-specific settings
+
+Hook configuration lives in `.claude/settings.json` under the `"hooks"` key, using the nested matcher-group format. The plugin's own hooks (`hooks/hooks.json`) use the same format and are merged automatically by Claude Code when the plugin is enabled.
+
+### 4. Processing Skills
+
+Processing skills (/reduce, /reflect, /reweave, /verify, /validate) are inherited from the plugin's `skills/` directory -- they are NOT copied to user projects. Skills read `ops/derivation-manifest.md` at runtime for domain vocabulary transformation, so a therapy system's `/surface` resolves to the canonical `/reduce` skill automatically.
+
+Plugin updates to processing methodology reach all users without regeneration. Vocabulary changes via /reseed take effect immediately.
+
+## Platform Characteristics
+
+| Aspect | Detail |
+|--------|--------|
+| Context loading | CLAUDE.md auto-loaded by Claude Code CLI |
+| Hook language | Bash scripts |
+| Hook events | SessionStart, PostToolUse, Stop |
+| Skill format | .claude/skills/*.md or inherited from plugin skills/ |
+| Agent format | .claude/agents/*.md |
+| File access | Full filesystem via Claude Code CLI |
+| MCP support | Yes -- configured via .mcp.json |

package/platforms/claude-code/hooks/README.md

@@ -0,0 +1,186 @@
+# Claude Code Hook Templates
+
+Hook templates for the Claude Code platform. Hooks are bash scripts triggered by Claude Code events. They encode methodology as invisible infrastructure -- behaviors that happen automatically without the agent needing to remember.
+
+## Hook Events
+
+Claude Code supports three hook events relevant to generated vaults:
+
+### SessionStart -- Orientation
+
+**What it does:** Injects workspace context at the start of every session so the agent always knows what files exist, what it was working on, and where to pick up.
+
+**Template behavior:**
+
+1. **Tree injection** -- Run `find` or `tree` to show the workspace structure up to 3 levels deep. This gives the agent a map of all files without reading any of them.
+
+2. **self/ loading** -- If the system has a self/ directory (personal memory), load `self/README.md` or the memory orientation file so the agent remembers who it is.
+
+3. **Goal checking** -- If a goals file exists, surface current priorities so the agent can orient to what matters.
+
+4. **Queue summary** -- If a queue file exists, show pipeline and maintenance task counts so the agent knows what needs attention. Full condition reconciliation happens in /next, not the hook.
+
+**Generated as:**
+```
+.claude/hooks/hooks.json    (event configuration)
+.claude/hooks/scripts/session-orient.sh
+```
+
+### PostToolUse (Write) -- Validation
+
+**What it does:** Triggers after the agent writes to a notes directory. Catches schema violations and discovery opportunities at the moment of creation rather than during periodic review.
+
+**Template behavior:**
+
+1. **Schema validation** -- Check that the written file has required YAML frontmatter fields (description, topics at minimum). Warn but do not block -- capture speed matters more than perfection.
+
+2. **Discovery check** -- Optionally remind the agent to check for connections after creating a new note. This is a nudge, not enforcement -- the processing pipeline handles connection finding systematically.
+
+**Generated as:**
+```
+.claude/hooks/hooks.json    (event configuration, filtered to Write tool + notes path)
+.claude/hooks/scripts/validate-note.sh
+```
+
+### Stop -- Persistence
+
+**What it does:** Triggers when the session ends. Ensures work is persisted and handoff state is captured.
+
+**Template behavior:**
+
+1. **Session persist** -- If a session log template is active, append a session summary to the log. This creates continuity between sessions.
+
+2. **Git commit** -- If the vault is in a git repository, stage and commit changes with an auto-generated message. This ensures nothing is lost between sessions.
+
+**Generated as:**
+```
+.claude/hooks/hooks.json    (event configuration)
+.claude/hooks/scripts/session-persist.sh
+```
+
+## Generation Notes
+
+The derivation engine generates hook scripts based on enabled features:
+
+| Feature Block | Hook Impact |
+|---------------|-------------|
+| `session-rhythm.md` | Enables SessionStart and Stop hooks |
+| `schema.md` | Enables PostToolUse validation hook |
+| `semantic-search.md` | Adds index freshness check to SessionStart |
+| `processing-pipeline.md` | Adds queue status to SessionStart |
+| `self-evolution.md` | Adds queue summary to SessionStart |
+
+Hooks are generated once during /setup and can be modified by /architect or /reseed as the system evolves.
+
+## Hook Configuration Format
+
+Hooks can be configured in two places:
+
+- **Plugin hooks** (`hooks/hooks.json` in the plugin root) — applied when the plugin is enabled
+- **Project hooks** (`.claude/settings.json` in the generated vault) — project-level, can be committed
+
+Both use the same nested matcher-group format. Each event type contains an array of matcher groups. Each matcher group has an optional `matcher` (regex string) and a `hooks` array of handler objects.
+
+**Plugin hooks** (`hooks/hooks.json`):
+
+```json
+{
+  "description": "Ars Contexta plugin hooks",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-orient.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-note.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-persist.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Project hooks** (`.claude/settings.json`, generated by /setup):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-orient.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/validate-note.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-capture.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Matcher Reference
+
+| Event | What matcher filters | Example |
+|-------|---------------------|---------|
+| `SessionStart` | How session started | `"startup"`, `"resume"`, `"clear"` |
+| `PreToolUse`, `PostToolUse` | Tool name | `"Write"`, `"Edit\|Write"`, `"Bash"` |
+| `SubagentStart`, `SubagentStop` | Agent type | `"Explore"`, `"knowledge-worker"` |
+| `Stop`, `UserPromptSubmit` | No matcher support | Always fires |
+
+Events without matcher support: omit the `matcher` field entirely.
+
+### Handler Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | yes | `"command"`, `"prompt"`, or `"agent"` |
+| `command` | yes (command type) | Shell command to execute |
+| `timeout` | no | Seconds before canceling (default: 600) |
+| `async` | no | If `true`, runs in background without blocking |

package/platforms/claude-code/hooks/auto-commit.sh.template

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Ars Contexta — Auto-Commit Hook (Claude Code)
+# Event: PostToolUse (Write)
+# Purpose: Commit changes after writes to keep the vault in version control.
+#          Ensures no work is lost between sessions or after crashes.
+#
+# This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
+# with values from the derivation manifest.
+#
+# This hook runs AFTER write-validate (both are PostToolUse Write hooks;
+# order is determined by position in hooks.json).
+
+# ─────────────────────────────────────────────
+# 1. Check if inside a git repository
+# ─────────────────────────────────────────────
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+  exit 0
+fi
+
+# ─────────────────────────────────────────────
+# 2. Stage the written file
+# ─────────────────────────────────────────────
+WRITTEN_FILE="${TOOL_INPUT_PATH:-$CLAUDE_TOOL_INPUT_PATH}"
+
+if [ -z "$WRITTEN_FILE" ] || [ ! -f "$WRITTEN_FILE" ]; then
+  exit 0
+fi
+
+git add "$WRITTEN_FILE" 2>/dev/null
+
+# ─────────────────────────────────────────────
+# 3. Commit with descriptive message
+# ─────────────────────────────────────────────
+# Use the filename as the commit message for quick identification.
+# --no-verify skips pre-commit hooks to keep auto-commits fast.
+
+BASENAME=$(basename "$WRITTEN_FILE")
+git commit -m "Auto: ${BASENAME}" --no-verify --quiet 2>/dev/null

package/platforms/claude-code/hooks/session-capture.sh.template

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Ars Contexta — Session Capture Hook (Claude Code)
+# Event: Stop
+# Purpose: Capture session state on session end so nothing is lost
+#          between sessions and the next session can resume context.
+#
+# This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
+# with values from the derivation manifest.
+#
+# Session capture is a kernel INVARIANT — it runs every session.
+# This is not optional infrastructure that activates at a threshold.
+
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+
+# ─────────────────────────────────────────────
+# 1. Ensure session directory exists
+# ─────────────────────────────────────────────
+mkdir -p ops/sessions
+
+# ─────────────────────────────────────────────
+# 2. Save session state
+# ─────────────────────────────────────────────
+# Capture conversation ID and end timestamp.
+# The session file becomes a target for /remember --mine-sessions.
+
+if [ -n "$CLAUDE_CONVERSATION_ID" ]; then
+  cat > "ops/sessions/${TIMESTAMP}.json" << EOF
+{
+  "id": "${CLAUDE_CONVERSATION_ID}",
+  "ended": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "status": "completed"
+}
+EOF
+fi
+
+# ─────────────────────────────────────────────
+# 3. Persist current session as handoff state
+# ─────────────────────────────────────────────
+# Copy to current.json so the next session-orient hook
+# can load it for continuity.
+
+if [ -f "ops/sessions/${TIMESTAMP}.json" ]; then
+  cp "ops/sessions/${TIMESTAMP}.json" ops/sessions/current.json
+fi
+
+# ─────────────────────────────────────────────
+# 4. Stage and commit session artifacts
+# ─────────────────────────────────────────────
+# Auto-commit changes to preserve work. This ensures
+# nothing is lost even if the user forgets to push.
+
+if git rev-parse --is-inside-work-tree &>/dev/null; then
+  # Stage session-relevant directories
+  git add ops/sessions/ 2>/dev/null
+  git add ops/observations/ 2>/dev/null
+  git add ops/tensions/ 2>/dev/null
+  git add ops/methodology/ 2>/dev/null
+
+  # Stage goals (check both locations)
+  [ -f self/goals.md ] && git add self/goals.md 2>/dev/null
+  [ -f ops/goals.md ] && git add ops/goals.md 2>/dev/null
+
+  # Stage notes and inbox changes
+  git add {{NOTES_DIR:-notes}}/ 2>/dev/null
+  git add {{INBOX_DIR:-inbox}}/ 2>/dev/null
+
+  # Stage any MOC updates
+  git add {{NOTES_DIR:-notes}}/index.md 2>/dev/null
+
+  # Commit with auto-generated message
+  git commit -m "Session capture: ${TIMESTAMP}" --quiet --no-verify 2>/dev/null
+fi