workgraph

Category: Tools & Productivity | Uploader: Versatly | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/Versatly/workgraph

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 531 B
  - 📄 notify-pr.yml 702 B
📁 apps/
- 📁 web-control-plane/
  - 📄 app.js 1.4 KB
  - 📄 autonomy-health.html 584 B
  - 📄 federation-status.html 590 B
  - 📄 index.html 1.6 KB
  - 📄 mission-progress.html 587 B
  - 📄 package.json 115 B
  - 📄 README.md 113 B
  - 📄 risk-dashboard.html 581 B
  - 📄 run-health.html 569 B
  - 📄 style.css 733 B
  - 📄 transport-health.html 587 B
  - 📄 trigger-health.html 581 B
📁 bin/
- 📄 workgraph.js 47 B
📁 docs/
- 📄 ARCHITECTURE_ROADMAP.md 7.1 KB
- 📄 INVARIANT_REPAIR_PLAYBOOK.md 4.0 KB
- 📄 MCP_V2_COLLABORATION_PROTOCOL.md 3.3 KB
- 📄 MIGRATION.md 1.4 KB
- 📄 OBSIDIAN_DEMO.md 1.1 KB
- 📄 PACKAGE_BOUNDARIES.md 3.2 KB
- 📄 PRD.md 9.4 KB
- 📄 SSE_EVENTS.md 1.8 KB
- 📄 VISION.md 15.6 KB
📁 examples/
- 📁 multi-agent-showcase/
  - 📁 scripts/
    
    📁 lib/
    
    📄 demo-utils.mjs 3.7 KB
    
    📄 01-governance.mjs 4.4 KB
    
    📄 02-collaboration.mjs 11.7 KB
    
    📄 03-trigger-loop.mjs 6.5 KB
    
    📄 run-showcase.mjs 4.9 KB
  - 📄 README.md 2.7 KB
  - 📄 run.mjs 389 B
  - 📄 run.sh 1.2 KB
📁 packages/
- 📁 adapter-claude-code/
  - 📁 src/
    
    📄 adapter.ts 4.1 KB
    
    📄 index.ts 30 B
  - 📄 package.json 389 B
  - 📄 tsconfig.json 141 B
- 📁 adapter-cursor-cloud/
  - 📁 src/
    
    📄 adapter.test.ts 4.4 KB
    
    📄 adapter.ts 20.7 KB
    
    📄 index.ts 30 B
  - 📄 package.json 376 B
  - 📄 tsconfig.json 141 B
- 📁 adapter-http-webhook/
  - 📁 src/
    
    📄 adapter.ts 7.7 KB
    
    📄 index.ts 30 B
  - 📄 package.json 327 B
  - 📄 tsconfig.json 141 B
- 📁 adapter-shell-worker/
  - 📁 src/
    
    📄 adapter.ts 7.5 KB
    
    📄 index.ts 30 B
  - 📄 package.json 390 B
  - 📄 tsconfig.json 189 B
- 📁 cli/
  - 📁 src/
    
    📁 cli/
    
    📁 commands/
    
    📄 adapter.ts 4.5 KB
    
    📄 autonomy.ts 6.8 KB
    
    📄 capability.ts 6.0 KB
    
    📄 conversation.ts 14.1 KB
    
    📄 cursor.ts 8.8 KB
    
    📄 dispatch.ts 14.2 KB
    
    📄 federation.ts 4.8 KB
    
    📄 mcp.ts 937 B
    
    📄 mission.ts 11.7 KB
    
    📄 portability.ts 2.7 KB
    
    📄 safety.ts 4.9 KB
    
    📄 trigger.ts 19.5 KB
    
    📄 webhook.ts 9.1 KB
    
    📄 core.ts 8.8 KB
    
    📄 cli.ts 89.6 KB
    
    📄 index.ts 19 B
  - 📄 package.json 488 B
  - 📄 tsconfig.json 141 B
- 📁 control-api/
  - 📁 src/
    
    📄 dispatch.ts 911 B
    
    📄 index.ts 139 B
    
    📄 server-entry.ts 353 B
    
    📄 server-events.test.ts 5.5 KB
    
    📄 server-events.ts 10.4 KB
    
    📄 server-lenses.ts 13.0 KB
    
    📄 server-projections.test.ts 2.5 KB
    
    📄 server-projections.ts 2.3 KB
    
    📄 server-webhooks.test.ts 2.8 KB
    
    📄 server-webhooks.ts 8.3 KB
    
    📄 server.test.ts 22.0 KB
    
    📄 server.ts 30.5 KB
    
    📄 webhook-gateway.test.ts 11.6 KB
    
    📄 webhook-gateway.ts 35.9 KB
  - 📄 package.json 357 B
  - 📄 tsconfig.json 141 B
- 📁 kernel/
  - 📁 src/
    
    📁 __snapshots__/
    
    📄 context-graph-contract.test.ts.snap 9.9 KB
    
    📄 schema-drift-regression.test.ts.snap 65.7 KB
    
    📁 diagnostics/
    
    📄 changelog.ts 5.4 KB
    
    📄 doctor.ts 17.9 KB
    
    📄 format.ts 2.1 KB
    
    📄 index.ts 173 B
    
    📄 primitives.ts 9.2 KB
    
    📄 render.ts 2.7 KB
    
    📄 replay.ts 5.9 KB
    
    📄 stats.ts 5.2 KB
    
    📄 viz.ts 7.2 KB
    
    📁 dispatch/
    
    📄 external-run-state.ts 12.3 KB
    
    📁 graph/
    
    📄 hygiene.ts 50 B
    
    📄 wiki-index.ts 101 B
    
    📁 orientation/
    
    📄 brief.ts 59 B
    
    📄 checkpoint.ts 56 B
    
    📄 lens.ts 100 B
    
    📄 status.ts 52 B
    
    📁 projections/
    
    📄 autonomy-health.ts 933 B
    
    📄 federation-status.ts 1.0 KB
    
    📄 index.ts 291 B
    
    📄 mission-progress.ts 1.1 KB
    
    📄 projections.test.ts 3.6 KB
    
    📄 risk-dashboard.ts 1.3 KB
    
    📄 run-health.ts 1.7 KB
    
    📄 transport-health.ts 1.5 KB
    
    📄 trigger-health.ts 984 B
    
    📄 types.ts 514 B
    
    📁 query/
    
    📄 engine.ts 62 B
    
    📄 filters.ts 58 B
    
    📁 search/
    
    📄 keyword.ts 45 B
    
    📁 transport/
    
    📄 _shared.ts 3.8 KB
    
    📄 dead-letter.ts 4.8 KB
    
    📄 envelope.ts 4.2 KB
    
    📄 inbox.ts 4.3 KB
    
    📄 index.ts 122 B
    
    📄 outbox.ts 6.8 KB
    
    📄 transport.test.ts 3.7 KB
    
    📁 validation/
    
    📄 schema.ts 46 B
    
    📄 adapter-claude-code.test.ts 6.3 KB
    
    📄 adapter-claude-code.ts 78 B
    
    📄 adapter-cursor-cloud.ts 80 B
    
    📄 adapter-http-webhook.test.ts 7.9 KB
    
    📄 adapter-http-webhook.ts 80 B
    
    📄 adapter-shell-worker.test.ts 6.2 KB
    
    📄 adapter-shell-worker.ts 80 B
    
    📄 adapters.test.ts 3.5 KB
    
    📄 agent-self-assembly.test.ts 6.9 KB
    
    📄 agent-self-assembly.ts 13.2 KB
    
    📄 agent.test.ts 8.7 KB
    
    📄 agent.ts 28.7 KB
    
    📄 auth.ts 22.6 KB
    
    📄 autonomy-daemon.test.ts 2.3 KB
    
    📄 autonomy-daemon.ts 9.1 KB
    
    📄 autonomy.test.ts 1.9 KB
    
    📄 autonomy.ts 5.8 KB
    
    📄 bases.test.ts 2.6 KB
    
    📄 bases.ts 4.4 KB
    
    📄 board.test.ts 4.7 KB
    
    📄 board.ts 4.8 KB
    
    📄 capability.test.ts 5.8 KB
    
    📄 capability.ts 10.7 KB
    
    📄 claim-lease.test.ts 4.8 KB
    
    📄 claim-lease.ts 10.3 KB
    
    📄 clawdapus.test.ts 2.8 KB
    
    📄 clawdapus.ts 1.2 KB
    
    📄 command-center.test.ts 2.8 KB
    
    📄 command-center.ts 5.2 KB
    
    📄 context-graph-contract-definitions.ts 8.5 KB
    
    📄 context-graph-contract.test.ts 2.1 KB
    
    📄 context-graph-contract.ts 7.2 KB
    
    📄 conversation.test.ts 7.0 KB
    
    📄 conversation.ts 35.5 KB
    
    📄 coordination.test.ts 8.2 KB
    
    📄 cron.test.ts 1.4 KB
    
    📄 cron.ts 5.8 KB
    
    📄 cursor-bridge.test.ts 6.0 KB
    
    📄 cursor-bridge.ts 24.6 KB
    
    📄 diagnostics.test.ts 7.8 KB
    
    📄 dispatch-evidence-loop.test.ts 5.6 KB
    
    📄 dispatch-run-audit.ts 2.4 KB
    
    📄 dispatch-run-evidence.ts 8.3 KB
    
    📄 dispatch.test.ts 13.1 KB
    
    📄 dispatch.ts 91.5 KB
    
    📄 environment.test.ts 2.0 KB
    
    📄 environment.ts 3.2 KB
    
    📄 errors.ts 3.0 KB
    
    📄 evidence.test.ts 5.9 KB
    
    📄 evidence.ts 7.7 KB
    
    📄 export-import.test.ts 3.4 KB
    
    📄 export-import.ts 5.3 KB
    
    📄 federation-helpers.ts 6.9 KB
    
    📄 federation-resolve.test.ts 6.5 KB
    
    📄 federation.test.ts 5.2 KB
    
    📄 federation.ts 29.6 KB
    
    📄 fs-reliability.ts 3.9 KB
    
    📄 gate-hardening.test.ts 6.2 KB
    
    📄 gate.test.ts 3.7 KB
    
    📄 gate.ts 12.5 KB
    
    📄 graph-board.test.ts 3.0 KB
    
    📄 graph-intelligence.test.ts 7.3 KB
    
    📄 graph.test.ts 7.3 KB
    
    📄 graph.ts 27.4 KB
    
    📄 index.ts 3.9 KB
    
    📄 intake.test.ts 3.6 KB
    
    📄 intake.ts 3.0 KB
    
    📄 integration-core.test.ts 4.7 KB
    
    📄 integration-core.ts 3.5 KB
    
    📄 integration.test.ts 1.7 KB
    
    📄 integration.ts 1.7 KB
    
    📄 ledger.test.ts 7.6 KB
    
    📄 ledger.ts 14.5 KB
    
    📄 lens.test.ts 6.5 KB
    
    📄 lens.ts 20.9 KB
    
    📄 mcp-events.test.ts 7.6 KB
    
    📄 mcp-events.ts 7.5 KB
    
    📄 mission-orchestrator.test.ts 4.2 KB
    
    📄 mission-orchestrator.ts 20.3 KB
    
    📄 mission.test.ts 6.9 KB
    
    📄 mission.ts 32.4 KB
    
    📄 onboard.test.ts 2.2 KB
    
    📄 onboard.ts 5.1 KB
    
    📄 orientation.test.ts 8.0 KB
    
    📄 orientation.ts 7.4 KB
    
    📄 policy-dispatch.test.ts 11.3 KB
    
    📄 policy.test.ts 4.4 KB
    
    📄 policy.ts 4.7 KB
    
    📄 query-orientation.test.ts 2.5 KB
    
    📄 query.test.ts 4.8 KB
    
    📄 query.ts 3.4 KB
    
    📄 reconciler-runs.test.ts 6.7 KB
    
    📄 reconciler.test.ts 5.6 KB
    
    📄 reconciler.ts 9.6 KB
    
    📄 registry.test.ts 5.2 KB
    
    📄 registry.ts 29.2 KB
    
    📄 runtime-adapter-contracts.test.ts 2.7 KB
    
    📄 runtime-adapter-contracts.ts 3.3 KB
    
    📄 runtime-adapter-registry.test.ts 2.4 KB
    
    📄 runtime-adapter-registry.ts 939 B
    
    📄 safety.test.ts 7.1 KB
    
    📄 safety.ts 22.7 KB
    
    📄 schema-drift-regression.test.ts 4.6 KB
    
    📄 search-qmd-adapter.test.ts 2.7 KB
    
    📄 search-qmd-adapter.ts 2.0 KB
    
    📄 server-config.ts 7.2 KB
    
    📄 skill.test.ts 6.4 KB
    
    📄 skill.ts 9.3 KB
    
    📄 starter-kit.ts 14.0 KB
    
    📄 storage-adapter.test.ts 1.7 KB
    
    📄 storage-adapter.ts 2.9 KB
    
    📄 store.test.ts 9.9 KB
    
    📄 store.ts 21.7 KB
    
    📄 swarm.test.ts 5.9 KB
    
    📄 swarm.ts 15.2 KB
    
    📄 thread-audit.test.ts 1.7 KB
    
    📄 thread-audit.ts 6.2 KB
    
    📄 thread-context.test.ts 4.6 KB
    
    📄 thread-context.ts 15.5 KB
    
    📄 thread-hardening.test.ts 9.7 KB
    
    📄 thread-participants.test.ts 4.2 KB
    
    📄 thread.test.ts 15.3 KB
    
    📄 thread.ts 45.1 KB
    
    📄 trigger-engine.test.ts 26.4 KB
    
    📄 trigger-engine.ts 74.7 KB
    
    📄 trigger-run-evidence-loop.test.ts 4.8 KB
    
    📄 trigger.test.ts 7.6 KB
    
    📄 trigger.ts 18.3 KB
    
    📄 types.ts 13.9 KB
    
    📄 validation.ts 2.7 KB
    
    📄 workspace-structure.test.ts 1.8 KB
    
    📄 workspace.test.ts 5.6 KB
    
    📄 workspace.ts 8.0 KB
  - 📄 package.json 381 B
  - 📄 tsconfig.json 348 B
- 📁 mcp-server/
  - 📁 src/
    
    📁 mcp/
    
    📁 tools/
    
    📄 collaboration-tools.ts 43.7 KB
    
    📄 read-tools.ts 20.1 KB
    
    📄 write-tools.ts 46.4 KB
    
    📄 auth.ts 1.5 KB
    
    📄 resources.ts 1.6 KB
    
    📄 result.ts 4.6 KB
    
    📄 types.ts 156 B
    
    📄 federation-tools.test.ts 4.8 KB
    
    📄 index.ts 71 B
    
    📄 mcp-http-server.test.ts 6.8 KB
    
    📄 mcp-http-server.ts 9.5 KB
    
    📄 mcp-server.test.ts 29.2 KB
    
    📄 mcp-server.ts 1.5 KB
    
    📄 projection-tools.test.ts 3.1 KB
    
    📄 transport-tools.test.ts 7.1 KB
  - 📄 package.json 368 B
  - 📄 tsconfig.json 141 B
- 📁 obsidian-integration/
  - 📁 src/
    
    📁 graph/
    
    📄 health.ts 119 B
    
    📁 kanban/
    
    📄 render.ts 51 B
    
    📄 sync.ts 47 B
    
    📄 bases.ts 4.4 KB
    
    📄 board.ts 4.8 KB
    
    📄 index.ts 332 B
  - 📄 package.json 335 B
  - 📄 tsconfig.json 141 B
- 📁 policy/
  - 📁 src/
    
    📄 contracts.ts 201 B
    
    📄 gates.ts 1.5 KB
    
    📄 index.ts 119 B
    
    📄 policy-registry.test.ts 1.9 KB
    
    📄 registry.ts 2.3 KB
    
    📄 types.ts 230 B
  - 📄 package.json 226 B
  - 📄 tsconfig.json 148 B
- 📁 runtime-adapter-core/
  - 📁 src/
    
    📄 adapter-registry.test.ts 2.5 KB
    
    📄 adapter-registry.ts 1.8 KB
    
    📄 contracts.ts 3.3 KB
    
    📄 default-composition.ts 915 B
    
    📄 index.ts 187 B
    
    📄 shell-adapter.test.ts 4.6 KB
    
    📄 shell-adapter.ts 7.4 KB
    
    📄 webhook-adapter.test.ts 6.0 KB
    
    📄 webhook-adapter.ts 7.6 KB
  - 📄 package.json 564 B
  - 📄 tsconfig.json 141 B
- 📁 sdk/
  - 📁 src/
    
    📄 index.ts 601 B
  - 📄 package.json 764 B
  - 📄 tsconfig.json 141 B
- 📁 search-qmd-adapter/
  - 📁 src/
    
    📄 index.ts 1.8 KB
  - 📄 package.json 311 B
  - 📄 tsconfig.json 141 B
- 📁 skills/
  - 📁 src/
    
    📄 index.ts 44 B
  - 📄 package.json 299 B
  - 📄 tsconfig.json 141 B
- 📁 testkit/
  - 📁 src/
    
    📁 contracts/
    
    📄 schema-conformance.test.ts 2.6 KB
    
    📁 fixtures/
    
    📄 dispatch.invalid.json 233 B
    
    📄 dispatch.valid.json 375 B
    
    📄 policy.invalid.json 207 B
    
    📄 policy.valid.json 252 B
    
    📄 primitive.invalid.json 111 B
    
    📄 primitive.valid.json 171 B
    
    📄 query.invalid.json 38 B
    
    📄 query.valid.json 133 B
    
    📄 run.invalid.json 251 B
    
    📄 run.valid.json 355 B
    
    📄 index.ts 239 B
  - 📄 package.json 233 B
  - 📄 tsconfig.json 141 B
📁 schemas/
- 📄 dispatch.schema.json 1.6 KB
- 📄 policy.schema.json 995 B
- 📄 primitive.schema.json 512 B
- 📄 query.schema.json 823 B
- 📄 run.schema.json 1.7 KB
📁 scripts/
- 📄 generate-demo-workspace.mjs 5.5 KB
- 📄 product-demo.mjs 9.2 KB
- 📄 run-tests.mjs 8.9 KB
- 📄 setup-obsidian-demo.mjs 4.6 KB
- 📄 swarm-orchestrator.mjs 8.8 KB
- 📄 swarm-worker.mjs 3.4 KB
📁 tests/
- 📁 architecture/
  - 📄 root-src-package-boundary.test.ts 453 B
- 📁 helpers/
  - 📄 cli-build.ts 3.8 KB
- 📁 integration/
  - 📄 cli-compat.test.ts 9.7 KB
  - 📄 multi-agent-showcase.test.ts 2.1 KB
  - 📄 portability-cli.test.ts 2.6 KB
  - 📄 trigger-cli.test.ts 3.8 KB
- 📁 stress/
  - 📄 capability-matching.test.ts 5.6 KB
  - 📄 concurrent-threads.test.ts 5.1 KB
  - 📄 federation-scale.test.ts 4.6 KB
  - 📄 full-lifecycle.test.ts 6.4 KB
  - 📄 ledger-integrity.test.ts 3.3 KB
  - 📄 participant-chaos.test.ts 4.4 KB
  - 📄 trigger-cascade.test.ts 6.7 KB
  - 📄 webhook-flood.test.ts 3.9 KB
📄 .gitignore 164 B
📄 .npmrc 106 B
📄 AGENTS.md 3.4 KB
📄 ARCHITECTURE-ROADMAP-PROMPT.md 9.0 KB
📄 docker-compose.yml 526 B
📄 Dockerfile 798 B
📄 MISSION-SPEC.md 8.2 KB
📄 package.json 2.7 KB
📄 pnpm-lock.yaml 78.5 KB
📄 pnpm-workspace.yaml 40 B
📄 README.md 11.6 KB
📄 SKILL.md 9.0 KB
📄 tsconfig.base.json 367 B
📄 tsconfig.json 238 B
📄 tsup.config.ts 1021 B
📄 versatly-workgraph-3.1.0.tgz 828.3 KB
📄 versatly-workgraph-3.1.1.tgz 859.4 KB
📄 vitest.config.ts 243 B
📄 workgraph-direction-v2.md 80.7 KB

SKILL.md

---
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 legacy memory scaffolding.
author: Versatly
source: https://github.com/Versatly/workgraph
user-invocable: true
---

# Workgraph Skill — Multi-Agent Coordination

This skill defines how autonomous agents should operate a shared workgraph workspace safely and predictably.

## Purpose

Use workgraph to coordinate execution, not to hoard generic memory.

- **Good fit:** ownership, decomposition, dependency scheduling, execution audit trail.
- **Not a fit:** journaling, free-form personal memory, semantic search infrastructure.

## Workspace Model

A workgraph workspace contains:

- `.workgraph.json` — workspace identity and mode.
- `.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:

```bash
workgraph init /path/to/workspace --json
```

## Core Operational Contract

### 1) Every mutating action must be attributable

Always pass `--actor <agent-name>` on thread/primitive mutation commands.

### 2) Always parse machine output

Use `--json` for all automation.

Success payload:

```json
{ "ok": true, "data": { ... } }
```

Failure payload (non-zero exit):

```json
{ "ok": false, "error": "..." }
```

### 3) Never assume a thread is claimable

Call `thread next --json` or `thread list --ready --json`, then claim.

### 4) Never mutate without ledger awareness

Before major orchestration steps, inspect:

```bash
workgraph ledger claims --json
workgraph ledger show --count 30 --json
workgraph ledger verify --json
```

## Standard Agent Loop

This loop is the canonical multi-agent behavior:

1. **Sense**
   - `workgraph thread next --json`
   - `workgraph ledger claims --json`
2. **Claim**
   - `workgraph thread claim <path> --actor <agent> --json`
3. **Execute**
   - Perform implementation work in repo.
4. **Publish state**
   - `workgraph thread done <path> --actor <agent> --output "<result>" --json`
   - OR `workgraph thread block <path> --blocked-by <dep> --reason "<why>" --actor <agent> --json`
5. **Continue**
   - Return to step 1.

## Dependency and Readiness Semantics

`thread next` and `thread list --ready` treat a thread as ready only when:

- status is `open`
- all dependency refs point to threads whose status is `done`
- external dependencies (prefix `external/`) are considered not ready

This allows deterministic autonomous scheduling without hidden state.

## Primitive Design Rules

When creating custom types:

1. Add only fields needed by a specific recurring coordination pattern.
2. Use `ref` or `list` fields for links to other primitives.
3. Keep state-machine-like fields explicit (`status`, `phase`, `go_no_go`, etc).
4. Define type once; instantiate many times.

Example:

```bash
workgraph primitive define command-center \
  --description "Operational cockpit for active agents" \
  --fields owner:string \
  --fields panel_refs:list \
  --fields active_agents:list \
  --dir command-centers \
  --actor agent-architect \
  --json
```

## Advanced Patterns

### Pattern: Decompose before contention

If several agents are idle and one large thread exists:

```bash
workgraph thread decompose threads/large-initiative.md \
  --sub "Schema|Model storage and indexes" \
  --sub "Execution|Implement worker pipeline" \
  --sub "Validation|Run multi-agent E2E checks" \
  --actor agent-lead \
  --json
```

### Pattern: Pull-based agent scheduling

Each worker repeatedly executes:

```bash
workgraph thread next --claim --actor agent-worker-X --json
```

No centralized scheduler is required.

### Pattern: Space-scoped queues

Teams can isolate execution lanes with `space`:

```bash
workgraph thread list --space spaces/backend --ready --json
workgraph thread next --space spaces/backend --claim --actor agent-backend-1 --json
```

### Pattern: Audit-first incident review

For postmortems:

```bash
workgraph ledger history threads/critical-thread.md --json
workgraph ledger show --count 200 --json
workgraph ledger blame threads/critical-thread.md --json
```

## pi-mono Compatibility Profile

This package is designed for shell-driven agents like `pi-mono`.

### Why it works

- CLI has deterministic JSON envelopes.
- Errors are machine-readable.
- No GUI dependency.
- No qmd dependency.

### Recommended command wrapper

For pi-mono or similar agents, always run:

```bash
workgraph <command...> --json
```

Then parse:

- `ok === true` -> continue
- `ok === false` -> route to retry/escalation path

### Suggested pi-mono orchestration sequence

1. `workgraph thread next --claim --actor pi-mono-worker --json`
2. if no thread: sleep/backoff
3. implement task
4. `workgraph thread done <path> --actor pi-mono-worker --output "<summary>" --json`
5. repeat

### pi-mono skill distribution flow

```bash
workgraph skill write "workgraph-manual" --body-file ./skills/workgraph-manual.md --actor pi-mono-curator --json
workgraph skill propose workgraph-manual --actor pi-mono-reviewer --space spaces/platform --json
workgraph skill promote workgraph-manual --actor pi-mono-lead --json
```

### Backoff recommendations

- Empty queue: exponential backoff (`2s`, `4s`, `8s`, `16s`, cap `60s`)
- Claim conflict: immediate refresh via `thread next --json`

## Safety and Concurrency Guardrails

1. Never force-claim an active thread.
2. Only owner can release/done owner-bound threads.
3. Use `block` when waiting on external or unresolved dependencies.
4. Keep `output` concise but sufficient for downstream agents.
5. Keep parent/child decomposition coherent; workers should usually claim leaf threads first.

## Exit Criteria for Agent Tasks

A task is complete only when:

- Thread transitioned to `done`
- Output summary recorded
- Any new primitives created are linked/referenced by path
- Ledger confirms expected final operations

## Recommended Team Conventions

- Agent names: `role-instance` (`agent-worker-1`, `agent-reviewer-a`)
- Thread titles: imperative and specific (`Implement token refresh API`)
- Dependency refs: workspace-relative paths (`threads/schema.md`)
- Use `external/<system>` for dependencies outside workgraph

## Quick Command Reference

```bash
# init
workgraph init /path/to/ws --json

# threads
workgraph thread create "Title" --goal "Outcome" --actor me --json
workgraph thread list --json
workgraph thread list --ready --json
workgraph thread next --claim --actor me --json
workgraph thread claim threads/x.md --actor me --json
workgraph thread block threads/x.md --blocked-by external/api --reason "Waiting token" --actor me --json
workgraph thread unblock threads/x.md --actor lead --json
workgraph thread done threads/x.md --actor me --output "Shipped" --json

# primitives
workgraph primitive define type-name --description "..." --fields key:string --actor me --json
workgraph primitive create type-name "Instance Title" --set key=value --actor me --json
workgraph primitive list --json

# bases
workgraph bases sync-registry --json
workgraph bases generate --json
workgraph bases generate --all --refresh-registry --json

# ledger
workgraph ledger show --count 30 --json
workgraph ledger claims --json
workgraph ledger history threads/x.md --json
workgraph ledger query --actor me --op claim --json
workgraph ledger blame threads/x.md --json
workgraph ledger verify --strict --json
workgraph ledger seal --json

# command center
workgraph command-center --output "ops/Command Center.md" --json

# skills
workgraph skill write "name" --body-file ./skills/name.md --actor me --json
workgraph skill load name --json
workgraph skill propose name --actor me --json
workgraph skill promote name --actor me --json
```

## Anti-Patterns

- Using workgraph as a dumping ground for unstructured notes.
- Skipping `--actor` on mutating operations.
- Parsing text output in automation instead of `--json`.
- Treating `open` as implicitly claimable without readiness checks.

## Migration Guidance (from memory-heavy flows)

If your agents currently use broad memory categories for execution coordination:

1. Move active execution tasks into `thread` primitives.
2. Store governance facts as `decision`/`fact` primitives if needed.
3. Keep long-term memory in a separate system/package.
4. Use workgraph only for active multi-agent execution topology.

## Split Clarification

- 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.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

workgraph

Directory Structure

SKILL.md

Report

Notice