flowdeck

Human↔AI collaboration via TODO.md files and git commits.

You write tasks. Claude does them. Git tracks the conversation.

Install

npm install -g flowdeck

Requires Node.js ≥ 18 and Claude Code.

Canonical home: flowdeck.ruco.dev — docs, changelog, and release notes live there. The old scoped package @ruco-ai/flowdeck is deprecated. Install flowdeck instead.

Why flowdeck

Flowdeck is the only agent harness that is natively frontend-agnostic. The same card deck runs in a terminal, a CI pipeline, a chat interface, or an IDE. You don't migrate your workflow when you change your tooling.

Flowdeck gives you the LangSmith feedback loop without LangSmith. Your git log is your trace. Your TODO.md is your eval. Your AGENT.md is your memory. The loop runs in plain text.

Quick start

cd your-project
flowdeck init

This creates a .flowdeck/ scaffold and a FLOWDECK.md at the project root:

FLOWDECK.md         ← living project document injected into every play/turn (edit this)
.flowdeck/
  AGENT.md          ← project context Claude reads on every play (edit this)
  TODO.md.template  ← card format reference
  start/
    TODO.md         ← your first work area
  _energy-cards/    ← mdblu templates (SPEC, MISSION, ADR, …)
  _blueprints/      ← reusable card blueprints (feature, bugfix, chore, spike, release)
  .flowdeckignore

Add a task for Claude in .flowdeck/start/TODO.md:

## BOT
- [ ] Add a README to this project

Then hand off:

flowdeck play start
# plays the "start" card — Claude reads it, completes the BOT tasks, marks them done, commits

flowdeck turn
# passes the full deck to Claude — Claude decides what to play, discard, or combine

How it works

TODO.md is the shared board

Every folder under .flowdeck/ is a column. Each column has a TODO.md card with two sections:

## BOT
- [ ] Task for Claude to do
- [x] Completed task
  > short note on what was done

## HUMAN
- [ ] Something Claude needs from you
  > why it's needed

## OUTCOME
What was built: key files, logic, notable numbers, and how to use the deliverable.

• ## BOT — Claude's inbox. Claude completes these and marks them [x] with a one-line note.
• ## HUMAN — Your inbox. Claude adds items here when it needs you to act.
• #### COMMENTS (under ## HUMAN) — Notable findings from execution: unexpected behaviour, real validations, non-obvious decisions. Added by Claude when there's something worth preserving beyond the task notes.
• ## OUTCOME — Appended automatically when all BOT tasks are done. 3–6 lines: what the card produced, key files or changes, and how to use the deliverable. The persistent record of what this card built.

Cards can optionally declare tool dependencies and bind their output to variables.

Tools, pills, and MCP servers

MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools and data sources. Claude Code speaks MCP natively — any MCP server you connect to it becomes a callable tool.

A pill is a lightweight, declarative flavour of MCP server. Instead of writing server code, you describe what the server does in a plain-Markdown PILL.md file. The mcpill CLI compiles that file into a runnable MCP server. Because pills are just Markdown, they're easy to read, share, and version alongside your project.

mcpill is the CLI that drives this workflow: init → describe → compile → run. Install it globally:

npm install -g mcpill

Once installed, mcpill run <name> starts a pill as a local process; mcpill publish packages it as an npm package so others can install and run it the same way. There is no centralised pill registry — pills are distributed via npm like any other package.

When a card lists a tool in ### TOOLS, the suffix tells flowdeck how to reach it:

• @local — flowdeck starts the pill as a transient process via mcpill run <name>, registers it with Claude Code for the duration of the card, then removes it on exit. Use this for pills you run from source locally.
• @mcp — the tool is already configured as an MCP server in Claude Code. Flowdeck calls it directly without spawning anything. Use this for persistently-running servers or cloud-hosted MCP endpoints.
• No suffix — defaults to @local.

To learn how to build your own pill, see github.com/ruco-dev/mcpill.

### TOOLS
- gmail-triage@local
- calendar-write@mcp

## BOT
- $threads = gmail-triage({ client: "HCV", days: 3 })
- write $threads to /inbox/{{ date }}.md
- for each $threads.threads where action_required = true → append card to TODO.md

• ### TOOLS (optional) — lists pill or MCP tool dependencies; @local resolves via mcpill run <name>; @mcp resolves as an MCP tool call; no suffix defaults to @local in Claude Code
• $var = tool({ args }) — invokes a tool and binds its structured JSON output to $var; reference as $var or $var.field in subsequent steps
• for each $var.field where condition → action — iterates over an array field; → separates the predicate from the action; where conditions are natural-language predicates

flowdeck play <slug> — single card

flowdeck play payments
# plays .flowdeck/payments/TODO.md, or infers the column if 'payments' is nested

flowdeck play col/payments
# explicit full slug — no scanning

flowdeck play get-gmail --arg-1 '[email protected]'
# replaces {--arg-1} placeholders in the card before Claude sees it

Claude reads the card, works through the ## BOT tasks, marks them done, and commits.

After each execution (play, flash, deal, kemps, turn), flowdeck appends a <!-- tokens YYYY-MM-DD command(Nick): in=N out=N --> comment to the card file — token counts plus the model alias that ran the command (e.g. <!-- tokens 2026-06-28 play(Glinder): in=1200 out=800 -->). Silently skipped if the field is absent.

At the end of each flash, deal, kemps, and play run, Claude also appends a <!-- next: <nick> --> annotation — its recommendation for which model to use for the next command on this card. Values: Casual (mechanical/well-defined tasks), Glinder (moderate coding work), Shark (complex reasoning or architecture), Wale (hardest, most ambiguous work). Pass it as --model <nick> to the next command.

<!-- lifecycle: recurring --> — place on line 2 of any card to mark it as a recurring pipeline. After play completes, flowdeck auto-resets all ## BOT checkboxes ([x] → [ ]) so the card stays on the table, ready to run again. Claude is instructed not to meld or manually reset the card. As a safety net, if a recurring card does get melded anyway, flowdeck meld detects the marker and automatically restores the card to the table via flowdeck blank --yes — no manual recovery needed. Use this for cards that run repeatedly on demand rather than shipping once — release pipelines, triage cards, recurring reports. The default behavior (no annotation, or <!-- lifecycle: one-shot -->) melts the card on completion.

Positional arguments (--arg-1, --arg-2, …--arg-N) let you parameterise a card at play time. Write {--arg-1} anywhere in the card body; the CLI substitutes the supplied value before handing the card to Claude. Unmatched placeholders pass through silently. Unused flags are ignored.

flowdeck flash <slug> — review without executing

flowdeck flash payments
# annotates the card with analysis, questions, and risks — no tasks executed

Claude reads the card and writes observations into ## HUMAN → #### COMMENTS. Anything requiring a decision becomes a - [ ] item under ## HUMAN. BOT tasks are left untouched. Useful before starting a card to surface unknowns.

flowdeck deal <slug> — write concrete tasks without executing

flowdeck deal payments
# reads COMMENTS and context, then fills in concrete BOT tasks — no tasks executed

flowdeck deal payments --upgrade
# enriches a card with subtasks, POSSIBILITIES, HUMAN questions, and RISKS — no tasks executed

flowdeck deal payments --upgrade --energy SPEC
# same as --upgrade, plus attaches a filled mdblu SPEC template as a companion doc

Claude reads the card's #### COMMENTS, HUMAN questions/answers, and any existing BOT items, then replaces placeholder or vague - [ ] items with concrete, actionable tasks (specific file paths, what to change, expected outcome). Nothing is executed. Useful after flash to translate analysis into a ready-to-play card.

The --upgrade flag switches to enrichment mode: Claude expands vague tasks into subtasks, adds a #### POSSIBILITIES section with unexplored approaches, appends unanswered decision questions under ## HUMAN, and adds a #### RISKS section. Use before play when a card needs more depth before execution.

The --energy <template> flag (usable standalone or with --upgrade) calls the mdblu use_template tool, saves the blank template to .flowdeck/_energy-cards/<slug>-<template>.md.template, fills it based on the card's context, and saves the filled version alongside the card at .flowdeck/<slug>/<slug>-<template>.md.

The --pick-energy-card flag lets the bot decide: it reads the available templates from .flowdeck/_energy-cards/, evaluates the card's context, and either auto-applies the single best match (same path as --energy) or writes a #### ENERGY note in the card if no template is applicable.

flowdeck kemps <slug> — suggest answers to HUMAN questions

flowdeck kemps payments
# suggests answers for all unanswered > _answer:_ stubs under ## HUMAN

Claude reads each unanswered - [ ] item under ## HUMAN — specifically those followed by an empty > _answer:_ stub — and replaces the stub with > _kemps:_ <suggested answer>. The - [ ] item stays unchecked; the human reviews the suggestion and either accepts it (changing _kemps:_ to _answer:_) or edits as needed. Useful when HUMAN questions are blocking deal or play and you want the AI to propose answers rather than waiting for manual input.

flowdeck blank <slug> — distill annotated card into a clean version

flowdeck blank payments
# prompts for confirmation before overwriting

Claude reads the full annotation history — answered questions, COMMENTS, checked tasks and their notes — and produces what you would have written from scratch knowing everything in that history. Answered questions become baked-in constraints in task descriptions; all annotation scaffolding (#### COMMENTS, > _answer:_, > _kemps:_ stubs, checked-off HUMAN items) is stripped. All checkboxes are reset to [ ]. This is not a reset — it's a distillation. The rewritten card is shown in the terminal and you confirm before it overwrites the original.

When to use blank vs deal: deal reads the card's intent and writes tasks from scratch, ignoring annotation history. blank reads a card that went through annotation cycles and produces a clean version incorporating every decision already made — eliminating the need to re-read history each time the card is played.

flowdeck turn — full hand

flowdeck turn

Passes every card with open ## BOT items to Claude in one call. Claude:

1. Assesses the hand — decides play order, flags duplicates, identifies cards that can be combined
2. Discards obsolete or redundant cards (moves items to ## DISCARDED, keeps the file)
3. Combines complementary cards into a single efficient pass
4. Executes — works through all cards in chosen order, committing after each
5. Docs pass — updates FLOWDECK.md, README.md (unless docs: flowdeck-only), AGENT.md insights, and cross-card notes holistically

--review flag — after each card's BOT section completes, a separate read-only reviewer agent checks the diff against the card's tasks and writes .flowdeck/<slug>/REVIEW.md (Pass / Needs attention + findings). The reviewer never modifies source files. Opt-in per card with review: true in card frontmatter, or apply to the whole turn with flowdeck turn --review.

model: frontmatter — override the model used to play a specific card. Accepts an alias (Shark, Wale, etc.) or a raw model ID. Example:

---
model: Shark
---

Backlog health — printed at the end of every turn: cards in _stock/, melded this week, played this turn. If melded > authored (stock + played), pause and write cards before the next turn. Target: 3–5 cards in _stock/.

FLOWDECK.md is the living project document

FLOWDECK.md at the project root is injected into every play and turn prompt after AGENT.md. It carries the current project state so Claude can make consistent decisions across sessions without re-reading the codebase. Update it at meld time to reflect what shipped.

Structure: ## Vision (one paragraph), ## Current state (shipped capabilities), ## Known gaps (open issues).

AGENT.md is the project context

.flowdeck/AGENT.md is the first thing Claude reads on every play and turn. Keep it updated with architecture notes, preferences, and current priorities. It's yours to maintain — flowdeck never overwrites it after init.

docs: mode — add a plain line docs: flowdeck-only anywhere in AGENT.md to restrict all doc updates to FLOWDECK.md only (no README edits). The default (docs: readme) lets Claude update both.

Templates

.flowdeck/_energy-cards/ contains a curated set of mdblu templates (SPEC, MISSION, OPEN-QUESTIONS, ADR, GENERALINSIGHTS, PROJECTINSIGHTS, CLAUDE). Claude can use these when creating structured documents during a session.

To get more templates:

mdblu get --all --output .flowdeck/_energy-cards/

Commands

| Command | What it does | |---------|-------------| | flowdeck auth google [--status\|--force] | Browser OAuth flow — opens system browser, saves tokens to ~/.config/flowdeck/tokens/google.json; reads credentials from ~/.config/flowdeck/google-oauth.json; --status shows token state; --force re-authorizes | | flowdeck init | Create .flowdeck/ scaffold in the current directory (idempotent for pile setup) | | flowdeck decks [--json] | List installable decks from the mdblu registry (name + description); --json for machine-readable output | | flowdeck install <deck> [--global] | Install a deck (blueprints + energy cards) from mdblu; defaults to local install when inside a project — runs flowdeck init if needed, patches AGENT.md, runs flowdeck wildcard <deck>-init --auto-discard; --global installs to ~/.flowdeck/ only (no scaffolding); supports local paths (../my-deck) | | flowdeck play <slug> [--arg-1 val] … | Play a single card — Claude executes all BOT tasks; --arg-N val substitutes {--arg-N} placeholders in the card before execution; single-segment slug infers column automatically | | flowdeck flash <slug> | Review a card — Claude annotates without executing; column inferred if slug has no / | | flowdeck deal <slug> | Write concrete BOT tasks from context — no execution; column inferred if slug has no / | | flowdeck kemps <slug> | Suggest answers to unanswered HUMAN questions — writes > _kemps:_ stubs; column inferred if slug has no / | | flowdeck all-in <card-slug> | One-shot pipeline over an existing card: flash → kemps → deal --pick-energy-card → play --auto-meld, where each step runs on the agent nick suggested by the previous step's <!-- next: --> comment (falls back to the command default when absent/unknown); optimistic (melds on success, recoverable from _meld/) | | flowdeck blank <slug> | Distill an annotated card into a clean, ready-to-play version — bakes decisions in, strips annotation history, confirms before overwrite; column inferred if slug has no / | | flowdeck clean | Reset .flowdeck/AGENT.md and FLOWDECK.md to generic scaffold content — strips project-specific context; use before open-sourcing a template. --yes / -y skips the confirmation prompt | | flowdeck turn | Pass the full hand to Claude — orchestrates cards in parallel, executes, documents | | flowdeck turn <column> | Restrict a turn to cards under the named column — warns on cross-column depends: | | flowdeck turn --serial | Run cards sequentially using the legacy single-agent path | | flowdeck turn --review | Run turn with a reviewer agent after each card; writes REVIEW.md per card | | flowdeck add <column> [title] | Create a new column and card — auto-slugifies name; if slug already exists anywhere (any deck or pile), appends -2, -3, … to make it unique; --blueprint <name> to start from a saved blueprint; --human to place the open task under ## HUMAN instead of ## BOT | | flowdeck create-card <deck> <column> <slug> [--data '{}'] | Programmatic card creation from a JSON payload — resolves <deck> against all installed decks (.flowdeck, .crunchdeck, etc.); validates column exists; auto-suffixes slug on collision; maps all --data keys to frontmatter with title as the card heading | | flowdeck append <column> <task> | Append a task to a card (ends with ? or --human → goes to HUMAN) — infers column for single-segment names, falls back to pile search | | flowdeck meld <card> | Move a completed card to _meld/ — bot writes delivery summary | | flowdeck meld <column> | Batch-meld all complete cards under a column in parallel — skips incomplete cards with a warning; errors if the name matches both a direct card and sub-cards | | flowdeck meld <card1> <card2> ... | Meld multiple slugs/columns in parallel — skips cards with open BOT items and reports a ✓ N melded, ✗ N failed summary; exits non-zero if any failed | | flowdeck discard <card> | Move a cancelled card to _discard/ — warns if open tasks remain; --force skips the prompt | | flowdeck frozen <card> [-m note] | Park a blocked card in _frozen/ — bot writes blocking condition and unfreeze signal | | flowdeck stock <card> | Move a card to _stock/ backlog | | flowdeck bring <card> | Return a card from any pile back to the table | | flowdeck bring --all | Move all cards from _stock/ back to the table in one shot | | flowdeck wildcard <blueprint> [--auto-meld\|--auto-discard] | Instantiate a blueprint with an auto-timestamp slug (<name>-YYYYMMDDHHmmss) and play it immediately — auto-melds on success (or discards with --auto-discard), stays on table on failure; both flags skip confirmation prompts; forwards --with params | | flowdeck blueprint save <card> [--global] [--force] | Copy a card to _blueprints/ (or ~/.flowdeck/_blueprints/ with --global) — resets checkboxes, strips comments and answers; --force overwrites existing blueprint | | flowdeck blueprint use <blueprint> <column> [title] [--force] | Create a new card from a saved blueprint; --force overwrites an existing card | | flowdeck blueprint list | List local and global blueprints | | flowdeck blueprint update [--force] | Pull global blueprints into local _blueprints/ (skip-if-present; --force overwrites) | | flowdeck agents | List resolved model aliases for this project — shows active alias → model-id mapping and which command maps to which player | | flowdeck fan | Agent commentary on the full hand — summary, dependencies, priorities; writes .flowdeck/fan.md (unstaged) | | flowdeck pick <card-slug> [--edit] | Print a card's TODO.md to stdout; resolves single-segment slugs like play; --edit opens it in nano | | flowdeck list | List card slugs on the table (one per line); --discard, --meld, --stock, --frozen to list a pile instead | | flowdeck lint | Check all table and _stock/ cards for structural issues | | flowdeck gh-sync <card-file> | Sync card state to a linked GitHub Issue | | flowdeck serve [--port 7331] | Start the HTTP API server on localhost |

Slash commands

After flowdeck init, your project gets slash commands in .claude/commands/:

| Slash command | What it does | |---------------|-------------| | /play-card <slug> | Play a single card by name | | /turn | Play the full hand (assess, discard, combine, execute, document) | | /add-card <column> [tasks] | Create a new column and card | | /append-card <column> <task> | Append a task or note to an existing card |

flowdeck gh-sync — GitHub Issues integration

Link a card to a GitHub Issue and keep them in sync across the human↔AI lifecycle.

Step 1 — add github_issue frontmatter to a card:

---
github_issue: owner/repo
github_labels: [feature, backend]
---
# payments

Step 2 — run gh-sync at each lifecycle phase:

# Create the GitHub Issue (writes issue number back to the card)
flowdeck gh-sync .flowdeck/payments/TODO.md

# After Claude completes BOT tasks — posts a completion report as a comment
flowdeck gh-sync .flowdeck/payments/TODO.md --phase bot-done

# After human review — closes the issue
flowdeck gh-sync .flowdeck/payments/TODO.md --phase human-done

Omitting --phase auto-detects: if all ## HUMAN checkboxes are checked → human-done, otherwise → bot-done.

Lifecycle labels applied automatically:

| Phase | Label applied | Labels removed | |-------|--------------|----------------| | created | flowdeck:draft | — | | bot-done | flowdeck:review | flowdeck:draft, flowdeck:bot | | human-done | flowdeck:done | flowdeck:draft, flowdeck:bot, flowdeck:review |

Labels are auto-created in the repo on first use.

Options:

| Flag | Effect | |------|--------| | --phase <created\|bot-done\|human-done> | Force a specific phase | | --dry-run | Print what would happen without making API calls | | --no-create | Error instead of auto-creating a new issue | | --token <token> | GitHub token (default: $GITHUB_TOKEN) | | --verbose | Log API requests to stderr |

Requires a GitHub token with repo scope (issues read/write). Set GITHUB_TOKEN or pass --token.

flowdeck serve — HTTP API

Expose flowdeck over a local HTTP API so any tool — GitHub Actions, VS Code extensions, Codex CLI, web dashboards — can drive the same workflow without coupling to Claude Code.

flowdeck serve                  # start on port 7331 (default)
flowdeck serve --port 9000      # custom port
flowdeck serve --no-auth        # disable token check
flowdeck serve --agent codex    # override default agent

The server binds to 127.0.0.1 only. Set FLOWDECK_API_TOKEN to enable bearer token auth (all endpoints except /flowdeck/health require the header when set).

Endpoints:

| Method | Path | What it does | |--------|------|-------------| | GET | /flowdeck/health | Liveness check — no auth required | | GET | /flowdeck/status | Server state, active card, git status | | GET | /flowdeck/cards | All cards with current states | | GET | /flowdeck/cards/:id | Single card | | POST | /flowdeck/run | Start a card's BOT section ({ card_id }) | | POST | /flowdeck/run/:id/cancel | Cancel a running card | | POST | /flowdeck/turn | Run a full deck turn | | POST | /flowdeck/cards/:id/human-done | Mark HUMAN section complete, commit | | GET | /flowdeck/deck | Full deck as JSON (raw + cards + agent context) | | POST | /flowdeck/deck/sync | git pull --rebase and re-parse deck | | GET | /flowdeck/events | SSE stream — real-time BOT output and state changes |

Card states: idle → bot-running → bot-done → human-pending → human-done → archived

SSE events: bot:output (streaming text), bot:done, state:change, error. Clients reconnect with Last-Event-ID to replay from the ring buffer (last 100 events).

Nested card slugs use -- as separator in URLs: .flowdeck/payments/stripe-webhook/TODO.md → card id payments--stripe-webhook.

Environment variables:

| Variable | Default | Effect | |----------|---------|--------| | FLOWDECK_API_TOKEN | — | Enable bearer auth | | FLOWDECK_PORT | 7331 | Default port | | FLOWDECK_AGENT | claude-code | Default agent |

Pile management — card lifecycle

Cards have a full lifecycle beyond the active table. Four piles handle different terminal and parked states:

.flowdeck/
  _meld/     ← shipped — all tasks done
  _discard/  ← cancelled or abandoned
  _frozen/   ← blocked on an external condition
  _stock/    ← backlog, not yet ready

flowdeck init creates these directories (idempotent — safe to run on an existing project). Existing done/ contents are migrated to _meld/ automatically.

flowdeck meld <card> — mark a card as successfully shipped. Claude reads the completed TODO.md and writes a delivery summary to _meld/<card>/MELD.md. The CLI appends a row to _meld/MELD.md index.

flowdeck discard <card> — cancel a card. If open tasks exist, you'll be prompted to confirm. Pass --force to skip the prompt and discard immediately. The CLI writes a DISCARD.md listing any dropped tasks. No index — discard is a graveyard.

flowdeck frozen <card> [-m "note"] — park a blocked card. The CLI moves it and writes a FREEZE.md stub. Claude then fills in the Blocking Condition and Unfreeze Signal — concrete, observable text so turn can auto-check whether the block has lifted. The card is added to _frozen/FROZEN.md.

flowdeck stock <card> — defer a card to the backlog. The CLI adds a row to _stock/STOCK.md with a description derived from the card's first task.

flowdeck bring <card> — return any card from any pile back to the active table. The CLI finds it, moves it, and removes it from the relevant index.

flowdeck bring --all — move every card from _stock/ back to the table in one command. Cards already on the table are skipped with a warning.

Decks

A deck is a named, installable set of blueprints and energy cards that extends flowdeck for a specific domain. Decks are distributed via mdblu under decks/<name>/ and installed into any project with a single command.

Installing a deck

# Inside any project — local install (default)
flowdeck install crunchdeck

# Global install — blueprints available to all future projects
flowdeck install crunchdeck --global

Local install (the default when .flowdeck/ is found or --local is passed) does four things in sequence:

1. Runs flowdeck init if .flowdeck/ doesn't exist yet
2. Copies the deck's blueprints into .flowdeck/_blueprints/ and energy cards into .flowdeck/_energy-cards/
3. Appends the deck's context section to .flowdeck/AGENT.md
4. Runs flowdeck wildcard <deck>-init --auto-discard — scaffolds the deck's working directory and discards the init card, leaving no residue in the active deck

One command from a blank project to a fully initialized environment.

--global skips steps 3 and 4 and installs into ~/.flowdeck/ only — blueprints become available to all future projects via flowdeck init, but no project-specific scaffolding runs.

Available decks (in mdblu/decks/):

| Deck | What it installs | |------|-----------------| | crunchdeck | Product management — PROFILE, BACKLOG, ROADMAP, ADR, and signal cards under .flowdeck/.crunchdeck/ | | emaildeck | Gmail filter rules as flowdeck cards — fetch, label, and create message cards under .flowdeck/.emaildeck/. Run flowdeck emaildeck init to scaffold the directory and install emaildeck_run.js (the Node runner that executes domain-based filters without a model). | | creamdeck | Project-scoped CRM — contacts, inbox items, and tickets under .flowdeck/.creamdeck/. Run flowdeck creamdeck init to scaffold the directory structure and install creamdeck_html.js (static HTML export for ticket reports). | | notedeck | Freeform notes as flowdeck cards under .flowdeck/.notedeck/ |

Creating a deck

The new-deck blueprint ships with every flowdeck init. Run it inside any deck registry (a repo with a decks/ folder):

flowdeck wildcard new-deck
# prompts for the deck name, then scaffolds decks/<name>/ and updates decks/DECKS.md

This creates the full deck skeleton:

decks/<name>/
  manifest.json          ← { "blueprints": [...], "energyCards": [...] }
  blueprints/
    <name>-init/
      TODO.md            ← scaffolds the deck's working directory on install
  energy-cards/
    .gitkeep             ← add *.md.template files here
  AGENT-section.md       ← appended to .flowdeck/AGENT.md on local install

After scaffolding: flesh out the init blueprint, add energy-card templates, fill in the description in DECKS.md, then push and install with flowdeck install <name>.

Blueprints

_blueprints/ stores reusable card skeletons. Unlike lifecycle piles, blueprints are resources — bring and find ignore them.

Five default blueprints ship with every flowdeck init: feature, bugfix, chore, spike, release.

flowdeck blueprint save <card> [--global] [--force] — copy an existing card to _blueprints/<card>/TODO.md. Resets all [x] items to [ ], strips the #### COMMENTS block, and removes > _answer:_ / > _kemps:_ lines. Add --global to save to ~/.flowdeck/_blueprints/ instead, making it available to all projects. --force overwrites an existing blueprint and updates its index entry.

flowdeck blueprint use <blueprint> <column> [title] [--force] — create a new card at .flowdeck/<column>/TODO.md using the named blueprint. Replaces the title line; everything else is verbatim. Falls back to ~/.flowdeck/_blueprints/ if the blueprint is not found locally. --force overwrites an existing card.

flowdeck blueprint list — print local blueprint names (one per line), then global ones tagged (global).

flowdeck blueprint update [--force] — pull global blueprints from ~/.flowdeck/_blueprints/ into the local _blueprints/. Skips any that already exist locally; use --force to overwrite.

flowdeck add <column> --blueprint <name> — shorthand for blueprint use; creates the card in one step with the column name as title unless a title is also given.

On flowdeck init, global blueprints are automatically copied into the new project's _blueprints/ (skip-if-present), so any blueprints you've saved globally appear in every new project.

During flowdeck turn, Claude reads _frozen/FROZEN.md and evaluates each card's Unfreeze Signal against the current codebase. Cards whose conditions are met are brought back automatically (or surfaced in ## HUMAN for your approval).

Folder structure

New subject → new folder under .flowdeck/:

.flowdeck/
  payments/
    TODO.md
    stripe-webhook/     ← subtask
      TODO.md
  auth/
    TODO.md

flowdeck add payments "Stripe integration"
flowdeck add payments/stripe-webhook

License

MIT