creamdeck

A CRM layer for flowdeck. Extends any .flowdeck/ project with structured contact management, issue tracking, interaction logging, and AI-driven follow-ups — all in Markdown, all in git.

Setup

npm install -g creamdeck
creamdeck init          # scaffold .creamdeck/ with demo records
creamdeck init --empty  # scaffold without demo data

Requires an existing .flowdeck/ project. If flowdeck is not installed, creamdeck installs it automatically.

Quick reference

creamdeck add person "Jane Smith" --class lead --org acme-ltd
creamdeck add org "Acme Ltd"
creamdeck add issue "Login broken" --person jane-smith --severity high
creamdeck add request "Custom export" --person jane-smith
creamdeck add call jane-smith
creamdeck add email jane-smith --subject "Re: proposal" --direction inbound

creamdeck list people [--class lead] [--org acme-ltd]
creamdeck list issues [--open]
creamdeck play <slug>   # play one card with full CRM context injected
creamdeck turn          # play all cards with open BOT tasks

Flowdeck proxy commands

creamdeck proxies the most useful flowdeck card commands so you never need to type .creamdeck/ paths. Pass the short card name — creamdeck resolves the rest:

creamdeck flash <slug>               # review card, add comments, no execution
creamdeck meld <slug>                # ship card → _meld/
creamdeck discard <slug>             # cancel card → _discard/
creamdeck frozen <slug> [-m <note>]  # block card → _frozen/
creamdeck stock <slug>               # move card to _stock/ backlog
creamdeck bring <slug>               # return card from _stock/ to the table
creamdeck blank <slug>               # distill annotated card into a clean version
creamdeck pick <slug> [--edit]       # print card content to stdout
creamdeck gh-sync <slug>             # sync card to linked GitHub Issue

Each command resolves the slug against all .creamdeck/ entity directories and forwards the full slug to flowdeck.

How cards work

Each entity (person, org, issue, request, interaction) is a flowdeck card — a directory with a TODO.md file. The ## BOT section is Claude's inbox. The ## HUMAN section is yours. creamdeck play <slug> injects linked context (PERSON.md, ORG.md, MESSAGE.md, attachments) before Claude runs.

Commented tasks

Entity cards ship with commented-out BOT tasks for one-off actions that don't justify a full blueprint. They sit at the bottom of the ## BOT section, dormant by default. When you want to perform the action, remove the comment markers — the task becomes active on the next play or turn.

## BOT
- [x] Review interactions/ log for the last 30 days
- [x] Draft follow-up or check-in message
- [ ] Note any open issues or requests linked to this contact
<!-- - [ ] Renew this client: review last_contact and open issues, draft renewal proposal -->

Uncomment when ready:

- [ ] Renew this client: review last_contact and open issues, draft renewal proposal

Available commented tasks by card type

| Card type | Class | Commented task | |-----------|-------|----------------| | person | lead | Promote this lead to client: update class, swap BOT tasks, log conversion | | person | client | Renew this client: review health, draft renewal proposal | | person | partner | Check in with this partner: summarise open items, draft message, list follow-ups | | org | — | Enrich org data: identify empty ORG.md fields, research and fill each one | | org | — | Fetch org emails from Gmail: search by org domain, retrieve threads, tag each with CREAMDECK | | issue | — | Close this issue: confirm resolution, update status, notify contact, log outcome | | email | — | Create contacts from this email: identify people mentioned or CC'd, scaffold new person cards | | email | — | Create cards from action items: extract commitments, scaffold an issue or request per item |

These are embedded in the card templates so every new card of that type gets them automatically.

Blueprints

Blueprints are reusable card templates scaffolded by flowdeck scaffold <name>. creamdeck ships one default blueprint:

weekly-review

A wildcard sweep for the whole CRM. Run it at the start of each week.

## BOT
- [ ] List all people with `last_contact` older than 7 days — flag overdue ones under HUMAN
- [ ] List open issues and requests; surface any blocked or stale ones under HUMAN
- [ ] Summarise the week: contacts made, issues closed, new leads added

## HUMAN
- [ ] Review the flagged overdue contacts and decide who to reach out to
- [ ] Review stale issues — close, reassign, or defer each one

It is not entity-bound — it works across the entire .creamdeck/ dataset, making it useful as a recurring wildcard regardless of which contacts or issues are currently active.

Scaffold one:

flowdeck scaffold weekly-review
flowdeck play weekly-review

Why only one blueprint

The other common CRM actions (renew, promote, check-in, close, enrich) are entity-specific by nature — they need a slug to operate on and produce a result that belongs on that entity's card. A full blueprint for those adds ceremony with no benefit over uncommenting a task line. The blueprint pattern is reserved for workflows that are context-free and recurring.

Directory structure

.flowdeck/
└── .creamdeck/
    ├── AGENT.md
    ├── contacts/
    │   ├── organizations/<org-slug>/{TODO.md, ORG.md}
    │   └── people/<person-slug>/{TODO.md, PERSON.md}
    ├── issues/<issue-slug>/TODO.md
    ├── requests/<request-slug>/TODO.md
    └── interactions/
        ├── calls/<YYYY-MM-DD-person-slug>/TODO.md
        └── emails/<YYYY-MM-DD-subject-slug>/{TODO.md, MESSAGE.md, attachments/}

creamdeck records live at level 4+ inside .flowdeck/, so flowdeck turn never picks them up. Use creamdeck turn to work the CRM hand.

Person classes

| Class | Focus | |-------|-------| | lead | Research + first outreach | | client | Follow-up + open issues | | partner | Shared initiatives + blockers | | colleague | Action items + sync agenda | | provider | Contract/SLA + invoices |

Each class generates class-appropriate default BOT tasks when the card is created.

Commit format

crm: <slug> — <what changed>