Plandeck

The visual Kanban for long-running agentic work. Nobody wants to read a markdown plan or stare at raw HTML while an agent grinds for an hour. Plandeck turns your AI agent's plan into a live board that organizes itself: dependencies unlock into Ready, the critical path lights up in gold, estimates roll up, and the one next move is always obvious. It stays a plain file on disk underneath, so it survives /clear and a context reset.

npx skills add https://github.com/othmanadi/plandeck --skill plandeck

Zero dependencies, so there is nothing to install. Prefer a global plandeck command over node scripts/cli.mjs? Run npm link in the repo. A published npx plandeck release is planned.

The problem

AI coding agents lose the thread. After a context compaction or a /clear, an agent drops half the TODO list and stops mid-task, or it picks up the wrong thing next because the plan never said what was actually blocked. Flat markdown plans make this worse: a checklist cannot express that card C003 needs C002 done first, so "what should I do now" stays ambiguous even in popular planning tools. The agent guesses. The guess is often wrong.

Plandeck is the fix. It turns the plan into a structured, queryable task graph. Dependencies are explicit. A ready-queue is computed, not guessed. There is exactly one unambiguous next move, and it survives a context reset because it lives in a file on disk.

Why it exists

Plandeck grows out of planning-with-files (OthmanAdi/planning-with-files, MIT), which gave crash-proof markdown plans that survive /clear plus a deterministic completion gate. Plandeck keeps that DNA (durable plans on disk, and a check command that only says COMPLETE when the work truly is) and adds the thing a wall of markdown can never give you: a live visual board with a brain.

That brain is a deterministic intelligence layer with no AI and no LLM anywhere in it. It is pure functions over YAML: given the cards, it computes the ready-queue, the critical path, the rollups, and the one next action. Because it is pure, it is fully testable, and it gives the same answer every time. The board server, the YAML reader, and the rendering are all Plandeck's own, with zero dependencies.

60-second Quickstart

# 1. Start the live board for the bundled example
node scripts/cli.mjs board examples/ship-onboarding-flow

# 2. Open the URL it prints, e.g.
#    http://plandeck.localhost:41747/ship-onboarding-flow/

# 3. In another window, open the plan and mark a card done:
#    edit examples/ship-onboarding-flow/plan.yaml
#    set one card's  column: done

# 4. Watch the board without touching the browser.

The payoff is immediate. When you set a card to done, every backlog card whose dependencies are now satisfied auto-promotes to Ready, the gold critical path recomputes and re-draws itself, the progress ring ticks up, and the "Do this next" banner points at the new single move. All of it streams over SSE. You never drag a card.

No Node handy? Open media/board-preview.html in any browser to see the board with the sample data baked in, no server required.

The board model

Six lanes. A card lands in Blocked when a dependency is unmet or you set status: blocked (or column: blocked). Ready is computed, never placed by hand.

Six lanes carry the flow: Backlog, Ready, In Progress, Review, Done, plus a
Blocked lane. The dependency graph below is the bundled sample. You author only
the depends_on edges; Plandeck computes the rest.

flowchart LR
    C001["C001 · Map onboarding"] --> C002["C002 · Design schema"]
    C002 --> C003["C003 · Signup API"]
    C002 --> C005["C005 · Welcome UI"]
    C002 --> C007["C007 · Optional SSO"]
    C002 --> C010["C010 · Update docs"]
    C003 --> C004["C004 · Email verify"]
    C004 --> C006["C006 · Analytics"]
    C004 --> C008["C008 · E2E test"]
    C005 --> C008
    C006 --> C009["C009 · Launch audit"]
    C008 --> C009

    classDef done fill:#d7f0e0,stroke:#2f8f5b,color:#14532d,stroke-width:1px
    classDef crit fill:#fbf1d6,stroke:#e0a100,color:#6b4e00,stroke-width:3px
    classDef ready fill:#eaf6ef,stroke:#2f8f5b,color:#14532d,stroke-dasharray:5 3
    classDef blocked fill:#fbe9e9,stroke:#c23b3b,color:#7a1c1c
    classDef backlog fill:#f2f2ef,stroke:#c9c9c4,color:#3a3a38

    class C001,C002 done
    class C003,C004,C008,C009 crit
    class C005,C010 ready
    class C007 blocked
    class C006 backlog

Green is done, the gold chain is the critical path (17 points, the longest one),
dashed green auto-promoted to Ready the moment C002 finished, and red is blocked.
plandeck next reads exactly this graph and points at the one card to do now.

Each card shows its id, an estimate chip, role / priority / risk badges, and dependency indicators (⛓ after X, 🔓 unlocks N). Click a card for full detail: dependencies met and unmet, verify commands, and the receipt.

The signature feature: the /clear-proof hand-off

After a context reset, an agent runs plandeck next . (or reads NEXT.md) and instantly knows the one move to make. NEXT.md is a tiny separate file, never an in-place rewrite of the big plan. That is deliberate: rewriting the large plan on every step would invalidate the model's prompt cache, so the breadcrumb is kept small and standalone to stay cache-safe.

# ▸ NEXT

**C003 · Build the signup API**  `P1` `critical path` `5 pts` `unblocks 1`
Resume the card already in progress.

- Progress: 15% (5/34 pts, 2/10 cards)
- Ready now: C005, C010
- Blocked: C007
- Critical path: C001 → C002 → C003 → C004 → C008 → C009 (17 pts)
- Live board: http://plandeck.localhost:41747/ship-onboarding-flow/

The deterministic brain

Every one of these is a pure function of the YAML, cycle-guarded, and tested. No AI.

• Ready detection. Topological. A backlog card auto-promotes to Ready the moment every one of its depends_on cards is done. A card caught in a dependency cycle is never marked Ready, and the cycle is flagged instead.
• Critical path. The longest points-weighted dependency chain, drawn in gold on the board.
• Rollups. An honest percent-complete derived from points, plus per-column point sums.
• Velocity and ETA. Opt-in. Set plan.velocity and the ETA is derived from it. Never manufactured.
• Aging. Cards idle too long in doing or review, or waiting in ready for over five days, are flagged from their updated_at timestamp.
• next. One tie-broken next-action id. It prefers the active card, then a Ready card on the critical path, then priority, then how many cards it unblocks.

Data model

A plan directory holds these files:

Fields you author

id (required, e.g. C001), title, column (backlog | ready | doing | review | done), status (optional: queued | active | blocked | done, where active marks the one in-flight card), role (scout | worker | judge | pm), estimate (story points, fibonacci 1/2/3/5/8/13 recommended, no hours), confidence (0..1), priority (P0..P4), risk (low | med | high), depends_on ([ids]), verify (commands that prove the card is done), next_action (the one concrete move), tags ([..]), updated_at (ISO, powers aging), and receipt ({result, summary, changed_files, commands, evidence, note}).

Fields Plandeck derives

Never hand-set these. They are recomputed on every read and serialize in the board payload as ready, onCriticalPath, unblocks (how many cards this one unblocks), unmetDeps, ageDays, the rollups, and the single next pointer.

A card, copy-paste

cards:
  - id: C003
    title: "Build the signup API"
    role: worker
    column: doing
    status: active
    estimate: 5
    confidence: 0.7
    priority: P1
    risk: med
    depends_on: [C002]
    verify: ["curl -f localhost:3000/api/signup -d @test/fixtures/user.json"]
    next_action: "Wire the POST /signup handler to the users table, return 201 with the new id."
    tags: [api, auth]
    receipt:
      result: null
      summary: null

Commands

From the repo root, run node scripts/cli.mjs <cmd>, or plandeck <cmd> after npm link. The table uses the plandeck name for brevity.

Compatibility

Honest and small on purpose.

• Claude Code (skill plus CLI, tested on Windows 11).
• Any agent that runs a shell and reads files can use the CLI (plandeck board / check / next).
• The bundled SKILL.md follows the open SKILL.md standard, so it loads anywhere that reads SKILL.md (Codex, Cursor, and others).

Got Plandeck working with another agent? Open a PR or an issue and we will list it once it is verified.

Credits and license

Plandeck grows out of planning-with-files by OthmanAdi (MIT): durable, crash-proof plans on disk and a deterministic completion gate. Everything else, the board server, the YAML reader, the intelligence layer, and the rendering, is Plandeck's own, with zero dependencies.

Plandeck is MIT, copyright 2026 Ahmad Othman Ammar Adi (CodingWithAdi). See LICENSE and NOTICE.