Fizzy Workflow Skill

High-level workflows for managing work using Fizzy cards. This skill builds on top of the base fizzy skill to provide structured workflows for starting, working on, and completing cards.

Prerequisites

• fizzy — Fizzy CLI binary. Download from github.com/basecamp/fizzy-cli/releases and place in your PATH.
• jq (optional) — Required as fallback if fizzy's built-in --jq flag is unavailable (currently unreleased). Install via brew install jq or apt install jq.

This skill also depends on the base fizzy skill for raw Fizzy CLI operations. If not already installed, install it from github.com/basecamp/fizzy-cli/tree/master/skills/fizzy.

Note on --jq flag: Examples in this skill use fizzy's built-in --jq filter flag, which is currently unreleased. Helper scripts fall back to external jq automatically. The fizzy CLI outputs JSON by default — no output format flag is needed. For inline patterns, replace fizzy ... --jq 'EXPR' with fizzy ... | jq 'EXPR' if needed.

---

Quick Reference

Workflow	When to Use
Start Card	Begin work on a card, move to Doing, assign to self
Complete Card	Finish card, post commit link, close
Update Progress	Mark step complete, post progress
Assign to Human	Delegate to human for manual tasks

---

Workflows

0. Planning Cards (optional)

When: Breaking down a larger task into multiple cards before starting work

Steps:

1. Write a JSON plan file describing all cards and their steps
2. Validate with --dry-run before creating
3. Run the plan to create all cards in one invocation
4. Then pick a card and follow the Start Card workflow

Plan file format:

{
  "board_id": "<board_id>",
  "cards": [
    {
      "title": "Card title",
      "description": "Optional description (markdown or HTML)",
      "tags": ["backend", "urgent"],
      "steps": [
        "Step one",
        "Step two"
      ]
    }
  ]
}

description, tags, and steps are optional per card. Before assigning tags, run fizzy tag list to see existing ones — prefer reusing existing tags over creating new ones to avoid duplicates.

If a card depends on another card, note it clearly in the description, e.g.:

Depends on: #42 (Set up authentication)

Example:

# Dry-run first to verify
python3 fizzy-workflow/scripts/fizzy-plan-create.py plan.json --dry-run

# Create all cards
python3 fizzy-workflow/scripts/fizzy-plan-create.py plan.json

Output (agent-friendly JSON):

{
  "ok": true,
  "dry_run": false,
  "created": [
    {"number": 42, "title": "Card title", "tags": ["backend"], "steps_created": 2}
  ]
}

On failure (e.g. mid-way through), partial is included so the agent knows what was already created:

{
  "ok": false,
  "error": "step create failed: ...",
  "partial": {"number": 42, "title": "Card title", "steps_created": 1}
}

---

1. Starting a Card

When: Beginning work on a new card

Steps:

1. Read the card thoroughly:
   • fizzy card show CARD_NUMBER — title, description, tags, steps
   • fizzy comment list --card CARD_NUMBER — full comment history
   • Understand all requirements, context, and prior discussion before doing anything else
2. Check current git branch:
   • If on main/master: checkout a new feature branch named after the feature (e.g. feat/short-description) — never include card/fizzy numbers in branch names
   • If on an existing feature branch: confirm with the user whether this branch is relevant to the card before continuing
   • It's acceptable to work on multiple cards in the same branch, but each card must be committed separately
3. Find "Doing" column ID: fizzy column list --board BOARD_ID
4. Move to "Doing" column: fizzy card column CARD_NUMBER --column <doing_column_id>
5. Assign to self: fizzy card self-assign CARD_NUMBER

Example:

# Read card thoroughly
fizzy card show 15
fizzy comment list --card 15

# Check branch and prepare
git branch --show-current
# If on main/master:
git checkout -b feat/short-description
# If on a feature branch that may not be relevant: STOP and confirm with user

# Get column IDs
fizzy column list --board BOARD_ID --jq '[.data[] | {id, name}]'

# Move to Doing
fizzy card column 15 --column <doing_column_id>

# Assign to self
fizzy card self-assign 15

What to tell the user:

Card #X moved to "Doing" and assigned. Starting implementation...

---

2. Working on a Card

During implementation:

Mark steps complete:

fizzy step update STEP_ID --card CARD_NUMBER --completed

Post SHORT progress comments:

• Only for completed steps or important milestones
• Keep concise (1-2 sentences) to save tokens
• Include brief justification for design/decision changes

Example progress comment:

fizzy comment create --card 12 --body "$(cat <<'EOF'
<p>✅ Feature X completed</p>
<p>Migration applied: <code>20260211040415_init</code></p>
EOF
)"

IMPORTANT:

• Comments are visible to team, so be clear but brief
• Focus on WHAT was done, not HOW
• Skip obvious/trivial updates

---

3. Completing a Card

When: All work is done and committed

Required steps:

Step 1: Commit to Git

Use conventional commit format, NEVER mention Fizzy (it's external to the project):

git add <files>
git commit -m "$(cat <<'EOF'
feat(scope): implement feature X

Detailed description of what was implemented.

Key changes:
- Feature A
- Feature B
- Feature C
EOF
)"

Conventional commit types:

• feat: New features
• fix: Bug fixes
• docs: Documentation
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance tasks

Step 2: Land changes into main branch

The card must only be closed after changes are in main/master. Infer the right approach from context, or ask the user if unclear:

Option A — Create PR/MR for review (preferred for team projects or when changes need review):

git push origin <branch>
# Then create a PR/MR via gh, glab, or the platform's CLI
gh pr create --title "feat: short description" --body "..."

Wait for the PR/MR to be merged before proceeding to close the card.

Option B — Merge directly to main (for solo projects or pre-approved changes):

git checkout main
git merge --no-ff <branch>   # NEVER fast-forward
git push origin main

Step 3: Get Commit Hash and Repo URL

COMMIT_HASH=$(git log -1 --format="%H")
REPO_URL=$(git remote get-url origin | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')

Step 4: Post Completion Comment

fizzy comment create --card NUMBER --body "$(cat <<'EOF'
<p>✅ Completed and merged to main</p>
<p><br></p>
<p>Commit: <a href="REPO_URL/commit/COMMIT_HASH">SHORT_HASH</a></p>
<p><br></p>
<p><strong>Summary:</strong></p>
<ul>
<li>Key deliverable 1</li>
<li>Key deliverable 2</li>
<li>Key deliverable 3</li>
</ul>
EOF
)"

Step 5: Close Card

fizzy card close CARD_NUMBER

What to tell the user:

✅ Card #X Complete!

**Commit:** [hash](github_url)

**Delivered:**
- Feature A
- Feature B
- Feature C

**Card Status:** ✅ Closed

---

4. Assigning to Human

When to assign to human:

• Tasks that can only be done manually by human
• Tasks requiring confirmation/approval
• Infrastructure decisions (deployment, hosting, CI/CD platforms)
• Security reviews or sensitive configurations
• UI/UX design decisions

How to find human user ID:

# List all users to find the right person
fizzy user list --jq '[.data[] | {id, name, email: .email_address}]'

Assign:

fizzy card assign CARD_NUMBER --user <human_user_id>

Post a comment explaining why:

fizzy comment create --card NUMBER --body "$(cat <<'EOF'
<p>🤝 Assigned for human decision</p>
<p><br></p>
<p><strong>Reason:</strong> [brief explanation]</p>
<p><strong>Questions:</strong></p>
<ul>
<li>Question 1?</li>
<li>Question 2?</li>
</ul>
EOF
)"

---

Best Practices

Comment Guidelines

✅ DO:

• Post when steps complete
• Post for design/decision changes
• Post for important milestones
• Keep to 1-2 sentences
• Use clear, actionable language

❌ DON'T:

• Post for every minor action
• Write long explanations
• Duplicate information already in code
• Use internal/technical jargon unnecessarily

Git Commit Guidelines

✅ DO:

• Use conventional commit format
• Focus on WHAT and WHY
• Include relevant scope
• List key changes in body

❌ DON'T:

• Mention Fizzy (it's external to project)
• Reference card numbers in commits
• Write vague messages
• Skip the commit body for complex changes

Card Management

✅ DO:

• Move cards through workflow stages
• Assign appropriately (self vs human)
• Close cards when truly complete
• Update steps as you progress
• Add relevant tags to cards for discoverability
• Run fizzy tag list and reuse existing tags before creating new ones
• Note dependencies on other cards in the description (Depends on: #N)

❌ DON'T:

• Leave cards in wrong columns
• Close cards with incomplete work
• Forget to assign cards
• Skip step updates
• Create duplicate or near-duplicate tags
• Start a card before its dependencies are complete

---

Common Patterns

Pattern: Multi-Step Card Workflow

# 0. Prepare branch (from main/master)
git checkout -b feat/short-description

# 1. Get board and column info
BOARD_ID=$(fizzy board list --jq '.data[0].id')
DOING_COL=$(fizzy column list --board $BOARD_ID --jq '.data[] | select(.name == "Doing") | .id')

# 2. Start the card
fizzy card column 15 --column $DOING_COL
fizzy card self-assign 15

# 3. Work and mark steps
fizzy step update STEP_1_ID --card 15 --completed
fizzy step update STEP_2_ID --card 15 --completed
# ... continue implementation ...

# 4. Commit
git add <files>
git commit -m "feat: implement feature"

# 5. Complete and close
COMMIT_HASH=$(git log -1 --format="%H")
SHORT_HASH=$(git log -1 --format="%h")
REPO_URL=$(git remote get-url origin | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')

fizzy comment create --card 15 --body "<p>✅ Done. Commit: <a href='$REPO_URL/commit/$COMMIT_HASH'>$SHORT_HASH</a></p>"
fizzy card close 15

Pattern: No-Steps Card Workflow

# 1. Start
fizzy card column 20 --column <doing_col_id>
fizzy card self-assign 20

# 2. Work (no steps to update)
# ... implementation ...

# 3. Commit and complete
git commit -m "feat: implement X"
fizzy comment create --card 20 --body "<p>✅ Done</p>"
fizzy card close 20

Pattern: Delegate to Human

# Find human user
HUMAN_USER=$(fizzy user list --jq '.data[] | select(.role == "owner") | .id')

# Assign and explain
fizzy card assign 26 --user $HUMAN_USER
fizzy comment create --card 26 --body "$(cat <<'EOF'
<p>🤝 Needs human decision on deployment platform</p>
<p>Options: AWS, GCP, or DigitalOcean?</p>
EOF
)"

---

Integration with Base Fizzy Skill

This workflow skill uses the base fizzy skill for all Fizzy CLI operations. When you need to:

• Search cards: Use base fizzy skill
• List boards/columns: Use base fizzy skill
• View card details: Use base fizzy skill
• Execute workflow: Use this skill

Example decision tree:

• User asks "Which cards are available?" → Use base fizzy skill
• User says "Work on card #15" → Use this workflow skill
• User asks "Show card #15 details" → Use base fizzy skill
• User says "Complete card #15" → Use this workflow skill

---

Token Optimization

Keep Comments Concise

Instead of:

<p>I have successfully completed the implementation of the feature which includes all components as specified in the requirements document. The changes have been tested and committed to the repository successfully.</p>

Use:

<p>✅ Feature completed and tested. Changes committed.</p>

Batch Operations

When possible, complete multiple steps before posting a single summary comment:

# Instead of commenting after each step
fizzy step update STEP1 --card 12 --completed
# [work]
fizzy step update STEP2 --card 12 --completed
# [work]
fizzy step update STEP3 --card 12 --completed

# Post one summary
fizzy comment create --card 12 --body "<p>✅ Steps 1-3 complete</p>"

---

Helper Scripts

scripts/fizzy-plan-create.py <plan.json> [--dry-run]

Create multiple cards with steps from a JSON plan file in a single invocation. Use --dry-run to validate the plan before executing. Outputs JSON with created card numbers.

python3 fizzy-workflow/scripts/fizzy-plan-create.py plan.json --dry-run
python3 fizzy-workflow/scripts/fizzy-plan-create.py plan.json

scripts/fizzy-context.sh <board_id>

Get column IDs and git remote for a board — run this before starting a card to look up the "Doing" column ID.

bash fizzy-workflow/scripts/fizzy-context.sh <board_id>

scripts/fizzy-open-cards.sh <board_id>

List all open cards on a board with number, title, and current assignees — useful for picking what to work on next.

bash fizzy-workflow/scripts/fizzy-open-cards.sh <board_id>