Markdown with frontmatter, and whatever shape the work needs.

A piece of work is one thing: a title, a summary for a person, and the text, pictures and files the next reader needs. There are no kinds, required sections or templates — the agent that takes it reads it and works out what done means. Under that, it is plain markdown, yours to grep, export and keep.

The fields, in order

Frontmatter is what the product reads: what the work is called, who it is for and where it came from. Strings and lists of strings only. Everything under it is for the reader.

title: What needs doing, in plain words. Required; it is the line on the board.
summary: One or two plain sentences for a person, 400 characters at most, no ids or paths. Required: it is what the hub shows first.
status: draft (read it first), ready or done (finished or archived). New work is Ready unless it says draft.
team: The team it is in, by slug. Without one it is yours alone.
to: Inside that team: @handle asks one person, #group asks the people who do a thing, several names ask each of them, and leaving it off asks the whole team.
id: 8 characters from a no-lookalike alphabet. An address, not a secret.
url: Its share link, written in by the server.
tags: A list. Lowercase, words joined by a hyphen. An agent may tag bug, feature or question as a description; no rule turns on a tag.
parent: The work this came from: a customer's request, or a bigger piece of work. Finishing it tells the parent.
blocked_by: A list of ids that must be Done before this one is handed out.
target_context: The repo it is for, as owner/repo, when there is one. Chosen when it is marked Ready if it has none.
stack_assumptions: A list, optional. The author's environment, to adapt rather than copy.

A document carrying kind: is refused by name: work has no kinds, and a field that used to steer the reader would now say something nobody meant.

The body

Free markdown. Write what the next reader needs, in the shape that fits: a sentence and a screenshot for a bug, a paragraph of context and a line saying "done when" for a feature. Nothing requires a heading. GitHub-flavored markdown renders — tables, task lists, footnotes and alerts (> [!WARNING]), so what must not be missed is not left to bold text.

What someone needs to know about a product — how it is built, a decision, what changed — belongs in its project's documents, not in a piece of work handed to one person.

How it is worked

Every piece of work is worked with the same calls, from the MCP server or the CLI, and each answer ends with what to call next.

take: Say you are doing it, and get it: by id, or the next one waiting. Nobody else can take it while you hold it.
progress: A one-line note at each milestone. Thirty minutes without one marks it stalled.
hand_in: Done, with evidence: what you ran and what came back, or a screenshot. It goes to Done; a person can reopen it with a reason.
pass: Not yours, or stuck: give it back with the reason for whoever is next.
ask: You need the person's answer. You keep it, stop, and take it again once they reply.

Share links

Every piece of work has a link, /w/<id>/<key>. The key is the secret: whoever holds the link reads it without an account, and appending .md gives the raw markdown. The page runs no script and is never indexed.

A piece of work

---
title: The upload button on Settings does nothing
summary: Clicking Upload on the Settings page does nothing on Safari. Whoever takes it fixes it.
team: acme
to: "#frontend"
tags: [bug]
target_context: acme/shop
---

On Safari 18, Settings → Profile → Upload does nothing: no file picker, no error.
Chrome is fine. Screenshot of the console:

![console](https://passalong.dev/v1/shots/k3mq2xa7)

Done when a Safari user can pick a picture and see it as their avatar.