flowdeck

Documentation

Human × AI task flow via structured TODO cards.

Overview

flowdeck is a Human × AI collaboration system built around a simple primitive: the card. Every card is a TODO.md file split into two sections — ## BOT (what Claude executes) and ## HUMAN (what only you can decide). The deck lives in .flowdeck/ in your project root.

The separation forces clarity: Claude never gets stuck waiting for a decision you didn't know it needed, and you never get surprised by an action you didn't sanction.

Install

npm install -g flowdeck

Initialize a deck

Run in any project root to scaffold the deck structure and a starter AGENT.md:

flowdeck init

This creates .flowdeck/ with the standard column structure and pile folders.

Cards

A card is a TODO.md file. The filename slug becomes the card's identifier. Cards follow this structure:

# Card title

Short description of the task.

---

## BOT

- [ ] Step Claude will execute
- [ ] Another automated step

---

## HUMAN

- [ ] Decision or action that requires your input

#### COMMENTS

Any notes from a prior run.

Bot items use standard GitHub-flavored Markdown task syntax. Claude marks each done with - [x] and adds a one-line note indented with >.

Columns

Columns are subdirectories inside .flowdeck/. Cards move between columns as work progresses. You define your own columns — common examples: start/, review/, done/.

Piles

Special subfolders that are never treated as playable columns:

  • _meld/ — shipped cards
  • _discard/ — cancelled or abandoned
  • _frozen/ — blocked, each with a FREEZE.md unfreeze signal
  • _stock/ — backlog, not yet ready to play
  • _blueprints/ — reusable card templates
  • _energy-cards/ — mdblu templates and prompts

AGENT.md

AGENT.md lives at .flowdeck/AGENT.md and carries persistent project context — architecture, conventions, current priorities. Claude reads it at the start of every play and turn. Update it as the project evolves.

play

Execute a single card by its slug (the folder path relative to .flowdeck/):

flowdeck play start/my-card

Pass --no-dep-check to skip dependency validation:

flowdeck play start/my-card --no-dep-check

turn

Play the full deck. Cards with no unmet depends: headers run in parallel; dependent cards wait:

flowdeck turn

Force serial execution if the dependency grouping is wrong:

flowdeck turn --serial

meld

Move a completed card to _meld/ after all BOT and HUMAN items are checked off:

flowdeck meld start/my-card