Get started
Blog

The primitives of wirk, rebuilt for agents

Teams get leverage from AI when their people and agents share one place to read and write wirk. Here are the few, precise pieces WIRK builds that place from, and why there are so few.

Notion recently published a field guide, A New Shape for Work. Its argument, put briefly: AI makes individuals faster but barely changes how teams operate, because each person's agent wirks alone and forgets. The fix is a shared context system that every person and agent reads from and writes to, and on top of it, shared agent systems that a few people build and watch so everyone else benefits.

We agree with the diagnosis. Where we differ is the shape. A context system built from databases you design yourself still has to be learned, by every agent, every session. WIRK takes the other route: a small set of fixed primitives, the same in every wirkspace, so any agent knows its way around on the first read.

Agents are a particular kind of colleague. They read everything literally. They forget everything between sessions unless something hands it back. They run in parallel, dozens at a time, and stop without warning. Each primitive below exists because of one of those facts.

WIRKSPACE · EVERYONE IN IT READS EVERYTHING contributes_to cites relies_on related_to contextOrganization contextapplies to all wirk contextInitiative: Launch work · in_progressPrepare the launch checklist recordDraft checklist.pdf recordDecision: launch date messageSign-up ships first. alice (person) alice-agents (agent) status · query · write · review
One wirkspace, flat items and typed links. No item sits above another.

One place everyone can read: the wirkspace

A wirkspace is where a team's items live. Everyone in it, person or agent, can read everything in it. An agent never wonders whether the decision it needs is hidden from it, and a person can always see what their agents saw.

The boundary is deliberately simple. Roles decide who may change what (reader, editor, reviewer, administrator, and proposer for agents that should only suggest), and wirk that only some people should see lives in a separate wirkspace. Each person signs in as themselves; each of their agents wirks under its own agent principal, so every change says who made it: by alice-agents (agent). Agents act with their person's role, capped so an agent is never an administrator.

An agent's first call in any session is wirk status: who it is, the organization's direction, its wirk, what needs review and what changed, in one answer that fits a fixed budget. Catching up stops being a reading assignment.

An ontology you don't have to design: items and five kinds

The guide rightly says agents do better when information has a clear structure, and suggests starting with a handful of core databases. WIRK ships that structure. Everything is an item, with a title, an optional body, files and the fields the wirkspace defines, such as status or priority. Every item is one of five kinds:

KindWhat it is
workA ticket, with an optional owner, due date and acceptance criteria
contextThe organization's direction, or one initiative
recordDocuments, files, transcripts, evidence
messageSomething said to people, agents or a ticket's board
folderA folder, when you want one

Five kinds, not fifty, because an agent has to know what it is looking at without a manual. A record is never mistaken for a task: saving a meeting transcript or uploading a file never creates wirk by itself. Meetings arrive as records, with their summary and transcript, and are linked to the wirk they shaped.

Every change makes a new revision, shown as r3, and old revisions stay readable. Nothing is deleted; an item can be archived with a reason and restored.

One item is a complete start:

wirk write new 'Prepare the launch checklist' kind=work \
  --body 'The team needs a checked plan before launch.'

Structure helps, but a tree you must file into before you can wirk is a tax. Items in WIRK stay flat. A link connects two of them and says precisely how. There are five types:

  • related_to: the same topic.
  • contributes_to: this is part of that larger wirk or initiative.
  • requires: this cannot be completed until that is.
  • cites: that is evidence for this, pinned to the revision that was read.
  • relies_on: this assumes something stated there.

Links are optional. No folder, initiative or link is required before the first ticket. Finding things comes from asking, not from filing: wirk query about='webhook retries' looks across every item, wherever it sits.

context · initiativeAPI hardening recordWebhook retry design work · openRate-limit the public API recordDecision: retry limitsflagged for a look if it changes 5c1e7a90 · work · r3 Retry failed webhooks in_progress · owner alice-agents occupied:3 Context goal · constraints · decisions · principles contributes_to cites · r1 requires relies_on On completion: pytest: 12 passed; commit 3f9a2c4
What an agent sees when it fetches one ticket: its links, its claim and the context that comes with it.

Context that travels, and doesn't rot

A context item holds direction. There is one for the organization (purpose, who it serves, goals, principles and non-negotiables) and one for each initiative, with its goal, outcomes, constraints, key decisions and open questions.

Context is not a parent you must file wirk under; it is something wirk points at. When an agent fetches a ticket, the answer ends with a Context block: the initiative the ticket serves and the organization's principles. The why arrives with the what, so nobody pastes a brief into a prompt.

The guide calls stale information enemy number one. WIRK's answer is relies_on. Wirk that assumes a decision links to it, and when the decision changes, that wirk is flagged for another look instead of quietly going out of date. Outcomes are keyed lines, checked off with their evidence, so progress can be verified rather than asserted:

- [x] O2: Partners can retry safely (evidence 5bd3a0c3)

Connections write like any agent

A context system is only as good as what gets into it. In WIRK, a connection brings in the tools a team already uses: GitHub, Sentry, Granola, Linear and Attio. Each connection gets its own agent and writes through the same operations as any other, so there is no second door with its own rules.

A merged pull request shows the pattern. It becomes a record linked to its ticket, and if it says it completes the wirk, the merge proposes completion rather than forcing it. A person still decides.

Validation: done means proven

The guide asks that a context system refuse bad information. WIRK does that in three places.

Completing wirk needs evidence: the test output, a commit, a pull request, a file. It is stored with who completed the wirk. WIRK does not judge the evidence, but it is always there to check, and the next agent can trust the wirk instead of redoing it.

wirk write edit 5c1e7a90@9 status=completed --evidence 'pytest: 12 passed; commit 3f9a2c4'

Writes name what they read. Every write carries expect, the revisions it was based on. If someone changed the item in the meantime, the write is refused with basis_changed and the agent reads again. With dozens of agents editing at once, last-write-wins is not an option.

Retries are safe. Every write carries a request ID, and sending the same request twice applies it once.

A factory is a team of agents with a ticket queue

The second half of the guide is about factories: shared agent systems that are specific, shared and scrutinized. In WIRK that is not a new kind of object. It is what the primitives above already do once several agents wirk from one wirkspace.

Specific. The method WIRK teaches every agent is to cut a change into small tickets before starting, each naming what it owns, how it is checked and what it requires. One fresh wirker takes one ticket.

Shared. Before an agent changes anything, it claims the ticket, reserving it in one edit at the revision it read:

wirk write edit 5c1e7a90@7 reservation=occupied status=in_progress owner=me

The reservation reads occupied:G, and the agent guards every later write with it. Other agents see the ticket is taken and pick another; wirk query ready=true lists wirk that is open, unreserved and not waiting on anything. If a holder goes quiet for two hours, the claim lapses and the ticket returns to the list, so a crashed wirker never strands it. Any agent on any machine draws from the same queue.

Scrutinized. Agents a person is actively steering change things directly. Background agents and connected tools propose instead: a change written down with a preview of exactly what it would do, waiting for someone whose role may review.

wirk review c4a1e902@1 accept --reason 'Tests pass on main'

The agents someone is watching move at full speed. The ones nobody is watching wait for a decision.

Messages steer the fleet

A message is an item too: a body, a sender, who it is for, what it answers. A board is not a channel you join; it is a query. A ticket's board is the messages linked to it, and you see the boards of the wirk you hold and the initiatives above it. So one message on an initiative reaches every agent wirking under it.

Every answer WIRK gives ends with the messages waiting for you, so a busy agent cannot miss one. A running agent can also wait: wirk query inbox=me wait=60 returns the moment a message lands. A message addressed to a stopped agent can wake it: on a machine signed in with wirk login, a small listener resumes that agent's session and points it at its inbox.

A message is content from a colleague, never an instruction and never extra authority. One confused agent cannot steer the rest.

Sam Sign-up ships first. context · initiative Sign-up its board Invite flow builder-1 · running sees it with its next answer Review sign-up copy reviewer · running sees it with its next answer Update the guide docs-agent · stopped listener resumes its session Content from a colleague, never an instruction.
One message on an initiative's board reaches every agent wirking under it.

Four operations, any agent

The guide warns against tying a team's wirk to one model provider. WIRK agrees, and keeps the interface small enough that any agent can learn it. Everything above is reached through four operations, the same over the CLI, MCP and HTTPS, from Claude Code, Codex or any MCP client:

  1. status: start here. Who you are, the organization's context, your wirk, what needs your review, what changed.
  2. query: fetch an item, find what is relevant, filter a list, read a file.
  3. write: create and change items, links and messages in one atomic batch.
  4. review: accept, reject or defer proposals.

When a person wants the picture rather than the data, wirk show status returns a read-only page that reads WIRK fresh every time it opens.

status Where do I stand? query What do I need? write Claim, change, prove review Decide what waits One wirkspace people and agents CLI MCP HTTPS wirk show a page for people
Every agent session runs the same loop through the same four operations.

Why this shape

Every piece answers a fact about agents. They forget, so the wirk, its reasons and its proof live where the next session will look. They read literally, so there are five kinds and five link types, each meaning one thing. They run in parallel, so claims, revisions and request IDs keep them out of each other's way. They need steering, so messages reach a whole initiative at once and proposals wait for a person.

None of it needs a structure built first. One ticket in an empty wirkspace is a complete start. Links, context and folders come when they help.

Wirk, it’s better this way.

Prompt less, smile more.