fizzydo

name	fizzydo
description	Tracks project work on fizzy.do via the fizzydo CLI. Auto-derives a canonical project name from the working directory, auto-creates a kanban board with TODO/DOING/DONE columns if one does not already exist, and tags every card with a shared task tag so multiple tasks can coexist on one project board. TRIGGER this skill automatically whenever you create a TODO item or break down a task into sub-tasks — every task should be traceable. Also trigger when the user asks to plan a task, track work, mentions fizzy.do, fizzydo, or kanban task management.
license	MIT
metadata	{"version":"0.1.0","author":"fizzydo","homepage":"https://github.com/delip/fizzy-cli"}

fizzydo — Agent Task Tracking

Tracks project work on fizzy.do through the fizzydo CLI. Auto-creates a per-project kanban board if none exists and tags each task's cards with a shared task tag so multiple tasks can coexist on one project board.

When to use this skill

• Automatically whenever you create a TODO item or break down a task into sub-tasks — every task should be traceable
• When the user asks to plan work, track tasks, or manage a kanban board
• When the user mentions fizzy.do, fizzydo, or kanban task management

Do NOT use for unrelated CLI work or queries that don't involve task tracking.

Pre-flight checks

Run these before first use in a session:

command -v fizzydo >/dev/null || { echo "Install fizzydo: pipx install fizzydo"; exit 1; }
command -v jq      >/dev/null || { echo "Install jq: brew install jq (or apt install jq)"; exit 1; }
fizzydo auth whoami >/dev/null 2>&1 || { echo "Set FIZZYDO_API_KEY in env or .env file"; exit 1; }

Step 1 — Source the helper library and resolve the board

source "<skill-dir>/scripts/fizzydo-lib.sh"
fizzydo_resolve_board

This handles the full chain automatically:

1. If .fizzydo.json exists, loads BOARD_ID, TODO_ID, DOING_ID, DONE_ID from it
2. Otherwise, derives a canonical project name from directory contents (pyproject.toml, package.json, Cargo.toml, go.mod, git origin, or basename)
3. Looks up a board with that name on fizzy.do
4. If none exists, creates it with three columns: TODO (gray), DOING (yellow), DONE (lime)
5. Writes .fizzydo.json and ensures it's in .gitignore

If the board was just created, announce its name to the user.

Step 2 — Choose the task tag

Before proposing a new tag, check the most recently changed card on the board:

RECENT_TAG=$(fizzydo --json cards list --board "$BOARD_ID" --sort latest --limit 1 \
  | jq -r '.[0].tags[0].title // empty')

• If a tag is found and the user's current request is a continuation of that work, re-use it. Announce: "Continuing task <tag>."
• Otherwise, derive a short kebab-case slug from the user's request (e.g., "add OAuth to login" becomes oauth-login). Announce: "I'll tag all cards for this task with oauth-login."
• Store the chosen tag: TASK_TAG="oauth-login"
• The tag is session-scoped — do NOT persist it to .fizzydo.json.

Step 3 — Seed TODO with the task breakdown

fizzydo_add_todo "Design token schema"   "- Pick storage backend\n- Document schema"
fizzydo_add_todo "Implement middleware"   "- Behind feature flag\n- Add unit tests"
fizzydo_add_todo "Write migration script" "- Background job\n- Verification query"

fizzydo_add_todo attaches $TASK_TAG atomically via --tag at creation time. Keep descriptions brief — simple bullet points, not long prose.

CRITICAL: Never call fizzydo cards tag directly — it is a toggle that will remove the tag on a second call. Always use fizzydo_add_todo or fizzydo --json cards create --tag.

Step 4 — Execute the workflow

fizzydo_start "$NUM"     # move card to DOING
fizzydo_finish "$NUM"    # move card to DONE
fizzydo_task_cards       # list this task's cards (JSON)

When new sub-tasks surface mid-work, create them immediately with fizzydo_add_todo — same TASK_TAG, straight into TODO.

The contract

• One board per project (auto-created on first use)
• Exactly three columns: TODO, DOING, DONE
• Every card tagged with TASK_TAG at creation time via --tag
• Plan first (seed TODO) before moving anything to DOING
• Add newly discovered work to TODO the moment you notice it
• Cards referenced by number (integer), not UUID
• Never parse Rich-table output — always use --json or --id
• Never call fizzydo cards tag (it's a toggle)
• Never use cards close/reopen/not-now/golden/watch/pin unless the user explicitly asks
• .fizzydo.json stays gitignored

References

• For the full derivation heuristic, all recipes, and anti-patterns: read references/workflow.md
• For the complete command catalog (every sub-app, every flag): read references/commands.md
• If a fizzydo call fails or returns a non-zero exit code: read references/troubleshooting.md

Example trace

source "<skill-dir>/scripts/fizzydo-lib.sh"
fizzydo_resolve_board                          # → Board 'my-project' (03ftrxk...)
TASK_TAG="oauth-login"
N1=$(fizzydo_add_todo "Design token schema"    "- Pick storage\n- Document schema")
N2=$(fizzydo_add_todo "Implement middleware"    "- Feature flag\n- Unit tests")
N3=$(fizzydo_add_todo "Write migration"         "- Background job\n- Verify query")
fizzydo_start "$N1"                            # → N1 moves to DOING
# ... do the work ...
fizzydo_finish "$N1"                           # → N1 moves to DONE
fizzydo_task_cards                             # → shows N2, N3 still in TODO