fizzy-workflow

skill.md

name	description
fizzy-workflow	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.

Fizzy Workflow Skill

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

1. Starting a Card

When: Beginning work on a new card

Steps:

1. Get card details: fizzy card show CARD_NUMBER
2. Find "Doing" column ID: fizzy column list --board BOARD_ID
3. Move to "Doing" column: fizzy card column CARD_NUMBER --column <doing_column_id>
4. Assign to bot/self: fizzy card assign CARD_NUMBER --user <bot_user_id>

Example:

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

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

# Assign to bot
fizzy card assign 15 --user <bot_user_id>

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: 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 3: Post Completion Comment

fizzy comment create --card NUMBER --body "$(cat <<'EOF'
<p>✅ Completed and committed to GitHub</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 4: 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: .id, name: .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 (bot vs human)
• Close cards when truly complete
• Update steps as you progress

❌ DON'T:

• Leave cards in wrong columns
• Close cards with incomplete work
• Forget to assign cards
• Skip step updates

---

Common Patterns

Pattern: Multi-Step Card Workflow

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

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

# 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 assign 20 --user <bot_user_id>

# 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 -r '.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 Script: Get Project Context

Save this as a shell script to quickly get project-specific IDs:

#!/bin/bash
# fizzy-context.sh - Get project context for workflows

echo "=== Fizzy Project Context ==="
echo

# Board info
echo "Boards:"
fizzy board list | jq -r '.data[] | "  \(.name): \(.id)"'
echo

# Ask for board
read -p "Enter board ID: " BOARD_ID

# Column info
echo "Columns:"
fizzy column list --board $BOARD_ID | jq -r '.data[] | "  \(.name): \(.id)"'
echo

# User info
echo "Your user ID:"
fizzy identity show | jq -r '.accounts[0].user | "  \(.name) (\(.email_address)): \(.id)"'
echo

# Repo info
echo "Git repository:"
git remote get-url origin 2>/dev/null || echo "  Not in a git repository"

---

Summary

This workflow skill provides structured patterns for:

1. Starting cards - Move to Doing, assign to bot
2. Working on cards - Mark steps, post concise updates
3. Completing cards - Commit (no Fizzy mention), post link, close
4. Delegating cards - Assign to human for manual tasks

Always use conventional commits, keep comments brief, and follow the established patterns for consistency across the project.