Workboard

Workboard is a file-native ticket management system for software teams and coding agents. It keeps canonical state in plain files, rebuilds discovery views from disk, and is designed so humans and agents can inspect, repair, and automate the same project state without a required database.

The implementation is written in Go and targets macOS, Windows, and Linux with minimal platform-specific behavior.

Why Workboard

• Filesystem first: canonical state lives in project files, not a hidden service.
• Agent oriented: tickets, claims, and events are easy for coding agents to read and write safely.
• Recovery friendly: indexes and queues are derived state that can be deleted and regenerated.
• Sync aware: append-only events and deterministic claim resolution are designed for shared folders and imperfect sync behavior.
• Cross-platform: path handling and workflow assumptions are built around macOS, Windows, and Linux support.

Project status

Workboard is early, but already usable. The current focus is protocol stability, validation and recovery, claim semantics, and deterministic indexing. The CLI works today for board creation, ticket creation, claims, events, validation, diagnosis, reconciliation, and agent skill installation, but the project should still be treated as evolving infrastructure rather than a locked v1 product.

AI usage disclosure

Codex was used extensively while developing this project, including implementation, refactoring, and documentation work. Human review, protocol decisions, and verification still matter, but AI-assisted development is a normal part of how Workboard is currently built.

Quickstart

Clone the repo, build the binary, and try it against a local example board before deciding whether to install it globally.

git clone https://github.com/chromeragnarok/workboard.git
cd workboard
make build
./bin/workboard help
./bin/workboard init ./example-board
./bin/workboard new ./example-board "Add passwordless email login" --priority P1
./bin/workboard show ./example-board T-0001
./bin/workboard claim ./example-board T-0001 --actor demo-agent
./bin/workboard event ./example-board T-0001 --actor demo-agent --kind worklog --summary "Investigated callback mismatch" --payload outcome=partial
./bin/workboard release ./example-board T-0001 --actor demo-agent

If you want the CLI on your PATH, see Install. If you want the bundled coding-agent guidance, see Agent skill installation.

How Workboard works

Workboard splits state into two categories:

• Canonical files: project.yaml, agents/*.yaml, ticket markdown, claim files, and event files. These are the source of truth.
• Derived files: indexes/*.json and queues/*.txt. These are safe to delete and regenerate.

That split matters because it keeps shared state inspectable and recoverable. A broken index is an inconvenience; a broken canonical file is a real protocol problem.

Example board layout:

example-board/
  project.yaml
  agents/
  tickets/
    T-0001/
      ticket.md
      spec.md
      plan.md
      result.md
      claims/
      events/
  indexes/
  queues/
  templates/

Using synced cloud storage

Workboard is intentionally designed to tolerate shared folders and imperfect sync behavior, so it can live in Google Drive, OneDrive, Dropbox, iCloud Drive, or a similar provider. That said, the filesystem protocol is safer than the sync layer: treat cloud sync as eventually consistent, not real time.

Recommended operating habits:

• Put the board in one dedicated shared folder and have every person or agent point at that same board path.
• Let sync settle after creating or editing canonical files before switching machines or expecting another collaborator to see the change.
• Avoid editing the same ticket markdown files from two machines at once; append-only event files are much safer than repeated shared-file rewrites.
• If a provider creates conflict copies or leaves the board in a suspicious state, resolve the canonical files intentionally and then run workboard validate, workboard doctor, and workboard reconcile as needed.
• Remember that indexes/*.json and queues/*.txt are derived state. They can be regenerated safely after sync weirdness.

Concurrent ticket creation warning

workboard new currently allocates the next ticket ID by scanning existing tickets/T-#### directories. If two authors create tickets at nearly the same time before Google Drive or OneDrive has finished syncing the first new ticket, both writers can decide that the same next ID is available.

In practice, that can lead to duplicate T-#### allocations, provider-generated conflict copies, or a partially merged ticket directory that needs manual cleanup. The safest workflow today is to serialize ticket creation: designate one writer for workboard new, or wait for the new ticket directory to sync fully before another author creates the next ticket.

If this race does happen, fix the canonical ticket directories first, keep the intended surviving ticket ID explicit, and then run workboard validate before continuing. After canonical files are clean again, regenerate discovery state with workboard index or workboard reconcile.

Install

Build from this checkout:

make build

The repository intentionally keeps make install non-defaulting. Choose one of the explicit install targets instead:

make install-home

Installs to ~/bin/workboard.

sudo make install-local

Installs to /usr/local/bin/workboard.

If you use make install-home, make sure ~/bin is on your PATH.

For zsh:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
exec zsh

For fish:

fish_add_path $HOME/bin

Verify the installed binary:

command -v workboard
workboard version
workboard help

Agent skill installation

Install the bundled using-workboard skill for supported local coding-agent homes:

workboard skill

workboard skill installs the bundled guidance into any detected personal agent homes at ~/.agents, ~/.codex, and ~/.claude. It does not install the workboard binary itself. Existing skill installs prompt before overwrite with yes, no, and all.

Contributing

If you want to contribute, start with CONTRIBUTING.md for local setup and pull request expectations, and read CODE_OF_CONDUCT.md for community behavior standards.

Versioning

Workboard is currently released under a pre-1.0 SemVer policy. See CHANGELOG.md for release notes and RELEASING.md for the manual release process and versioning expectations.

Current CLI surface

Board and repo commands:

• workboard help
• workboard version
• workboard doctor [path]
• workboard index [path]
• workboard init [path]
• workboard reconcile [path]
• workboard validate [path]

Ticket and workflow commands:

• workboard new [path] "Title" [--priority P1] [--parent T-0001] [--depends-on T-0001]...
• workboard edit [path] <ticket-id> [--depends-on T-0001]... [--parent T-0002 | --clear-parent]
• workboard show [path] <ticket-id>
• workboard claim [path] <ticket-id> [--actor <actor-id>] [--type <agent|human>] [--ttl-minutes 45] [--intent implement]...
• workboard renew [path] <ticket-id> [--actor <actor-id>] [--ttl-minutes 45]
• workboard release [path] <ticket-id> [--actor <actor-id>]
• workboard event [path] <ticket-id> [--actor <actor-id>] [--type <agent|human>] --kind <kind> --summary <text> [--payload <key=value>]...

Agent integration:

• workboard skill

Reference notes

Core command behavior

• init creates project.yaml, agents/, tickets/, indexes/, queues/, and templates/ with default ticket.md, spec.md, plan.md, result.md, and agent.yaml.
• new creates the next T-#### ticket directory with ticket.md, spec.md, plan.md, result.md, and empty claims/ and events/ directories. It defaults to status: backlog and priority: P2, normalizes optional --depends-on entries, and can attach the new ticket to an existing parent with --parent.
• edit replaces a ticket's dependency list from repeatable --depends-on flags, can set or clear the ticket's parent relationship with --parent or --clear-parent, refreshes updated_at, rejects missing referenced tickets, and rejects dependency or parent cycles.
• show renders a compact single-ticket summary from canonical files, including dependency state, parent and child relationships, readiness, linked documents, active claims, contested claim state, and recent events.
• claim creates or replaces the caller's claim file, defaults --type to agent, defaults --ttl-minutes from project.yaml, defaults --intent to implement, appends a claim-acquired event, and returns non-zero when the actor cannot be resolved or when the claim loses to an existing active implementation claim.
• renew extends an existing active claim without changing claim_id, acquired_at, actor_type, or intent, appends a claim-renewed event, and returns non-zero when the actor has no active claim, the claim is expired, or the implementation claim is no longer winning.
• release marks the caller's active claim as released, appends a claim-released event, and returns non-zero when the actor cannot be resolved or has no active claim on the ticket.
• event appends one canonical event file, requires --kind and --summary, accepts repeatable --payload <key=value> flags, rejects duplicate payload keys without writing, and leaves ticket.md, claim files, and derived indexes unchanged.
• index rebuilds derived discovery files from canonical ticket, claim, and event files only.
• validate checks YAML and frontmatter parseability, duplicate IDs, status and priority membership, dependency references, dependency cycles, parent references, parent cycles, parent/child mirror drift, ticket document references, and claim or event timestamps.
• doctor inspects canonical protocol health and derived board health without mutating files. It reports validation failures, contested active implementation claims, expired claims still marked active, and missing or stale derived files.
• reconcile validates canonical files first, normalizes expired or losing implementation claims when appropriate, rewrites derived discovery files when needed, and does not edit ticket.md status automatically.

Actor resolution

claim, event, renew, and release resolve actor identity in this order:

1. explicit --actor
2. WORKBOARD_ACTOR_ID
3. in Codex, CODEX_THREAD_ID mapped to codex-<thread8>

Outside Codex, set WORKBOARD_ACTOR_ID if you want to omit --actor.

.workboard redirects

You can run commands from a project root that contains a .workboard file pointing at the actual board directory:

./my-app/.workboard
../shared/workboard

or:

./my-app/.workboard
/absolute/path/to/shared/workboard

When .workboard is present, doctor, index, init, new, reconcile, edit, claim, event, renew, release, show, and validate operate on the referenced board directory instead of the project root itself.

Derived discovery files

workboard index rebuilds:

• indexes/tickets_by_status.json
• indexes/open_claims.json
• indexes/agent_picklist.json
• queues/ready.txt
• queues/blocked.txt
• queues/in_progress.txt

Expired claims are treated as inactive for discovery views without mutating canonical claim files.

Version stamping

• workboard version and workboard --version print the current binary version.
• workboard help prints the current binary version above the top-level command list.
• make build VERSION=v0.1.0 injects an explicit release version.
• Plain make build still embeds the build commit and uses that as the displayed version when no release version is provided.

Dependency rules

• Every --depends-on ticket must already exist.
• workboard new and workboard edit reject dependency cycles.
• Dependency lists are normalized by trimming duplicates and sorting ticket IDs.

Parent-child rules

• --parent must reference an existing ticket.
• The child ticket's parent field is canonical.
• The parent ticket's children list is a synchronized mirror for inspection and show output.
• workboard new, workboard edit, and workboard validate reject parent cycles.
• workboard validate reports drift when stored children values do not match the child tickets that point at that parent.

License

This repository is available under the MIT License. See LICENSE.