gabrielmoreira Gitea Workflow Orchestrator
A skill that guides agents through structured agile development workflows for Gitea repositories by intelligently invoking commands in sequence. Uses checkpoint-based flow control to auto-progress between steps while pausing at key decision points.
When to Use This Skill
Use this skill when:
- Working with a Gitea-hosted repository
- Starting work for the day ("run morning standup", "start my day")
- Working on a task ("implement next task", "continue working")
- Completing a development cycle ("finish this task", "prepare PR")
- Running sprint ceremonies ("start sprint", "end sprint", "retrospective")
- Resuming interrupted work ("what's next", "where was I")
Do NOT use this skill when:
- Working with GitHub repositories (use agile-workflow instead)
- Running a single specific command (use that command directly)
- Just checking status (use
/statusdirectly) - Only doing code review without full cycle (use
/review-codedirectly) - Researching or planning without implementation
Prerequisites
Before using this skill:
- Git repository initialized with worktree support
- Gitea Tea CLI installed and authenticated (
tea login) - Context network with backlog structure at
context-network/backlog/ - Task status files at
context-network/backlog/by-status/*.md - GITEA_URL environment variable set (or configured in tea)
- GITEA_TOKEN environment variable set for API scripts
Workflow Types Overview
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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
State Detection
The skill determines current workflow state automatically. No manual tracking needed.
Detection Signals
| Signal | How to Check | Indicates |
|---|---|---|
| Worktree exists | git worktree list |
Task in progress |
| Task branch active | git branch --show-current matches task/* |
Active implementation |
| Uncommitted changes | git status --porcelain |
Active coding |
| PR exists | tea pulls list --state open |
In review |
| PR merged | tea pulls + check state |
Ready for cleanup |
State Matrix
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
─────────────────────────────────────────────────────────────
For detailed detection algorithms, see references/state-detection.md.
Invocation Patterns
# 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
Task Cycle Phase
The primary workflow for completing a single task from selection to merge.
Step 1: Sync Reality
Ensure context network matches actual project state.
Run: sync --last 1d --dry-run
Purpose: Detect drift between documented and actual state
Output: Sync report showing completions, partial work, divergences
Step 2: Select Task
Identify the next task to work on.
Run: next
Purpose: Find highest priority ready task
Output: Task ID, title, branch name suggestion
CHECKPOINT: TASK_SELECTED
- Pause to confirm task selection
- User can accept or choose different task
- On accept: continue to implementation
Step 3: Implement
Test-driven development in isolated worktree.
Run: implement [TASK-ID]
Purpose: Create worktree, write tests first, implement, verify
Output: Working implementation with passing tests
CHECKPOINT: IMPL_COMPLETE
- Pause after implementation completes
- Show test results and coverage
- On success: continue to review
Step 4: Review
Quality validation of implementation.
Run: review-code --uncommitted
Run: review-tests --uncommitted
Purpose: Identify quality issues, security concerns, test gaps
Output: Review reports with issues and recommendations
CHECKPOINT: REVIEWS_DONE
- Display combined review results
- If critical issues: must address before continuing
- If no issues: auto-continue to PR prep
- User decides: apply recommendations now or defer
Step 5: Apply Recommendations (Conditional)
Address review findings intelligently.
Run: apply-recommendations [review-output]
Purpose: Apply quick fixes now, defer complex changes to tasks
Output: Applied fixes + created follow-up tasks
Step 6: Prepare PR
Create pull request with full documentation.
Run: pr-prep
Purpose: Validate, document, and create PR
Output: PR created with description, tests verified
CHECKPOINT: PR_CREATED
- Display PR URL and CI status
- Wait for CI checks to complete (verify manually or via API script)
- On CI pass + approval: continue to merge
- On CI fail: stop, address issues
Step 7: Complete PR
Merge and cleanup.
Run: pr-complete [PR-NUMBER]
Purpose: Merge PR, delete branch, remove worktree, update status
Output: Task marked complete, cleanup done
Step 8: Update Backlog and Project Status
Persist progress to source-of-truth documentation.
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
Why this step matters: Without it, completed tasks remain marked "ready" in backlog files and project status stays stale. Internal tracking files are session-scoped; the backlog and status files are the persistent source of truth.
For detailed task-cycle instructions, see references/phases/task-cycle.md.
Daily Phase
Quick sequences for start and end of workday.
Morning Standup (~5 min)
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
Evening Wrap-up (~10 min)
Run sequence:
1. checklist # Ensure nothing lost
2. discovery # Capture learnings
3. sync --last 1d # Update task statuses
Output: Knowledge preserved, state synchronized
For detailed daily instructions, see references/phases/daily.md.
Sprint Phase
Ceremonies for sprint boundaries.
Sprint Start (~60 min)
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
Sprint End (~90 min)
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
For detailed sprint instructions, see references/phases/sprint.md.
Checkpoint Handling
Checkpoints are pauses for human decision-making.
Checkpoint Behavior
At each checkpoint:
- Summarize what just completed
- Show key results and any issues
- Present next steps
- Wait for user input
Checkpoint Responses
| Response | Action |
|---|---|
| "continue" / "proceed" / "yes" | Move to next step |
| "stop" / "pause" | Save state, exit workflow |
| "back" | Re-run previous step |
| "skip" | Skip current step (use cautiously) |
| Custom input | May adjust next step parameters |
Auto-Continue Conditions
Some checkpoints can auto-continue when conditions are met:
| Checkpoint | Auto-Continue If |
|---|---|
| IMPL_COMPLETE | All tests pass, build succeeds |
| REVIEWS_DONE | No critical or high severity issues |
| PR_CREATED | CI passes (verified via API), required approvals obtained |
For detailed checkpoint handling, see references/checkpoint-handling.md.
Command Reference
Each workflow step uses embedded command instructions:
| Command | Reference | Purpose |
|---|---|---|
| sync | references/commands/sync.md | Reality synchronization |
| groom | references/commands/groom.md | Task refinement |
| next | references/commands/next.md | Task selection |
| implement | references/commands/implement.md | TDD implementation |
| review-code | references/commands/review-code.md | Code quality review |
| review-tests | references/commands/review-tests.md | Test quality review |
| apply-recommendations | references/commands/apply-recommendations.md | Triage and apply fixes |
| pr-prep | references/commands/pr-prep.md | PR creation |
| pr-complete | references/commands/pr-complete.md | PR merge and cleanup |
| discovery | references/commands/discovery.md | Learning capture |
| retrospective | references/commands/retrospective.md | Post-work analysis |
| maintenance | references/commands/maintenance.md | Context network cleanup |
Example: Complete Task Cycle
Scenario: Start of day, implement next available task
Invocation:
/gitea-workflow --phase task-cycle
Flow:
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-Specific Notes
CI Status Checking
Gitea uses external CI systems (Drone, Woodpecker, Jenkins, etc.). To check CI status:
- Via API Script: Use
scripts/gitea-ci-status.shto query commit statuses - Manual Verification: Check your CI dashboard directly
- PR Mergeability: Check if PR shows as mergeable in Gitea UI
Tea CLI Command Reference
| Operation | Tea CLI Command |
|---|---|
| List open PRs | tea pulls list --state open |
| Create PR | tea pulls create --title "..." --description "..." --base main --head branch |
| View PR | tea pulls |
| Merge PR (squash) | tea pulls merge --style squash |
| Merge PR (merge) | tea pulls merge --style merge |
| Merge PR (rebase) | tea pulls merge --style rebase |
| Approve PR | tea pulls approve |
| List issues | tea issues list |
API Scripts
For operations not available in the tea CLI, use the provided API scripts:
scripts/gitea-ci-status.sh- Check CI status via Gitea APIscripts/gitea-pr-checks.sh- Get PR review/approval status
Limitations
- Requires context network with specific backlog structure
- Gitea-centric (uses
teaCLI for PR operations) - Single-task focus (parallel task work not orchestrated)
- Manual CI verification may be needed (Gitea uses external CI)
- Some features depend on Gitea version and configuration
Related Skills
- skill-maker - Create new skills following agentskills.io spec
- research-workflow - For research tasks before implementation
- gitea-coordinator - For multi-task orchestration with Gitea