Agent Workspace

A shared working contract, binding standards, and durable memory for teams where AI agents and developers work on the same code.

Every agent — Claude Code, Cursor, Copilot, Codex, Gemini CLI — reads the same rules from the same place. Every session that ends leaves behind enough for the next person or agent to continue. Nothing internal leaks into a client's repository, and nothing of one organisation's leaks into this one.

The problem it solves

Agents lose context when a session ends. Developers switch tools. Standards written inside a product repo diverge the moment there is a second product. And a codebase shared with a client is the wrong place for your own engineering notes.

This repository is the how, kept separate from the what:

• Standards an agent must follow, in packs you switch on per stack
• Skills — task-shaped instructions an agent reads before starting, pulled from Agent-Skills a pack at a time
• Memory and runs — what happened, what is in flight, what the next session needs
• Two clocks — human hours and agent hours, recorded separately and never summed
• A CLI (ws) that wires the repositories together and checks they stay separate

Nothing here names an organisation. Clone it, run .agents/bin/ws init, and it is yours.

A caveat worth reading before you adopt it. core carries the git workflow, the REST API contract, and the definition of done. Testing, security, and observability live in the stack packs: java for Quarkus services, web for TypeScript/JavaScript. Enable the packs you actually run (packs = core, java, web). ws doctor warns if only core is on.

---

Start here

Joining an organisation that already uses this workspace:

git clone <workspace-remote> workspace && cd workspace
cp workspace.conf.example workspace.conf        # leave context_remote empty for local-only
.agents/bin/ws install                         # make `ws` available to agent shells
.agents/bin/ws bootstrap                        # skills, and product repos that have remotes
.agents/bin/ws context init                     # only if context/ is not already present
.agents/bin/ws ide                              # copy the shared editor defaults
.agents/bin/ws doctor                           # check isolation, ignores, toolchain

Leave context_remote empty while context stays on this machine. Set it only when the context repository is shared. ws doctor reports a context with no remote as private-local.

Adopting the workspace for a new organisation, team, or client:

git clone <workspace-remote> workspace && cd workspace
.agents/bin/ws init            # writes local settings without an organisation name
.agents/bin/ws install         # make `ws` available to agent shells
.agents/bin/ws context init    # create an empty context repository for it
.agents/bin/ws doctor

The framework stores no company name. Private client names, projects, memory, and access boundaries live in the separate context repository.

Clone it wherever you like — nothing tracked here assumes a path, and ws where resolves the root from anywhere.

Then open your editor at that root — not at projects/<x>. The reason is in AGENTS.md §2.

Full first-day onboarding: docs/onboarding.md.

---

Map

Three repositories share one directory. Full explanation in AGENTS.md §1.

1. Framework — this repository, shared across organisations

Path	Contents
AGENTS.md	Working contract for agents + developers. Read this first.
workspace.conf	Local settings that point to the private context
.agents/standards/	Binding standards, in packs (core, java, web)
test/ws.test.sh	The CLI's test suite — zero dependencies, runs in CI
.agents/skills.manifest	Which skills to pull, and from where
.agents/templates/	Templates: ADR, run, memory, endpoint spec
.agents/bin/ws	Workspace CLI
docs/adr/	Decisions about the workspace mechanism itself

2. Context — a separate repo per organisation, ignored here — what it is and why

Path	Contents
context/registry.tsv	Which product repos this organisation has
context/memory/projects/	Cross-session memory, per project
context/runs/	Per-task working memory
context/skills/	This organisation's domain skills
context/works/	Human and agent hours, kept apart
context/docs/	Client ADRs, proposals, kick-off notes

It must be private when it has a remote: it names clients and holds the hours behind invoices. A context with no remote is valid (private-local). ws doctor fails only if a configured remote can be read without credentials.

3. Product — the client's repos, ignored here

Path	Contents
projects/<group>/<repo>/	Product code — separate git repos with their own remotes
.local/	Client documents & scratch — ignored, never pushed

---

Why this structure

Three problems it solves:

1. Standards do not leak into client repos. Product repos are often hosted by the client. The workspace's standards, memory, and skills do not belong there. Here they have one home, one history, one owner.

2. One project is not the only project, and one organisation is not the only organisation. Standards rewritten per repo diverge immediately. Written here once, they apply to every project — and, because nothing but workspace.conf names a company, to every team or client that adopts the workspace later.

3. Agents change; context persists. Sessions hit quota, developers switch tools, people take leave. context/memory/ and context/runs/ let another person or agent pick the work up without redoing the investigation.

---

Active projects

This repository does not list them. Projects, their clients, and their memory belong to whoever owns the clone and live in the context repository — context/registry.tsv and context/memory/projects/. Run ws list to see them.

---

Common commands

ws session bind <project-key>              # bind this conversation to one project
ws route --project <key> "add an order summary endpoint"   # skills for that project
ws skills available                        # what the skills repository offers
ws skills add code-review                  # take one, pinned to a commit
ws run <project-key> "task title"          # start a run (multi-session work)
ws log <project-key> "milestone"           # append to the project log
ws note <project-key> "title" "body"       # keep a project note (body - reads stdin)
ws task add <project-key> "title" --priority high   # an operator task, in backlog
ws task status <project-key> <task-id> in_progress  # backlog|ready|in_progress|review|done
ws task edit <project-key> <task-id> --due 2026-11-20 --assignee agent:claude   # fields; none clears
ws task show <project-key> <task-id> --json        # fields, checklist, activity
ws task list --all --due-before 2026-11-01 --json  # across projects, for the desk and agents
ws task comment <project-key> <task-id> "text"     # appended to the task's activity
ws task add @<client> "Send the report" --due 2026-10-31 --recur monthly  # the client's own work
ws remind <project-key>|@<client> "Call" --at "2026-10-20 14:00"          # a reminder task
ws today                                   # overdue, due today, waiting for you, in progress
ws alerts --json | ws alerts snooze <id> --for 1d   # computed alerts; snoozes stay local
ws client show <client> [--json]            # profile, projects, open work, interactions
ws client log <client> "Call: agreed scope" # the client's interaction log
ws mcp                                     # stdio MCP server for coding agents (see below)
ws plan status <project-key> <run-id> 2 done        # a run's plan row; owner only
ws clock in <project-key> "what you'll do" # human hours
ws agent in <project-key> "what it'll do"  # agent hours, counted separately
ws hours --month 2026-09                   # both, side by side
ws sync                                    # pull workspace, report repo state
ws new <key> <folder> [remote]             # register a new product repo
ws link <key>                              # pointer + commit guard in a client repo
ws doctor                                  # health check: isolation, portability, drift
ws verify <project-key> [--run <run-id>] [--worktree <path>]  # run the operator-owned verification contract
ws policy check <key> --action <action>    # classify read/change/approval-required work
ws eval validate <file>                    # validate synthetic agent scenarios
ws compat validate <file>                  # validate pinned release metadata
ws install                                 # install the user-level launcher for agent shells

ws install writes a small dispatcher to ~/.local/bin/ws (or XDG_BIN_HOME). The dispatcher resolves the workspace from the agent's current directory, so multiple workspace clones can coexist without one clone being hard-coded into a shell profile. If the command reports that the chosen directory is not on PATH, add that directory to the environment used by the agent. Until then, invoke the CLI directly from the workspace root:

.agents/bin/ws <command> [args]

---

Language

Everything written here — documentation, code, comments, commit messages, identifiers — is in English. An organisation whose domain carries statutory or regulated vocabulary with no precise English equivalent may keep those terms as-is; that glossary then lives in its own context repository (context/skills/<domain>/SKILL.md), never here.

---

Rules most often broken

1. Opening the editor at projects/<x> → standards do not load. Open the root.
2. Putting client documents outside .local/ → risk of pushing them. Always .local/.
3. Committing in projects/<x> thinking it is this repo → that is the client repo.
4. Deviating from a standard without an ADR → write the ADR, don't bury it in one file.
5. Running git clean -ffxd at the root → deletes the product repo and any unpushed commit in it. Plain -xdf is safe; -ff is not. See AGENTS.md §2.

Verification contracts belong under the operator-owned .local/agent/contracts/ directory or another path outside the product repository. ws verify records command IDs, status, and durations but never captures command output, so secrets and client data do not become evidence artifacts. Use --run <run-id> to write the sanitized report to the private context run. --worktree <path> runs the contract in an agent's worktree instead of the primary checkout, where the agent's change is; the path must be one of the project's worktrees under .local/worktrees/<key>/ and share the product repository, and the contract may live in neither checkout.

Project management for agents

Tasks, milestones, reminders, alerts, and client profiles are files in context/, changed through ws (ADR-0024). Agents get them three ways, all within their session's bind:

• the work digest that ws session bind writes into CONTEXT.md;
• the CLI with --json: ws today, ws alerts, ws task list|show|add|edit|status|comment|check;
• the MCP server ws mcp, registered once per tool, for example claude mcp add workspace -- ws mcp (Claude Code) or the same command in another tool's MCP settings. It offers pm_today, pm_alerts, pm_list_tasks, pm_get_task, pm_add_task, pm_update_task, pm_comment, pm_check, and client_profile, and refuses any scope outside the bound project and its client. Contacts and commercial terms never leave the desk.

The agentic governance workflow validates the public templates and helper syntax without checking out context/ or any product repository. Configure these workflow jobs as required status checks in the public repository: ws test suite, workspace hygiene, agentic contracts, and the pinned security gate. Branch protection and deployment environments are administrator settings; they are not inferred from agent output or product-controlled files.