gitea-workflow

Gitea 工作流编排器

此技能通过按顺序智能调用命令，引导 Agent 在 Gitea 仓库中遵循结构化敏捷开发工作流。通过基于检查点的流程控制，在步骤之间自动推进，同时在关键决策点暂停。

何时使用此技能

在以下情况下使用此技能：

• 使用托管在 Gitea 上的仓库
• 开始一天的工作（“run morning standup”、“start my day”）
• 处理任务（“implement next task”、“continue working”）
• 完成开发周期（“finish this task”、“prepare PR”）
• 举行冲刺会议（“start sprint”、“end sprint”、“retrospective”）
• 恢复中断的工作（“what's next”、“where was I”）

请勿在以下情况下使用此技能：

• 使用 GitHub 仓库（请改用 agile-workflow）
• 运行单个特定命令（直接使用该命令）
• 只查看状态（直接使用 /status）
• 只进行代码审查，不执行完整周期（直接使用 /review-code）
• 研究或规划，但不进行实现

前提条件

使用此技能前：

• Git 仓库已初始化并支持 worktree
• Gitea Tea CLI已安装并完成身份验证（tea login）
• 上下文网络中有位于 context-network/backlog/ 的待办事项结构
• 任务状态文件位于 context-network/backlog/by-status/*.md
• 已设置 GITEA_URL 环境变量（或在 tea 中完成配置）
• 已设置用于 API 脚本的 GITEA_TOKEN 环境变量

工作流类型概览

WORKFLOW TYPES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TASK CYCLE (Primary)     DAILY                SPRINT
──────────────────────   ──────────────────   ──────────────────
sync                     Morning:             Start:
  ↓                        sync --last 1d       sync --all
next → [CHECKPOINT]        status --brief       groom --all
  ↓                        groom --ready        plan sprint-goals
implement                                       status
  ↓                      Evening:
[CHECKPOINT]               checklist          End:
  ↓                        discovery            sync --sprint
review-code                sync --last 1d       retrospective
review-tests                                    audit --sprint
  ↓                                             maintenance --deep
[CHECKPOINT]
  ↓
apply-recommendations (if issues)
  ↓
pr-prep → [CHECKPOINT]
  ↓
pr-complete
  ↓
update-backlog & status
  ↓
END
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

状态检测

此技能会自动确定当前工作流状态，无需手动跟踪。

检测信号

信号	检查方式	表示
Worktree 存在	git worktree list	任务进行中
任务分支处于活动状态	git branch --show-current 与 task/* 匹配	正在进行实现
有未提交的更改	git status --porcelain	正在编写代码
PR 存在	tea pulls list --state open	正在审查
PR 已合并	tea pulls + 检查状态	可进行清理

状态矩阵

STATE DETECTION LOGIC
─────────────────────────────────────────────────────────────
Check                           → State           → Next Step
─────────────────────────────────────────────────────────────
No worktree, no in-progress     → IDLE            → sync, next
Worktree exists, uncommitted    → IMPLEMENTING    → continue implement
Worktree exists, all committed  → READY_REVIEW    → review-code
PR open, CI pending             → AWAITING_CI     → wait or address
PR open, CI pass                → READY_MERGE     → pr-complete
PR merged, worktree exists      → CLEANUP         → pr-complete
─────────────────────────────────────────────────────────────

有关详细的检测算法，请参阅 references/state-detection.md。

调用模式

# Auto-detect state and continue from where you are
/gitea-workflow

# Start specific workflow phase
/gitea-workflow --phase task-cycle
/gitea-workflow --phase daily-morning
/gitea-workflow --phase daily-evening
/gitea-workflow --phase sprint-start
/gitea-workflow --phase sprint-end

# Resume work on specific task
/gitea-workflow --task TASK-123

# Preview what would happen without executing
/gitea-workflow --dry-run

任务周期阶段

从选择到合并，完成单个任务的主要工作流。

第 1 步：同步实际状态

确保上下文网络与项目的实际状态一致。

Run: sync --last 1d --dry-run
Purpose: Detect drift between documented and actual state
Output: Sync report showing completions, partial work, divergences

第 2 步：选择任务

确定要处理的下一个任务。

Run: next
Purpose: Find highest priority ready task
Output: Task ID, title, branch name suggestion

检查点：TASK_SELECTED

• 暂停并确认任务选择
• 用户可以接受或选择其他任务
• 接受后：继续实现

第 3 步：实现

在隔离的 worktree 中进行测试驱动开发。

Run: implement [TASK-ID]
Purpose: Create worktree, write tests first, implement, verify
Output: Working implementation with passing tests

检查点：IMPL_COMPLETE

• 实现完成后暂停
• 显示测试结果和覆盖率
• 成功后：继续审查

第 4 步：审查

验证实现质量。

Run: review-code --uncommitted
Run: review-tests --uncommitted
Purpose: Identify quality issues, security concerns, test gaps
Output: Review reports with issues and recommendations

检查点：REVIEWS_DONE

• 显示综合审查结果
• 如果存在严重问题：必须先解决才能继续
• 如果没有问题：自动继续准备 PR
• 用户决定：立即应用建议，还是延后处理

第 5 步：应用建议（有条件）

智能处理审查发现的问题。

Run: apply-recommendations [review-output]
Purpose: Apply quick fixes now, defer complex changes to tasks
Output: Applied fixes + created follow-up tasks

第 6 步：准备 PR

创建附带完整文档的拉取请求。

Run: pr-prep
Purpose: Validate, document, and create PR
Output: PR created with description, tests verified

检查点：PR_CREATED

• 显示 PR URL 和 CI 状态
• 等待 CI 检查完成（手动验证或通过 API 脚本验证）
• CI 通过且获得批准后：继续合并
• CI 失败：停止并解决问题

第 7 步：完成 PR

合并并清理。

Run: pr-complete [PR-NUMBER]
Purpose: Merge PR, delete branch, remove worktree, update status
Output: Task marked complete, cleanup done

步骤 8：更新待办事项和项目状态

将进度保存到事实来源文档中。

Run: Part of pr-complete (Phase 6)
Purpose: Update epic file (task → complete), unblock dependents, update project status
Output: Backlog and project status reflect actual progress

为何此步骤很重要： 否则，已完成的任务仍会在待办事项文件中标记为“就绪”，项目状态也会过时。内部跟踪文件仅限当前会话使用；待办事项和状态文件才是持久的事实来源。

详细的任务周期说明，请参阅 references/phases/task-cycle.md。

每日阶段

工作日开始和结束时的快捷流程。

晨会（约 5 分钟）

Run sequence:
1. sync --last 1d --dry-run   # What actually happened yesterday
2. status --brief --sprint    # Current sprint health
3. groom --ready-only         # What's ready to work on

Output: Clear picture of today's priorities

晚间总结（约 10 分钟）

Run sequence:
1. checklist                  # Ensure nothing lost
2. discovery                  # Capture learnings
3. sync --last 1d            # Update task statuses

Output: Knowledge preserved, state synchronized

详细的每日说明，请参阅 references/phases/daily.md。

冲刺阶段

冲刺周期开始和结束时的例会。

冲刺开始（约 60 分钟）

Run sequence:
1. sync --all                 # Full reality alignment
2. groom --all               # Comprehensive grooming
3. plan sprint-goals         # Architecture and goals
4. status --detailed         # Baseline metrics

Output: Sprint plan with groomed, ready backlog

冲刺结束（约 90 分钟）

Run sequence:
1. sync --sprint             # Final sprint sync
2. retrospective             # Capture learnings
3. audit --scope sprint      # Quality review
4. status --metrics          # Sprint metrics
5. maintenance --deep        # Context network cleanup

Output: Sprint closed, learnings captured, ready for next

详细的冲刺说明，请参阅 references/phases/sprint.md。

检查点处理

检查点是供人工决策的暂停点。

检查点行为

在每个检查点：

1. 总结刚刚完成的工作
2. 展示关键结果和任何问题
3. 说明后续步骤
4. 等待用户输入

检查点响应

响应	操作
“continue” / “proceed” / “yes”	移至下一步
“stop” / “pause”	保存状态，退出工作流
“back”	重新执行上一步
“skip”	跳过当前步骤（谨慎使用）
自定义输入	可调整后续步骤的参数

自动继续条件

满足某些条件时，部分检查点可以自动继续：

检查点	自动继续条件
IMPL_COMPLETE	所有测试均通过，构建成功
REVIEWS_DONE	没有严重或高严重性问题
PR_CREATED	CI 通过（通过 API 验证），并已获得所需审批

详细的检查点处理说明，请参阅 references/checkpoint-handling.md。

命令参考

每个工作流步骤都使用内嵌的命令说明：

命令	参考	用途
sync	references/commands/sync.md	同步实际情况
groom	references/commands/groom.md	优化任务
next	references/commands/next.md	选择任务
implement	references/commands/implement.md	TDD 实现
review-code	references/commands/review-code.md	代码质量审查
review-tests	references/commands/review-tests.md	测试质量审查
apply-recommendations	references/commands/apply-recommendations.md	分类并应用修复
pr-prep	references/commands/pr-prep.md	创建 PR
pr-complete	references/commands/pr-complete.md	合并 PR 并清理
discovery	references/commands/discovery.md	记录所学内容
retrospective	references/commands/retrospective.md	工作后分析
maintenance	references/commands/maintenance.md	清理上下文网络

示例：完整任务周期

场景： 一天开始时，实施下一个可用任务

调用：

/gitea-workflow --phase task-cycle

流程：

Agent: Detecting current state...
       No worktree found, checking ready tasks...

Agent: Running sync --last 1d --dry-run
       [Sync output: 0 tasks completed but undocumented]

Agent: Running next
       Found: TASK-042 - Add user preferences endpoint
       Priority: High | Size: Small | Branch: task/TASK-042-preferences

       ╔═══════════════════════════════════════════╗
       ║  CHECKPOINT: Task Selection               ║
       ╠═══════════════════════════════════════════╣
       ║  Selected: TASK-042                       ║
       ║  Proceed with implementation?             ║
       ║                                           ║
       ║  [continue] [stop] [other task]           ║
       ╚═══════════════════════════════════════════╝

User: continue

Agent: Creating worktree at .worktrees/TASK-042/
       Running implement TASK-042
       [Implementation proceeds with TDD...]

       Tests: 12 passing
       Coverage: 87%
       Build: Success

       ╔═══════════════════════════════════════════╗
       ║  CHECKPOINT: Implementation Complete      ║
       ╠═══════════════════════════════════════════╣
       ║  All tests passing, ready for review      ║
       ║  Proceed to code review?                  ║
       ║                                           ║
       ║  [continue] [stop]                        ║
       ╚═══════════════════════════════════════════╝

[Flow continues through review, PR, merge...]

Gitea 专属说明

CI 状态检查

Gitea 使用外部 CI 系统（Drone、Woodpecker、Jenkins 等）。检查 CI 状态的方法：

1. 通过 API 脚本： 使用 scripts/gitea-ci-status.sh 查询提交状态
2. 手动验证： 直接查看 CI 仪表板
3. PR 可合并性： 在 Gitea UI 中检查 PR 是否显示为可合并

Tea CLI 命令参考

操作	Tea CLI 命令
列出未关闭的 PR	tea pulls list --state open
创建 PR	tea pulls create --title "..." --description "..." --base main --head branch
查看 PR	tea pulls
合并 PR（squash）	tea pulls merge --style squash
合并 PR（merge）	tea pulls merge --style merge
合并 PR（rebase）	tea pulls merge --style rebase
批准 PR	tea pulls approve
列出 issue	tea issues list

API 脚本

对于 tea CLI 不支持的操作，请使用提供的 API 脚本：

• scripts/gitea-ci-status.sh - 通过 Gitea API 检查 CI 状态
• scripts/gitea-pr-checks.sh - 获取 PR 审查/批准状态

限制

• 需要采用特定待办事项结构的上下文网络
• 以 Gitea 为中心（使用 tea CLI 执行 PR 操作）
• 专注于单个任务（不编排并行任务）
• 可能需要手动验证 CI（Gitea 使用外部 CI）
• 某些功能取决于 Gitea 版本和配置

相关技能

• skill-maker - 按照 agentskills.io 规范创建新技能
• research-workflow - 用于实现前的研究任务
• gitea-coordinator - 用于使用 Gitea 编排多项任务