dadamsuk/slipdock-work

Working from the slipdock

The board is the plan of record: what to do next, and where the record of what happened goes. The server documents its own conventions — read them first, once per session, before choosing or updating anything:

slipdock guide                    # markdown, from GET /api/guide

Without the CLI on this machine — which is the usual case, since the CLI needs Elixir:

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"   # ask the user if neither is set
curl -s -H "Authorization: Bearer $SLIPDOCK_TOKEN" "$B/api/guide"

The server's address comes from $SLIPDOCK_URL, else ~/.config/slipdock/url (written by slipdock url or by the server's /install.sh). If you have neither, ask the user for the address of their Slipdock rather than guessing at one — a hosted board is something like https://app.slipdock.us, a self-hosted one whatever name they reach it by.

Pass the token if there is one ($SLIPDOCK_TOKEN, else ~/.config/slipdock/token). The guide needs no token, but with one it ends with the user's actual boards, every list on them, and which list is the ready list, the backlog, the one for work in progress and the one for done work — which is exactly what you need in order to pick something up.

The guide wins over this file. It comes from the running server, so it is current: the endpoints, the vocabularies and the board layout in it are generated at request time. This file only tells you to go and get it, and what to do while you have not.

Finding something nobody can name

slipdock cards <board> --search Q filters one board by substring. Its other filters ask about state instead of words, and they are the ones that answer "what should I pick up": --deps ready leaves out anything waiting on an unfinished card, --no-assignee leaves out other people's work, --due overdue is what has slipped. So the eligible list is one call:

slipdock cards <board> --column "To Do" --open --deps ready --no-assignee

slipdock search <words...> is different: it matches by meaning, across every board the user can see, and covers comments and status updates as well as cards. Use it when the user describes a thing rather than naming it ("the card about the refund rounding problem"), when what you want was probably said in a comment rather than a title, or when you do not know which board to look on. Read the matched chunk it prints, then slipdock card <id> for the whole card before touching it.

The short version it will expand on

• Epics and subcards. A top-level card is an epic: an outcome, holding the priority, dates and discussion. The work lives in its subcards, one sitting each. Checklist items are the steps inside a task. New work you discover goes under the epic it serves, as a subcard — not as a new top-level card.
• Picking. Finish what is already in progress; then the ready list (To Do), and the backlog only when nothing there is eligible. Highest priority first, position in the list breaking ties. Skip anything completed, archived, blocked, waiting, snoozed, or assigned to someone else — --open --deps ready --no-assignee does most of that skipping for you (snoozed cards are left out of slipdock cards already) — and any stand-in (↪stand-in-for:#N): it only marks where a card went into a sprint. If the board answers PAUSED (paused in the JSON), a person has held runner work on it: take nothing and stop. When the card you land on has subcards, descend into it and work those to done before coming back up for the next top-level card.
• Updating as you go. Move the card to in progress and assign it to yourself when you start; comment at every decision, surprise or dead end; flag it (blocked, review) with a comment saying what you are waiting for; when only a person can give what you need, open a wait and stop (slipdock wait <id> "what you need" [--on EMAIL] [--choice X]..., or update_card wait; several questions go as --question Q --question Q / questions, one each, never one block): it flags the card waiting, and answering it (slipdock answer) gets the work going again — or, when what it waits for has a date, snooze it instead (slipdock snooze <id> <date> --note "…"): it leaves the lists and comes back on the day, at the top of its list; on finishing, set completed: true and move it to the done list. Complete an epic only when its rollup shows every subcard done.
• Verified work, where a board has it on (its line in the guide says verified work: …). Write the card's bar before starting it (slipdock edit <id> --bar "…"), and never try to change it once work has started. Complete it with what you checked (slipdock done <id> --evidence-commit <sha> --tests a,b --suite passed:38:0 --evidence "…"). On a board where a second agent verifies, done submits the card and leaves it pending: don't move it to Done yourself. A rejected card comes back with its reason in the comment, the job's prompt and get_card's rejection (the handoff says Rework: …): read that reason first, since it is the next brief. Verifying someone else's card (never your own) means checking out the evidence's commit in a clean tree, running the suite (on a pull request board, checking its CI passed at that commit instead), judging it against the bar, then slipdock accept <id> or slipdock reject <id> --reason "…". On a board that ships by pull request (the board's line says so, as do the claimed job's prompt and slipdock card), never push the default branch: commit on card-<id>, push it, open the pull request once (gh pr create --head card-<id> --title "<title> (#<id>)" --fill; a rejected card's next attempt pushes the same branch), watch its checks (the full test run: before pushing, run only the tests you added or changed), and complete with slipdock done <id> --pr <url>. Accepting the card merges it; don't merge it yourself. A failed merge sends the card back rejected with the reason: rebase the branch and submit again.
• Lanes, where they are on (the board's line in the guide says lanes: on). Before starting a card, write the paths its work will touch: slipdock edit <id> --paths "lib/foo/**,docs/manual.md", as narrow as the brief allows. A move refused for overlapping a card in progress names that card: narrow the paths, or leave the card blocked by it; only a person overrides a lane. On a push board a card awaiting verification frees its lane and its dependents; on a pull request board it holds both until the merge. Whether or not the board has lanes, on a card with paths stage only files under them, by name, and with another session active in the same repository work in a git worktree of your own (git worktree add ../<repo>-lanes/card-<id> -b card-<id>), unless a runner already put you in one ($SLIPDOCK_WORKTREE).
• Read the handoff first, leave one when you stop short. A card's handoff (Left off: at the top of slipdock card <id>; handoff in its JSON) is where whoever had it last left it: the one next step and a short note. Read it before the comments when you pick a card up. Whenever you stop with a card unfinished — end of a session, handed back, blocked, out of time — leave one: slipdock handoff <id> --next "<the one next step>" --body "State: … Gotchas: … Open: … Pointers: …" (over MCP, leave_handoff). It replaces the last one; the history is kept. Comments stay the running log; the handoff is the now. On a finished card the handoff is for the person: what they must do, check or know (a deploy, a reinstall, a question, a caveat) as --next, with where things stand in a few bullets. Nothing left for them: leave it blank, and slipdock handoff <id> --clear one left from earlier.
• Re-read the card before you push, and its comments after. Once the work is checked, slipdock card <id> again: a changed description or a comment newer than your claim is still this card — do it before committing. Once the build has started, read the comments once more for anything added meanwhile.
• Incidents and deploys. When the board records deploys (slipdock dora <board> answers rather than saying delivery metrics are off), an outage or a broken release is an ordinary card tagged incident; if you know the deploy that caused it, slipdock incident-of <card> <deploy-id>. Name the card in the fix's commit (#57), as with any card: that is how its deploy is counted as a fix and the card gets its Shipped line. Never record or finish deploys by hand — that is CI's, with its own token.
• Tidy-up suggestions are the person's to decide. slipdock garden <board> (over MCP, garden) lists what the board's gardener found: epics done but open, cards stuck in progress, duplicates, orphaned pages. Show them when asked to tidy up, and apply (slipdock garden apply <id>, garden_decide) only what the person approves; working unattended, never apply or dismiss one — a dismissal is remembered.
• Long-running work gets interim updates. If the task will take more than a short sitting, comment at each milestone while it is still running — what has landed, what is left, anything that changed the plan — and move percent_complete with it. One write-up at the end is too late to be useful: a card in progress with nothing newer than the move on it reads as abandoned. An epic running across several sittings gets the same treatment, one line as each subcard closes.
• Comments are Markdown, and are skimmed. Open with a bold line saying what it is (**Picked up.**, **Built.**, **Decision:** …), then short bullets, one fact each, with paths, commands and commit ids in backticks; never one dense paragraph of clauses. Send anything over a line with slipdock comment <id> --body - <<'EOF' … EOF (quoted, so backticks survive); words on the command line lose their line breaks.
• Commit, and link it. When the project is a git repository, commit the card's work once it is complete — before closing the card — with the card id (#42) in the commit message. The closing comment links to the commit, or to the PR if one was opened (Commit: https://github.com/…/commit/abc1234). With no remote to link to, give the short hash and branch instead.
• Token cost in the write-up. The closing comment on a card ends with a line giving the tokens the work used, e.g. Token cost: ~135k tokens (context budget 15.00M → 14.86M, claim to close). Take a reading of the remaining-token counter (total_tokens left in system messages) when you claim the card and again when you close it, and give the difference. If several cards were worked in one stretch, measure each from its own claim. If no counter is visible, say "Token cost: not measured" rather than estimating. Add the same figure to the epic's progress comment.
• Read their favourites first. slipdock favourites lists the boards, lists, cards and saved views this person has marked — where they actually work, which a list of boards does not tell you. When "what should I work on next?" is asked without naming a board, a favourite is the strongest hint you have. They are personal: never add or remove one unless asked.
• Archived boards are work that has been set aside. slipdock boards leaves them out on purpose; --all shows them with an archived state. Everything on one still reads and writes, but never pick work off an archived board without asking, and never put new work there.
• Write down what the card cannot hold. A board says what is being done; it is a bad home for how something works, what was decided and why, or the shape of a thing. Those go on the board's wiki — slipdock page ls <board>, slipdock page read <page>, slipdock page new <board> <title...>. The test is whether it will be read again after this card closes: a decision, a runbook, a spec or an investigation's findings will be, and belongs on a page (linked from the card's closing comment by its code, W-31); progress, blockers and what happened now belong in a comment on the card. Never both — a page that repeats the comments is a page nobody trusts. Search before writing one (slipdock page ls <board> --q <the thing>): extending the page that exists beats a fourth page about deployment. Pass --message on every edit, and --base-hash on any edit to a page you did not just write yourself, so a save can never quietly land on top of someone else's.
• Keep titles short. A card title is about 60 characters at most, a series as <Series> <n>: <what> (Agent supervision 5: Parked jobs), the detail in the description. A card's title becomes a folder and shows in tight lists, and a sequence of cards that share their first 40 characters can't be told apart there.
• Don't delete cards (archive instead), rewrite a title to match what you actually did, tidy other people's cards, or leave a card in progress with no comment newer than the move. Archiving or reordering a whole board is further still from your business: only on an explicit ask, naming that board.

When this applies

• "What should I work on next?", "carry on with the plan", "work through the backlog", "next task" → fetch the guide, then pick by its rules and say which card you took and why.
• "Put this plan on the board", "break this into tasks" → epics with subcards, per the guide's shape.
• You are already mid-task on something that came off the board → the card is where progress, decisions and blockers get written, as they happen rather than in one dump at the end.
• You finished something that came off the board → close it out on the board before reporting it done here.
• You were started for a runner job (your prompt begins "Work on Slipdock card #N", or you took one with slipdock claim-job / the MCP claim_job) → work that card as usual, and also report on the job: slipdock job-progress <job> --message "…" (the note is a comment on the card too, and it renews the job's lease — never leave 20 minutes between them), stop if it answers cancel, and end with slipdock finish-job <job> --status done|failed --summary "…" once the card is closed or handed back. Need a person? Open a wait (slipdock wait <card> "…") and stop: the job is parked, and the answer starts a fresh one. The card may be a subcard of the job's card: ask on the subcard itself.
• "What is waiting on me?", "what needs me?" → slipdock work: waits on you, review and waiting flags on your cards, runner trouble, cards in progress with nobody on them, oldest first. Answer one with slipdock answer <id> "…" (or --choice N) — only with the user's own answer.
• The work produced an answer someone will want again — a decision, a runbook, a gotcha, the shape of a design → a wiki page on that board, named in the card's closing comment.

One board is not work: Getting Started, the tour the server builds for a new account. Its cards are instructions for a person to follow in the UI, so never pick one up, finish one, or tidy the board. If it is the only board there, say so and ask what the user wants doing.

For command and endpoint syntax, slipdock --help and the slipdock skill; the API is the contract and the CLI is a convenience. Report card ids back to the user as #42 so they can find them in the UI, and call a board by its code — the short, unique handle each board has (qvm-v1-rem for "QVM V1 Remediation"), which slipdock boards lists and every <board> argument accepts. It is stabler than a name and unambiguous where a name is not.

If the board is unreachable

could not reach … means the server is down or SLIPDOCK_URL is wrong, and 401 means the token is missing or dead (the user makes one under Account → API tokens). Say so and ask. Never guess at what is on the board, and never report work as tracked when the write did not land.