Concepts
On this page
Start with one work item: Prepare the launch checklist. It can stand alone in a wirkspace, the shared place for a team's items. Give it a title and a reason. Add an owner, status, or criteria when useful. A person can see what is planned and what was done; an authorized agent can read the item and update it as work proceeds.
Other items add detail when you need it. A record can hold the draft checklist or evidence; it is not another task. A context item can explain a team goal or an initiative. A link can connect the work to either one. Items remain flat: no initiative, folder, context item, record, or link is required before that first task.
When the checklist is completed, the edit includes evidence of the result. The item keeps its earlier revisions, so readers can see what changed. A proposal holds a suggested change for someone with review authority to decide. The sections below explain these parts and link to the operations and first-use guide.
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, each adding to the one before, and proposer, for agents only: a proposer reads and proposes, and applies nothing, completing work included. Agents are never administrators. An agent with no membership of its own acts with its person's role, capped at reviewer; an agent given a membership of its own acts only through it. 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. The wirkspace's administrators define fields; agents use them. Keys are stable; display names can change. status lists the keys and values your wirkspace uses. The launch checklist is work; a draft checklist saved as a record does not gain a work status just because it is linked.
Every item has one of five 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. |
context | The organization's context or an initiative (see below) |
folder | An item made as a folder |
record | Everything else: documents, uploaded files, transcripts, evidence |
message | A message sent with message.send, to people or agents or to an item's board; it never changes once sent (see Messages) |
Uploading a file or saving a transcript never creates a task by itself.
Completing work means changing its status to a completed value and providing evidence: text naming passing tests, a commit, a link or file path, or a file attached or cited in the same write. Any member who can read the work may make this status-only change with evidence. Changing its title, body, owner, or other details requires edit rights. The evidence is stored with who completed the work and shown on the item; the service does not judge it. In the CLI, provide it with --evidence; in MCP and HTTP, use 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. For example, the launch-checklist work might later contributes_to a launch initiative or cites a supporting record. Both links are optional. There are five types:
related_to
A ↔ B: the same topic. No extra data.
contributes_to
A → B: A is part of B, a parent work item or an initiative. An item can contribute to several parents. contribution says what A does for B, for example “Advances O1”; criteria says what parent work needs from A and does not apply to initiatives.
requires
A → B: work A cannot be completed until work B is. It gates completion, not starting. It may name a criterion_id.
cites
A → B: B is evidence for A at a pinned revision. A citation names target_revision, selector (the part of B) and relation (supports, contradicts or background), with an optional quotation.
relies_on
A → B: A assumes something stated in B as of a revision. When B changes, A is flagged for another look. It names target_revision and a one-line assumption.
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 decision. 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 under "Needs your review" for everyone whose role may review them.
- Anyone whose role may review, a person or an agent working for one, accepts, rejects or defers with review. Accepting is one action and applies the change exactly as previewed.
- Background agents never decide: they are set up with the editor role, which cannot review (
not_authorized: your role (editor) cannot review). A context proposal is decided by its maintainer or an administrator; an agent with no membership of its own whose person maintains it decides it too (below). An agent acts with its person's role unless it has a membership of its own, and a proposal's author may decide it like anyone else. - A decision names the proposal's revision you read, so you never decide on something that changed under you.
Organization context and initiatives
Context can carry the team's direction to agents. Three useful scopes are:
- Organization context: one item per wirkspace, shown under the wirkspace's 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. The launch checklist may contribute to one, but does not need one. - Work and evidence: flat items. Work may link to the initiatives it serves; evidence can be cited when a recorded source supports it.
Organization context and initiatives are items of kind context; they do not impose a hierarchy on work or docs. 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. See write for details of creating them.
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,
- [ ] O2: Partners can retry safely, checked off with its evidence:- [x] O2: Partners can retry safely (evidence 5bd3a0c3). Key decisions and open questions take keys the same way (- D1: …,- Q3: …): one or two capital letters and a number, then:,.or). The noticecontext_parsedcounts outcomes, decisions and questions without one.
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. An administrator's agent writes context directly, with its person's authority, unless it was given a membership of its own. When unsure, write it: a refused write applies nothing, and requires_review says to 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. - After any refusal, send the corrected body under a new request ID.
wirk query receipt=REQUEST_IDfinds the receipt of a write, review or upload when you lost the answer. An administration request is recovered by sending the identical request again, which returns its stored receipt.
Duplicates and suggestions
On the Pro and Enterprise plans, 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.
On Free and Team, nothing is refused as a likely duplicate and no link is suggested, and receipts don't say so: check titles before creating (wirk query 'Exact title', or text=). Ranking about= and a status task by meaning is on Pro too; on Free and Team, WIRK matches words and says so.
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.