scratchboard

Your markdown tickets as a kanban board, for any git repository

Read-only by choice: tickets are agent-driven, so the agent moves the card.
It owns no directory and no file format: it reads the layout your repo already has.

npx scratchboard

npx scratchboard reads the markdown tickets already in your repo, maps them to lanes, and
opens a board in your browser. One self-contained HTML file in your temp directory. No config,
no dependencies, nothing written back to your repo. It reads the file layout the
mattpocock/skills agent skills write, so a
/wayfinder map or a feature spec gets a view of its own rather than one
more card.

There is no drag and drop and no write-back, so your current flow stays safe.

npx scratchboard                            # the board
npx skills add darecstowell/scratchboard    # the skill, for the setup that needs judgment

Node 18 or later.

One board, two themes. Both are the tickets in this repo, not a fixture.

Live demo: darecstowell.github.io/scratchboard
is this repo's own backlog, baked by this repo's own scratchboard on every push to main.

The /wayfinder view

/wayfinder is Matt Pocock's skill for an effort that is
too big for one agent session. It charts the effort as a map of decision tickets on your tracker,
then resolves them one at a time until the way is clear. The map is the plan, so the plan outlives
the session that wrote it.

Your tracker shows that map as a list of issues. A list does not tell you where you are.
Scratchboard reads the same files and lays the voyage out left to right: the decisions behind you
and the answer each one produced, the tickets you can take right now, and the work still in the
fog. Hover any ticket and it draws what it unblocks, so you see what a decision releases before
you make it.

There is nothing new to write. It reads the map the skill already wrote.

The /wayfinder view is experimental. A planning folder gets a tab of its own, and the shape of
that view may change. The board itself does not: a repo with no planning folder renders exactly as
it did before, with no tab row at all.

How it works

Run it in a repo with no config and it does three things.

1. Finds your tickets. It checks .scratch/, .tickets/, docs/issues/, issues/, and
   tasks/, then any other directory holding three or more markdown files it can read. YAML
   front matter and a plain Key: value block both need no setup.
2. Maps them to lanes. Folders first, so todo/, in-progress/, and done/ become the
   lanes in that order. With no folders to go on it uses a status field. Any other metadata
   whose values repeat becomes a filter chip.
3. Bakes one HTML file and opens it. It lands in the OS temp directory, so nothing shows up
   in git status. That file travels too. Attach it to a pull request, or drop it in a chat.

Search, filters, and sort live in the URL hash, so a filtered board is a link you can send. Two
themes ship, latte and phosphor.

To keep the guess, the first run offers to save it and scratchboard init writes it any time.
Both write scratchboard.json at the repo root. Commit it and later runs skip detection.

Live reload

--serve keeps the board open and reloads it when the files change. Leave it on a second
monitor while an agent works the tickets underneath you, and the cards move on their own.

npx scratchboard --serve

Configuration

Every key is optional, and anything you leave out comes from detection. A lane is a match rather
than a location, so a ticket never gets moved to join one.

{
  "title": "Roadmap",
  "tickets": ".scratch/**/issue.md",
  "format": "yaml-frontmatter",
  "idPattern": "^(\\d+)-",
  "lanes": [
    { "name": "Todo",        "icon": "issue-opened", "match": { "path": ".scratch/todo/**" } },
    { "name": "In progress", "icon": "workflow",      "match": { "path": ".scratch/in-progress/**" } },
    { "name": "Done",        "icon": "check",         "match": { "path": ".scratch/done/**" }, "collapsed": true }
  ],
  "facets": [
    { "field": "priority", "icon": "alert", "colors": { "p0": "red", "p1": "amber", "p2": "cyan", "p3": "neutral" } },
    { "field": "labels" }
  ]
}

A priority of p0 to p3, or of critical to low, is ranked and coloured with no config at
all, and so is a status. Naming colors or order yourself replaces the default. Detection
leaves a vocabulary it does not recognise alone rather than guessing at it.

icon marks a lane header or a facet from a small curated set. A lane that names none carries no
glyph, so the headers stay quiet until you ask for them.

Every key, every flag, the glob tokens, the lane and facet rules, the icon set, and what
detection does in full: docs/reference.md.

The skill

The CLI is the whole tool. The skill is for the part that needs judgment: looking at a repo full
of tickets and deciding what the lanes should be.

npx skills add darecstowell/scratchboard

It has three jobs, and none of them is narrating a command you could have run yourself.

1. Ask where the tickets live, and confirm the glob against real files.
2. Read the detection report and correct the lane mapping. Tickets sitting in the trailing
   Unmapped lane are the signal.
3. Write a parser when neither preset reads your format.

For all three it writes only scratchboard.json and scratchboard.parser.mjs, it asks before
each, and it never touches a ticket. SKILL.md follows the
agentskills.io format, so Claude Code, Codex CLI, Cursor, Windsurf,
Copilot, Amp, and Gemini CLI all read it.

Custom parsers

Neither preset reads your format? A module of about 30 lines covers it, and nothing else in the
config changes.

// scratchboard.parser.mjs
export function parse(path, text) {
  return { id, title, body, fields };
}

The only boundary is one line: the body has to be markdown, because the board renders it. The
metadata format is fully open, and fields is untyped, so your own severity or team field
works with no code change. See the
full contract, or let the skill write it.

What it is not

Scratchboard is not a task manager. It does not create tickets, move them, or edit their front
matter.

Backlog.md leads this category and it earns the lead: a
CLI that creates and edits tasks, a web UI with drag and drop, a terminal board, MCP for agents,
and a backlog/ folder it owns end to end. If you want a task manager that owns your files,
use Backlog.md. It will serve you better than this will.

Scratchboard is for the other case. Your tickets already exist, in a shape you picked, and you
want a window onto them.

Those tickets have to be files. A repo that keeps its tickets behind a tracker API, such as
GitHub Issues or Jira, has nothing on disk for a file reader to see, so the board comes up
empty.

• No write-back, no drag and drop. Tickets are agent-driven, so the agent moves the card.
• One board per config. A second board means a second config file, on purpose.
• No single-file TODO.md format. One ticket is one file. If you keep everything in one
  file, md-kanban handles that shape.
• No hosted service, no accounts, no telemetry. The board is one HTML file in your temp
  directory. Nothing phones home.
• Zero dependencies, and that is a rule rather than a current state.

Third-party

Two bundled fonts, and palettes derived from a third project. Each notice travels with the files
it covers, including the base64 bytes inlined into a baked board.

The latte and phosphor themes are original palettes derived from Catppuccin rather than
copies of it.

Where it came from

Scratchboard was the internal board on OffMain and turned out to be
useful on its own. That repo's ticket tree is the corpus every change here is tested against.

Licence

MIT. See LICENSE.