Back to Details

fizzy-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fizzy Workflow Skill

Fizzy 工作流技能

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卡片管理工作的高级工作流。本技能基于基础
fizzy
技能构建，提供用于启动、处理和完成卡片的结构化工作流。

Prerequisites

前提条件

The following must be available in 
PATH
:
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.
以下工具必须在
PATH
环境变量中可用：
本技能还依赖于基础
fizzy
技能来执行原始Fizzy CLI操作。如果尚未安装，请从github.com/basecamp/fizzy-cli/tree/master/skills/fizzy安装。

Quick Reference

快速参考

WorkflowWhen to Use
Start CardBegin work on a card, move to Doing, assign to self
Complete CardFinish card, post commit link, close
Update ProgressMark step complete, post progress
Assign to HumanDelegate to human for manual tasks
工作流使用场景
启动卡片开始处理新卡片，移至“进行中”，分配给自己
完成卡片完成卡片，发布提交链接，关闭卡片
更新进度标记步骤完成，发布进度
分配给人工将手动任务委派给人工处理

Workflows

工作流

1. Starting a Card

1. 启动卡片

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:
bash
undefined
适用场景： 开始处理新卡片
步骤：
  1. 获取卡片详情：
    fizzy card show CARD_NUMBER
  2. 查找“进行中”列ID：
    fizzy column list --board BOARD_ID
  3. 移至“进行中”列：
    fizzy card column CARD_NUMBER --column <doing_column_id>
  4. 分配给机器人/自己：
    fizzy card assign CARD_NUMBER --user <bot_user_id>
示例：
bash
undefined

Get column IDs

获取列ID

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

Move to Doing

移至“进行中”列

fizzy card column 15 --column <doing_column_id>
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...

---
fizzy card assign 15 --user <bot_user_id>

**需要告知用户的内容：**
卡片 #X 已移至“进行中”并完成分配。开始实施...

---

2. Working on a Card

2. 处理卡片

During implementation:
Mark steps complete:
bash
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:
bash
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
实施过程中：
标记步骤完成：
bash
fizzy step update STEP_ID --card CARD_NUMBER --completed
发布简短进度评论：
  • 仅在步骤完成或达到重要里程碑时发布
  • 保持简洁（1-2句话）以节省令牌
  • 包含设计/决策变更的简要说明
进度评论示例：
bash
fizzy comment create --card 12 --body "$(cat <<'EOF'
<p>✅ Feature X completed</p>
<p>Migration applied: <code>20260211040415_init</code></p>
EOF
)"
重要提示：
  • 评论对团队可见，因此要清晰简洁
  • 聚焦于已完成的内容，而非实现方式
  • 跳过明显/琐碎的更新

3. Completing a Card

3. 完成卡片

When: All work is done and committed
Required steps:
适用场景： 所有工作已完成并提交
必要步骤：

Step 1: Commit to Git

步骤1：提交至Git

Use conventional commit format, NEVER mention Fizzy (it's external to the project):
bash
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
使用规范提交格式，绝对不要提及Fizzy（它是项目外部工具）：
bash
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
)"
规范提交类型：
  • feat
    : 新功能
  • fix
    : 漏洞修复
  • docs
    : 文档更新
  • refactor
    : 代码重构
  • test
    : 添加测试
  • chore
    : 维护任务

Step 2: Get Commit Hash and Repo URL

步骤2：获取提交哈希和仓库URL

bash
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$//')
bash
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

步骤3：发布完成评论

bash
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
)"
bash
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

步骤4：关闭卡片

bash
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
bash
fizzy card close CARD_NUMBER
需要告知用户的内容：
✅ 卡片 #X 已完成！

**提交：** [hash](github_url)

**交付内容：**
- 功能A
- 功能B
- 功能C

**卡片状态：** ✅ 已关闭

4. Assigning to Human

4. 分配给人工

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:
bash
undefined
分配给人工的场景：
  • 只能由人工手动完成的任务
  • 需要确认/审批的任务
  • 基础设施决策（部署、托管、CI/CD平台）
  • 安全审查或敏感配置
  • UI/UX设计决策
如何查找人工用户ID：
bash
undefined

List all users to find the right person

List all users to find the right person

fizzy user list | jq '.data[] | {id: .id, name: .name, email: .email_address}'

**Assign:**
```bash
fizzy card assign CARD_NUMBER --user <human_user_id>
Post a comment explaining why:
bash
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
)"
fizzy user list | jq '.data[] | {id: .id, name: .name, email: .email_address}'

**分配：**
```bash
fizzy card assign CARD_NUMBER --user <human_user_id>
发布评论说明原因：
bash
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
✅ 建议：
  • 步骤完成时发布评论
  • 设计/决策变更时发布评论
  • 重要里程碑时发布评论
  • 保持1-2句话的长度
  • 使用清晰、可操作的语言
❌ 禁止：
  • 每次微小操作都发布评论
  • 编写冗长的解释
  • 重复代码中已有的信息
  • 不必要地使用内部/技术术语

Git Commit Guidelines

Git提交指南

✅ 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
✅ 建议：
  • 使用规范提交格式
  • 聚焦于内容和原因
  • 包含相关范围
  • 在提交正文中列出主要变更
❌ 禁止：
  • 提及Fizzy（它是项目外部工具）
  • 在提交中引用卡片编号
  • 编写模糊的提交信息
  • 复杂变更时跳过提交正文

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
✅ 建议：
  • 按工作流阶段移动卡片
  • 合理分配（机器人 vs 人工）
  • 真正完成时再关闭卡片
  • 进度更新时同步更新步骤
❌ 禁止：
  • 让卡片停留在错误的列中
  • 关闭未完成工作的卡片
  • 忘记分配卡片
  • 跳过步骤更新

Common Patterns

常见模式

Pattern: Multi-Step Card Workflow

模式：多步骤卡片工作流

bash
undefined
bash
undefined

1. Get board and column info

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')
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

2. Start the card

fizzy card column 15 --column $DOING_COL fizzy card assign 15 --user $BOT_USER
fizzy card column 15 --column $DOING_COL fizzy card assign 15 --user $BOT_USER

3. Work and mark steps

3. Work and mark steps

fizzy step update STEP_1_ID --card 15 --completed fizzy step update STEP_2_ID --card 15 --completed
fizzy step update STEP_1_ID --card 15 --completed fizzy step update STEP_2_ID --card 15 --completed

... continue implementation ...

... continue implementation ...

4. Commit

4. Commit

git add <files> git commit -m "feat: implement feature"
git add <files> git commit -m "feat: implement feature"

5. Complete and close

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
undefined
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
undefined

Pattern: No-Steps Card Workflow

模式：无步骤卡片工作流

bash
undefined
bash
undefined

1. Start

1. Start

fizzy card column 20 --column <doing_col_id> fizzy card assign 20 --user <bot_user_id>
fizzy card column 20 --column <doing_col_id> fizzy card assign 20 --user <bot_user_id>

2. Work (no steps to update)

2. Work (no steps to update)

... implementation ...

... implementation ...

3. Commit and complete

3. Commit and complete

git commit -m "feat: implement X" fizzy comment create --card 20 --body "<p>✅ Done</p>" fizzy card close 20
undefined
git commit -m "feat: implement X" fizzy comment create --card 20 --body "<p>✅ Done</p>" fizzy card close 20
undefined

Pattern: Delegate to Human

模式：委派给人工

bash
undefined
bash
undefined

Find human user

Find human user

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

Assign and explain

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 )" ```
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

与基础Fizzy技能的集成

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
本工作流技能使用基础
fizzy
技能执行所有Fizzy CLI操作。当你需要：
  • 搜索卡片：使用基础
    fizzy
    技能
  • 列出看板/列：使用基础
    fizzy
    技能
  • 查看卡片详情：使用基础
    fizzy
    技能
  • 执行工作流：使用本技能
决策树示例：
  • 用户问“有哪些可用卡片？” → 使用基础
    fizzy
    技能
  • 用户说“处理卡片#15” → 使用本工作流技能
  • 用户问“显示卡片#15的详情” → 使用基础
    fizzy
    技能
  • 用户说“完成卡片#15” → 使用本工作流技能

Token Optimization

令牌优化

Keep Comments Concise

保持评论简洁

Instead of:
html
<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:
html
<p>✅ Feature completed and tested. Changes committed.</p>
替代：
html
<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>
使用：
html
<p>✅ Feature completed and tested. Changes committed.</p>

Batch Operations

批量操作

When possible, complete multiple steps before posting a single summary comment:
bash
undefined
尽可能在完成多个步骤后再发布一条总结评论：
bash
undefined

Instead of commenting after each step

Instead of commenting after each step

fizzy step update STEP1 --card 12 --completed
fizzy step update STEP1 --card 12 --completed

[work]

[work]

fizzy step update STEP2 --card 12 --completed
fizzy step update STEP2 --card 12 --completed

[work]

[work]

fizzy step update STEP3 --card 12 --completed
fizzy step update STEP3 --card 12 --completed

Post one summary

Post one summary

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

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

---

Helper Script

辅助脚本

Use 
scripts/fizzy-context.sh BOARD_ID
to quickly get project-specific IDs:
bash
bash fizzy-workflow/scripts/fizzy-context.sh <board_id>
使用
scripts/fizzy-context.sh BOARD_ID
快速获取项目特定ID：
bash
bash fizzy-workflow/scripts/fizzy-context.sh <board_id>