gitea-coordinator

Gitea Coordinator

Gitea リポジトリのバックログにある、整理済みのタスクを実装するために複数のワーカーエージェントを調整し、タスクの割り当て、進捗の監視、マージの調整、検証を行います。

基本原則

調整に徹し、実装はしません。 コーディネーターはタスクをワーカーに割り当て、進捗を監視し、マージを調整して、結果を検証します。実際の実装は、ワーカーが gitea-workflow スキルを通じて行います。

クイックリファレンス

使用する場面

• Gitea でホストされているリポジトリで作業する場合
• バックログに実装可能なタスクが複数ある場合
• 開発作業を自律的にまとめて実行したい場合
• 競合を避けるためにマージを調整する必要がある場合
• 複数のタスクの進捗を追跡したい場合

呼び出し

/gitea-coordinator                    # Auto-discover and execute ready tasks
/gitea-coordinator TASK-001 TASK-002  # Execute specific tasks
/gitea-coordinator --dry-run          # Preview execution plan only
/gitea-coordinator --parallel         # Run workers in parallel
/gitea-coordinator --sequential       # Run workers one at a time (default)

フラグ

フラグ	説明	デフォルト
--sequential	タスクを一度に1つずつ実行します	Yes
--parallel	タスクを並行して実行します	No
--max-workers N	同時に実行するワーカーの最大数	2
--dry-run	実行せずに計画を表示します	No
--autonomous	すべてのチェックポイントで自動的に続行します	Yes
--supervised	各タスクの完了後に一時停止します	No
--verbose	すべてのワーカーの更新を表示します	No
--summary-only	主なマイルストーンのみを表示します	Yes

---

ワークフローのフェーズ

フェーズ 1：検出

バックログを読み込み、実装可能なタスクを探します。

Actions:
1. Read context/backlog/ for task files
2. Filter to status: ready
3. Parse task metadata (priority, size, dependencies)
4. Sort by priority (high → medium → low)
5. Present findings

Output: List of ready tasks with metadata

フェーズ 2：計画

タスクの特性に基づいて実行計画を作成します。

Actions:
1. Determine execution mode (sequential or parallel)
2. Check for task dependencies (A must complete before B)
3. Assign tasks to workers in priority order
4. Generate worker instructions

Output: Execution plan with task assignments

チェックポイント：TASKS_DISCOVERED

• 表示内容：実行可能なタスクと提案する実行計画
• 自動続行：--autonomous フラグが指定され、タスクが見つかった場合
• オプション：continue、reorder、exclude [TASK-ID]、stop

フェーズ 3：実行

ワーカーエージェントを起動して監視します。

For SEQUENTIAL mode:
  for each task in queue:
    1. Spawn worker with Task tool
    2. Worker runs gitea-workflow for the task
    3. Monitor progress via file system
    4. When complete: proceed to merge phase
    5. On failure: handle error, decide continue/stop

For PARALLEL mode:
  1. Spawn workers up to max_workers
  2. Monitor all workers concurrently
  3. As workers complete: queue their PRs for merge
  4. Spawn next worker if tasks remain
  5. Continue until all tasks processed

チェックポイント：WORKER_COMPLETE（ワーカーごと）

• 表示内容：ワーカーの概要、PR 番号、次のアクション
• 自動続行：成功し、--autonomous が指定されている場合
• オプション：continue、retry、skip、stop

フェーズ 4：マージ

競合を避けるため、順番にマージを実行します。

Actions:
1. For each completed PR in merge queue:
   a. git checkout main && git pull
   b. Merge PR (via tea pulls merge or git merge)
   c. Verify merge succeeded
   d. Delete feature branch
2. If conflict: pause and alert user

Output: All PRs merged to main

フェーズ 5：検証

すべてのマージ後に、システムの整合性を検証します。

Actions:
1. git checkout main && git pull --rebase
2. npm run build (verify build passes)
3. npm test (run full test suite)
4. Check for regressions
5. Generate verification report

Output: Verification status (PASSED/FAILED)

チェックポイント：VERIFIED

• 表示内容：テスト結果、ビルドの状態
• 自動続行：すべてのテストが成功した場合
• オプション：done、investigate、revert

フェーズ 6：概要

包括的な完了レポートを生成します。

Output:
- Tasks completed with PR numbers and commits
- Metrics (workers spawned, PRs merged, tests added)
- Verification status
- Remaining backlog tasks

---

ワーカープロトコル

ワーカーは Claude Code の Task ツールを使用して起動され、割り当てられたタスクに対して gitea-workflow を実行します。

ワーカー指示テンプレート

templates/worker-instruction.md を参照してください。

ワーカーの主な要件：

1. 自律モードで gitea-workflow を実行する
2. 進捗を .coordinator/workers/{worker-id}/progress.json に書き込む
3. 自分でマージしないでください。代わりに、マージ可能な状態であることを通知します
4. gitea-workflow のすべてのチェックポイントを自動的に処理する

進捗の追跡

ワーカーはファイルシステム経由で進捗を報告します。

// .coordinator/workers/worker-1/progress.json
{
  "worker_id": "worker-1",
  "task_id": "TASK-006",
  "status": "in_progress|completed|failed|ready-to-merge",
  "phase": "implement|review|pr-prep|pr-complete",
  "pr_number": null,
  "branch": "task/TASK-006-description",
  "last_update": "2026-01-20T10:15:00Z",
  "milestones": [
    {"phase": "implement", "timestamp": "..."},
    {"phase": "review", "timestamp": "..."}
  ]
}

---

状態の追跡

コーディネーターは .coordinator/state.json で状態を管理します。

{
  "session_id": "coord-2026-01-20-abc123",
  "state": "EXECUTING",
  "config": {
    "execution_mode": "sequential",
    "autonomy_level": "autonomous"
  },
  "tasks": {
    "queued": ["TASK-008"],
    "in_progress": ["TASK-007"],
    "completed": ["TASK-006"],
    "failed": []
  },
  "workers": [...],
  "merge_queue": [],
  "verification": null
}

詳細は references/state-tracking.md を参照してください。

---

失敗への対処

失敗の種類	検出方法	復旧方法
ワーカーの失敗	進捗に failed と表示される	再試行、スキップ、または中止を提案します
テストの失敗	npm test がゼロ以外の値で終了する	ワーカーは最大 2 回まで再試行します
マージ競合	git merge が失敗する	一時停止して、ユーザーに通知します
検証の失敗	マージ後のテストが失敗する	調査または取り消しを提案します

詳細は references/failure-handling.md を参照してください。

---

gitea-workflow との連携

コーディネーターは gitea-workflow を実行するワーカーを起動します。

gitea-coordinator (orchestrator)
    │
    ├── Worker 1 → gitea-workflow --task TASK-006
    ├── Worker 2 → gitea-workflow --task TASK-007
    └── Worker 3 → gitea-workflow --task TASK-008

主な連携ポイント：

• ワーカーは自律モードで gitea-workflow を実行します
• コーディネーターがマージを担当します（ワーカーは PR を作成しますが、マージはしません）
• 進捗はファイルシステム経由で同期されます
• すべてのマージ後に、コーディネーターが検証を実行します

---

アンチパターン

AP1：並列マージ

パターン：複数の PR を同時にマージする 問題：マージコンフリクトが発生し、main ブランチが破損します 対処法：必ず順番にマージし、各マージの前に pull します

AP2：ワーカーによる自己マージ

パターン：ワーカーが自分の PR をマージする 問題：競合状態が発生し、マージが調整されません 対処法：ワーカーはマージ可能になったことを通知し、コーディネーターがマージを実行します

AP3：検証なし

パターン：マージ後の検証を省略する 問題：リグレッションを検出できません 対処法：マージ完了後は必ずテストスイート全体を実行します

---

インタラクション例

User: /gitea-coordinator

Coordinator: Discovering ready tasks...

Found 2 ready tasks:
1. TASK-006 - Persistent Message Status (medium priority, medium size)
2. TASK-007 - Add Unit Tests (high priority, large size)

Execution Plan:
- Mode: sequential
- Order: TASK-006 → TASK-007

Proceed? [continue/reorder/stop]

User: continue

Coordinator: Starting TASK-006...
[Spawns Worker 1]

**Milestone**: TASK-006 - PR #123 created, CI passing

Coordinator: Merging PR #123...
**Milestone**: TASK-006 complete (commit abc123)

Coordinator: Starting TASK-007...
[Spawns Worker 2]

**Milestone**: TASK-007 - PR #124 created, CI passing

Coordinator: Merging PR #124...
**Milestone**: TASK-007 complete (commit def456)

Coordinator: Running verification...
- Build: PASSED
- Tests: 47/47 passing
- Coverage: 82%

## Summary
Tasks completed: 2
- TASK-006: PR #123 merged (commit abc123)
- TASK-007: PR #124 merged (commit def456)

Verification: PASSED

---

統合グラフ

インバウンド（他のスキルから）

ソーススキル	トリガー	アクション
requirements-elaboration	タスクの整理完了	コーディネーターが実行可能
gitea-agile	バックログの準備完了	コーディネーターがタスクを検出

アウトバウンド（他のスキルへ）

このアクション	トリガーされるスキル	用途
ワーカーの起動	gitea-workflow	タスクの実装
検証の失敗	research	デバッグ調査

補完的なスキル

スキル	関係
gitea-workflow	ワーカーがこのスキルを実行します
gitea-agile	このスキルが読み取るバックログを管理します

---

設計上の制約

• ワーカーの起動には Claude Code の Task ツールが必要です
• ワーカー同士が直接通信することはできません
• 進捗の調整にはファイルシステムを使用します
• マージは順番に行います（並列マージは無効です）
• コンテキストネットワークのバックログ構造を前提とします

実行しないこと

• タスクを直接実装すること（ワーカーが実装します）
• PR を並列にマージすること（必ず順番にマージします）
• 検証を省略すること（マージ後は必ず検証します）
• ユーザーの同意なく、重大な失敗の後も続行すること