Workhall

English | 简体中文

A local-first coordination hall built for long-running AI collaboration—keeping state continuous across windows, threads, and collaborators, preserving provenance for every change, and rejecting stale overwrites.

Whether the same AI collaborator is carrying work across windows and threads, or several AI collaborators are working on the same long-running project, the hardest part is rarely “can one task be completed?” It is:

• Will the next window, thread, or collaborator know where the work currently stands?
• Why was a decision made, and is it still valid?
• Has an outcome actually been accepted?
• Can a write silently overwrite an update that somebody else just completed?
• When several tasks advance in an interleaved way, can their state, evidence, and next steps remain independent?
• After many rounds of iteration, do the code, documentation, and operating rules still describe the same reality?
• Can lessons learned in one window or client be reliably discovered, understood, and absorbed by later windows and other clients?

Workhall provides a set of clearly scoped coordination surfaces for these problems, and protects shared state with revision checks, idempotent requests, atomic transactions, post-commit readback, and provenance chains.

It is not another chat transcript, nor a general-purpose project manager or CRUD database. It is a local coordination hall designed for long-running work across changing contexts.

Workhall has been used in real daily work since July 10, 2026, continuously dogfooded, refined, and iterated through cross-window, cross-thread, interleaved-task, and multi-collaborator practice.

Quick Start

On the currently verified Windows route, a fresh checkout can be initialized and verified with:

uv sync --locked
.\.venv\Scripts\python.exe .\tools\workhall_cli.py init --root .
.\.venv\Scripts\python.exe .\tools\workhall_cli.py verify --root .

See Installation and MCP setup for the Dashboard command, a client configuration template, the localhost-only boundary, and the full test command.

What Problem Does Workhall Solve?

Chat transcripts are good at preserving a conversation, but they do not naturally answer questions such as:

• Which plan is currently being executed?
• Which constraint has been accepted?
• Where should the work resume now?
• Which outcomes have been completed and accepted?
• Who did a conclusion come from, and who changed it?
• When two collaborators edit at the same time, who is writing from stale content?
• When code, READMEs, operating documents, and agent instructions disagree across versions, which one reflects current reality?

Workhall separates design, execution, process, acceptance, long-term constraints, system maps, and reusable lessons into surfaces suited to each kind of information. Each kind has its own lifecycle instead of being compressed into one ever-growing master document.

Not Just for Cross-Client Collaboration

Cross-client collaboration is only the most visible form of broken continuity. Even with a single AI client, the same agent does not automatically retain its complete prior working state after opening a new window, entering a new thread, going through context compaction, or starting a new session.

Without a suitable persistent coordination layer, it may need to reread long conversations, rely on outdated summaries, reconsider decisions that were already accepted, or repeat work completed in a previous window.

The fundamental unit in Workhall is not “how many agents are involved,” but “does this work need to continue reliably after the context changes?”

That means one collaborator working across windows, threads, and sessions can use the same surfaces and safeguards as multiple clients, models, or collaborators. Provenance, revisions, and concurrency protection matter even more as collaborators multiply, but clear re-entry points, current truth, and durable completion evidence are equally valuable for one collaborator.

Multiple Tasks Can Advance in an Interleaved Way

When continuity depends on a single handoff note or session summary, the handoff naturally becomes linear. The latest summary must explain everything happening at once; as soon as Task A is blocked, Task B is inserted, and Task C finishes, their progress, evidence, and next steps can be compressed into the same repeatedly rewritten narrative.

Workhall does not require the entire project to fit into “the latest handoff.” Each active task has its own task card, state, revision, scope, authority, stop conditions, and evidence pointers. Related Design, Promise, and Devlog records keep their own responsibilities. Cockpit only identifies where to resume now; it does not need to impersonate the archive of every active task.

Task B can therefore advance while Task A is blocked. When Task C is accepted, its Devlog preserves the result and evidence, and the active task card is removed. When somebody returns to Task A, they read that task's current card and related records instead of reconstructing its stopping point from the latest global narrative.

Handoff notes can still provide background, tone, or a short entry point, but they are no longer the sole container for all state. A reliable handoff can be short: point to the specific task and authoritative records, then let Workhall preserve classification, current state, rules, provenance, and history.

Workhall at a Glance

flowchart LR
    R["Protocol / House Map<br/>Rules and system map"] -. boundaries and entry points .-> W
    DP["Design / Promise<br/>Design and long-term constraints"] --> W["Workboard<br/>Task A · Task B · Task C"]
    W --> V["Devlog<br/>Outcomes, process, and evidence"]
    W -. accepted or cancelled .-> X["Task card removed"]
    W <--> C["Cockpit<br/>Mid-task re-entry"]
    V --> L["Lesson<br/>Reusable experience"]
    H["Home / Status<br/>Current overview"] -. overview .-> DP
    H -. overview .-> W
    H -. overview .-> V

This is not a mandatory pipeline. It is a map of responsibilities:

• Protocol and House Map provide shared operating rules, an authorized system map, and stable entry points.
• Design and Promise provide design rationale and long-term constraints.
• Workboard holds only active tasks. A new card starts in_progress; it may be blocked and resumed.
• Devlog preserves stable outcomes, necessary process, and verification evidence.
• Cockpit helps collaborators re-enter work after an interruption.
• Lesson distills reusable experience from completed work.
• Home / Status provides a current overview of the whole hall.

Accepted work is recorded in Devlog and then removed from Workboard. Cancelled work is removed directly. Workboard is not an archive.

Core Capabilities

• Structured, persistent shared state for one collaborator across windows and threads, as well as for multiple clients and collaborators.
• Independent task state, revisions, and evidence pointers so several tasks can advance in an interleaved way.
• expected_revision checks that reject writes based on stale content.
• request_id support for safely replaying logical requests with uncertain outcomes.
• Atomic transactions for operations that must succeed or fail together.
• Post-commit readback with the final revision and fields that actually changed.
• Provenance through source, edited_by, contributors, and source_refs.
• Bounded reads, exact-ID-first search, and surface-aware filtering.
• A local Dashboard that gives humans a view of shared state.
• Promise, Protocol, House Map, and Lesson surfaces that resist information drift in long-running collaboration.

Surface Map

| Surface | Question it answers | Why it exists separately | |---|---|---| | Home / Status | Is the hall healthy? What needs attention? | An overview should not require opening every record one by one. | | Design | Why was this designed this way? What is the current design decision? | Design rationale and execution state have different lifecycles. | | Workboard | What is active? What are its scope, authority, evidence, and stop conditions? | Active tasks need clear, compact, transitionable state instead of being buried in long documents. | | Cockpit | If work stops now, where should the next session resume? | Re-entry guidance is short-lived working state, not a formal task or completion record. | | Devlog | What happened? Which surfaces changed? What evidence exists, and what remains unverified? | It preserves traceable process without automatically treating every process note as an accepted result. | | Promise | Which long-term constraints, default routes, or safety statements have been accepted? | Current truth and its verification history need to remain together. | | Lesson | What reusable experience came out of this work? | One-off process and transferable experience are not the same material. | | Named Anchors | Where do important entry points, Protocols, House Maps, or persistent pointers lead now? | Stable entry points and governance material should not be scattered across tasks and chats. | | Search | Given an ID, phrase, date, or pointer, how do I find it? | Cross-surface retrieval needs one entry point without flattening the meaning of each surface. |

What Is in Home / Status?

Home / Status is not a vague green light that merely says “everything is fine.” It combines several kinds of information:

• Operational route truth: the currently accepted route for work records and the basis for that conclusion.
• Local health: schema, root marker, database, SQLite checks, and foreign-key state.
• Readiness and attention: backup readiness, Lessons awaiting review, record thresholds, and the latest public IDs.
• Cockpit: short-term items that still need to be resumed.
• Named Anchors: important entry points that need stable long-term access.

Together, these provide a quiet, trustworthy picture of current state before a collaborator acts.

Sharing More Than State

Workhall does more than show several collaborators the same task list. It helps them share a bounded working reality: what is currently true, which rules apply, how existing systems relate to one another, and what has already been learned.

Promise: Resisting Semantic Drift Across Versions

After a system has gone through several iterations, its code, README, operating documentation, caller guidance, and agent instructions rarely update at exactly the same time.

An old statement may survive in one corner. A rolled-back route may still be described as the default. Code may have changed while the documentation still explains the previous behavior. The longer this continues, the harder the conflict is to notice.

A Promise preserves:

• the current state and actual reality;
• statements that are safe to rely on;
• applicable scope and responsibility boundaries;
• the history of checks, findings, and adjustments.

It does not automatically edit every piece of code or documentation. Instead, it provides a shared reference baseline. Whenever a collaborator works on the relevant feature again, they can first confirm what is actually true now, then check whether the other surfaces still agree.

That keeps omissions during version iteration from silently becoming new facts, and gives conflicting statements an explicit place to be reconciled.

Protocol: Helping New Collaborators Join the Work Correctly

Protocol stores the operating rules for Workhall itself.

It explains which surface should hold each kind of information, what must be read before writing, when a revision is required, how provenance and evidence should be preserved, and what does not belong in Workhall.

A collaborator joining a project no longer has to infer working conventions from old chats or depend on another client to recite every rule. After reading the curren