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. A light/dark theme toggle sits at the bottom of the sidebar — your choice is remembered on this machine.

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.
• Remove a project: open the project and click ⌫ Remove project next to its title. To prevent accidents you must type the project's name to confirm. It is then archived, not deleted — it leaves the active list but all its data stays on disk and can be restored.

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.

In the editor you can also set an optional Scheduled start and a Due date — a card past its due date that isn't Done is flagged overdue (the Flow view counts them). Below that, add comments and decision notes to record discussion and the choices you made, and read the activity timeline — a derived history of everything that happened to the card (created, lane moves, handoff, agent reports, notes).

5. Toolbar

• Search filters cards by title, description, or category.
• Category filter and Label filter narrow the board to one category or one label (an initiative).
• Rank by score moves every Idea into Ranked.
• Push top 3 sends the three highest-priority Idea/Ranked cards to Development and selects them.
• Select filtered selects every not-yet-shipped card matching the current search / category / label filters — ideal for a whole label or initiative. Fine-tune with each card's Select toggle.
• Push N → Development (appears once cards are selected) moves the whole selection into Development in one batch; Clear empties the selection.
• 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.

Open GitHub issues can be pulled in here too — they arrive as suggestions in the Inbox (see Importing below).

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 choose a source:

• roadmap.html — paste a roadmap.html file's contents or give its path; Threlmark recreates the cards, keeping their scores.
• Trello — paste a Trello board's JSON export (or its path). Lists map to lanes (Done / Development / Ranked / Ideas); labels, due dates and checklist items come across as labels, due dates and acceptance criteria.
• GitHub — paste issue or project JSON, or fetch open issues live by entering owner/repo (plus an optional token for private repos). Issues land in the project's Inbox as suggestions to accept or dismiss.

Every source is idempotent: re-importing updates the same cards by stable source id 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.

Develop all in one click. Next to the project title, ⇥ Develop all hands off every card in the Development lane to Claude or Codex at once — it generates the combined brief, records the handoff, and copies the brief to your clipboard so you can paste it straight into the agent.

Automatic report-back (no manual step)

The generated brief includes a reporting protocol that tells Claude/Codex to report status by itself — you don't drag the card to Done. The agent posts started when it begins, then done (with a one–two-sentence summary and the verification commands it ran) once the acceptance criteria pass, or blocked / failed with the reason. It reports either by calling Threlmark's API or by dropping a small JSON file into the project's reports/ folder (Threlmark ingests it on the next load). A done report moves the card to Done automatically, and the board shows a live toast (🤖 claude done: …). The summary is also saved into the item's Outcome field — a record of what was built — which you can read or edit in the item editor. That closes the loop: rank → hand off → the agent builds and reports → the card lands in Done with its outcome, and Flow counts it.

13. Works with IdeaClyst

Threlmark's data on disk is a shared contract, so other local-first tools can read and write your roadmaps. The first is IdeaClyst, an idea engine that turns product ideas into plans and scouts the web for opportunities.

• IdeaClyst reads a project's roadmap (read-only) and computes a gap map — which categories and lanes are thin.
• IdeaClyst writes suggestions into that project's suggestions/ folder — proposed Features, Spin-offs and Services, scored and grounded in live web research, tagged source: ideaclyst.
• You stay in control in Threlmark's Inbox: Accept turns a suggestion into a ranked item (or promote it into another project), or Dismiss it.

The full loop: IdeaClyst proposes what to build (from research + your roadmap gaps) → it lands in your Inbox → you accept and rank it → hand it off to an agent → the agent builds and reports back → the card reaches Done. Any tool that speaks the contract can join the same loop.