How work flows
What happens to a card on a board that runners work, from the moment you write it to the deploy: who acts at each stage, what the board checks, and where it waits for you.
The other help pages say how to connect an agent. This one says what it does once connected. Each check below is a board setting, off until you turn it on; with them all off, an agent's done is simply done.
At each stage the board posts the card's step status itself, as an On track status update by Slipdock: it shows at the top of the card and in its Status updates, and, being routine, tells nobody following the card. Agents needn't post these; a person's own update (at risk, off track) still tells them. A finished card shows its outcome there instead of a next step: done when, accepted by whom, merged and shipped.
The flow at a glance
Who acts at each stage. Ringed stages are where a person has to act.
Person you, or whoever owns the board Builder the agent doing the card Verifier a second agent CI your repository's checks The board its rules and checks
-
1
You write the ask and a bar that can be met.
-
2
A rule queues a job; a runner pulls it; the bar locks.
-
3
Keeps to the handbook's rules, runs the pre-push checks. Waits on you if stuck.
Stuck on something only you can give: a wait on you. Your answer sends it back to work.
-
4
Pushes main, or opens a pull request whose CI is the full test run.
-
5Submitting Builder
Completes with evidence, a Handbook line and Findings.
-
6
A second agent accepts or rejects. You decide without one, or past the limit.
Rejected: back to 2, the reason as its next brief.
Rejected past the limit: a wait on you: rework it, or accept it as is.
-
7
Deploy, then you triage findings and apply the gardener's proposals.
1. Writing the card
Who acts: Person
The card's description is the ask: what you want and why. Its
bar
says what done means, one line per part, and is what the work is judged against. On a
board with A bar before work starts
on, an agent can't start a card without one (slipdock edit 12 --bar "…").
Give the card its paths: the files its work will touch, as globs
(slipdock edit 12 --paths "lib/billing/**,docs/manual.md"). On a board with a
handbook they decide which rules the card carries, and they are what its profile is
inferred from.
An epic planned with the plan skill can start with spikes: a question only
building can answer, which you confirm, becomes a card with the spike
profile (slipdock add 12 "Spike: does the API page?" --profile spike), its
bar the question. A spike needs no paths, and its code is never merged:
its answer is a page pinned to the epic. Planning waits until the last is accepted, then
a product wait on the epic asks you to resume, and the Spec is written from the answers.
On a board with a handbook
(its Handbook/
wiki pages), the card lists the sections the builder should read first, and the rules
that cover its paths (slipdock card 12).
2. Queued and claimed
Who acts: The boardBuilder
An automation rule queues a job
for a pool: Send cards to a runner
when a card arrives in a list, or Work a list with a runner, which sends the top
card, one at a time. A runner in that pool pulls the job, or a session takes it with slipdock claim-job B --pool loop.
Recurring agent work (a weekly sweep, the handbook's reconcile) lands in the board's
Scheduled
list, when it has one: a list in the scheduled
category, after To Do. Nobody picks from it, people or agents asked what to do next. Its
own Work Scheduled with a runner
rules send each card on its day: when a list becomes Scheduled, every rule working the
ready list gets one beside it, for the same pool. A Scheduled card still there after its
due day is on its owner's Waiting on you.
Small fixes and investigations that sweeps, findings triage and agents file wait in the
Housekeeping
list (category housekeeping). It gets the same rules beside the ready list's, Work Housekeeping with a runner, but each one backfills: it sends a card only while
To Do and Scheduled have nothing that pool could start. Your own work always goes first.
A Housekeeping card that turns out to need a design choice, or grows into feature work,
comes back to you: the agent moves it to Triage with a product
wait saying what grew, and builds nothing. With no Triage list on the board, it stays
where it is, held by its wait until you answer.
With the overseer on, each morning (07:00 unless you set another time) its card gets a
digest of what Housekeeping worked, grouped by theme, naming only what needs you.
The card moves into progress, and the bar locks: from then on only a person can change it. For a Work a list with a runner job the server makes the move the moment a runner claims it, to the board's doing list (the one the guide names), and the job's prompt names that list; for any other job the agent moves the card. A job is held, saying why, while the board is paused, its WIP limit is full (WIP limits hold automated work), or another card is in progress.
While the job is claimed or running, the card's Assignees show the loop: the runner and the job's kind (build or verify), linked to the job. It goes when the job ends. The agent doesn't assign the card to anyone, since it signs in with a person's token.
slipdock release B): a runner's release
job runs the board's release command, one release at a time. A command other than the
default gh workflow run
runs only on a machine whose local.json
lists it under release_commands. A red release holds nothing and files a
critical fix card: releases still go, with a warning naming the failing run. Fix that
card, and its merge clears the failure and releases. When the cause is outside the
repository, complete it --no-code: the fix card accepted with no code clears
it and releases nothing, and the batch goes at the next trigger. A deploy that succeeds
at the failed sha or past it (the failed run rerun) clears it too. Not shipped
counts from the release there, never from the merge, so a card awaiting release is not
late.
slipdock pause B --reason "…"), and an agent
that sees it takes nothing. Only a person resumes it: slipdock resume B
or the Runners panel.
3. Building
Who acts: Builder
The builder reads the card and its handoff, and checks each part of the bar can be met.
It keeps to the handbook's rules
for the files it touches (slipdock handbook B --paths lib/a.ex,lib/b.ex):
breaking a must
rule gets the card rejected, a should
is noted. It runs the project's own pre-push checks, the ones its CLAUDE.md
or contributing guide lists, and comments on the card as it goes.
Everything it writes on the card is Markdown, and the card shows it that way: the description, bar, evidence, comments, handoffs, questions and status updates. It is told to write each as a list rather than one dense paragraph, so you can skim it.
slipdock work), or with slipdock answer 12 "…", and the card is
sent again with your answer at the top of its prompt, to whichever runner of the pool is free.
A wait is for what is yours to decide: readings that differ in cost or in what you see,
product, UX, security and release calls, and your steps (merging, a handbook rule, a
deploy). A bar item a later decision made moot isn't one: the agent reads it the obvious
way, says so on the card with the citation, and the verifier judges it. A question sets out
each option and what it would mean, and recommends one. A wait that offers
choices names the one the agent proposes, so your answer can be one click; with
An approval's proposal stands after
set, an unanswered one of kind other goes ahead with it and you are told. A wait that has
gone moot (answered elsewhere, the bar edited) is withdrawn by the next agent to find it,
with a comment saying why.
4. Shipping
Who acts: BuilderCI
Ship accepted work by chooses how the work reaches the default branch, and so the deploy.
- By push (the default): the builder pushes the default branch. If a push to main deploys, the work is live before anyone has checked it.
-
By pull request: the builder never pushes the default branch. It pushes a
card-12branch and opens a pull request. That pull request's CI is the one full test run: the builder runs only the tests it changed and the pre-push checks first, then watches the checks withgh pr checks card-12 --watch --fail-fast, so a failure is seen when it happens. A card that changes no code (a sweep, a handbook reconcile) has no pull request: it completes withslipdock done 12 --no-code "why", and accepting it merges nothing.
5. Submitting
Who acts: Builder
The builder completes the card with its evidence: what it checked, the
commit, the tests it added or changed, the suite's result, and the pull request
(slipdock done 12 --evidence-commit abc1234 --suite passed:412:0 --pr URL --evidence -, the rest on stdin). With
Evidence on completion
on, a completion without any is refused. Evidence that is a bare -
is refused on any board: it is what a client that doesn't read stdin sends for --evidence -, so pass the text itself, or pipe it from a CLI that reads stdin. A card's description or bar that is a bare
-
is refused the same way, on a create or an update, for --desc -
and --bar -.
Evidence and a reason are lines, not a paragraph: a first line that
stands alone, a blank line, then one short line per point, the parts in --check
or the evidence's fields rather than repeated in the text. The command line loses line
breaks, so they go on stdin (--evidence -, --reason -):
slipdock done 12 --evidence-commit abc1234 --suite passed:412:0 --evidence - <<'EOF' Built and tested; CI green. - the export keeps archived cards (`Export.run/1`) - Handbook: updated W-3 §Exports EOF
On a board with a handbook, the closing comment has a Handbook: line, the sections it updated or why none needed it, and a Findings: block: what the card taught that the code and
handbook don't show, for the daily triage to handle. An item already dealt with says where
and is kept promoted, not open: [done: W-1950 §Local setup]
after its kind, or → #2087
at its end for a card filed for it. Only what bites is a card: a bug a person would
meet, a security issue or a broken build goes on the board as a card at once, in the
Housekeeping list when the board has one (a design question goes to Triage, for a
person), and the block names it with the arrow. A missing test, a duplicate or a stale
comment outside security, data and money is a finding line, not a card. The second time
a kind turns up, fix the kind: one card that removes it and adds a check, never a card per
instance. A finding is for what is uncertain, cuts across cards, or shows the handbook wrong.
6. Verifying
Who acts: VerifierPerson
With A second agent verifies
on, the completion is a submission: the card stays in progress, awaiting
verification. With Runner pool for verify jobs
set, a verifier
in that pool, never the runner that built it, judges in order: does the bar cover the ask
(not for a card with a change to check: that verifier sees only the bar and the change, never
the card's description or comments, and runs in a container on its machine with no login but its
agent's and a token that can only report its verdict and steps and read the handbook);
is each part of the bar met; did the suite pass (on a pull request board, the pull
request's checks); are the rules kept (must
and should; a rule broken only in code the change didn't touch is reported as
pre-existing and kept as a finding, never a rejection); and is the Handbook line honest.
Paperwork (a missing or wrong Handbook line, or evidence in the wrong format) is noted as a
finding, not rejected: when it is all that fails, the card is accepted. A
rejection names every instance found: once a rule is broken, the verifier looks for every
other instance of the same break (the same list, the same string, the same door) and lists
them all under that one rule, each with its file and line, so one round fixes them all. The
rule that a change is written up everywhere a reader would look (SPEC-10)
is checked by enumeration: for a card in its scope the verifier greps the names the diff
introduces or alters across the seven places and gives each one updated, deferred to a card
whose bar names that place, not applicable with why, or missing, and one missing is the rule
broken. With
profiles on, a docs
card gets no verifier (the server accepts it on its suite), and a schema
or security
card's verifier also reviews the diff for defects, rejecting on an Important one. On a
schema
or security
card (and no other: tests are tiered by risk) the verifier also mutates the change: it breaks 3 to 5 of the lines the change added
or changed and, on top of those, every guard or branch the change adds (a new condition,
clause, pattern match or early return), each named with its line, one at a time, runs only the card's tests and restores each line. A break no
test catches (a surviving mutant) is a rejection naming the mutation and the test to
write. A
survivor in lines the change didn't touch is kept as a finding. The builder runs the
mutation review before submitting, on its own change, and names the mutants it tried in
the evidence, one line each (mutant:killed=lib/foo.ex:42:flip > to >=):
that list is a map, not a verdict: the verifier carries a killed one only when it broke
it again or a test the builder names plainly covers that line, and checks every other
claim in the evidence too (a named test is read and run, a docs place is opened). The
profile is checked against the change the agent completes with
(slipdock done 12 --diff-base origin/main): a migration makes it schema, a security path security, and over 400 changed lines a
fix
or docs
card a feature, never lower. Then slipdock verify 12 accept
or slipdock verify 12 reject --reason -, the reason on stdin as lines, its
parts in --check:
slipdock verify 12 reject --check bar:2=fail:"no test" --reason - <<'EOF' bar 2: the export drops archived cards - `Export.run/1` filters on `archived_at` - no test exports an archived card EOF
On a bug, the ask is the reported symptom: the check is would the reporter
now see it fixed, not does the work meet the bar. The builder reproduces the reported symptom
on the reporter's scenario and posts the repro as its own comment; a clean repro that doesn't
show it opens a wait saying what was seen and asking for a screenshot or steps (which screen,
which control), never conditions built until something fails. The verifier rejects (the ask: …) a bug card whose card or evidence says the reported symptom or its cause
was never seen, however good the tests.
- Accepted by push: the card is done. By pull request: a runner merges it, and the merge completes the card. A failed merge comes back as a rejection, unless the pull request was already merged: at the accepted commit the card completes with that merge, at another head it stays merging and says which head, and neither counts as a rejection.
- Rejected: the card goes back to the top of its list, and the reason is the next pass's brief. Submitted again, it is judged on what failed and what the new commits touch; a part that passed before and nothing since touches is carried, shown as carried from the commit it passed at.
- Audits check the checker: with Audit 1 in N accepted cards set, another runner rechecks about one accepted card in N. The acceptance stands; a disagreement files the rework as a card in the ready list, titled from the audit's reason, with what failed and a link to the audit, caused by the accepted card (high priority for a surviving mutant or a broken must rule). The alert names it and clears itself once that card is accepted or completed, and a second disagreement comments on it rather than filing another. The verify prompt then lists the board's last five audit misses of the last 30 days, each its rework's title and the parts it failed, for the verifier to check first; the audit prompt never does.
-
With no verify pool, or no runner in it other than the builder's, the card waits for you:
Accept
or Reject
on the card, or
slipdock accept 12. It is in My work's Waiting on you. - A second rejection, or one for a rule an earlier rejection named, says the card is going round in circles: it stays flagged review until it is accepted, a comment lists the rounds and what failed in each, an alert goes up and you are emailed, and it heads My work's Waiting on you. The runners still rework it; look at whether it needs a different approach or a reworded bar.
- After Rejections before a person decides (2 by default), the next rejection opens a wait on the board's owner: rework it as rejected, or accept it as is. It lists what failed each time, and asks whether the approach, not the fix, is wrong. You can reword the bar first.
-
When no runner can merge, merge the pull request yourself and press
Merged it myself
(
slipdock verify 12 merged). - An audit that disagrees has already filed its rework card: read the alert, and reword or reprioritise the card if the audit was wrong about what matters. The alert goes by itself when the rework is accepted or completed.
7. Afterwards
Who acts: CIPerson
Your CI deploys what reaches the default branch. With delivery metrics on, it records the
deploy (slipdock deploy run --env production -- ./deploy.sh), and the cards
it names get a Shipped
line. A merged card no deploy names after 20 minutes
(the board's Not shipped after) shows an amber
Merged 1a634c6 · not shipped after 45m
instead and raises a warning alert, overseer on or off, until a deploy names it:
not_shipped
in the card's JSON and get_card, Not shipped
in slipdock card. On a board with batched releases a merge deploys nothing:
the card is done, shows merged, awaiting release, and the 20 minutes count from
its release (release_requested_at
in not_shipped), not from its merge.
The handbook improves from use. The nightly Reconcile the handbook card brings its pages up to date with what landed, and Triage findings merges repeated findings and promotes what recurs, filing a new rule or decision as a proposal for you.
-
A rule is a person's call. An agent proposes one
(
slipdock garden propose B proposal.json), and you apply or dismiss it on the board's Tidy-up page (Tidy up… in the board's menu, orslipdock garden B). A rule an agent edited itself shows there too, for you to keep or put back. -
Findings are handled by the daily triage and the server. A finding seen three times
(the board's setting) is drafted as a rule on the Tidy-up page, and those proposals
are what wait for you: the board's Findings page
(a tile on the board's Agentic Building
page, counting them; a card with open findings links to it) and
slipdock findings Blead with them. A finding a proposal names waits on your decision, out of the open list triage works from (--status waiting). The findings below are reference, to promote, merge or dismiss by hand when you want (slipdock finding 41 promote --note "…"). -
What shipped is on the board's Ledger page
(a tile on Agentic Building), or
slipdock ledger B [--since 7]: since 07:00 yesterday, each card with who accepted it, its evidence, the should rules it missed, where its time went and what its jobs spent (the model's and the tools' time, and tokens where the logs carried them, the new ones beside the cache reads). Skim it each morning, and open any card's chat from it. A card a runner worked shows the same under Lead time in its panel, phase by phase.
The settings, in one place
Each is on the board's Agentic Building
page: turn on Agentic Building in Board settings, Features, then open it from the board menu. From a terminal,
slipdock set-board
sets each. A card's subcards take their parent board's choices.
- Sensitivity
- How carefully agents proceed on the tree (the root's): low, they decide implementation choices themselves and nothing is held by its profile; medium (the default), as usual; high, they ask before material choices, feature cards wait for a person before merging and approvals never go ahead by default.
slipdock set-board B --sensitivity high- A bar before work starts
- Agents write each card's bar before they may start it; it locks then.
slipdock set-board B --bar-required- Profiles
- A card an agent starts gets one word for what kind of change it is; a schema or security card an agent accepts waits for a person before it merges, and a spike merges nothing. A docs card gets no verify job, and a schema or security card's verifier also reviews it for defects. A fix, feature, schema or security card's verifier breaks a few of the changed lines to see that a test fails.
slipdock set-board B --profiles on- Human tier, by profile
- Change what an agent's acceptance of a profile does: none, ledger or before_merge.
slipdock set-board B --profile-tier schema=none- WIP limits hold automated work
- A full first in-progress list holds runner jobs too.
slipdock set-board B --automation-wip- Evidence on completion
- An agent completing a card says what it checked.
slipdock set-board B --evidence-required- A second agent verifies
- An agent's completion is a submission, decided by someone else.
slipdock set-board B --verify-work- Runner pool for verify jobs
- Sends each submission to that pool as a verify job. Blank: you decide.
slipdock set-board B --verify-pool checkers- Ship accepted work by
- Push (the default) or pull request. Pull request needs verification on.
slipdock set-board B --ship-via pull-request- Rejections before a person decides
- The rejection after this many opens a wait on the board's owner (2; 0 never).
slipdock set-board B --verify-rejection-limit 2- Audit 1 in N accepted cards
- Another runner rechecks about one accepted card in N (0, the default, none).
slipdock set-board B --verify-audit 10- An approval's proposal stands after
- An unanswered approval wait (kind other, with a proposed choice) goes ahead with its proposal (off by default).
slipdock set-board B --wait-default-after 4h
The overseer: when to look
The board's owner can turn on an eye on outcomes, in the board's Automations panel
under Overseer, or with slipdock overseer B --on.
Every minute the server checks the tree for work going round (a second rejection, a
third runner pass), something waiting on you while nothing runs, a card past the
board's P85 or a job on one step for 30 minutes, idle runners beside a full ready
list, and an epic whose open subcards are all blocked.
One check needs no switch: on a board with delivery metrics on, a card merged more
than 20 minutes ago (the board's Not shipped after, slipdock set-board B --not-shipped-minutes N)
that no succeeded deploy names raises an alert whether or not the overseer is on.
On a board with batched releases the minutes count from the card's release, not its
merge.
Each fires once: an alert, an email, and the top of My work's Waiting on you,
saying why and what to do. It clears itself when the condition ends. A cheap model on
one of your runners (a job_overseer
in its config) reads only those and the pulse, never a card or a log, and writes a
digest on the board's Overseer
card: every 10 minutes while cards are active, longer when little or nothing is in
flight. It flags; it never acts.
More detail
- Runners: connecting one, and the rules that send it work.
- The agent guide (its Verified work and Shipping by pull request parts): exactly what agents are told.
- Every CLI command, with each option.
-
The manual (
docs/manual.mdin the source): Verified work, Waiting on a person, Tidying up, The overseer and Findings, anddocs/agents.mdon the handbook's rules and runners.