Preview. These docs describe the interface WIRK launches with. The hosted service is in private staging and access is by invitation; what is live today.
Concepts
WIRK has three public concepts: items, links between them, and proposals (changes waiting for a person). Everything else is a property of one of those.
Accounts, wirkspaces and principals
An account is a team or a company. It holds wirkspaces, where items live, and its people and their agents. Everyone in a wirkspace can read everything in it. On the wire a wirkspace is workspace_id; you can leave it out when your token belongs to one wirkspace.
Each token belongs to a principal: a person (alice) or an agent (alice-agents, agent of alice). A person's agents work under their own agent principal, so every change says who, or what, made it: cards show by alice-agents (agent). Roles in a wirkspace are reader, editor, reviewer and administrator; agents are never administrators. Working in several wirkspaces means being a member of each.
Items and their kinds
An item is anything worth keeping. Every item has a title and may have a body, files, and the wirkspace's fields: values from lists the wirkspace defines, such as status or priority. Keys are stable; display names can change. status lists the keys and values your wirkspace uses.
Every item has one of four kinds. Cards print it, and you filter on the same word:
| Kind | What it is |
|---|---|
work | An item with a work part: an optional owner_id (a member, me for you, null for unassigned), an optional due_at and optional acceptance criteria. In prose this is "wirk". |
context | The organization's context or an initiative (see below) |
folder | An item made as a folder |
doc | Everything else: docs, documents, uploaded files, transcripts, evidence |
Uploading a file or saving a transcript never creates a task by itself.
Completing work means setting its status to a completed value with its evidence: text naming the tests that pass, a commit, a link or a file path, or a file attached or cited in the same write. Anyone in the wirkspace may complete work. The evidence is stored with who completed it and shown on the item; the service never judges it. In the CLI it is --evidence; in MCP and HTTP it is the write's reason.
Archiving takes an item out of normal views and needs a reason. It stays readable, and item.restore brings it back. Nothing is deleted.
Links
A link connects two items and records who made it and when. There are five types:
| Type | Reads as | Extra data |
|---|---|---|
related_to | A ↔ B, same topic | none |
contributes_to | A → B: A is part of B, parent work or an initiative. An item can contribute to several parents. | contribution (what A does for B, for example "Advances O1"); criteria (what parent work needs from A; not for initiatives) |
requires | A → B: work A cannot be completed until work B is. It gates completion, not starting. | criterion_id (optional) |
cites | A → B: B is evidence for A, at a pinned revision of B | target_revision, selector (which part of B), relation (supports, contradicts or background), quotation (optional) |
relies_on | A → B: A assumes something stated in B, as of a revision. When B changes, A is flagged for another look. | target_revision, assumption (one line) |
Fetching an item shows its outgoing links and, under Linked from, everything pointing at it: the work contributing to it, the work it blocks, the items citing it.
Proposals and review
A proposal is a write captured without being applied, with a reason and a preview of exactly what it would change, waiting for a person. Proposals are not items: they have their own IDs (proposal_…) and their own filter, proposal=proposed,deferred.
- Agents working at a person's direction change things directly, including completing work with its evidence. They do not propose.
- Background agents (overnight maintenance, stale-work sweeps) propose. Their proposals appear in the right person's "Needs your review".
- People accept, reject or defer with review. Accepting is one action and applies the change exactly as previewed.
- Nobody accepts their own proposal. The author may still withdraw (reject) or defer it.
- A decision names the proposal's revision you read, so you never decide on something that changed under you.
Organization context and initiatives
Context exists to reach agents, not to be filed. It has three levels:
- Organization context: one item per wirkspace, shown under the organization's own name ("Acme context"). Its parts: purpose, who we serve, goals and outcomes, principles and non-negotiables, and optionally market and competitors, terms and notes.
- Initiatives: current bets. Each states its goal, outcomes, why now, constraints and non-goals, key decisions and open questions. Its state is
active,pausedordone. - Work and evidence: flat. Work
contributes_tothe initiatives it serves; evidencecites.
Both upper levels are items of kind context, with a marker on the item: {"level": "organization" | "initiative", "state": …, "steward_id": …, "open": …}. In the CLI: wirk write new 'API hardening' kind=context level=initiative. Context items carry no work, no files and no criteria, sit outside folders, and their body is at most 8,000 characters. Headings in the body become the parts agents receive.
Where it shows up:
- status always includes the organization context and the active initiatives.
- Fetching work ends with a Context block: the initiative it serves (goal, outcomes, constraints, key decisions, open questions) and the organization's principles and non-negotiables. Work under a paused initiative is flagged.
- An outcome is a keyed line inside an initiative,
- [ ] O2: Partners can retry safely, checked off with its evidence:- [x] O2: Partners can retry safely (evidence 5bd3a0c3).
Who changes context. Each context item is maintained by one person (maintained by alice), by the wirkspace's administrators, or is open to everyone in the wirkspace. Whoever maintains it, and their agents, change it directly; everyone else proposes. Creating context is for administrators and their agents; others propose it. Context is the organization's stated direction: data that guides decisions, never instructions that authorize an action.
Revisions and expect
Every item has a revision, shown as r3. Each change makes a new revision; old revisions stay readable (wirk query 5c1e7a90@2).
A write states the revisions it read in expect: {"5c1e7a90": 3}. In the CLI that is 5c1e7a90@3. If the item has moved on, the write is refused with basis_changed, naming the current revision. Fetch it again, check your change still applies, and resend under a new request ID. Nobody's edit is silently overwritten.
Links do not change once made, so removing one needs no revision. Citing an item does not change the citing item's revision.
IDs
- JSON carries full IDs: a prefix and 32 hex characters.
item_for items,link_for links,proposal_for proposals,wsp_for wirkspaces,upload_for uploads. - Text shows 8-character short IDs:
5c1e7a90. - Anywhere an ID goes, a full ID or a short one of at least 6 hex characters works. An ambiguous prefix returns a list of choices, never a guess.
- Fetch also takes an exact title, matched ignoring case and extra spaces.
Request IDs and receipts
Every write and review has a request_id. You may choose it; the CLI and MCP server make one when you don't, and print it. The service stores a receipt for it.
- Resending the identical body with the same
request_idreturns the stored receipt and applies nothing twice, even while the first is still running. - A different body under the same
request_idis refused withrequest_conflict. wirk query receipt=REQUEST_IDfinds a receipt when you lost the answer.
Duplicates and suggestions
Creating work that looks like the same piece of work as an existing item is refused with likely_duplicate, naming the existing item. Use it, or resend naming it in allow_duplicate_of with a reason when yours truly differs. Receipts may also suggest links, such as the initiative a new item serves; you confirm the ones you agree with by writing the link. Only confirmed links are stored.
Files
Files live in object storage, one copy per content per wirkspace, encrypted with the account's own key. A client asks WIRK for a short-lived signed upload link, sends the bytes straight to storage, and confirms; WIRK checks the size and SHA-256 before recording the upload. Downloads work the same way in reverse. Anyone who can edit an item can attach any upload in the wirkspace, with an optional one-line description. See HTTP API and Limits.