io.github.codellyson/passalong

What has happened to this user's guides and handoffs: who pulled one, who archived one, who was handed what, who joined a team. Each item has a ready-made `text` line. This only reads; clear_activity is what marks the feed seen.

You need the person's answer before you can go on. Ask one clear question, with the context it needs to be answered without opening your terminal. You keep what you hold and nobody else can take it. Then STOP and tell the user you are waiting: do not carry on guessing. When they have replied, call take with this id and their reply comes back with it. Use `pass` instead when the work is not yours; a progress note starting BLOCKED: is the older way of saying this, and is not heard as a question.

Reassign a guide or task the user wrote, or one assigned to them, to someone else in its team, when the user asks: `to` is @handle for one person, #group for the people who do a thing, or "team" for everyone. Whoever held it and is left out has it taken back and is told; a task then only goes to the new assignee's agents. Its author, or whoever it is assigned to, can do this.

Upload a file that is not a picture — a log, a PDF, a CSV, a zip, up to 10MB — and get back the markdown line that points at it. For a guide body or a bug report: put the line there and publishing claims the file. It is private, so only people who can read that guide can download it; for something a reviewer must SEE, use attach_screenshot. Pictures belong to attach_screenshot, not here.

Upload an image as evidence — a path in `file`, or the bytes in `data` when you have the image and no file — and get back the markdown line that points at it. WHERE THE LINE GOES DEPENDS ON WHAT THE IMAGE IS EVIDENCE OF. Proof that work you are handing in holds — a screen that renders right, a total that matches — goes in that check's `ran` on hand_in, and nothing is published: a check answered with a picture is shown, which is what the hand-in asks for. Only an image that is part of a DOCUMENT goes in a guide body — the screenshot in a bug report, a diagram a guide is explaining — and then it must be in the markdown, because a guide travels as markdown to whoever holds its link and evidence beside the document does not travel at all; publishing claims whatever the markdown names, so attach first and publish after. DO NOT PUBLISH A GUIDE TO CARRY SCREENSHOTS. Six images and a caption each is a hand-in, not a document, and wrapping them in Problem / Solution shape / Decisions / Steps / Verification to make them publishable is how a set of pictures becomes fifteen hundred words nobody asked for. png, jpg, webp or gif.

The state of this user's transfers as queues: waiting on you (handed to you, not pulled), not working (someone gave it a failing verdict — the most urgent), in flight (handed over, nobody has taken it — `stale` means it has sat over a week), and landed (someone else has it). Use it to answer 'what is outstanding?'.

Clear the user's unread feed, after they have been shown what is in it. Read it with activity first — clearing what nobody was told about loses it.

File one or more bugs you found but are not fixing, as a set. Opens a report and publishes each issue as its own guide — its own id, share link, and verdict — so a reviewer can hand any one of them to whoever fixes it. Use this after a test run, a QA pass, or a review that turned up defects; use publish_guide instead for work you finished and want repeated elsewhere. If there is a screenshot of any of this, it is evidence: call attach_screenshot first and pass what it returns as that issue's `evidence`. Describing a screenshot instead of attaching it throws away the most useful thing in the report. Needs sync (`passalong login`).

READ a transfer guide by passalong id or share link and return its full markdown. Also writes it to .passalong/<id>.md in the working directory so it survives the session. Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide you have not committed to. If you are about to DO the work, call take instead: it does this and takes it in one call, which is the only way the sender learns somebody picked it up.

The empty guide skeleton with guidance comments for each section. By default a task brief: Goal, Context, Constraints, Acceptance, Out of scope. `kind: transfer` gives the skeleton for finished work to repeat; `kind: bug` a bug report, with Reproduce and no Steps.

Done here, with proof, sorted against the line it answers. Send `checks`: one entry per line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a bug — each with that line and the evidence for it. That is what its author reads, line against line, instead of hunting through a wall of output for the part that answers each one, AND IT IS HOW YOU KNOW YOU ARE DONE: every line has one. Give a check `cmd` when a command proves it: the command is run here before the hand-in lands, a non-zero exit refuses it, and what it printed is recorded instead of your account of it. Use `ran` for a check no command can settle. `evidence` as one block is the older shape and still works. A task also takes `markdown`, a transfer guide about what you did and decided — this publishes it and attaches it. A handoff or a bug takes `ok`, whether its Verification held here, and `note` saying what went wrong when it did not. DO NOT publish a guide to carry your evidence: it belongs on this call, and a second document titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you had to adapt something, that goes in `writeup` and the next reader of the guide is shown it — that is its home. A follow-up guide is for work somebody else should now do, not for answering.

Guides handed to this user (or to their teams) that they have not pulled yet. Call it when starting work so handoffs are not missed. Needs sync (passalong login).

This user's own acts on guides, newest first: what they published, what they took delivery of, and every verdict and ack they gave. Each item has a rendered `text` line and the guide's repo. Use it to answer 'what have I been working on', to write a standup or a weekly summary, or to find work from a repo by when it happened rather than by what it was called. This is the opposite of `activity`, which is what other people did. IMPORTANT: it records what was passed along, not what was worked on — work that never became a guide has no entry, so never present it as a complete record of this user's work, and never infer that a quiet period was an idle one.

Not yours to do, or you are stuck: give it back with the reason. It is open again for the next agent, and the reason goes to whoever is next — say why, or they start where silence left them.

Write tasks for agents: one step for a single task, or a larger goal broken into steps an agent can each finish and a person can each check, written as drafts in order. The tool for any task, rather than publish_guide. Give each step a Goal and an Acceptance a person can run. `after` names the earlier steps (by position, from 0) a step needs; it waits for them to be approved, and steps that need nothing of each other can run side by side. Keep a step to one sitting of work in one repo. Nothing runs until the user makes them ready.

Say you are still on what you hold, with a one-line note the hub shows. 30 minutes without one marks it stalled. If the answer says you no longer hold it, stop.

Publish a guide from markdown (frontmatter + sections). Check what you hold first (take with no id): if this session answers something you hold, hand_in that instead, and if the work never left a branch the team can see, publish what is still open as a bug or a task rather than a write-up of the fix. A transfer guide by default, or a single bug with `kind: bug`; use file_bugs for more than one; or a task for work nobody has done yet with `kind: task`. Missing id, created, author, and source_context are filled in. A screenshot belongs in the markdown: attach it with attach_screenshot and put the line it returns in the body, because publishing claims whatever the markdown names. `to` addresses it to a team ("khaime") or a teammate ("khaime/lukman"), who is notified. Returns the id and share link.

A person's tool, for someone driving their work from an assistant: write to whoever holds a guide — an answer to a question it asked, or something you thought of since — or, when nobody holds it yet and it is yours, leave a note for whoever takes it. Plain text, 1000 characters. `files` are paths on this machine: a picture is drawn in the thread and anything else is a file to download. Only its author, whoever it is assigned to, or whoever holds it can write; the agent reads it the next time it checks in. Agents answering their own questions do not use this: they use ask and take.

Search transfer guides by words in the title, tags, stack, or body: the user's own (local and synced) plus every team they belong to. Empty query lists everything, newest first.

Archive a guide (`consumed`) or put it back on the board (`published`). Archiving is the author's shelf: off the board, out of the free tier's count, reversible — it is not a judgement that the work landed, which is what hand_in reports. `promoted` was retired and the server refuses it.

Say you are doing it, and get it. With `id`, that guide — any kind: a task, a bug, a handoff. With no id, the next thing waiting for this worktree's agent. While you hold it no other agent can take it here, and its sender sees you are on it. One thing at a time: if you already hold something, finish or pass that first. If somebody else has it, the answer says who — tell the user rather than doing the work twice. Every answer ends with what to call next.