Gitea Coordinator Orchestrates multiple worker agents to implement groomed tasks from the backlog in Gitea repositories, handling task assignment, progress monitoring, merge coordination, and verification. Core Principle Coordinate, don't implement. The coordinator assigns tasks to workers, monitors their progress, coordinates merges, and verifies results. Workers execute the actual implementation via the gitea-workflow skill. Quick Reference When to Use Working with a Gitea-hosted repository Multiple ready tasks in the backlog need implementation You want autonomous batch execution of development work You need coordinated merges to avoid conflicts You want progress tracking across multiple tasks Invocation /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)

Flags

Flag

Description

Default

--sequential

Execute tasks one at a time

Yes

--parallel

Execute tasks concurrently

No

--max-workers N

Maximum concurrent workers

2

--dry-run

Show plan without executing

No

--autonomous

Auto-continue at all checkpoints

Yes

--supervised

Pause after each task completes

No

--verbose

Show all worker updates

No

--summary-only

Show major milestones only

Yes

Workflow Phases

Phase 1: Discovery

Read the backlog to find tasks ready for implementation.

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

Phase 2: Planning

Create an execution plan based on task characteristics.

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

Checkpoint: TASKS_DISCOVERED

Display: Ready tasks and proposed execution plan

Auto-continue: If --autonomous flag and tasks found

Options:

continue

,

reorder

,

exclude [TASK-ID]

,

stop

Phase 3: Execution

Spawn and monitor worker agents.

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

Checkpoint: WORKER_COMPLETE

(per worker)

Display: Worker summary, PR number, next action

Auto-continue: If successful and --autonomous

Options:

continue

,

retry

,

skip

,

stop

Phase 4: Merging

Execute merges sequentially to avoid conflicts.

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

Phase 5: Verification

Verify system integrity after all merges.

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)

Checkpoint: VERIFIED

Display: Test results, build status

Auto-continue: If all tests pass

Options:

done

,

investigate

,

revert

Phase 6: Summary

Generate comprehensive completion report.

Output:

- Tasks completed with PR numbers and commits

- Metrics (workers spawned, PRs merged, tests added)

- Verification status

- Remaining backlog tasks

Worker Protocol

Workers are spawned using Claude Code's Task tool and run

gitea-workflow

for their assigned task.

Worker Instruction Template

See

templates/worker-instruction.md

Key requirements for workers:

Run

gitea-workflow

with autonomous mode

Write progress to

.coordinator/workers/{worker-id}/progress.json

Do NOT self-merge - signal ready-to-merge status instead

Handle all gitea-workflow checkpoints automatically

Progress Tracking

Workers report progress via file system:

// .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"

:

"..."

}

]

}

State Tracking

The coordinator maintains state in

.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

}

See

references/state-tracking.md

for details.

Failure Handling

Failure Type

Detection

Recovery

Worker fails

Progress shows

failed

Offer retry, skip, or abort

Tests fail

npm test exits non-zero

Worker retries up to 2x

Merge conflict

git merge fails

Pause, alert user

Verification fails

Post-merge tests fail

Offer investigate or revert

See

references/failure-handling.md

for details.

Integration with gitea-workflow

The coordinator spawns workers that execute

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

Key integration points:

Workers run gitea-workflow in autonomous mode

Coordinator handles merges (workers create PRs but don't merge)

Progress synced via file system

Coordinator runs verification after all merges

Anti-Patterns

AP1: Parallel Merges

Pattern

Merging multiple PRs simultaneously

Problem

Creates merge conflicts, corrupts main branch

Fix

Always merge sequentially, pull before each merge

AP2: Worker Self-Merge

Pattern

Workers merge their own PRs

Problem

Race conditions, uncoordinated merges

Fix

Workers signal ready-to-merge, coordinator executes merges

AP3: No Verification

Pattern

Skipping post-merge verification

Problem

Regressions go undetected

Fix

Always run full test suite after merges complete Example Interaction 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 Integration Graph Inbound (From Other Skills) Source Skill Trigger Action requirements-elaboration Tasks groomed Coordinator can execute gitea-agile Backlog ready Coordinator discovers tasks Outbound (To Other Skills) This Action Triggers Skill For Spawn worker gitea-workflow Task implementation Verification fails research Debug investigation Complementary Skills Skill Relationship gitea-workflow Workers execute this skill gitea-agile Manages backlog this reads Design Constraints Requires Claude Code's Task tool for spawning workers Workers cannot directly communicate with each other File system used for progress coordination Sequential merges only (parallel merges disabled) Assumes context network backlog structure What You Do NOT Do Implement tasks directly (workers do this) Merge PRs in parallel (always sequential) Skip verification (always verify after merges) Continue after critical failures without user consent