🚀 fpm (Fizzy Project Manager)

fpm is a CLI tool that bridges remote Fizzy boards with your local workspace. Pull boards as markdown, edit locally, and sync changes back.

Use with the fizzy CLI — fpm handles local board mirroring and sync; fizzy handles all direct Fizzy operations (cards, comments, columns, etc.).

✨ Key Features

• fpm setup [boardId]: Initialize a project with .fizzy.yaml config and install git hooks
• fpm new <name>: Create a new Fizzy board and local directory (auto-pulls after creation)
• fpm pull [boardId]: Mirror a remote board locally as markdown files. Omit boardId to pull the current branch's board.
• fpm push: Push local markdown changes back to Fizzy cards (alias: sync)
• fpm card <title>: Create a new card on the current board with rich metadata
• fpm comment <card> <text>: Add a comment to a card and pull latest state
• fpm assign <card>: Self-assign a card
• fpm ls: List all locally tracked boards and branches

🛠️ Installation

# Clone and install globally
git clone https://github.com/transitchat/fizzy-project-manager.git
cd fizzy-project-manager
npm install -g .

📖 Workflow

For an interactive workflow you can run fpm and you would have access to everything you need to get started in a user friendly interface.

For a more traditional cli

# 1. Initialize (creates .fizzy.yaml + git post-checkout hook)
fpm setup

# 2. Pull a board (or switch to its branch)
fpm pull <board_id>

# 3. Edit card files locally
# Edit .fpm/<board>/<column>/<number>-<slug>.md

# 4. Push changes back
fpm push

# 5. Comment on a card (auto-pulls after)
fpm comment 212 "Needs revision"

# 6. Self-assign a card
fpm assign 212

# 7. Create a new card on the current board
fpm card "Fix login bug" -d "Description here" -c "Backlog"

# 8. Create new boards (auto-pulls after creation)
fpm new "Feature Name"

# 9. List local boards
fpm ls

📂 Card File Format

Card files use YAML frontmatter for metadata and markdown sections for content:

---
title: Fix login bug
card_id: 03gllives91u85q81r56ey7of
number: 212
column: Design
column_id: 03gllis6lig0q2dhervvytj46
created_at: '2026-08-01T03:27:57.179Z'
closed: false
comments:
  - author: Walter Jenkins
    created_at: '2026-08-01T04:59:36.753Z'
    body: this is a test comment
---

## Description

Fix the login bug reported by user #1234

• Frontmatter: Metadata (title, card_id, column, timestamps, comments)
• ## Description: Card body — synced to Fizzy on fpm push

When pushing, frontmatter is stripped; only the ## Description body is sent to Fizzy. Comments are stored locally only (in frontmatter) and are not synced to Fizzy.

📂 File Structure

.fpm/
├── fpm.json                  # Central registry (boards, columns)
└── <board-slug>/
    ├── <column-1>/
    │   └── <number>-<slug>.md # Card content
    └── <column-2>/
        └── <number>-<slug>.md

fpm.json

Central registry at .fpm/fpm.json. Tracks all boards, columns, and their remote IDs.

.fizzy.yaml

Local config (auto-added to .gitignore). Stores your Fizzy profile and defaults.

🪝 Git Integration

fpm setup installs a .git/hooks/post-checkout hook that auto-pulls the board when you switch branches:

git checkout some-branch
# → fpm pull runs automatically

This enables a single board per git branch workflow — each branch tracks a separate Fizzy board.

🧩 Agent Skill

The .agents/skills/fpm/ directory contains a skill file that teaches AI agents how to use fpm. When cloned, agents will auto-discover and use these commands.

🛠️ Development

# Run locally
pnpm start [command]

# Run TUI
pnpm tui

# Run tests
pnpm test

# Build
tsc

Limitations

• No card movement — Use fizzy card column <number> --column <id> to move cards
• Descriptions only — fpm push syncs card descriptions, not comments or steps (comments are stored locally only)