Skip to content

README.md

Latest commit

 

History

History
407 lines (307 loc) · 10.7 KB

README.md

File metadata and controls

407 lines (307 loc) · 10.7 KB
Raw

WorkMesh Documentation

This is the canonical human guide for WorkMesh.

If you read only one document, read this one. The rest of the docs are supporting references.

1. What WorkMesh Is

WorkMesh is a docs-first project and task system for developers and coding agents.

It is built for:

  • repo-local task tracking
  • chat-driven development with durable context
  • stable decision tracking through Truth Ledger
  • parallel feature work across worktrees
  • the same workflow through CLI and MCP

It is not built to be:

  • a hosted ticketing product
  • a remote SaaS project manager

2. How State Is Stored

WorkMesh keeps operational state close to the repo:

  • tasks/: Markdown task files
  • .workmesh/context.json: repo-local working scope
  • .workmesh/truth/: durable decisions
  • docs/projects/<project-id>/: PRDs, decisions, updates

Global continuity lives under ~/.workmesh/:

  • sessions
  • worktree/workstream registries
  • indexes and integrity metadata

3. Install

Verify installed binaries:

workmesh --version
workmesh-mcp --version

Build from source:

git clone git@github.com:luislobo/workmesh.git
cd workmesh
cargo build -p workmesh
cargo build -p workmesh-mcp

4. Agent Setup

Codex MCP example:

[mcp_servers.workmesh]
command = "/usr/local/bin/workmesh-mcp"
args = []

Supported run modes:

  • CLI: workmesh
  • MCP stdio: workmesh-mcp

For lower-level setup details, see:

5. Recommended Workflow

This project is Codex-first. The intended usage is prompt-driven, not command-matrix-driven.

Day-to-day entry flow:

  1. cd into a repo
  2. run codex or codex resume
  3. prompt:
Bootstrap WorkMesh in this repo. Use MCP if available, otherwise CLI.
  1. then prompt:
Use WorkMesh for this feature end to end. Create/update PRD, create and maintain tasks with acceptance criteria and definition of done, keep context current, and track stable decisions in Truth Ledger.

That is the main path. You should not need to memorize commands to get started.

6. Bootstrap Behavior

bootstrap is designed to handle mixed repo states:

  • brand new repo with no WorkMesh data
  • modern WorkMesh repo
  • legacy backlog/focus layout
  • long-lived clone workflow that should eventually move to worktrees

Expected behavior:

  • initialize when no WorkMesh data exists
  • validate and continue when the modern layout already exists
  • migrate deprecated structures when needed
  • keep work moving and recommend worktree adoption when the repo uses parallel clones

7. Core Concepts

Tasks

Task files live under tasks/ by default.

Legacy layouts remain readable:

  • workmesh/tasks/
  • .workmesh/tasks/
  • backlog/tasks/
  • project/tasks/

Default task-quality requirements:

  • Description
  • Acceptance Criteria
  • Definition of Done
  • outcome-based Definition of Done content, not only hygiene lines like “code committed” or “docs updated”

These defaults are configurable through project or global config:

  • task_require_description
  • task_require_acceptance_criteria
  • task_require_definition_of_done
  • task_require_outcome_based_definition_of_done

Actionable tasks:

  • To Do and In Progress tasks must already satisfy the required section quality gate.
  • Incomplete work must stay in Draft or Needs Refinement until the task is properly specified.
  • next_task, next_tasks, and ready_tasks ignore tasks that are not yet actionable.

Context

.workmesh/context.json stores the current repo-local scope:

  • project
  • epic
  • objective
  • task working set
  • active workstream

Truth Ledger

Truth records live under .workmesh/truth/.

Use them for decisions that must survive:

  • restarts
  • agent changes
  • worktree changes
  • feature handoffs

Workstreams and Worktrees

Workstreams are the parallel-work model.

Typical pattern:

  • one canonical repo
  • multiple git worktrees
  • one active workstream per worktree

Useful commands:

workmesh --root . workstream create --name "OCA integration" --project <project-id> --objective "..." --json
workmesh --root . workstream restore --json
workmesh --root . worktree adopt-clone --from <path-to-clone> --apply --json

8. Daily Work Pattern

A good WorkMesh-driven feature flow looks like this:

  1. create or update the PRD
  2. create tasks that support the real work
  3. keep the repo’s configured task-quality requirements complete before moving work into To Do or In Progress
  4. keep repo-local context current
  5. capture durable feature truths when a decision should persist
  6. make atomic commits per task or coherent task slice
  7. archive completed tasks after the work is actually done

9. Restore After Reboot

Single repo/worktree:

  1. cd <repo-or-worktree>
  2. codex resume
  3. ask Codex to restore context, truths, and next tasks

Recommended resume prompt:

Rehydrate this session with WorkMesh. Read current context, accepted truths, active workstream state, and next actionable tasks. Then summarize what I was doing, what constraints still apply, and the next concrete step.

Multiple active workstreams:

workmesh --root . workstream restore --json

The restore output gives you:

  • worktree_path
  • session_id
  • context
  • next_task
  • resume_script

That is the deterministic recovery path after losing terminals or rebooting.

Resume checklist for agents:

  1. restore current context
  2. read accepted truths for the current scope
  3. inspect workstream restore state if parallel work exists
  4. identify the active task or smallest valid working set
  5. summarize current objective, constraints, and next step before new implementation work

10. CLI Fallback

If you are not using MCP, these are the main direct commands:

workmesh --root . bootstrap --project-id <project-id> --feature "<feature-name>" --json
workmesh --root . context show --json
workmesh --root . next --json
workmesh --root . list --json
workmesh --root . workstream restore --json

CLI render fallback:

workmesh --root . render table --data '[{"task":"task-001","status":"Done"}]'

11. Important Command Families

Read and navigation

  • list
  • show
  • next
  • next-tasks
  • ready
  • board
  • blockers
  • stats

Task mutation

  • add
  • add-discovered
  • set-status
  • set-field
  • label-add / label-remove
  • dep-add / dep-remove
  • note
  • set-body
  • set-section
  • claim
  • release

Context and truth

  • context show|set|clear
  • truth propose|accept|reject|supersede|show|list|validate

Workstream runtime

  • workstream create|show|list|switch|pause|close|reopen|rename|restore
  • worktree list|attach|detach|adopt-clone

Diagnostics and migration

  • doctor
  • validate
  • migrate audit|plan|apply
  • truth migrate audit|plan|apply

For the exhaustive surface, see:

12. Renderers

WorkMesh has native renderers for human-friendly output:

  • table
  • kv
  • stats
  • list
  • progress
  • tree
  • diff
  • logs
  • alerts
  • chart-bar
  • sparkline
  • timeline

Use MCP render tools first when available. Use CLI render ... as the local fallback. For MCP render tools, send data as a JSON-encoded string and configuration as an optional typed object. Native JSON values for data still work as a deprecated compatibility path, but agents should not rely on that form.

13. Mutation Response Contract

MCP mutation tools default to compact acknowledgements to save tokens.

Typical response:

{ "ok": true, "id": "task-001", "status": "Done" }

Bulk default:

{ "ok": false, "updated_count": 3, "failed_count": 1, "failed_ids": ["task-009"] }

If you need richer post-write state:

  • pass verbose=true
  • or call the matching read tool afterwards

14. Architecture

Current crate boundaries:

  • workmesh-core: domain logic, storage, state
  • workmesh-render: renderers
  • workmesh-tools: shared tool contract
  • workmesh: CLI adapter
  • workmesh-mcp-server: MCP adapter
  • workmesh-mcp: stdio wrapper

Contributor rule:

  • shared tool semantics go into workmesh-tools
  • CLI-only behavior goes into workmesh
  • MCP transport-only behavior goes into workmesh-mcp-server
  • domain/state/storage logic goes into workmesh-core

Architecture diagrams:

15. Safety and Storage

Critical tracking files use lock-safe and atomic storage primitives.

Important guarantees:

  • versioned mutable snapshots
  • CAS-based writes
  • append-safe JSONL event streams
  • integrity recovery through doctor

Useful repair path:

workmesh --root . doctor --fix-storage --json

Archive defaults are intentionally conservative:

  • Done
  • Cancelled
  • Canceled
  • Won't Do
  • Wont Do

Non-terminal statuses are archived only when explicitly requested.

16. Supporting Documents

These remain useful, but they are no longer the primary entrypoint:

17. Skills

WorkMesh uses a layered skill model so agents do not have to rediscover the workflow on every session.

The skills are:

  • workmesh: router skill that selects CLI-first or MCP-first execution
  • workmesh-cli: CLI adapter skill
  • workmesh-mcp: MCP adapter skill

Canonical skill sources live under skills/. Installed project-local agent paths follow the standard layout:

  • .agents/skills/ for Codex and Cursor
  • .claude/skills/ for Claude

Each skill is self-contained and carries its doctrine reference inside its own directory.

The shared doctrine covers:

  • task quality rules
  • SOLID/TDD expectations
  • compaction-safe persistence discipline
  • when to use tasks vs notes vs truths vs context updates
  • output/rendering rules
  • mutation response expectations

Recommended agent behavior under compaction pressure:

  1. restore context, accepted truths, and current task before starting new work
  2. claim/set In Progress and validate task quality before coding
  3. update WorkMesh immediately when scope, blockers, dependencies, or durable decisions change
  4. before likely compaction or topic switches, persist a concise note, ensure context is correct, and capture durable truths
  5. only mark Done after goals, acceptance criteria, and definition of done are truly satisfied

The main principle is simple:

  • tasks are the work contract
  • context is the current pointer
  • truths are durable decisions
  • notes are the volatile breadcrumb trail
  • sessions/workstreams are the continuity layer