@versatly/workgraph 0.1.0 → 0.3.0

package/README.md

@@ -1,19 +1,27 @@
-# @clawvault/workgraph
+# @versatly/workgraph
 
 Agent-first workgraph workspace for multi-agent collaboration.
 
-`@clawvault/workgraph` is the coordination core extracted from ClawVault. It focuses only on:
+`@versatly/workgraph` is the standalone coordination core for multi-agent execution. It focuses only on:
 
 - Dynamic primitive registry (`thread`, `space`, `decision`, `lesson`, `fact`, `agent`, plus custom types)
-- Append-only event ledger (`.clawvault/ledger.jsonl`)
-- Ledger claim index (`.clawvault/ledger-index.json`) for fast ownership queries
-- Tamper-evident ledger hash-chain (`.clawvault/ledger-chain.json`)
+- Append-only event ledger (`.workgraph/ledger.jsonl`)
+- Ledger claim index (`.workgraph/ledger-index.json`) for fast ownership queries
+- Tamper-evident ledger hash-chain (`.workgraph/ledger-chain.json`)
 - Markdown-native primitive store
 - Thread lifecycle coordination (claim/release/block/unblock/done/decompose)
 - Space-scoped thread scheduling (`--space`)
 - Generated markdown command center (`workgraph command-center`)
 - Native skill primitive lifecycle (`workgraph skill write/load/propose/promote`)
 - Primitive-registry manifest + auto-generated `.base` files
+- Orientation loop commands (`workgraph status/brief/checkpoint/intake`)
+- Multi-filter primitive query (`workgraph query ...`)
+- Core + QMD-compatible keyword search (`workgraph search ...`)
+- Obsidian Kanban board generation/sync (`workgraph board generate|sync`)
+- Wiki-link graph indexing and hygiene reports (`workgraph graph index|hygiene`)
+- Policy party registry and sensitive transition gates
+- Programmatic dispatch contract (`workgraph dispatch ...`) with explicit status transitions
+- Trigger dispatch bridge (`workgraph trigger fire ...`) with idempotency keying
 - JSON-friendly CLI for agent orchestration
 
 No memory-category scaffolding, no qmd dependency, no observational-memory pipeline.
@@ -21,13 +29,13 @@ No memory-category scaffolding, no qmd dependency, no observational-memory pipel
 ## Install
 
 ```bash
-npm install @clawvault/workgraph
+npm install @versatly/workgraph
 ```
 
 Or global CLI:
 
 ```bash
-npm install -g @clawvault/workgraph
+npm install -g @versatly/workgraph
 ```
 
 ## Agent-first CLI
@@ -51,6 +59,24 @@ workgraph thread create "Ship command center" \
   --json
 
 workgraph thread next --claim --actor agent-worker --json
+workgraph status --json
+workgraph brief --actor agent-worker --json
+workgraph query --type thread --status open --limit 10 --json
+workgraph search "auth" --mode auto --json
+workgraph checkpoint "Completed API layer" --next "implement tests" --actor agent-worker --json
+workgraph board generate --output "ops/Workgraph Board.md" --json
+workgraph graph hygiene --json
+workgraph graph neighbors context-nodes/context-node-1 --json
+workgraph dispatch create "Review blockers" --actor agent-lead --json
+workgraph dispatch mark run_123 --status succeeded --output "Review complete" --actor agent-lead --json
+workgraph dispatch create-execute "Close all ready threads in platform space" \
+  --actor agent-lead \
+  --agents agent-a,agent-b,agent-c \
+  --space spaces/platform \
+  --json
+workgraph trigger fire triggers/escalate-blocked.md --event-key "thread-blocked-001" --actor agent-lead --json
+workgraph onboarding update onboarding/onboarding-for-agent-architect.md --status paused --actor agent-lead --json
+workgraph mcp serve -w /path/to/workspace --actor agent-ops --read-only
 workgraph ledger show --count 20 --json
 workgraph command-center --output "ops/Command Center.md" --json
 workgraph bases generate --refresh-registry --json
@@ -65,6 +91,38 @@ All commands support `--json` and emit:
 
 This is intended for robust parsing by autonomous agents.
 
+### Monorepo layout (MVP)
+
+The repository is now organized as a workspaces monorepo while preserving the
+published `@versatly/workgraph` package compatibility surface.
+
+Key workspace packages:
+
+- `packages/kernel`
+- `packages/cli`
+- `packages/sdk`
+- `packages/control-api`
+- `packages/runtime-adapter-core`
+- `packages/adapter-cursor-cloud`
+- `packages/policy`
+- `packages/testkit`
+- `packages/search-qmd-adapter`
+- `packages/obsidian-integration`
+- `packages/skills`
+
+Migration notes: see `docs/MIGRATION.md`.
+
+### Demo vault generator
+
+Generate the large Obsidian demo workspace used for stress-testing:
+
+```bash
+npm run demo:workspace
+npm run demo:obsidian-setup
+```
+
+Runbook: `docs/OBSIDIAN_DEMO.md`.
+
 ### Space-scoped scheduling
 
 ```bash
@@ -81,7 +139,7 @@ workgraph thread next --space spaces/backend --claim --actor agent-api --json
 ### Auto-generate `.base` files from primitive registry
 
 ```bash
-# Sync .clawvault/primitive-registry.yaml
+# Sync .workgraph/primitive-registry.yaml
 workgraph bases sync-registry --json
 
 # Generate canonical primitive .base files
@@ -114,11 +172,36 @@ workgraph skill write "workgraph-manual" \
 workgraph skill propose workgraph-manual --actor agent-reviewer --space spaces/platform --json
 workgraph skill promote workgraph-manual --actor agent-lead --json
 workgraph skill load workgraph-manual --json
+workgraph skill list --updated-since 2026-02-27T00:00:00.000Z --json
+workgraph skill history workgraph-manual --limit 10 --json
+workgraph skill diff workgraph-manual --json
+```
+
+### Optional Clawdapus integration
+
+List supported optional integrations:
+
+```bash
+workgraph integration list --json
+```
+
+Install by integration ID (extensible pattern for future integrations):
+
+```bash
+workgraph integration install clawdapus \
+  --actor agent-architect \
+  --json
+```
+
+Refresh from upstream later (or use the `integration clawdapus` alias):
+
+```bash
+workgraph integration install clawdapus --force --actor agent-architect --json
 ```
 
-## ClawVault memory vs Workgraph primitives (split clarification)
+## Legacy memory stacks vs Workgraph primitives
 
-`@clawvault/workgraph` is **execution coordination only**.
+`@versatly/workgraph` is **execution coordination only**.
 
 - Use it for: ownership, decomposition, dependency management, typed coordination primitives.
 - Do not use it for: long-term memory categories (`decisions/`, `people/`, `projects/` memory workflows), qmd semantic retrieval pipelines, observer/reflector memory compression.
@@ -141,7 +224,7 @@ This split keeps the workgraph package focused, portable, and shell-agent-native
 ## Programmatic API
 
 ```ts
-import { registry, thread, store, ledger, workspace } from '@clawvault/workgraph';
+import { registry, thread, store, ledger, workspace } from '@versatly/workgraph';
 
 workspace.initWorkspace('/tmp/wg');
 

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: workgraph
 version: "0.1.0"
-description: Agent-first multi-agent coordination skill for markdown-native workgraph workspaces. Use when coordinating threads, ownership, dependencies, and custom primitive schemas across multiple agents. Do not use for general long-term memory capture; this package intentionally excludes ClawVault memory scaffolding.
+description: Agent-first multi-agent coordination skill for markdown-native workgraph workspaces. Use when coordinating threads, ownership, dependencies, and custom primitive schemas across multiple agents. Do not use for general long-term memory capture; this package intentionally excludes legacy memory scaffolding.
 author: Versatly
-source: https://github.com/Versatly/clawvault/tree/main/packages/workgraph
+source: https://github.com/Versatly/workgraph
 user-invocable: true
 ---
 
@@ -23,12 +23,12 @@ Use workgraph to coordinate execution, not to hoard generic memory.
 A workgraph workspace contains:
 
 - `.workgraph.json` — workspace identity and mode.
-- `.clawvault/registry.json` — primitive type definitions.
-- `.clawvault/ledger.jsonl` — append-only event stream.
-- `.clawvault/ledger-index.json` — derived claim snapshot for fast ownership checks.
-- `.clawvault/ledger-chain.json` — tamper-evident hash-chain state.
-- `.clawvault/primitive-registry.yaml` — canonical primitive registry manifest.
-- `.clawvault/bases/*.base` — generated Obsidian Bases files.
+- `.workgraph/registry.json` — primitive type definitions.
+- `.workgraph/ledger.jsonl` — append-only event stream.
+- `.workgraph/ledger-index.json` — derived claim snapshot for fast ownership checks.
+- `.workgraph/ledger-chain.json` — tamper-evident hash-chain state.
+- `.workgraph/primitive-registry.yaml` — canonical primitive registry manifest.
+- `.workgraph/bases/*.base` — generated Obsidian Bases files.
 - Primitive directories (e.g. `threads/`, `spaces/`, `agents/`, custom directories).
 
 Initialize once:
@@ -298,7 +298,7 @@ If your agents currently use broad memory categories for execution coordination:
 
 ## Split Clarification
 
-- `clawvault` package: memory + retrieval + broader vault lifecycle.
-- `@clawvault/workgraph` package: coordination substrate only.
+- legacy memory packages: memory + retrieval + broader vault lifecycle.
+- `@versatly/workgraph`: coordination substrate only.
 
 Treat this package as the authoritative runtime for multi-agent primitives and claims, not as a memory taxonomy tool.