gitea-workflow

Gitea ワークフローオーケストレーター

コマンドを順序立てて適切に呼び出し、Gitea リポジトリでの構造化されたアジャイル開発ワークフローをエージェントに案内するスキルです。チェックポイントベースのフロー制御により、重要な判断ポイントでは一時停止しながら、各ステップ間を自動的に進めます。

このスキルを使用する場面

次の場合にこのスキルを使用します。

• Gitea でホストされているリポジトリで作業する場合
• その日の作業を開始する場合（「朝会を実行」「今日の作業を始める」）
• タスクに取り組む場合（「次のタスクを実装」「作業を続ける」）
• 開発サイクルを完了する場合（「このタスクを完了」「PR を準備」）
• スプリントのセレモニーを実施する場合（「スプリントを開始」「スプリントを終了」「振り返り」）
• 中断した作業を再開する場合（「次は何をする？」「どこまで進んだ？」）

次の場合はこのスキルを使用しないでください。

• GitHub リポジトリで作業する場合（代わりに agile-workflow を使用）
• 特定のコマンドを 1 つだけ実行する場合（そのコマンドを直接使用）
• ステータスを確認するだけの場合（代わりに /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 をマージ（スカッシュ）	tea pulls merge --style squash
PR をマージ（マージ）	tea pulls merge --style merge
PR をマージ（リベース）	tea pulls merge --style rebase
PR を承認	tea pulls approve
イシューを一覧表示	tea issues list

API スクリプト

tea CLI で利用できない操作には、用意されている API スクリプトを使用します。

• scripts/gitea-ci-status.sh - Gitea API 経由で CI のステータスを確認
• scripts/gitea-pr-checks.sh - PR のレビュー／承認ステータスを取得

制限事項

• 特定のバックログ構造を持つコンテキストネットワークが必要です
• Gitea を中心としています（PR 操作には tea CLI を使用）
• 単一タスクに特化しています（並行タスクの作業はオーケストレーションされません）
• CI の手動確認が必要になる場合があります（Gitea は外部 CI を使用します）
• 一部の機能は Gitea のバージョンと設定に依存します

関連スキル

• skill-maker - agentskills.io の仕様に沿って新しいスキルを作成します
• research-workflow - 実装前の調査タスクに使用します
• gitea-coordinator - Gitea を使用した複数タスクのオーケストレーションに使用します