How to use Threlmark

Threlmark is a local-first hub for all your projects and their roadmaps. Each project gets a ranked, kanban-style board; everything is stored as plain JSON files on your own computer. This manual walks through every part of the tool and how to set it up.

1. Getting started

Threlmark runs on your own machine. Start it from the project folder:

npm install
npm run dev      # then open http://localhost:3000

The first screen is the Portfolio. It's empty until you create a project. All your data lives in a folder called ~/.threlmark in your home directory.

2. Projects

A project is one app or product with its own roadmap. Use the left sidebar to switch between projects or create one.

• Create: click + New project, give it a name, an optional description, a repo path (used for handoff briefs), and an accent colour.
• Switch: click any project in the sidebar.
• Archive: archived projects move out of the active list but stay readable on disk.

3. The roadmap board

Each project has four lanes:

Move a card between lanes by dragging it, or with the buttons on the card (Push, Rank, Done, Reopen). The lane a card is in is its status.

Scoring & priority

Every card is scored 1–5 on four axes — Impact, Evidence, Fit, Effort — using the sliders on the card. Threlmark computes a single priority:

priority = max(0, round(impact·3 + evidence·2 + fit·2 − effort·1.5))

Higher impact/evidence/fit raise priority; higher effort lowers it. The number in the dark badge on each card is its priority.

4. Adding & editing items

Use the Add item form in the right panel: title, category, description, likely files, and the four score sliders. New items land in Ideas. Click any card's Edit button to change its full details, move it to another project, or turn it into a shared item.

5. Toolbar

• Search filters cards by title, description, or category.
• Category filter narrows the board to one category.
• Rank by score moves every Idea into Ranked.
• Push top 3 sends the three highest-priority Idea/Ranked cards to Development and selects them.
• Copy dev brief copies a Markdown implementation brief of the selected cards to your clipboard.

6. Selecting cards & the handoff brief

Click Select on cards to add them to the Development brief in the right panel (anything in Development is included automatically). Switch between Queue, Markdown and JSON tabs. The Markdown brief is a file-scoped prompt for Claude or Codex, complete with acceptance checkboxes and verification commands — copy or download it from the Handoff tab.

7. Inbox & suggestions

Other tools can suggest roadmap items by dropping a small JSON file into a project's suggestions/ folder. They appear in the project's Inbox. There you can:

• Accept here — turns the suggestion into a normal roadmap item (tagged with its source).
• Accept into… — promotes it into a different project.
• Dismiss — files it away.

8. Working across projects

• Portfolio (home) ranks the top items across all projects by status-weighted priority.
• Move an item to another project from its editor.
• Link / depend — connect two items (blocks, relates, duplicates) from the Portfolio; blockers are flagged.
• Share — turn a card into one shared item referenced by several projects.

9. Importing an existing roadmap

Open Import, pick a target project, and either paste a roadmap.html file's contents or give its path. Threlmark reads the cards and recreates them, keeping their scores. Re-importing the same file updates items instead of duplicating them.

10. Your data

Everything is plain JSON under ~/.threlmark — no cloud, no account, nothing leaves your machine. Back it up or sync it however you like. You can point Threlmark at a different folder with the THRELMARK_DATA_DIR environment variable.

11. Setup & self-hosting

Run it locally (recommended)

git clone <your-threlmark-repo>
cd Threlmark
npm install
npm run dev            # http://localhost:3000
# custom data folder:
THRELMARK_DATA_DIR=~/Dropbox/threlmark npm run dev

Host it for yourself (online, single user)

Threlmark needs a Node.js server (its API reads and writes files at request time), so ordinary shared hosting won't run it. To use it from anywhere:

1. Deploy on a small Node host (a VPS, or a service like Fly.io) and build with npm run build && npm start.
2. Set THRELMARK_DATA_DIR to a persistent, backed-up folder.
3. Put it behind a password (e.g. HTTP Basic auth on a reverse proxy) — Threlmark has no built-in login and stores one shared roadmap set.

12. Flow: WIP limits, metrics & agent throughput

Threlmark is more than a status board — it manages flow.

WIP limits & policies

Open Workflow settings (the ⚙ button in the toolbar) to set a WIP limit per lane and a short policy describing what each lane means. A lane over its limit shows its count in red (e.g. 3 / 2) — your cue to finish work before starting more.

The Flow tab

The Flow tab shows throughput (items finished per week), cycle time (Development → Done), and aging work (oldest first; stale items flagged). Cards also carry a time-in-lane badge (⏱ 4w) and turn red when they go stale.

Agent flow

On the Handoff tab, pick an agent and choose Generate & mark handed off. Threlmark stamps the items and tracks brief → shipped time, agent throughput (handed-off items finished per week), and stalled briefs (handed off but not Done after 7 days). The home page shows a portfolio-wide flow strip.