Waymark Blackboard

Waymark

Durable blackboard coordination for Claude Code agents

What Waymark Is

Waymark is a Claude Code plugin for running long-horizon agent work through a persistent, SQLite-backed blackboard instead of a fragile chat transcript. A user-approved mission contract seeds a Fact-Intent graph; Claude subagents then coordinate indirectly by writing durable facts, intents, claims, releases, completion evidence, and verification records through the waymark CLI.

The CLI and blackboard.sqlite are the authority. Generated files such as STATE.md, graph.yaml, timeline.txt, events.jsonl, hook-events.jsonl, and reports/final.md are views and logs for humans and agents. A run is complete only when waymark final-status --json returns ready=true.

Waymark is domain-general. It can drive software work, research, writing, data analysis, planning, or any task where the final state can be described as evidence-backed criteria rather than a vague "done" claim.

The Problem

Long-running agent work has a state problem:

• Chat transcripts compact, drift, and bury the facts that matter.
• Direct worker-to-worker conversation creates hidden dependencies and unreviewable coordination.
• "Done" claims are cheap unless they are backed by criteria, evidence, and verification.
• Parallel or resumed work needs durable leases and a shared state model, not another prompt convention.
• Hooks and stop conditions are easy to overstate unless they are explicitly read-only or explicitly authoritative.

Core Idea

Waymark separates mission, coordination, execution, and completion proof:

1. waymark-goal drafts a mission contract: origin, goal, falsifiable acceptance criteria, constraints, assumptions, and handoff triggers.
2. The user reviews that contract before waymark init; init is the semantic commitment point.
3. The CLI stores the contract and graph state in blackboard.sqlite.
4. /goal + PROTOCOL.md supervises the run and dispatches subagents, but it does not own semantic state.
5. Workers mutate state only through bin/waymark.
6. audit, verify, verification-record, and final-status decide whether completion is real.

flowchart TD
  U["User request"] --> WG["waymark-goal skill"]
  WG --> MC["Mission contract"]
  MC --> INIT["waymark init"]
  INIT --> DB[("blackboard.sqlite")]

  DB --> SUP["/goal + PROTOCOL.md"]
  SUP --> BOOT["bootstrap-worker"]
  SUP --> REASON["reason-worker"]
  SUP --> EXPLORE["explore-worker"]
  BOOT --> CLI["bin/waymark"]
  REASON --> CLI
  EXPLORE --> CLI
  CLI --> DB

  DB --> VIEWS["Generated views"]
  VIEWS --> STATE["STATE.md"]
  VIEWS --> GRAPH["graph.yaml"]
  VIEWS --> TIME["timeline.txt"]
  VIEWS --> EVENTS["events.jsonl"]
  VIEWS --> REPORT["reports/final.md"]

  SUP --> AUDIT["audit"]
  AUDIT --> VERIFIER["verifier-worker"]
  VERIFIER --> RECORD["verification-record"]
  RECORD --> FS["final-status"]
  FS -->|ready=true| DONE["WAYMARK_RUN_COMPLETE"]
  FS -->|handoff or failed proof| HANDOFF["WAYMARK_HANDOFF"]

  HOOKS["PostToolUse / SubagentStop / Stop hooks"] -. "observe; strict Stop can gate" .-> FS
  WF["Dynamic Workflow reference"] -. "optional bounded waves" .-> SUP

Design Philosophy

Waymark is built around explicit principle/mechanism pairs.