CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

kanban

Tracks coding work on a file-based kanban board: turns requests into cards with testable acceptance criteria and records verification evidence. Use for kanban board requests.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Kanban board

Hard rules

  • node .kanban/tools/kanban.mjs is the only sanctioned mutation path. Never hand-edit a card file, never hand-edit BOARD.md.
  • Never edit the JSON block between <!-- kanban:record:start --> and <!-- kanban:record:end --> inside a card, and never generate or repair the surrounding Markdown sections by hand. Read the card; write through the CLI.
  • BOARD.md is generated. Regenerate it with render; never patch it. standup --write likewise owns STANDUP.md.
  • Never pass a gate flag, fake a TTY, edit a record to look approved, or otherwise work around a gate. Hand the exact gate command to the user instead.
  • If the CLI refuses, the refusal is correct. Fix the cause it names and retry the same command.

The board

Cards are Markdown files under .kanban/cards/<ID>.md; archived ones move to .kanban/archive/. Columns are backlog → todo → doing → review → done; blocked is a flag on top of whichever column holds the card, not a column. Every mutation appends to .kanban/log/events.jsonl.

Card ids are opaque random tokens such as K-7F3A. Never construct one, never infer a position or order from one, and never renumber or reuse one; always use the id a command printed or list returned.

.kanban/cards/ and .kanban/archive/ are tracked in git and merge like code. BOARD.md, .kanban/log/events.jsonl, .kanban/.tmp/, and .worktrees/ are gitignored.

Commands

Prefix every command with node .kanban/tools/kanban.mjs.

CommandExact formUse it to
listlist [--status <column>] [--blocked] [--search <text>] [--json]survey the board; --search matches title, id, and tags
showshow <id> [--history] [--json]read one card plus its event history
nextnext [--n <count>]get the highest-priority unblocked todo card
newnew --title "<title>" [--priority P0-P3] [--estimate 1|2|3|5|8] [--tag <tag>]... [--accept "<criterion>"]... [--status backlog|todo] [--order <n>] [--note <text>]create a card; the id is generated for you
movemove <id> <column> [--note <text>]change column
blockblock <id> --reason "<concrete blocker>"flag a card as blocked in place
unblockunblock <id> [--note <text>]clear the blocked flag
check addcheck add <id> --name <name> --command "<exact command>"declare a verification and the command that proves it
check setcheck set <id> <name> [--status pending|pass|fail] [--evidence "<observed result>"] [--command "<exact command>"]record the observed result, or correct a mis-declared command
linklink <id> [--branch <name>] [--commit <sha>]... [--pr <url>] [--file <path>]...attach the branch, commits, touched files, and the PR
unlinkunlink <id> [--clear-branch] [--clear-pr] [--commit <sha>]... [--file <path>]...detach linkage that is wrong
worktreeworktree start <id> [--name <slug>] [--base <ref>] [--allow-dirty] / worktree finish <id> [--force] / worktree list [--json]isolate a workstream in its own worktree and branch
renderrenderregenerate BOARD.md
validatevalidate [--json]check the whole board for problems
wipwipshow current usage against each WIP limit
initinitcreate or repair the board directory; safe to re-run
standupstandup [--days <n> | --since <YYYY-MM-DD>] [--write]review recent movement, checks, blockers, and next work
doctordoctor [--strict]detect linkage drift (missing commits, branches, files)

Global options: --board <dir> targets another board, --no-render skips regenerating BOARD.md, --json prints machine-readable output where supported, and --help prints the whole usage block.

Titles are one line, at most 200 characters, unique among cards that are not done. Creating a card does not accept acceptance criteria after the fact: pass every --accept at new time, or the card can never start.

Confirm with show <id> --json that what you linked is what was stored.

Intake: request to cards

  1. Restate the request in one line; if that line is ambiguous, ask the user before creating anything.
  2. Decompose into one card per independently verifiable deliverable, not per file or per keystroke.
  3. Give every card testable acceptance criteria. Write "the endpoint returns 404 for an unknown id", never "make it good". Pass each as --accept.
  4. Set an estimate from 1|2|3|5|8 and a priority from P0–P3.
  5. Run list --search <term> first. If an open card already covers the work, use it instead of creating another.
  6. Create with --status backlog for ideas nobody has committed to, --status todo for agreed work. Those two are the only creatable columns: doing, review, and done are reachable only through their gates.
  7. Where the scope is known, link <id> --file <path> to record the expected touch points.
  8. Ask the user before creating more than five cards at once, or when scope is genuinely ambiguous.
  9. The CLI rejects duplicate titles. Treat that as correct and do not reword the title to slip past it: either the existing card is the right home, or the two deliverables genuinely differ and the new title should say how.

Execution loop

  1. next (or list --status todo) to pick work.
  2. move <id> doing. The CLI refuses this without acceptance criteria and a valid estimate, and enforces the doing WIP limit.
  3. Break the card into the session's steps with the todo_write tool. See Boundaries.
  4. Do the work.
  5. Before running each verification, declare it with check add <id> --name <name> --command "<exact command>". Then run that command and record what you actually observed with check set <id> <name> --status pass|fail --evidence "<observed result>". A pass without evidence is refused, and only real observed output is acceptable as evidence.
  6. If you declared a check's command wrongly, fix it with check set <id> <name> --command "<corrected>". That invalidates the recorded result — the status drops back to pending and the evidence clears — because a result observed for the old command proves nothing about the new one. Re-run it and record the fresh result.
  7. link <id> --commit <sha> --file <path> as the work lands, and --pr <url> once one exists.
  8. move <id> review. This requires at least one recorded check plus either a branch or a file, and enforces the review WIP limit.

review is entered from doing only, so never try to jump a card from todo straight to review. A card's acceptance criteria are proven in review, not in doing: entering review is a claim that the evidence is complete, so gather it before you move the card. If a check fails, fix the cause, re-run it, and check set the new result. Never delete a check to make a card look clean, and never move a card to review with a check still pending.

Parallelism

When the user asks for work, fan it out rather than doing everything serially.

  • For a doing card, split it into independent parts: exploration, separate modules, tests, docs.
  • Delegate with the subagent tool (use workflow for larger fan-outs), and issue all independent delegations in a single message so they run concurrently.
  • Subagents share this session's working directory; DSH gives them no filesystem isolation. Give each parallel writer a disjoint set of files and never let two subagents edit the same file. Research, exploration, and review are safe to parallelise freely.
  • Reconcile the results yourself, verify them, then update the card.
  • Gate decisions stay with you. Never let a subagent approve, close, archive, or reopen a card, and never let one record evidence it did not observe.
  • This repository's standing rules are in AGENTS.md at the repo root. Follow them; where this skill and AGENTS.md both apply, obey both.

Blocked work

  • The moment work cannot proceed, run block <id> --reason "<concrete blocker>" naming the actual obstacle, not "waiting".
  • A blocked card is exempt from WIP limits and cannot change column until unblock <id>. Attempting a move while blocked is refused.
  • Do not leave a stale blocker. Re-check each blocked card during standup and unblock it when the cause is gone.

Session isolation

Each workstream runs in its own git worktree, on its own branch. DSH gives a session exactly one writable root — its own working directory — so parallel sessions cannot share a board directory, and the board travels in git instead. Never write outside your own session's working directory, and never assume another session's worktree is readable.

  • worktree start <id> [--name <slug>] [--base <ref>] [--allow-dirty] creates .worktrees/<id> on branch card/<id>-<slug>, records both on the card, and prints the directory this workstream's session should run in.
  • worktree list [--json] shows each worktree, its branch, and its card.
  • worktree finish <id> [--force] removes the worktree and keeps the branch for merging or a pull request. --force discards uncommitted changes, so use it only when you mean to.

start refuses a card in backlog (promote it first), a blocked card, a done card, and a card that already has a worktree. For a todo card it applies the ready gate and the doing WIP limit, then moves the card to doing. It also refuses while .kanban, .dsh, AGENTS.md, or CLAUDE.md have uncommitted changes, because a worktree is a checkout of a commit and would start without them — commit those files first rather than reaching for --allow-dirty.

Opening the new worktree's session is the one step that needs the human. After worktree start succeeds, give the user the printed directory and tell them to add it as a workspace in the DSH GUI, or start the harness from it. Never claim a worktree exists until the command has actually created it.

The event log is per-checkout, so it cannot see work done in sibling worktrees. standup compensates: Blocked, Next up, and Ageing come from card state, and Movement and Checks entries are reconstructed from card state for anything the log cannot see. Reconstructed bullets are marked from card state, and a footnote is printed under Movement when that happens — a fully-logged board shows no markers and no footnote. --json reports the split as movementSource: { log, derived } (counting bullets, not card headings). Use show <id> --history for one card's full log.

Review to Done

All four gate commands are human-only: outside a real terminal they exit with code 3 and refuse. You do not run them; you hand them to the user. They check card state first, though, so a card that cannot pass anyway reports that as exit 1: resolve everything you are able to — unblock it, record every check as pass with evidence, link a commit, get it into review — and hand over a command that will actually succeed rather than sending the user to a terminal for a failure. unblock is not gated, so a blocked card is yours to fix. The gate makes self-approval impossible to do accidentally and impossible to do quietly — validate reports a done card with no recorded human approval, and every mutation lands in the event log and the git diff. Faking a TTY, editing a card, or fabricating an approval is prohibited; the honest path is always to hand the exact command to the user.

  1. If the card is blocked, unblock it first, noting how the blocker was resolved — done refuses a blocked card.
  2. Confirm every check on the card is pass with evidence, and that at least one commit is linked. validate reports cards that reached done without these.
  3. Present the evidence to the user in chat: what changed, the exact commands run, and their observed results.
  4. Get the user's explicit approval in their own words. Never invent it, infer it from silence, or accept a pre-emptive "looks fine".
  5. Hand over both commands for the user to run themselves in their own terminal:
node .kanban/tools/kanban.mjs approve <id> --quote "<their approval in their own words>"
node .kanban/tools/kanban.mjs done <id>

Run done <id> yourself before handing anything over. Because it validates state before the terminal gate, exit 1 names exactly what is still missing — a missing approval is the expected one at this point — and exit 3 means every precondition holds and only the user's terminal is needed. That makes it a cheap readiness check; it is never a way to close the card.

approve works only on a card in review with at least one recorded check, and done additionally requires a recorded approval, every check passing with evidence, and a linked commit. archive and reopen are gated the same way.

Standup and review hygiene

  • Start a session with standup --days 1 instead of guessing: what moved, which checks passed, what is blocked, what is next.
  • Run doctor when linkage may have drifted — commits not reachable, branches deleted, recorded files gone. It exits non-zero only with --strict.
  • Re-run render if a command was issued with --no-render, and standup --write when a durable STANDUP.md snapshot is wanted.
  • Hooks are not tracked by git, so a fresh clone has none. If .git/hooks/pre-commit is missing, tell the user to run install-hooks so validate runs before every commit.

Boundaries with the other planning tools

  • todo_write is this session's step list and dies with the session. The board is the durable, cross-session plan. A doing card's session steps belong in todo_write; its acceptance criteria and evidence belong on the card.
  • A single long-running objective belongs to the goal tool, with cards as its deliverables.
  • Never let two systems hold the same list. One list, one home.

Failure handling

  • Exit 2: usage error. Fix your invocation — a bad flag value, a missing required option, an unknown column — and retry.
  • Exit 1: board or validation failure. Read the message, fix the cause it names, retry. Do not edit files to silence it.
  • Exit 3: the command is human-only and the card itself is ready. Hand it to the user with the exact command line. Note that move <id> done routes into the done gate, and that a gate reached with an unready card exits 1 first, naming the state problem you can fix yourself.
  • Run validate before finishing a work session. Never leave a card in a state the CLI would call invalid.
  • When a card will not move, or linkage looks wrong, read show <id> --history and run doctor; the event log explains how the card reached its current state.
Repository

pmcf69/ss-demo-ungated

Path

.dsh/skills/kanban/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.