Gitea Coordinator

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

---

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: 1. Run gitea-workflow with autonomous mode 2. Write progress to .coordinator/workers/{worker-id}/progress.json 3. Do NOT self-merge - signal ready-to-merge status instead 4. 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

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)

Outbound (To Other Skills)

Complementary Skills

---

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

Failure Handling

How the coordinator handles various failure scenarios in Gitea repositories.

Failure Categories

1. Worker Implementation Failure

Cause: Tests fail, build fails, or worker encounters error during implementation.

Detection:

• Worker progress file shows status: failed
• Worker progress file shows error: "..." field

Recovery Options:

Retry Limits: Max 2 retries per task before requiring human intervention.

2. Test Failure

Cause: Tests fail during worker implementation phase.

Detection:

• Worker logs show test failures
• npm test exits with non-zero code

Recovery:

• Worker should attempt to fix (up to 2 attempts)
• If worker cannot fix, mark as failed
• Coordinator offers retry with fresh context or skip

Example Worker Retry:

Attempt 1: 3 tests failing
Worker fixes test assertions
Attempt 2: 1 test still failing
Worker investigates root cause
Attempt 3: All tests pass

3. CI Failure

Cause: External CI (Drone, Woodpecker, Jenkins, etc.) fails after PR created.

Detection:

• CI status via API script shows failure:

  ./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)
  # Returns: "failure"

• Worker progress shows phase: awaiting-ci for extended time
• Manual check of CI dashboard

Recovery:

• Worker should return to implementation phase
• Fix the issue, push updates
• CI re-runs automatically
• If repeated failures, mark as failed

4. Merge Conflict

Cause: PR cannot merge due to conflicts with main.

Detection:

• tea pulls merge fails with conflict error
• PR shows conflict status in Gitea UI

Recovery Options:

See merge-coordination.md for details.

5. Verification Failure

Cause: Tests fail after all PRs merged.

Detection:

• npm test fails in verification phase
• Build fails in verification phase

Severity: HIGH - merged code may have regressions.

Recovery Options:

6. Infrastructure Failure

Cause: Git unavailable, network issues, disk full, etc.

Detection:

• Git commands fail with connection errors
• File system operations fail

Recovery:

• Retry with exponential backoff (1s, 2s, 4s)
• Max 3 retries before failing
• Preserve state for resume

Failure Recovery Flowchart

            FAILURE DETECTED
                  │
                  ▼
         ┌───────────────┐
         │ Categorize    │
         │ Failure       │
         └───────┬───────┘
                 │
    ┌────────────┼────────────┬────────────┐
    ▼            ▼            ▼            ▼
 Worker      Merge       Verify      Infra
 Failure     Conflict    Failure     Failure
    │            │            │            │
    ▼            ▼            ▼            ▼
┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐
│ Retry? │  │ Auto-  │  │Revert? │  │ Retry  │
│ Skip?  │  │resolve?│  │        │  │ w/back │
│ Abort? │  │Manual? │  │        │  │ off    │
└────┬───┘  └────┬───┘  └────┬───┘  └────┬───┘
     │           │           │           │
     ▼           ▼           ▼           ▼
  Continue    Continue    Continue    Continue
  or Stop     or Stop     or Stop     or Stop

Graceful Degradation

Principle

When failures occur, preserve as much progress as possible.

Rules

1. Complete what you can: If one task fails, other independent tasks can continue 2. Never leave orphans: Clean up branches, worktrees on abort 3. Preserve state: Always save state before stopping 4. Clear communication: Tell user exactly what happened and options

Example: Partial Completion

Tasks: TASK-006, TASK-007, TASK-008

TASK-006: Completed, merged
TASK-007: Failed (tests not passing)
TASK-008: Not started

Coordinator response:
"TASK-006 completed successfully.
TASK-007 failed: 3 tests not passing.

Options:
[retry TASK-007] - Try again with fresh context
[skip to TASK-008] - Continue with remaining tasks
[stop] - Stop here (TASK-006 remains merged)"

Error Messages

Standard Error Display

╔════════════════════════════════════════════════════════════════╗
║  ERROR: [Category]                                             ║
╠════════════════════════════════════════════════════════════════╣
║                                                                 ║
║  Task: [TASK-ID] - [Title]                                     ║
║  Phase: [phase]                                                 ║
║  Error: [error message]                                         ║
║                                                                 ║
║  Details:                                                       ║
║  [relevant details, logs, file paths]                          ║
║                                                                 ║
║  Options:                                                       ║
║  [option1] - Description                                        ║
║  [option2] - Description                                        ║
║                                                                 ║
║  Progress so far:                                               ║
║  - TASK-006: completed (merged)                                 ║
║  - TASK-007: failed                                             ║
╚════════════════════════════════════════════════════════════════╝

Logging

What to Log

• Timestamp of failure
• Failure category
• Task and worker context
• Error message and stack trace (if available)
• Recovery action taken
• Outcome of recovery

Log Location

.coordinator/logs/
├── session-2026-01-20.log    # Session log
└── errors/
    └── TASK-007-failure.log  # Per-task error details

Log Format

[2026-01-20T10:25:00Z] ERROR worker-2 TASK-007 implementation
  Phase: implement
  Error: 3 tests failing in message-tools.test.ts
  Details: Expected array of 3, received array of 2
  Action: Offering retry

[2026-01-20T10:25:05Z] INFO user selected: retry

[2026-01-20T10:25:10Z] INFO spawning worker-3 for TASK-007 (retry 1)

Gitea-Specific Notes

CI Status Checking

Since Gitea uses external CI, check status via API script:

./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)

Possible returns: pending, success, failure, error, none

PR Review Status

Check if PR has approvals:

./scripts/gitea-pr-checks.sh owner repo $PR_NUMBER

Returns JSON with approved, review_count, mergeable fields.

Merge Coordination

How the coordinator manages merges to prevent conflicts in Gitea repositories.

Core Principle

All merges are sequential. Even in parallel execution mode, PRs are merged one at a time to main. This prevents merge conflicts and maintains a clean commit history.

Why Sequential Merges

The Problem with Parallel Merges

Scenario: Two PRs ready simultaneously

PR #1 (TASK-006)         PR #2 (TASK-007)
    │                         │
    ▼                         ▼
 merge to main            merge to main
    │                         │
    └─────────┬───────────────┘
              │
              ▼
        CONFLICT!

Both PRs were based on the same main.
When merged simultaneously, they may
modify the same files or have
incompatible changes.

Sequential Merge Solution

PR #1 (TASK-006)         PR #2 (TASK-007)
    │                         │
    ▼                         │ (waits)
 merge to main                │
    │                         │
    ▼                         ▼
main updated ────────► rebase PR #2
                              │
                              ▼
                        merge to main
                              │
                              ▼
                         main updated

No conflicts because each merge
happens on the latest main.

Merge Queue

The coordinator maintains a merge queue for PRs ready to merge.

Queue Structure

{
  "merge_queue": [
    {
      "pr_number": 123,
      "task_id": "TASK-006",
      "worker_id": "worker-1",
      "branch": "task/TASK-006-persistence",
      "added_at": "2026-01-20T10:15:00Z"
    },
    {
      "pr_number": 124,
      "task_id": "TASK-007",
      "worker_id": "worker-2",
      "branch": "task/TASK-007-tests",
      "added_at": "2026-01-20T10:18:00Z"
    }
  ]
}

Queue Processing

While merge_queue not empty:
  1. Take first PR from queue
  2. git checkout main && git pull
  3. Attempt merge
  4. If success:
     - Remove from queue
     - Update worker status to completed
     - Delete feature branch
  5. If conflict:
     - Pause and alert user
     - Offer resolution options

Merge Execution

Using Gitea Tea CLI

# Squash merge (recommended)
tea pulls merge 123 --style squash

# Or merge commit
tea pulls merge 123 --style merge

# Or rebase
tea pulls merge 123 --style rebase

# Or rebase-merge
tea pulls merge 123 --style rebase-merge

# Note: tea may not auto-delete branch, do it manually:
git push origin --delete task/TASK-006-persistence

Using Git Directly

# Ensure on latest main
git checkout main
git pull --rebase origin main

# Merge the PR branch
git merge --no-ff task/TASK-006-persistence

# Push to origin
git push origin main

# Delete feature branch
git branch -d task/TASK-006-persistence
git push origin --delete task/TASK-006-persistence

Conflict Handling

Detection

Conflicts are detected when:

• tea pulls merge fails with conflict error
• git merge fails with conflict markers
• PR shows conflict status in Gitea

Resolution Options

╔════════════════════════════════════════════════════════════════╗
║  MERGE CONFLICT: PR #124 (TASK-007)                            ║
╠════════════════════════════════════════════════════════════════╣
║                                                                 ║
║  Conflicting files:                                             ║
║  - src/mastra/schemas/message-status.ts                        ║
║  - src/mastra/services/message-processor.ts                    ║
║                                                                 ║
║  Options:                                                       ║
║  [resolve] - Attempt automatic resolution                       ║
║  [manual] - Exit for manual conflict resolution                 ║
║  [skip] - Skip this PR, continue with others                    ║
║  [abort] - Stop merge process entirely                          ║
╚════════════════════════════════════════════════════════════════╝

Automatic Resolution

For simple conflicts, the coordinator can attempt:

# Checkout the PR branch
git checkout task/TASK-007-tests

# Rebase onto latest main
git rebase origin/main

# If conflicts during rebase:
# - For auto-generated files: accept theirs/ours
# - For code: use merge tool or abort

# Force push updated branch
git push --force-with-lease

# PR will update, CI re-runs

Manual Resolution

If automatic resolution fails:

1. Coordinator pauses 2. User resolves conflicts manually 3. User pushes resolved changes 4. User signals coordinator to continue 5. Coordinator verifies CI passes (via API script) 6. Coordinator completes merge

Rollback Procedures

Reverting a Single Merge

If verification fails after a merge:

# Find the merge commit
git log --oneline -5

# Revert the merge commit
git revert -m 1 <merge-commit-sha>

# Push the revert
git push origin main

Reverting Multiple Merges

If multiple merges need to be reverted:

# Option 1: Revert each in reverse order
git revert -m 1 <latest-merge>
git revert -m 1 <previous-merge>

# Option 2: Reset to known good state
git reset --hard <last-known-good-sha>
git push --force-with-lease origin main  # DANGEROUS

Best Practices

1. Always pull before merge: Ensure you have the latest main 2. Use squash merge: Creates cleaner history 3. Delete branches after merge: Prevents branch pollution 4. Verify CI passes: Check via API script or manually before merge 5. One merge at a time: Never attempt parallel merges 6. Keep merge queue visible: Log what's pending

Gitea-Specific Notes

Tea CLI Merge Styles

Branch Cleanup

Tea CLI may not automatically delete branches. Clean up manually:

git push origin --delete task/TASK-006-persistence

CI Status Verification

Before merging, verify CI passed using the API script:

./scripts/gitea-ci-status.sh owner repo $(git rev-parse task/TASK-006-persistence)

Or check your CI dashboard directly.

State Tracking

How the coordinator maintains and persists its state.

State Machine

┌──────────┐
│   IDLE   │ ◄─────────────────────────────┐
└────┬─────┘                               │
     │ /agile-coordinator                  │
     ▼                                     │
┌────────────┐                             │
│ DISCOVERING│                             │
└────┬───────┘                             │
     │ tasks found                         │
     ▼                                     │
┌──────────┐                               │
│ PLANNING │                               │
└────┬─────┘                               │
     │ plan confirmed                      │
     ▼                                     │
┌───────────┐      ┌─────────┐            │
│ EXECUTING │─────►│ MERGING │            │
└────┬──────┘      └────┬────┘            │
     │ all complete     │ all merged      │
     │◄─────────────────┘                 │
     ▼                                     │
┌───────────┐                              │
│ VERIFYING │                              │
└────┬──────┘                              │
     │ verified                            │
     ▼                                     │
┌────────────┐                             │
│ SUMMARIZING│─────────────────────────────┘
└────────────┘

State File

Location: .coordinator/state.json

Full Schema

{
  "session_id": "coord-2026-01-20-abc123",
  "state": "EXECUTING",
  "started_at": "2026-01-20T10:00:00Z",
  "updated_at": "2026-01-20T10:25:00Z",

  "config": {
    "execution_mode": "sequential",
    "max_workers": 2,
    "autonomy_level": "autonomous",
    "reporting": "summary-only"
  },

  "tasks": {
    "queued": ["TASK-008"],
    "in_progress": ["TASK-007"],
    "completed": ["TASK-006"],
    "failed": []
  },

  "workers": [
    {
      "id": "worker-1",
      "task_id": "TASK-006",
      "status": "completed",
      "pr_number": 123,
      "commit": "abc123",
      "merged": true,
      "started_at": "2026-01-20T10:01:00Z",
      "completed_at": "2026-01-20T10:20:00Z"
    },
    {
      "id": "worker-2",
      "task_id": "TASK-007",
      "status": "in_progress",
      "pr_number": null,
      "commit": null,
      "merged": false,
      "started_at": "2026-01-20T10:21:00Z",
      "completed_at": null
    }
  ],

  "merge_queue": [123],

  "verification": {
    "status": null,
    "tests_total": null,
    "tests_passed": null,
    "build_status": null,
    "completed_at": null
  },

  "summary": null
}

State Transitions

IDLE → DISCOVERING

Triggered by: /agile-coordinator invocation

Actions: 1. Create .coordinator/ directory 2. Generate session_id 3. Initialize state.json 4. Read backlog for ready tasks

DISCOVERING → PLANNING

Triggered by: Tasks found in backlog

Actions: 1. Parse task metadata 2. Sort by priority 3. Check dependencies 4. Generate execution plan 5. Display checkpoint for confirmation

PLANNING → EXECUTING

Triggered by: User confirms plan (or auto-continue)

Actions: 1. Update config with flags 2. Initialize task queues 3. Spawn first worker(s)

EXECUTING → MERGING

Triggered by: Worker reports ready-to-merge

Actions: 1. Add PR to merge_queue 2. Execute merge 3. Update worker status 4. Return to EXECUTING if tasks remain

EXECUTING → VERIFYING

Triggered by: All tasks completed or in merge_queue empty

Actions: 1. Pull latest main 2. Run build 3. Run tests 4. Record results

VERIFYING → SUMMARIZING

Triggered by: Verification complete

Actions: 1. Generate summary report 2. Display to user 3. Cleanup state

SUMMARIZING → IDLE

Triggered by: Summary displayed

Actions: 1. Archive or remove .coordinator/ 2. Return to idle state

Resume from Interrupted Session

If the coordinator is interrupted, it can resume:

Detection

On /agile-coordinator invocation: 1. Check if .coordinator/state.json exists 2. If exists and state != IDLE: offer resume

Resume Prompt

Found interrupted session:
- Session: coord-2026-01-20-abc123
- State: EXECUTING
- Completed: TASK-006
- In Progress: TASK-007

Options:
[resume] Continue from where you left off
[restart] Start fresh (clears progress)
[abort] Stop and cleanup

Resume Actions

By state:

• DISCOVERING: Re-run discovery
• PLANNING: Show plan again for confirmation
• EXECUTING: Check worker progress, continue monitoring
• MERGING: Check merge status, continue queue
• VERIFYING: Re-run verification
• SUMMARIZING: Generate summary again

Cleanup

On Successful Completion

# Option 1: Archive
mv .coordinator .coordinator.archive.$(date +%s)

# Option 2: Remove
rm -rf .coordinator

On Abort

# Clean up any orphaned branches
git branch -D task/TASK-* 2>/dev/null || true

# Remove coordinator state
rm -rf .coordinator

Worker Management

How the coordinator spawns, monitors, and manages worker agents for Gitea repositories.

Spawning Workers

Workers are spawned using Claude Code's Task tool with the general-purpose subagent type.

Task Tool Invocation

Task({
  description: "Implement TASK-006",
  prompt: workerInstruction,
  subagent_type: "general-purpose"
})

Worker Instruction Structure

Each worker receives a prompt that includes:

1. Task Assignment: Which task to implement 2. Skill Invocation: Run gitea-workflow for the task 3. Progress Reporting: Write to .coordinator/workers/{id}/progress.json 4. Merge Protocol: Don't self-merge, signal ready-to-merge instead 5. Checkpoint Behavior: Auto-continue at all gitea-workflow checkpoints

See ../templates/worker-instruction.md for the full template.

Progress Monitoring

File-Based Communication

Workers cannot directly communicate with the coordinator or each other. Instead, they write progress to the file system:

.coordinator/
├── state.json                    # Coordinator state
└── workers/
    ├── worker-1/
    │   └── progress.json         # Worker 1 progress
    └── worker-2/
        └── progress.json         # Worker 2 progress

Progress File Format

{
  "worker_id": "worker-1",
  "task_id": "TASK-006",
  "status": "in_progress",
  "phase": "implement",
  "pr_number": null,
  "branch": "task/TASK-006-persistence",
  "commits": 0,
  "tests_passing": null,
  "last_update": "2026-01-20T10:15:00Z",
  "milestones": [
    {
      "phase": "started",
      "timestamp": "2026-01-20T10:00:00Z"
    },
    {
      "phase": "implement",
      "timestamp": "2026-01-20T10:05:00Z"
    }
  ],
  "error": null
}

Status Values

Phase Values

Polling Strategy

The coordinator polls worker progress files to track status:

Sequential Mode

While current_worker not complete:
  1. Check worker progress file
  2. If status changed: log milestone
  3. If failed: handle failure
  4. If ready-to-merge: proceed to merge
  5. Sleep 5 seconds

Parallel Mode

While any worker active:
  1. Check all worker progress files
  2. For each status change: log milestone
  3. For each failure: handle failure
  4. For each ready-to-merge: add to merge queue
  5. If workers < max and tasks remain: spawn next
  6. Sleep 5 seconds

Worker Lifecycle

SPAWNED
   │
   ▼
IMPLEMENTING ──────┐
   │               │ (if error)
   ▼               │
REVIEWING          │
   │               │
   ▼               │
PR_CREATED         │
   │               │
   ▼               │
AWAITING_CI ───────┤
   │               │
   ▼               │
READY_TO_MERGE     │
   │               │
   ▼               ▼
COMPLETED      FAILED

Handling Worker Completion

Successful Completion

When a worker reports ready-to-merge:

1. Log the milestone 2. Add PR to merge queue 3. If sequential: proceed to merge phase 4. If parallel: continue monitoring others

Worker Failure

When a worker reports failed:

1. Log the error details 2. Check error type (recoverable vs fatal) 3. Offer options: retry, skip, abort 4. If retry: spawn new worker with same task 5. If skip: move to next task 6. If abort: stop all workers, cleanup

Cleanup

After all tasks complete or on abort:

1. Remove .coordinator/workers/ directory 2. Update .coordinator/state.json to IDLE 3. Optionally remove .coordinator/ entirely

Gitea-Specific Notes

CI Status During Awaiting-CI Phase

Workers should check CI status via the API script:

./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)

Since Gitea uses external CI, this queries the commit status API.

PR Approval Check

Before signaling ready-to-merge, workers should verify approvals:

./scripts/gitea-pr-checks.sh owner repo $PR_NUMBER

Summary Report Template

Template for the final orchestration summary for Gitea repositories. Replace {{variables}} with actual values.

---

Full Template

## Orchestration Summary

**Session**: {{SESSION_ID}}
**Started**: {{START_TIME}}
**Completed**: {{END_TIME}}
**Duration**: {{DURATION}}

---

### Configuration

| Setting | Value |
|---------|-------|
| Execution Mode | {{EXECUTION_MODE}} |
| Max Workers | {{MAX_WORKERS}} |
| Autonomy Level | {{AUTONOMY_LEVEL}} |

---

### Tasks Completed

{{#each COMPLETED_TASKS}}
#### {{TASK_ID}}: {{TASK_TITLE}}

- **Status**: Completed
- **Worker**: {{WORKER_ID}}
- **PR**: #{{PR_NUMBER}}
- **Commit**: {{COMMIT_SHA}}
- **Branch**: {{BRANCH_NAME}}
- **Duration**: {{TASK_DURATION}}

{{/each}}

---

### Tasks Failed

{{#if FAILED_TASKS}}
{{#each FAILED_TASKS}}
#### {{TASK_ID}}: {{TASK_TITLE}}

- **Status**: Failed
- **Worker**: {{WORKER_ID}}
- **Phase**: {{FAILED_PHASE}}
- **Error**: {{ERROR_MESSAGE}}
- **Attempts**: {{RETRY_COUNT}}

{{/each}}
{{else}}
None
{{/if}}

---

### Tasks Skipped

{{#if SKIPPED_TASKS}}
{{#each SKIPPED_TASKS}}
- {{TASK_ID}}: {{TASK_TITLE}} ({{SKIP_REASON}})
{{/each}}
{{else}}
None
{{/if}}

---

### Metrics

| Metric | Value |
|--------|-------|
| Tasks Attempted | {{TASKS_ATTEMPTED}} |
| Tasks Completed | {{TASKS_COMPLETED}} |
| Tasks Failed | {{TASKS_FAILED}} |
| Tasks Skipped | {{TASKS_SKIPPED}} |
| Workers Spawned | {{WORKERS_SPAWNED}} |
| PRs Created | {{PRS_CREATED}} |
| PRs Merged | {{PRS_MERGED}} |
| Commits | {{TOTAL_COMMITS}} |
| Tests Added | {{TESTS_ADDED}} |

---

### Verification

| Check | Status |
|-------|--------|
| Build | {{BUILD_STATUS}} |
| Tests | {{TEST_STATUS}} ({{TESTS_PASSED}}/{{TESTS_TOTAL}}) |
| Coverage | {{COVERAGE_PERCENT}}% |

**Verdict**: {{VERIFICATION_VERDICT}}

{{#if VERIFICATION_FAILURES}}
#### Failures

{{#each VERIFICATION_FAILURES}}
- {{TEST_FILE}}: {{FAILURE_MESSAGE}}
{{/each}}
{{/if}}

---

### Backlog Status

| Status | Count |
|--------|-------|
| Completed (this session) | {{COMPLETED_THIS_SESSION}} |
| Ready | {{REMAINING_READY}} |
| In Progress | {{REMAINING_IN_PROGRESS}} |
| Total Backlog | {{TOTAL_BACKLOG}} |

---

### Next Steps

{{#if REMAINING_READY}}
Ready tasks remaining:
{{#each REMAINING_READY_TASKS}}
- {{TASK_ID}}: {{TASK_TITLE}} ({{PRIORITY}} priority)
{{/each}}

Run `/gitea-coordinator` to continue.
{{else}}
All ready tasks have been implemented!

Next actions:
- Review completed PRs
- Groom backlog for new tasks
- Run `/gitea-workflow --phase daily-evening` to wrap up
{{/if}}

---

Example: Filled Report

## Orchestration Summary

**Session**: coord-2026-01-20-abc123
**Started**: 2026-01-20T10:00:00Z
**Completed**: 2026-01-20T10:45:00Z
**Duration**: 45 minutes

---

### Configuration

| Setting | Value |
|---------|-------|
| Execution Mode | sequential |
| Max Workers | 2 |
| Autonomy Level | autonomous |

---

### Tasks Completed

#### TASK-006: Persistent Message Status Storage

- **Status**: Completed
- **Worker**: worker-1
- **PR**: #123
- **Commit**: 5cc6e36
- **Branch**: task/TASK-006-persistence
- **Duration**: 18 minutes

#### TASK-007: Add Unit and Integration Tests

- **Status**: Completed
- **Worker**: worker-2
- **PR**: #124
- **Commit**: 94750f0
- **Branch**: task/TASK-007-tests
- **Duration**: 22 minutes

---

### Tasks Failed

None

---

### Tasks Skipped

None

---

### Metrics

| Metric | Value |
|--------|-------|
| Tasks Attempted | 2 |
| Tasks Completed | 2 |
| Tasks Failed | 0 |
| Tasks Skipped | 0 |
| Workers Spawned | 2 |
| PRs Created | 2 |
| PRs Merged | 2 |
| Commits | 4 |
| Tests Added | 142 |

---

### Verification

| Check | Status |
|-------|--------|
| Build | PASSED |
| Tests | PASSED (142/142) |
| Coverage | 82% |

**Verdict**: VERIFIED

---

### Backlog Status

| Status | Count |
|--------|-------|
| Completed (this session) | 2 |
| Ready | 0 |
| In Progress | 0 |
| Total Backlog | 8 |

---

### Next Steps

All ready tasks have been implemented!

Next actions:
- Review completed PRs
- Groom backlog for new tasks
- Run `/gitea-workflow --phase daily-evening` to wrap up

Worker Instruction Template

Template for worker agent prompts for Gitea repositories. Replace {{variables}} with actual values.

---

Full Template

You are Worker {{WORKER_ID}}, assigned to implement {{TASK_ID}}.

## Task Assignment

**Task**: {{TASK_ID}} - {{TASK_TITLE}}
**Priority**: {{PRIORITY}}
**Size**: {{SIZE}}

Read the full task specification at:
`context/backlog/{{TASK_FILE}}`

## Your Mission

Complete the FULL implementation cycle for this task:

1. **Understand**: Read the task file for requirements and implementation plan
2. **Implement**: Follow TDD - write tests first, then implement
3. **Review**: Ensure code quality and test coverage
4. **PR**: Create a pull request with your changes
5. **Signal**: Update your progress file when ready for merge

## Execution

Run the gitea-workflow skill for your assigned task:

This executes the full implementation cycle

/gitea-workflow --task {{TASK_ID}}

## Checkpoint Handling

Handle all gitea-workflow checkpoints automatically:

| Checkpoint | Action |
|------------|--------|
| TASK_SELECTED | Continue (task is assigned to you) |
| IMPL_COMPLETE | Continue if tests pass; fix and retry if not |
| REVIEWS_DONE | Fix critical/high issues; defer medium/low |
| PR_CREATED | Verify CI via API script, then signal ready |
| PR_MERGED | (Coordinator handles merge) |

## Progress Reporting

After each major phase, update your progress file:

**File**: `.coordinator/workers/{{WORKER_ID}}/progress.json`

{ "worker_id": "{{WORKER_ID}}", "task_id": "{{TASK_ID}}", "status": "in_progress", "phase": "implement", "pr_number": null, "branch": "task/{{TASK_ID}}-...", "last_update": "{{TIMESTAMP}}", "milestones": [], "error": null }

Update `status` to one of:
- `in_progress` - Still working
- `ready-to-merge` - PR created, CI passed, ready for merge
- `failed` - Encountered unrecoverable error

Update `phase` to reflect current phase:
- `started` → `implement` → `review` → `pr-prep` → `awaiting-ci` → `ready-to-merge`

## IMPORTANT: Merge Protocol

**DO NOT merge your PR yourself.**

When your PR is created and CI passes:
1. Check CI status via API script:

./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)

2. If CI passed, update progress status to `ready-to-merge`
3. Stop and wait
4. The coordinator will handle the merge

This ensures sequential merges and prevents conflicts.

## Error Handling

If you encounter an unrecoverable error:
1. Update progress status to `failed`
2. Set the `error` field with a description
3. Stop execution

The coordinator will decide whether to retry or skip.

## Success Criteria

Your task is complete when:
- All tests pass
- Code reviews pass (no critical/high issues)
- PR is created
- CI passes (verified via API script)
- Progress file shows `ready-to-merge`

BEGIN IMPLEMENTATION

---

Example: Filled Template

You are Worker worker-1, assigned to implement TASK-006.

## Task Assignment

**Task**: TASK-006 - Persistent Message Status Storage
**Priority**: medium
**Size**: medium

Read the full task specification at:
`context/backlog/TASK-006-persistent-message-status.md`

## Your Mission
...

---

Usage Notes

1. Replace all {{VARIABLE}} placeholders with actual values 2. The worker will execute autonomously once spawned 3. Progress file must be created/updated by the worker 4. Coordinator monitors progress file for status changes 5. CI status must be checked via API script since Gitea uses external CI