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

Loading

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, Lesson state counts, 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 current Protocol, they can enter the work in the same way as the existing collaborators.

Protocol standardizes the working method; it does not expand permissions that a caller did not already have. Changes to a protected Protocol require an explicit approval basis and cannot be silently introduced through an ordinary edit.

House Map: A Shared System Map Within the User-Authorized Scope

In long-running collaboration, an agent needs more than the knowledge that “a task exists.” It also needs to understand the system environment around that task.

House Map describes the systems and functions that the user has authorized collaborators to know about, including:

• which systems, services, and important functions exist;
• what each one is responsible for;
• how they connect, depend on, or affect one another;
• where the current entry points and authoritative sources are;
• what requirements, goals, and boundaries are known.

House Map contains no secrets and grants no new access. It only organizes the system reality that is already within the user's authorized scope into a shared map.

This helps collaborators avoid missing important dependencies and prevents them from guessing across boundaries, rebuilding existing capabilities, or wandering into unrelated areas. As with Protocol, changes to a protected House Map require an explicit approval basis.

Lesson: Sharing Experience Across Clients Without Erasing Their Differences

A failure, repair, or design tradeoff is often first observed by an agent in only one client. If the experience remains inside that session or that client's local instructions, other collaborators can still fall into the same trap.

Lesson provides a shared path:

1. A client judges an insight worth retaining and records it with provenance. Both note and self_note start as reviewed, with no candidate queue or automatic review.
2. Other clients read the experience and its uncertainty, then decide whether it applies to them. Reviewed observations need not pretend their tentative explanations are proven.
3. Once implemented and checked in a concrete Skill, the Lesson can be marked skilled. A candidate is not completed adoption; the change's reason must name the implemented Skill.
4. lesson_write is the only Lesson-specific tool. Use document_edit(section="lesson") for later content edits or a state patch in either direction between reviewed and skilled, with a current revision, a fresh request ID, caller attribution, and a non-empty reason for state changes. There is no separate review tool or compatibility review action. Lessons cannot be deleted.

What propagates is validated experience and judgment, not a mechanically copied paragraph across different tool ecosystems. Each client can keep its most natural implementation while sharing the same lesson, provenance, and applicability boundaries.

Explicit Lesson State Upgrade

New databases use schema v6. An existing v5 database is not migrated on import, service construction, status, or ordinary record reads. New Lesson writes and revisions fail with schema_upgrade_required until the explicit conversion; other desks remain available. Code on the production import path can be loaded by a newly spawned consumer, even before existing processes are reloaded.

The authorized operator must stop concurrent writers and run tools/migrate_workhall_v5_to_v6.py --database <exact-database-path> --edited-by <operator> with the repository's Python runtime. Do not use init to upgrade an existing database. The migration uses one exclusive native transaction, rebuilds only lesson_notes with its two-value CHECK, and creates no database copy, new field, or business table. reviewed_active and reviewed_skill_candidate become reviewed; neither proves Skill adoption. Pending, inactive, superseded, unknown, or inconsistent records block conversion until an authorized judgment resolves them. No records are automatically reviewed, discarded, or marked skilled.

Each converted Lesson gains a guarded revision and provenance event; its body, original source, references, historical lesson_reviews, and idempotency history remain. Historical labels stay in that history only; current classification uses the two states. An error rolls back the complete transaction. After commit, reconnect consumers and verify their actual schemas and readback; a source test is not proof of live migration or activation.

Why Completed Task Cards Disappear

Workboard is a small active-work surface, not a second archive. A task is created directly as in_progress; blocked is the only alternate state. When the user accepts the result, the main collaborator first writes a Devlog entry with the outcome and evidence, then closes the task, which deletes its card. A cancelled task is deleted through the explicit cancellation action without manufacturing a completion record.

Devlog is the durable record of accepted work. It explains what happened, which surfaces were affected, how far verification went, which boundaries remain unconfirmed, and what may come next.

Why Records Have Length Limits

One of the most common problems when agents write coordination records is that “do not leave anything out” gradually becomes “record everything in detail.”

A result that fits in one sentence becomes three. Necessary evidence is mixed with complete reasoning. Process continuously crowds out the conclusion. The record appears more complete while becoming less usable to the next collaborator.

Different hosts, tools, and context windows all have read limits. When a record is too long, a response may contain only part of it. The agent reading that response may not notice the truncation every time, and may not tell the user that it did not receive the whole record. The harder a record tries to preserve everything, the more likely it becomes to produce an incomplete understanding.

Workhall's length limits are therefore also an attention architecture.

They require collaborators to decide:

• What outcome truly needs to be preserved?
• Which evidence is sufficient to support it?
• Which unverified boundaries must be stated explicitly?
• Which detailed reasoning belongs in a long document connected by a pointer?
• Which material is merely repetition, padding, or over-coordination?

Workhall does not silently truncate, rewrite, or summarize overlong input on behalf of the caller. It rejects the input explicitly and asks the caller to reorganize it.

This keeps shared state from drowning in endlessly expanding records and protects the agent's own attention, so limited context is spent on understanding, judgment, and action rather than repeatedly carrying text that could have been expressed more clearly.

Designed for Cross-Context, Multi-Collaborator Writes

Rejecting Stale Overwrites

Updating an existing record requires expected_revision.

If a caller read an older revision and another collaborator has already updated the record, Workhall rejects the write. The caller must read the current state before deciding how to merge.

This prevents a silent “last writer wins” outcome.

Idempotent Requests

Writes use request_id to identify one logical request.

If the network, host, or caller is uncertain whether the request completed, it can safely replay the same request without risking duplicate records or repeating the same change.

Atomic Transactions and Post-Commit Readback

An operation that must change several related records together runs in one transaction. If any step fails, the whole operation rolls back.

After success, Workhall can return the newly committed records, the fields that actually changed, and the final revision, allowing the caller to confirm what the database truly stored.

Provenance Chain

Records preserve the following caller-provided fields:

• source: the original source;
• edited_by: who made the current change;
• contributors: participants;
• source_refs: pointers to related evidence or materials.

Timestamps, revisions, transaction results, and idempotency records are generated and maintained by the server.

These fields provide a provenance and audit trail, not authentication. Workhall does not treat a caller-provided name as a securely verified identity.

MCP Tools Shaped Around Work Intent

The schema-v6 source contract exposes 19 MCP tools shaped around real work intent.

They cover:

• reading status, exact records, and bounded search;
• writing Devlog, Promise, Lesson, Workboard, and Design records;
• reconciling Promises;
• revising Lesson classification between reviewed and skilled;
• operating Cockpit;
• blocking, resuming, accepting, or cancelling tasks;
• restoring historical Design versions.

Generic compatibility handlers may remain internal, but the default discovery surface does not encourage callers to bypass semantics and perform arbitrary CRUD.

Architecture

flowchart TB
    A["AI sessions / threads / collaborators"]
    M["Intent-shaped MCP tools"]
    K["Shared Workhall service kernel"]
    S["SQLite<br/>records · revisions · provenance · idempotency"]
    B["Local Dashboard"]

    A --> M
    M --> K
    B --> K
    K --> S

Loading

MCP and the Dashboard reuse the same service kernel. Transactions, revisions, idempotency, provenance, search, read boundaries, and validation rules are not reimplemented separately for each entry point.

The Dashboard is currently read-oriented. It lets humans inspect status, active tasks, designs, logs, and long-term constraints. Lesson filters show reviewed or skilled; an explicit classification action requires a reason and revision protection. Old candidate/discard actions are retired. Most structured work writes go through the intent-shaped MCP tools.

Local-First and Data Boundaries

Workhall currently runs local-first:

• the service and Dashboard run on the local machine by default;
• the Dashboard binds only to localhost by default;
• persistent records live in a local SQLite database;
• the source repository tracks only code, tests, schema, documentation, tools, and safe static assets;
• live databases, SQLite sidecars, logs, caches, machine paths, runtime markers, generated reports, rollback exports, and backup manifests do not enter source history.

Therefore:

A source checkout is not a Workhall data backup, nor is it a complete recovery copy of a running environment.

Workhall is also not responsible for storing:

• raw chat transcripts;
• personality or identity continuity memories;
• passwords, tokens, or other hard secrets;
• unfiltered full-machine or workspace archives.

Those materials should be managed by systems suited to them.

Local-first does not mean automatically secure. Workhall does not treat provenance fields as an authentication system. Until authentication, authorization, and network boundaries have been designed independently, the local service should not be exposed directly to the public network.

Offline Migration Boundary

The included v2-to-v4 migration command is a single-operator bridge. Keep exclusive ownership of the candidate path and its sidecar names from preflight through publication. Its initial absence check followed by os.replace provides atomic publication, but it is not a concurrent no-clobber guarantee: do not run competing migration operators or another writer against the same candidate family.

The command creates disposable offline candidate evidence only. It does not snapshot, swap, or activate a live database; change a caller route or default schema; reload configuration; restart a process; or prove that a live caller has cut over to schema v4.

Who Is Workhall For?

Workhall is suited to:

• individuals carrying work across windows, threads, or sessions in one AI client;
• individuals and small teams continuing the same work across different clients, models, or AI collaborators;
• long-running projects that need tasks, decisions, evidence, and provenance to survive across sessions;
• projects advancing several tasks at once without relying on an ever-growing master handoff document;
• projects that do not want important state to exist only inside chat context;
• cross-window and multi-collaborator workflows that need to detect and reject stale concurrent writes;
• MCP projects that want humans to inspect shared state through a Dashboard.

It does not try to replace:

• simple one-off chats;
• cloud enterprise project-management platforms;
• general-purpose knowledge bases;
• Git itself;
• secret managers;
• automated authentication or authorization systems.

Runtime Baseline

Workhall's currently used and verified route is a local Windows environment. Its main technical baseline includes:

• Python 3.14.6;
• the official MCP Python SDK 2.x (the source environment is currently locked to 2.0.0);
• SQLite;
• a local MCP service;
• a Dashboard bound to localhost;
• a local Windows runtime.

Fresh-checkout initialization, MCP client configuration, Dashboard startup, and minimal verification are documented in Installation and MCP setup. Existing live databases and internal machine paths are not used as generic installation templates.

License

Workhall uses layered licensing:

• software code, tests, schemas, tools, and configuration are licensed under the Sustainable Use License 1.0, SPDX identifier SUL-1.0;
• the README files, documentation, and original documentation diagrams are licensed under CC BY-NC-SA 4.0;
• LICENSING.md is the authoritative path map.

SUL-1.0 allows personal, non-commercial, and internal business use, including modification and study. Distribution or provision to others must be free of charge and non-commercial. It is a source-available license with use restrictions, not an open-source license under the OSI definition.

Authorship

Copyright © 2026 Luluane (@LuluaneS)
Created by Luluane & Astrean-Codex.

---

Workhall does not try to make AI “remember everything.” It helps AI collaborators recall the right thing at the right time and immediately find the right coordinates from which to continue, so shared work always has a place where it can reliably resume.