Gitea Workflow

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 /status directly)
• Only doing code review without full cycle (use /review-code directly)
• 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

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: 1. Summarize what just completed 2. Show key results and any issues 3. Present next steps 4. Wait for user input

Checkpoint Responses

Auto-Continue Conditions

Some checkpoints can auto-continue when conditions are met:

For detailed checkpoint handling, see references/checkpoint-handling.md.

Command Reference

Each workflow step uses embedded command instructions:

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:

1. Via API Script: Use scripts/gitea-ci-status.sh to query commit statuses 2. Manual Verification: Check your CI dashboard directly 3. PR Mergeability: Check if PR shows as mergeable in Gitea UI

Tea CLI Command Reference

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 API
• scripts/gitea-pr-checks.sh - Get PR review/approval status

Limitations

• Requires context network with specific backlog structure
• Gitea-centric (uses tea CLI 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

State Transition Matrix

Quick reference for workflow state transitions.

State Definitions

Transition Triggers

IDLE ─────────────────────────────────────────────────────────────────────────
  │
  │ [next: task selected]
  ▼
IMPLEMENTING ─────────────────────────────────────────────────────────────────
  │
  │ [implement: complete with passing tests]
  ▼
READY_FOR_REVIEW ─────────────────────────────────────────────────────────────
  │
  │ [review-code, review-tests: complete]
  ▼
IN_REVIEW ────────────────────────────────────────────────────────────────────
  │
  ├──[issues found] ──► IMPLEMENTING (loop back)
  │
  │ [no issues OR issues fixed]
  ▼
READY_FOR_PR ─────────────────────────────────────────────────────────────────
  │
  │ [pr-prep: PR created]
  ▼
AWAITING_CI ──────────────────────────────────────────────────────────────────
  │
  ├──[CI failed] ──► CI_FAILED ──► IMPLEMENTING
  │
  │ [CI passed]
  ▼
AWAITING_APPROVAL ────────────────────────────────────────────────────────────
  │
  │ [approved]
  ▼
READY_FOR_MERGE ──────────────────────────────────────────────────────────────
  │
  │ [pr-complete: merge]
  ▼
CLEANUP ──────────────────────────────────────────────────────────────────────
  │
  │ [pr-complete: cleanup done]
  ▼
COMPLETED ────────────────────────────────────────────────────────────────────
  │
  │ [next task cycle]
  ▼
IDLE

Detection Signals by State

Valid Transitions Only

Transitions that should NOT happen:

• IDLE → anything except IMPLEMENTING
• IMPLEMENTING → READY_FOR_MERGE (must go through review)
• IN_REVIEW → COMPLETED (must create and merge PR)
• AWAITING_CI → IMPLEMENTING (must go through CI_FAILED first)
• Any state → COMPLETED without going through CLEANUP

Recovery from Invalid States

If state detection finds inconsistent signals:

1. Worktree exists but task marked complete

• PR was merged outside workflow
• Action: Clean up worktree

2. No worktree but task marked in-progress

• Worktree was deleted manually
• Action: Recreate worktree or reset task status

3. PR merged but worktree still exists

• pr-complete wasn't run
• Action: Run pr-complete to cleanup

4. Branch exists without worktree

• Work started on different machine
• Action: Create worktree from branch

Checkpoint Mapping

Workflow Diagrams

Visual representations of agile-workflow phases.

Complete Workflow Overview

                         AGILE WORKFLOW OVERVIEW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                    ┌────────────────────────────────────┐
                    │           SPRINT CYCLE             │
                    │                                    │
    ┌───────────────┴───────────────┐                    │
    │        SPRINT START           │                    │
    │  sync → groom → plan → status │                    │
    └───────────────┬───────────────┘                    │
                    │                                    │
                    ▼                                    │
    ┌───────────────────────────────────────────────┐   │
    │              DAILY CYCLE                      │   │
    │                                               │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │        MORNING STANDUP             │     │   │
    │   │  sync → status → groom             │     │   │
    │   └────────────────┬───────────────────┘     │   │
    │                    │                          │   │
    │                    ▼                          │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │         TASK CYCLES                │     │   │
    │   │                                    │     │   │
    │   │  ┌──────────────────────────────┐ │     │   │
    │   │  │ sync → next → implement →    │ │     │   │
    │   │  │ review → apply → pr-prep →   │ │     │   │
    │   │  │ pr-complete                  │ │     │   │
    │   │  └──────────────────────────────┘ │     │   │
    │   │       (repeat as needed)          │     │   │
    │   └────────────────┬──────────────────┘     │   │
    │                    │                          │   │
    │                    ▼                          │   │
    │   ┌────────────────────────────────────┐     │   │
    │   │        EVENING WRAP-UP             │     │   │
    │   │  checklist → discovery → sync      │     │   │
    │   └────────────────────────────────────┘     │   │
    │                                               │   │
    └───────────────────────────────────────────────┘   │
                    │                                    │
                    ▼ (repeat daily)                     │
                    │                                    │
    ┌───────────────┴───────────────┐                    │
    │         SPRINT END            │                    │
    │  sync → retro → audit →       │                    │
    │  status → maintenance         │                    │
    └───────────────────────────────┘                    │
                    │                                    │
                    └────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task Cycle Detail

                           TASK CYCLE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

                         ┌─────────┐
                         │  START  │
                         └────┬────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │      sync       │ Reality check
                    └────────┬────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │      next       │ Select task
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Task Selection          ║
               ╚════════════╤═════════════╝
                            │
                            ▼
                    ┌─────────────────┐
                    │   implement     │ TDD in worktree
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Implementation Done     ║
               ╚════════════╤═════════════╝
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
    ┌─────────────────┐         ┌─────────────────┐
    │  review-code    │         │  review-tests   │
    └────────┬────────┘         └────────┬────────┘
              └─────────────┬─────────────┘
                            │
                            ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  Reviews Complete        ║
               ╚════════════╤═════════════╝
                            │
                   ┌────────┴────────┐
                   │  Has issues?    │
                   └────────┬────────┘
                      Yes   │   No
                       ▼    │    │
        ┌────────────────┐  │    │
        │ apply-recomm.  │  │    │
        └───────┬────────┘  │    │
                └─────┬─────┘    │
                      │◄─────────┘
                      ▼
                    ┌─────────────────┐
                    │    pr-prep      │ Create PR
                    └────────┬────────┘
                              │
                              ▼
               ╔══════════════════════════╗
               ║  CHECKPOINT              ║
               ║  PR Created              ║
               ║  (await CI + approval)   ║
               ╚════════════╤═════════════╝
                            │
                            ▼
                    ┌─────────────────┐
                    │  pr-complete    │ Merge + cleanup
                    └────────┬────────┘
                              │
                              ▼
                         ┌─────────┐
                         │   END   │
                         └─────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Daily Sequences

                     DAILY SEQUENCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    MORNING (~5 min)              EVENING (~10 min)
    ────────────────              ─────────────────

    ┌─────────────┐               ┌─────────────┐
    │ sync        │               │ checklist   │
    │ --last 1d   │               │             │
    │ --dry-run   │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ status      │               │ discovery   │
    │ --brief     │               │             │
    │ --sprint    │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ groom       │               │ sync        │
    │ --ready     │               │ --last 1d   │
    │ -only       │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    "Ready to work"               "Day complete"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Sprint Sequences

                     SPRINT SEQUENCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    SPRINT START (~60 min)        SPRINT END (~90 min)
    ──────────────────────        ────────────────────

    ┌─────────────┐               ┌─────────────┐
    │ sync --all  │               │ sync        │
    │             │               │ --sprint    │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ groom --all │               │retrospective│
    │             │               │             │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ plan        │               │ audit       │
    │ sprint-goals│               │ --scope     │
    │             │               │ sprint      │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    ┌─────────────┐               ┌─────────────┐
    │ status      │               │ status      │
    │ --detailed  │               │ --metrics   │
    │             │               │ --detailed  │
    └──────┬──────┘               └──────┬──────┘
           │                             │
           ▼                             ▼
    "Sprint ready"                ┌─────────────┐
                                  │ maintenance │
                                  │ --deep      │
                                  └──────┬──────┘
                                         │
                                         ▼
                                  "Sprint closed"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

State Flow Diagram

                        STATE TRANSITIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    ┌──────────┐
    │   IDLE   │◄──────────────────────────────────────┐
    └────┬─────┘                                       │
         │ [next]                                      │
         ▼                                             │
    ┌──────────────┐                                   │
    │ IMPLEMENTING │◄──────────────────────┐           │
    └──────┬───────┘                       │           │
           │ [complete]                    │           │
           ▼                               │           │
    ┌──────────────────┐                   │           │
    │ READY_FOR_REVIEW │                   │           │
    └──────┬───────────┘                   │           │
           │ [review]                      │           │
           ▼                               │           │
    ┌──────────────┐                       │           │
    │  IN_REVIEW   │───[issues]────────────┘           │
    └──────┬───────┘                                   │
           │ [clean]                                   │
           ▼                                           │
    ┌──────────────┐                                   │
    │ READY_FOR_PR │                                   │
    └──────┬───────┘                                   │
           │ [pr-prep]                                 │
           ▼                                           │
    ┌──────────────┐                                   │
    │ AWAITING_CI  │───[failed]───► CI_FAILED ───────┐│
    └──────┬───────┘                                 ││
           │ [passed]                                ││
           ▼                                         ││
    ┌────────────────────┐                           ││
    │ AWAITING_APPROVAL  │                           ││
    └──────┬─────────────┘                           ││
           │ [approved]                              ││
           ▼                                         ││
    ┌────────────────┐                               ││
    │ READY_FOR_MERGE│                               ││
    └──────┬─────────┘                               ││
           │ [merge]                                 ││
           ▼                                         ││
    ┌──────────────┐                                 ││
    │   CLEANUP    │                                 ││
    └──────┬───────┘                                 ││
           │ [complete]                              ││
           ▼                                         ▼│
    ┌──────────────┐                     ┌───────────┐│
    │  COMPLETED   │                     │IMPLEMENTING││
    └──────┬───────┘                     └───────────┘│
           │                                          │
           └──────────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Checkpoint Handling Reference

Pause/resume behavior at workflow checkpoints for Gitea repositories.

Overview

Checkpoints are moments in the workflow where human review and decision-making is valuable. The skill pauses at these points, presents information, and waits for user direction.

Checkpoint Types

Decision Checkpoints

Require explicit user choice between options.

Examples:

• TASK_SELECTED: Confirm or change task
• REVIEWS_DONE: Fix issues now or defer

Validation Checkpoints

Verify a condition before proceeding.

Examples:

• IMPL_COMPLETE: All tests passing?
• PR_CREATED: CI passing? (verify via API or manually)

Information Checkpoints

Present status for awareness.

Examples:

• Post-sync summary
• Review results display

Checkpoint Definitions

TASK_SELECTED

Triggers after: next command

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Task Selection                           ║
╠═══════════════════════════════════════════════════════╣
║  Selected: [TASK-ID] - [Task Title]                   ║
║  Priority: [Level]                                    ║
║  Size: [Estimate]                                     ║
║  Branch: [suggested-branch]                           ║
║                                                       ║
║  Proceed with implementation?                         ║
╚═══════════════════════════════════════════════════════╝

User Options:

• continue / yes → Proceed to implement
• other / different → Return to task selection
• stop / pause → Exit workflow

Auto-Continue: Never (always requires confirmation)

---

IMPL_COMPLETE

Triggers after: implement command completes

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Implementation Complete                  ║
╠═══════════════════════════════════════════════════════╣
║  Tests: [X] passing, [Y] failing                      ║
║  Coverage: [Z]%                                       ║
║  Build: [PASS/FAIL]                                   ║
║  Lint: [PASS/FAIL]                                    ║
║                                                       ║
║  Ready for code review?                               ║
╚═══════════════════════════════════════════════════════╝

User Options:

• continue → Proceed to reviews
• back → Continue implementing
• stop → Exit workflow (save state)

Auto-Continue Condition:

• All tests passing AND
• Build succeeds AND
• Lint passes

If all conditions met, can auto-continue with brief countdown.

---

REVIEWS_DONE

Triggers after: review-code and review-tests complete

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Reviews Complete                         ║
╠═══════════════════════════════════════════════════════╣
║  Code Review:                                         ║
║    Critical: [A] | High: [B] | Medium: [C] | Low: [D] ║
║  Test Review:                                         ║
║    Critical: [E] | High: [F] | Medium: [G] | Low: [H] ║
║                                                       ║
║  [If issues exist:]                                   ║
║  Top Issue: "[issue description]"                     ║
║                                                       ║
║  How to proceed?                                      ║
╚═══════════════════════════════════════════════════════╝

User Options:

• fix all → Apply all recommendations
• fix critical → Fix critical/high only, defer rest
• defer all → Create tasks, proceed to PR
• stop → Exit workflow

Auto-Continue Condition:

• No critical issues AND
• No high issues
• (Auto-continue to PR prep)

Blocking Condition:

• Critical issues present → MUST fix before PR

---

PR_CREATED

Triggers after: pr-prep command

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: PR Created                               ║
╠═══════════════════════════════════════════════════════╣
║  PR: #[number] - [title]                              ║
║  URL: [GITEA_URL]/[owner]/[repo]/pulls/[number]       ║
║                                                       ║
║  CI Status: [Check via API or CI dashboard]           ║
║  Approvals: [X]/[Y] required                          ║
║                                                       ║
║  [Status-specific message]                            ║
╚═══════════════════════════════════════════════════════╝

User Options:

• check → Refresh CI/approval status via API
• merge → Proceed to merge (if ready)
• stop → Exit (PR remains open)

Auto-Continue Condition:

• CI passed (verified via API script) AND
• Required approvals obtained

Blocking Conditions:

• CI failed → Must fix
• Missing approvals → Must wait

Gitea-Specific:

• CI status must be checked via API script or manually
• Run: ./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)

---

PR_MERGED

Triggers after: pr-complete merge step

Display:

╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: PR Merged                                ║
╠═══════════════════════════════════════════════════════╣
║  Task: [TASK-ID] - [Title]                            ║
║  PR: #[number] - Merged ✓                             ║
║                                                       ║
║  Cleanup:                                             ║
║  - [x] Branch deleted                                 ║
║  - [x] Worktree removed                               ║
║  - [x] Task marked complete                           ║
║                                                       ║
║  Task cycle complete!                                 ║
╚═══════════════════════════════════════════════════════╝

User Options:

• next → Start another task cycle
• done → Exit workflow

Auto-Continue: Never (natural end of cycle)

---

Checkpoint Behavior Protocol

Standard Flow

1. COMMAND COMPLETES
        │
        ▼
2. GATHER CHECKPOINT DATA
   - Collect relevant metrics
   - Determine status
   - Check auto-continue conditions
        │
        ▼
3. DISPLAY CHECKPOINT
   - Show formatted checkpoint box
   - Present options
        │
        ▼
4. WAIT FOR INPUT
   - Parse user response
   - Map to action
        │
        ▼
5. EXECUTE ACTION
   - Continue to next step
   - Loop back to previous
   - Exit with state preserved

Auto-Continue Logic

if autoConditionsMet AND userPrefersAutoFlow:
    display "Auto-continuing in 5 seconds..."
    display "[Press any key to pause]"

    wait 5 seconds with interrupt check

    if no interrupt:
        proceed to next step
    else:
        show full checkpoint options

Interrupt Handling

At any checkpoint, user can:

• Type response to take action
• Type stop to exit
• Press Ctrl+C to abort

State is preserved on any exit.

---

Checkpoint Configuration

User Preferences

Users may configure checkpoint behavior:

# .gitea-workflow/config.yaml
checkpoints:
  auto_continue: true          # Enable auto-continue when safe
  auto_continue_delay: 5       # Seconds before auto-continue
  verbose: false               # Show detailed checkpoint info
  require_confirmation:
    - TASK_SELECTED            # Always confirm these
    - PR_CREATED

Per-Invocation Override

# Disable auto-continue for this run
/gitea-workflow --no-auto

# Maximum verbosity
/gitea-workflow --verbose

# Skip non-critical checkpoints
/gitea-workflow --fast

---

State Preservation

When workflow is interrupted at a checkpoint:

1. Current State Saved

• Detected workflow state
• Task context
• Last completed step
• Pending action

2. Resume Information

• How to continue: /gitea-workflow (auto-detects)
• What will happen: [next step description]

3. No Work Lost

• All git commits preserved
• All files in worktree preserved
• PR remains open if created
• Context network updated

---

Error at Checkpoint

When an error occurs:

╔═══════════════════════════════════════════════════════╗
║  ERROR: [Error Type]                                  ║
╠═══════════════════════════════════════════════════════╣
║  [Error description]                                  ║
║                                                       ║
║  Suggested Resolution:                                ║
║  1. [Step to fix]                                     ║
║  2. [Step to fix]                                     ║
║                                                       ║
║  After fixing, run: /gitea-workflow                   ║
║  (State will be detected automatically)               ║
╚═══════════════════════════════════════════════════════╝

Errors don't lose state - workflow can resume after fixing the issue.

Gitea-Specific Notes

CI Status at PR_CREATED Checkpoint

Since Gitea uses external CI systems, the checkpoint cannot directly query CI status like GitHub Actions. Instead:

1. Use API Script:

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

2. Check CI Dashboard: Navigate to your CI system (Drone, Woodpecker, Jenkins, etc.)

3. Refresh Status: Type check at the checkpoint to re-query via API

PR URL Format

Gitea PR URLs follow the format:

[GITEA_URL]/[owner]/[repo]/pulls/[number]

Example: https://gitea.example.com/myorg/myrepo/pulls/42

Apply Recommendations Command Reference

Triage and apply recommendations from reviews.

Purpose

Analyze recommendations from code/test reviews and intelligently split them into immediate actions (apply now) and deferred tasks (create follow-up).

When Used in Workflow

• Task Cycle: After reviews, when issues were found
• Conditionally invoked based on review results

Common Invocation Patterns

apply-recommendations [review-output]
apply-recommendations --quick-only    # Only low-risk fixes
apply-recommendations --defer-all     # Convert all to tasks
apply-recommendations --dry-run       # Preview without applying

Core Principle: Smart Triage

Not all recommendations are equal. Some should be fixed immediately, others need planning. The decision matrix:

APPLY NOW if ALL of:

• Effort: Trivial or Small
• Risk: Low or (Medium with good test coverage)
• Dependencies: Independent or Local
• Clear fix is obvious
• Won't break existing functionality

DEFER TO TASK if ANY of:

• Effort: Large
• Risk: High
• Dependencies: System or Team
• Requires design decisions
• Needs performance benchmarking
• Could introduce breaking changes

Assessment Criteria

Effort Required

• Trivial: < 5 minutes, single line changes
• Small: 5-30 minutes, single file
• Medium: 30-60 minutes, 2-3 files
• Large: > 60 minutes, multiple files/systems

Risk Level

• Low: Style, documentation, isolated cleanup
• Medium: Logic changes, refactoring with tests
• High: Architecture, external APIs, data handling

Dependencies

• Independent: Can be done in isolation
• Local: Requires understanding of immediate context
• System: Requires broader architectural knowledge
• Team: Needs discussion or approval

Category Handling

Critical Security Issues → ALWAYS APPLY NOW

• Hardcoded secrets/credentials
• SQL injection vulnerabilities
• XSS vulnerabilities
• Exposed sensitive data

High Priority Bugs → USUALLY APPLY NOW

• Null reference errors
• Unhandled promise rejections
• Memory leaks (if isolated)
• Clear logic errors

Code Quality → SELECTIVE

Apply Now:

• Dead code removal
• Obvious duplications (< 10 lines)
• Simple variable renames
• Missing error handling (simple cases)

Defer:

• Large-scale refactoring
• Architecture changes
• Complex abstraction creation

Test Improvements → USUALLY APPLY NOW

• Adding missing assertions
• Fixing tautological tests
• Improving test names
• Fixing test isolation

Documentation → APPLY NOW

• Adding missing comments
• Updating incorrect docs
• Clarifying confusing names

Output Format

# Recommendation Application Report

## Summary
- Total recommendations: X
- Applied immediately: Y
- Deferred to tasks: Z

## Applied Immediately

### 1. [Recommendation Title]
**Type**: [Security/Bug/Quality/Test/Documentation]
**Files Modified**:
- `path/to/file.ts` - [What changed]
**Risk**: Low

## Deferred to Tasks

### High Priority

#### Task: [Clear Task Title]
**Original Recommendation**: [What was recommended]
**Why Deferred**: [Reason]
**Effort Estimate**: [Size]
**Created at**: `/tasks/[type]/[filename].md`

## Validation
- [ ] All tests pass
- [ ] Linting passes
- [ ] No regressions detected

## Next Steps
1. Review applied changes
2. Run full test suite
3. Review high-priority deferred tasks

Quality Guidelines

1. Never break working code - If unsure, defer 2. Maintain test coverage - Add tests for bug fixes 3. Preserve behavior - Refactoring shouldn't change functionality 4. Document decisions - Explain why items were deferred 5. Incremental progress - Many small improvements > one risky change

Orchestration Notes

After applying recommendations:

• If all applied successfully: ready for PR prep
• If issues remain: loop back to review
• Deferred tasks are created but don't block workflow

Discovery Command Reference

Capture learning moments and insights in the context network.

Purpose

Document insights as they happen, preventing knowledge loss and building institutional memory. Create discovery records, update location indexes, and maintain learning paths.

When Used in Workflow

• Daily Evening: Capture learnings from the day
• Post-Task: After completing implementation
• Ad-hoc: Any "aha moment" during development

When to Create Discovery Records

Invoke when:

• Spent >5 minutes figuring out how something works
• Read >3 files to understand one feature
• Had an "aha!" moment about system design
• Discovered why something was implemented a certain way
• Found the actual location of important functionality
• Mental model of a component changed

Discovery Documentation Process

Phase 1: Trigger Assessment

Identify discovery type:

Complexity Triggers:

• Multi-file understanding sequences
• Non-obvious component interactions
• Surprising implementation approaches

Navigation Triggers:

• Finding key entry points
• Understanding component organization
• Discovering configuration patterns

Understanding Triggers:

• Mental model evolution
• Assumption corrections
• Pattern recognition

Phase 2: Record Creation

Create record at /discoveries/records/YYYY-MM-DD-###.md:

# Discovery: [Brief Title]

**Date**: YYYY-MM-DD
**Context**: [What task/exploration led to this]

## What I Was Looking For
[1-2 sentences about the original goal]

## What I Found
**Location**: `path/to/file:lines`
**Summary**: [One sentence explaining what this does/means]

## Significance
[Why this matters for understanding the system]

## Connections
- Related concepts: [[concept-1]], [[concept-2]]
- Implements: [[pattern-name]]
- See also: [[related-discovery]]

## Keywords
[Terms someone might search for]

Phase 3: Location Index Updates

When discovering key code locations: 1. Check existing indexes in /discoveries/locations/ 2. Add new locations with file paths and line numbers 3. Explain significance 4. Include navigation patterns

Phase 4: Learning Path Updates

When understanding evolves significantly: 1. What did you think before? 2. What do you understand now? 3. What changed your understanding?

Update or create learning path to show progression.

Quality Guidelines

For Discovery Records

• Be Specific: Include exact file paths and line numbers
• Include Context: Explain what led to exploration
• Use Keywords: Think about search terms
• Connect to Existing: Link to related concepts

For Location Indexes

• Keep Current: Update paths when code moves
• Explain Significance: Not just locations, but why they matter
• Include Navigation Hints: Help others explore

Integration with Development

During Development Tasks

• Create records for "figuring out" moments
• Update location indexes for new key areas
• Note architecture understanding evolution

During Debugging

• Document root cause discoveries
• Record surprising behavior explanations
• Note workarounds and rationale

During Code Review

• Create records for reusable patterns
• Document insights from others' approaches
• Record "I didn't know you could do that" moments

Maintenance Schedule

• Daily: Review and link related discoveries
• Weekly: Update learning paths, organize records
• Monthly: Consolidate into primary documentation

Orchestration Notes

Discovery is typically an end-of-workflow activity:

• Run after task completion to capture learnings
• Run during daily wrap-up
• Creates valuable context for future work

Groom Command Reference

Transform context network's task list into actionable backlog.

Purpose

Refine tasks from "planned" status to "ready" status by ensuring they have clear acceptance criteria, proper scoping, and all dependencies resolved.

When Used in Workflow

• Sprint Start: Comprehensive grooming of all tasks
• Daily Morning: Check what's ready for today
• Task Selection: Before /next to ensure tasks are properly prepared

Common Invocation Patterns

groom                     # Groom all tasks
groom --ready-only       # Only show tasks that are ready
groom --blocked          # Focus on identifying/unblocking blocked tasks
groom --stale 7          # Re-groom tasks older than 7 days
groom --generate-sprint  # Create sprint plan from groomed tasks

Grooming Process

Phase 1: Task Inventory

Scan task sources:

• /planning/sprint-*.md
• /planning/backlog.md
• /tasks/**/*.md
• /decisions/**/*.md (for follow-up actions)
• Files with "TODO:", "NEXT:", "PLANNED:" markers

Phase 2: Task Classification

Classify each task as:

• A: Claimed Complete - Marked done but needs follow-up
• B: Ready to Execute - Clear criteria, no blockers
• C: Needs Grooming - Vague requirements or missing context
• D: Blocked - Waiting on dependencies or decisions
• E: Obsolete - No longer relevant or duplicate

Phase 3: Reality Check

For each task, assess:

• Still needed? (Check against current project state)
• Prerequisites met? (Identify missing dependencies)
• Implementation clear? (Flag ambiguities)
• Success criteria defined? (Note what's missing)
• Complexity estimate: Trivial/Small/Medium/Large/Unknown

Phase 4: Task Enhancement

Transform vague tasks into actionable items with:

• Specific, measurable title
• Clear context and rationale
• Input/output specifications
• Acceptance criteria checklist
• Implementation notes
• Identified dependencies
• Effort estimate

Phase 5: Priority Scoring

Score tasks based on:

• User value (High/Medium/Low)
• Technical risk (High/Medium/Low)
• Effort (Trivial/Small/Medium/Large)
• Dependencies (None/Few/Many)

Output Format

# Groomed Task Backlog

## Ready for Implementation

### 1. [Specific Task Title]
**One-liner**: [What this achieves]
**Effort**: [Estimate]
**Files to modify**: [Key files]

<details>
<summary>Full Details</summary>

**Context**: [Why needed]
**Acceptance Criteria**:
- [ ] [Specific criterion]
- [ ] [Another criterion]

**Implementation Guide**:
1. [First step]
2. [Second step]

**Watch Out For**: [Pitfalls]
</details>

## Ready Soon (Blocked)

### [Task Title]
**Blocker**: [What's blocking]
**Prep work possible**: [What can be done now]

## Needs Decisions

### [Task Title]
**Decision needed**: [Specific question]
**Options**: [List with pros/cons]

## Summary Statistics
- Ready for work: Y
- Blocked: Z
- Archived: N

Red Flags to Identify

• Task has been "almost ready" for multiple sprints
• No one can explain what "done" looks like
• "Just refactor X" - usually hides complexity
• Task title contains "and" - should be split
• "Investigate/Research X" without concrete output

Orchestration Notes

Grooming updates happen on main branch (not feature branches) because:

• Backlog state is shared across all work
• Tasks need to be visible to all developers
• Status changes aren't implementation changes

Implement Command Reference

Test-driven development in isolated worktree.

Purpose

Implement a task using TDD methodology: write tests first, then implementation, in an isolated worktree to keep main branch clean.

When Used in Workflow

• Task Cycle: After task selection, the main development step

Invocation

implement [TASK-ID]       # Implement specific task in worktree

Core Principle: Test-First Development

NEVER write implementation code before writing tests. Tests define the contract and guide the implementation.

Implementation Process

Phase 1: Setup & Validation

1. Locate Planning Documents

• Find relevant plans in /context-network/planning/
• Review architecture in /context-network/architecture/
• Check decisions in /context-network/decisions/

2. Validate Requirements

• Confirm understanding of acceptance criteria
• Identify any ambiguities
• Check for missing specifications

3. Create Worktree

   git worktree add .worktrees/[TASK-ID] -b task/[TASK-ID]-description
   cd .worktrees/[TASK-ID]

Phase 2: Test-Driven Development (MANDATORY)

Write tests before ANY implementation code

1. Write Tests First

• Happy path tests - Core functionality
• Edge case tests - Boundary conditions
• Error tests - Failure scenarios
• Integration tests - Component interactions

2. Test Structure

   describe('ComponentName', () => {
     beforeEach(() => { /* Setup */ });
     afterEach(() => { /* Cleanup */ });

     describe('functionName', () => {
       it('should handle normal input correctly', () => {
         // Arrange
         const input = setupTestData();
         // Act
         const result = functionName(input);
         // Assert
         expect(result).toEqual(expectedOutput);
       });

       it('should throw error for invalid input', () => {
         // Test error conditions
       });
     });
   });

3. Run Tests (Red Phase)

• Confirm ALL tests fail appropriately
• Validate test assertions are meaningful
• DO NOT PROCEED until tests are failing correctly

Phase 3: Implementation (Only After Tests)

STOP! Have you written tests? If no, go back to Phase 2.

1. Minimal Implementation

• Write ONLY enough code to make the next test pass
• No premature optimization
• No features not covered by tests
• Focus on one test at a time

2. Implementation Order

• Run test - see it fail
• Write minimal code to pass
• Run test - see it pass
• Refactor if needed (tests still pass)
• Move to next test

3. Code Quality

• Proper separation of concerns
• Clear naming conventions
• SOLID principles
• Every public method must have tests

Phase 4: Refinement (Red-Green-Refactor)

1. Verify All Tests Pass (Green Phase)

• ALL tests must be green
• No skipped tests
• Coverage > 80% minimum

2. Refactor With Confidence

• Improve code structure (tests protect you!)
• Remove duplication
• Optimize performance
• Run tests after EVERY refactor

Phase 5: Integration

1. Wire Up

• Connect to existing systems
• Update configuration
• Add to dependency injection

2. Commit Changes

   git add .
   git commit -m "[TASK-ID]: Implement [feature]

   - Added tests for [functionality]
   - Implemented [component]
   - Updated configuration

   Co-Authored-By: Claude <noreply@anthropic.com>"

Output Format

## Implementation Complete: [Task Name]

### Summary
- **What**: [Brief description]
- **Why**: [Business/technical reason]
- **How**: [High-level approach]

### Changes Made
- `path/to/new/file.ts` - [Purpose]
- `path/to/modified/file.ts` - [What changed]

### Testing
- [ ] **Tests written BEFORE implementation**
- [ ] Unit tests passing
- [ ] Edge cases tested
- [ ] Error conditions tested
- Test coverage: [X]%
- Number of tests: [Count]

### Validation
- [ ] Linting passes
- [ ] Type checking passes
- [ ] Build succeeds

Quality Checklist

Before marking complete:

• [ ] Tests were written FIRST (not retrofitted)
• [ ] All acceptance criteria met
• [ ] Coverage > 80%
• [ ] All tests pass consistently
• [ ] Code follows project patterns
• [ ] No console.logs or debug code
• [ ] Error handling is comprehensive

Orchestration Notes

After implementation completes:

• CHECKPOINT: IMPL_COMPLETE - Pause to verify work
• Show test results, coverage, build status
• If all pass: ready to proceed to review
• If failures: must address before continuing

Maintenance Command Reference

Context network audit and cleanup.

Purpose

Systematically review and maintain the integrity of the context network, ensuring it remains valuable, navigable, and accurate.

When Used in Workflow

• Sprint End: Deep cleanup between sprints
• Weekly: Regular maintenance
• Ad-hoc: When network feels disorganized

Common Invocation Patterns

maintenance              # Standard maintenance
maintenance --deep       # Thorough cleanup

Audit Categories

1. Structural Integrity

File Organization:

• Verify standard directory structure
• Check planning docs are in context network (not project root)
• Ensure no build artifacts in context network
• Validate .context-network.md exists and is accurate

Node Size & Scope:

• Flag nodes > 1500 words (consider splitting)
• Identify sparse nodes < 200 words (consider consolidating)
• Verify single-concept focus per node

Naming Conventions:

• Consistent file naming patterns
• Accurate node titles
• No duplicate names

2. Relationship Network

Link Integrity:

• Verify bidirectional relationships
• Identify orphaned nodes
• Flag broken links
• Check relationship type consistency

Relationship Quality:

• Explicit relationship types (not just "relates to")
• Meaningful relationship descriptions
• Identify missing connections

Cross-Domain Connections:

• Adequate connections between domains
• Well-documented interface points

3. Content Accuracy

Project Alignment:

• Compare descriptions against actual project
• Flag outdated architecture descriptions
• Identify missing documentation

Temporal Accuracy:

• Verify metadata reflects actual update dates
• Identify stale content
• Flag nodes marked "Dynamic" that haven't changed

4. Navigation & Usability

Entry Points:

• Main discovery.md provides orientation
• Domain-specific entry points current
• Navigation guides accurate

Search & Discovery:

• Key terms in appropriate nodes
• Tag consistency
• Discovery records use effective keywords
• Location indexes current

5. Metadata Consistency

• Complete classification on all nodes
• Consistent date formatting
• Accurate stability ratings
• Proper confidence levels

Red Flags to Check

1. Planning documents in project root 2. Architecture diagrams outside context network 3. Orphaned nodes with no connections 4. Circular navigation paths 5. Missing bidirectional links 6. Stale "Dynamic" content 7. Undefined relationship types 8. Inconsistent classification schemes 9. Missing change history 10. Build artifacts in context network 11. Discovery records without keywords 12. Location indexes with stale paths 13. Learning paths not connected to discoveries 14. Obsolete content not archived

Output Format

# Context Network Audit Report - [Date]

## Executive Summary
- Overall health score
- Critical issues requiring attention
- Key recommendations

## Detailed Findings

### Structural Integrity
- [Issues with examples]
- [Severity ratings]
- [Recommended fixes]

### Relationship Network
- [Link integrity issues]
- [Missing connections]

### Content Accuracy
- [Outdated information]
- [Missing documentation]

### Navigation & Usability
- [Navigation issues]
- [Discovery problems]

## Prioritized Recommendations

### Critical (Address Immediately)
1. [Issue] → [Fix] → [Impact]

### High Priority (This Week)
1. [Issue] → [Fix] → [Impact]

### Medium Priority (This Month)
1. [Issue] → [Fix] → [Impact]

## Process Improvements
- [Workflow changes]
- [Automation opportunities]

Orchestration Notes

Maintenance is typically run:

• At workflow boundaries (sprint end, week end)
• Before major planning sessions
• When navigation feels difficult
• Ensures context network remains useful

Next Command Reference

Identify the single next best task to work on from the groomed backlog.

Purpose

Select the highest priority ready task, providing just enough information to start implementation.

When Used in Workflow

• Task Cycle: After sync, before implement
• Ad-hoc: When asking "what should I work on?"

Invocation

next                      # Select next task from ready queue

Selection Process

Step 1: Load Ready Tasks

Read context-network/backlog/by-status/ready.md to get available tasks.

Step 2: Selection Logic

Priority Order: 1. Critical Priority tasks (if any) 2. High Priority tasks 3. Medium Priority tasks 4. Low Priority tasks

Within same priority level, prefer:

• Tasks with no dependencies over those with dependencies
• Smaller tasks (trivial/small) over larger ones (medium)
• Tasks that unblock other work
• Tasks in sequence (e.g., TASK-004-2 before TASK-004-3)

Step 3: Output

If ready task found:

**Next Task:** [TASK-ID] - [Task Title]

**Priority:** [Critical/High/Medium/Low]
**Size:** [trivial/small/medium]
**Branch:** [suggested-branch-name]

Start with: implement [TASK-ID]

If no ready tasks:

No tasks are currently ready for implementation.

Run groom to prepare tasks from the planned backlog.

What NOT to Do

• Don't load or display full task details
• Don't show multiple task options
• Don't provide extensive context about the task
• Don't analyze task content in depth
• Don't check dependencies (should already be resolved for ready tasks)

Output Format

Keep it minimal:

• Task ID
• Task title
• Priority and size
• Suggested branch name
• How to start

Orchestration Notes

After next completes:

• CHECKPOINT: TASK_SELECTED - Pause for user confirmation
• User can accept the suggestion or request different task
• On acceptance, proceed to implement with the task ID

PR Complete Command Reference

Merge approved PR, cleanup worktree, and update task status for Gitea.

Purpose

Complete the pull request lifecycle: merge, cleanup branches and worktrees, mark task as complete.

When Used in Workflow

• Task Cycle: Final step after PR approval

Prerequisites

• PR has been created and reviewed
• CI checks are passing (verified externally or via API)
• Required approvals obtained

Completion Process

Phase 1: Verify PR Status

# View PR details
tea pulls

# Check if PR is approved (via API script)
./scripts/gitea-pr-checks.sh owner repo $PR_NUMBER

# Verify CI status (via API script)
./scripts/gitea-ci-status.sh owner repo $(git rev-parse HEAD)

Manual verification:

• Check your Gitea PR page for approval status
• Check your CI dashboard for build status

Phase 2: Pre-Merge Validation

# Navigate to worktree
cd .worktrees/[TASK-ID]/

# Update from main
git fetch origin main

# Check for conflicts
git merge origin/main --no-commit --no-ff
git merge --abort  # Just checking

# Final test run
npm test
npm run lint
npm run build

Phase 3: Merge Pull Request

# Squash merge (recommended)
tea pulls merge $PR_NUMBER --style squash

# Or merge commit
tea pulls merge $PR_NUMBER --style merge

# Or rebase merge
tea pulls merge $PR_NUMBER --style rebase

# Or rebase-merge (creates merge commit after rebase)
tea pulls merge $PR_NUMBER --style rebase-merge

Note: Tea CLI may not automatically delete the branch. Delete manually if needed:

git push origin --delete task/[TASK-ID]-description

Phase 4: Worktree Cleanup

# Navigate out of worktree
cd /path/to/main/repo

# Remove worktree
git worktree remove .worktrees/[TASK-ID]/

# Verify removal
git worktree list

# Prune stale references
git worktree prune

Phase 5: Update Task Status

CRITICAL: After PR merge, status updates happen ON MAIN

# Ensure on main
git checkout main
git pull origin main

# Update task file
# - Status: completed
# - PR: #[PR_NUMBER] (merged)
# - Completed: [current date]

# Update status indexes
# - Remove from in-review.md
# - Add to completed.md

# Commit to main (only case we commit directly)
git add context-network/backlog/
git commit -m "Complete: [TASK-ID] merged via PR #$PR_NUMBER"
git push origin main

Note: This is the ONLY command that commits to main because:

• PR has already been reviewed and approved
• We're just recording completion in the backlog
• Feature branch and worktree no longer exist
• This is administrative bookkeeping

Phase 6: Update Backlog Epic File and Project Status

CRITICAL: Persist progress to source-of-truth documentation.

Without this phase, internal tracking (worker progress files, coordinator state) diverges from the backlog and project status files that humans and future sessions rely on.

# Ensure on main
git checkout main

Step 1: Update task status in the backlog epic file

# Locate the epic file that contains this task
# e.g., context-network/backlog/by-epic/E1-feature-name.md

# Change the task's status from "ready" (or "in-progress") to "complete"
# Update any completion metadata (date, commit hash, PR number)

Step 2: Update epic-level progress

# Recalculate the epic's completion count
# e.g., "Status: In Progress (22/28 complete)" → "Status: In Progress (23/28 complete)"
# If all tasks complete, update epic status to "Complete"

Step 3: Unblock dependent tasks

# Check if any tasks in the epic were blocked on the just-completed task
# If so, update their status from "blocked" to "ready"
# Example: If TASK-023 was blocked by TASK-022, and TASK-022 is now complete,
#          change TASK-023 status to "ready"

Step 4: Update project status file

# Update context/status.md (or equivalent project status file) with:
# - Current project phase
# - Epic progress table (tasks completed / total per epic)
# - Recently completed work
# - Active/upcoming work summary

Step 5: Commit documentation updates

git add context-network/backlog/ context/status.md
git commit -m "docs: Update backlog and project status after [TASK-ID] completion"
git push origin main

Why this phase exists: Internal tracking files (.coordinator/state.json, worker progress files) are ephemeral and session-scoped. The backlog epic files and project status are the persistent source of truth. Skipping this phase causes documented state to drift from reality — future sessions will see stale "ready" statuses for already-completed tasks.

Error Handling

PR Not Approved

Error: PR #X is not approved yet
Required approvals: Y
Current approvals: Z
Request review via Gitea UI or:
tea pulls review

CI Checks Failing

Error: CI checks are failing
Check your CI dashboard for details.
Fix issues in worktree and push updates.

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

Merge Conflicts

1. cd .worktrees/[TASK-ID]/
2. git pull origin main
3. Resolve conflicts
4. git add . && git commit
5. git push
6. Re-run pr-complete

Output Format

## PR Merged Successfully!

**Task:** [TASK-ID] - [Task Title]
**PR:** #[PR_NUMBER]
**Merge Method:** Squash merge
**Status:** Completed

### Cleanup Complete
- [x] PR merged to main
- [x] Feature branch deleted
- [x] Worktree removed
- [x] Task status updated
- [x] Backlog indexes updated
- [x] Epic file updated (task marked complete, dependents unblocked)
- [x] Project status file updated

### Next Available Tasks
[Top 3 ready tasks from backlog]

Rollback Procedure

If issues discovered after merge:

# Create revert commit
git revert [merge-commit-sha]
git push origin main

# Or create a revert PR via Gitea UI

Orchestration Notes

After completion:

• Task cycle is complete
• Can immediately start next task cycle
• Consider running /discovery to capture learnings
• Consider /retrospective for larger tasks

Gitea-Specific Notes

Tea Merge Styles

Branch Deletion

Tea CLI may not automatically delete branches after merge. To clean up:

# Delete remote branch
git push origin --delete task/[TASK-ID]-description

# Delete local branch (if exists)
git branch -d task/[TASK-ID]-description

Verifying Merge

# Check PR state
tea pulls list --state merged

# Verify on main
git checkout main
git pull
git log --oneline -5  # Should show your merge

PR Prep Command Reference

Prepare and create pull request with full documentation for Gitea.

Purpose

Validate implementation, generate PR documentation, and create the pull request using Gitea Tea CLI.

When Used in Workflow

• Task Cycle: After reviews and fixes, before merge

Prerequisites

• Task implementation complete in worktree
• All changes committed to feature branch
• Gitea Tea CLI installed (tea --version)
• Authenticated with Gitea (tea login)
• GITEA_URL and GITEA_TOKEN environment variables set (for API scripts)

PR Preparation Process

Phase 1: Identify Context

# Check current branch
git branch --show-current

# Should be in worktree
pwd  # .worktrees/[TASK-ID]/

Phase 2: Validation Suite

ALL CHECKS MUST PASS before creating PR

1. Run Test Suite

   npm test
   npm run test:integration

2. Code Quality Checks

   npm run lint
   npm run typecheck

3. Build Verification

   npm run build

4. Coverage Check

• Ensure > 80% coverage for new code

Phase 3: PR Documentation

Generate comprehensive PR description:

## [TASK-ID]: [Task Title]

### Summary
[Brief description of what was implemented]

### Changes
- [Key change 1]
- [Key change 2]
- [Key change 3]

### Acceptance Criteria
[Copy from task file, mark completed items]
- [x] Criterion 1 completed
- [x] Criterion 2 completed

### Testing
- Unit tests: [count] added/modified
- Integration tests: [count] added/modified
- Coverage: [before]% → [after]%
- All tests passing

### Technical Notes
[Any important implementation details]

### Related Issues/Tasks
- Implements: #[TASK-ID]
- Related to: [other task IDs]

### Checklist
- [x] Tests written and passing
- [x] Linting passes
- [x] Type checking passes
- [x] Build succeeds
- [x] Documentation updated
- [x] No console.logs or debug code

Phase 4: Create Pull Request

# Push to remote
git push -u origin task/[TASK-ID]-description

# Create PR using tea CLI
tea pulls create \
  --title "[TASK-ID]: [Task Title]" \
  --description "$(cat /tmp/pr-description.md)" \
  --base main \
  --head task/[TASK-ID]-description

Alternative with inline description:

tea pulls create \
  --title "[TASK-ID]: [Task Title]" \
  --description "## Summary

Implements [feature description].

## Changes
- Change 1
- Change 2

## Testing
All tests passing."

Phase 5: Update Task Status

Status updates happen in worktree, committed to feature branch

# Update task file
# - Add PR number
# - Update status to 'in-review'
# - Note PR creation timestamp

# Commit status changes
git add context-network/backlog/
git commit -m "Status: Move [TASK-ID] to in-review (PR #$PR_NUMBER)"
git push

Validation Checklist

Before creating PR:

• [ ] All tests pass
• [ ] Code coverage meets minimum (80%)
• [ ] Linting has no errors
• [ ] Type checking passes
• [ ] Build succeeds
• [ ] No debug code remains
• [ ] Documentation updated
• [ ] Commits are clean and descriptive

Error Handling

If Tests Fail

1. Fix issues in worktree 2. Commit fixes 3. Re-run validation 4. Do NOT create PR until passing

If Not in Worktree

cd .worktrees/[TASK-ID]/
# Or error if task not in progress

Output Format

## PR Created Successfully!

**Task:** [TASK-ID] - [Task Title]
**PR:** #[PR_NUMBER]
**URL:** [GITEA_URL]/[owner]/[repo]/pulls/[PR_NUMBER]
**Status:** In Review

### Next Steps
1. Wait for CI checks to complete (check your CI dashboard)
2. Request code review if needed
3. Address any review comments
4. Once approved, run pr-complete to merge

Orchestration Notes

After PR creation:

• CHECKPOINT: PR_CREATED - Pause for CI and review
• Monitor CI status via your CI dashboard or API script:

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

• Wait for required approvals
• On all green: ready for pr-complete

Gitea-Specific Notes

Tea CLI PR Creation Options

# Full options
tea pulls create \
  --title "Title" \
  --description "Description" \
  --base main \
  --head feature-branch \
  --assignee username

# The PR number is shown in output after creation

Verifying PR Created

# List your open PRs
tea pulls list --state open

# View the PR you just created
tea pulls

CI Status

Gitea uses external CI systems. After PR creation:

1. Check your CI dashboard (Drone, Woodpecker, Jenkins, etc.) 2. Or use the API script:

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

3. CI results are typically posted as commit statuses

Retrospective Command Reference

Post-task analysis and context network updates.

Purpose

Conduct retrospective analysis after completing a task to identify what should be captured in the context network and what adjustments need to be made.

When Used in Workflow

• Sprint End: Comprehensive sprint retrospective
• Post-Task: After significant task completion
• Weekly: End of week review

Domain Boundary Reminder

• Context Network: Planning, architecture, design, strategies
• Project Artifacts: Source code, configuration, tests, public docs

Retrospective Process

Phase 1: Task Review

Task Summary:

• What was the original objective?
• What was actually accomplished?
• Were there deviations from plan?

Decision Inventory:

• What architectural decisions were made?
• What trade-offs were considered?
• What alternatives were rejected and why?

Discovery Log:

• What unexpected challenges emerged?
• What new patterns were discovered?
• What assumptions proved incorrect?
• What discovery records were created?

Phase 2: Gap Analysis

Missing Documentation:

• Planning documents that would have helped?
• Design decisions not captured anywhere?
• New patterns that should be documented?
• Discovery records that would have saved time?

Outdated Information:

• Documentation that was incorrect?
• Nodes whose relationships changed?
• Confidence levels that need updating?

Relationship Gaps:

• Connections between nodes not documented?
• New cross-domain relationships discovered?
• Navigation paths that would help?

Phase 3: Update Requirements

For each gap, determine:

Update Type:

• New node creation
• Existing node modification
• Relationship establishment
• Navigation guide enhancement

Priority:

• Critical: Would cause immediate problems
• Important: Would improve future work significantly
• Nice-to-have: Enhances understanding

Phase 4: Execute Updates

New Node Creation:

## Node: [Title]

### Classification
- Domain: [Where it fits]
- Stability: [Change frequency]
- Confidence: [How certain]

### Key Content
[Essential information]

### Critical Relationships
- Depends on: [Prerequisites]
- Enables: [What it makes possible]

### Task Context
- Discovered during: [Task name]
- Relevance: [Why this matters]

Node Modification:

## Update for: [Node Title]

### What Changed
- Previous: [Old understanding]
- New: [Current understanding]
- Reason: [What led to change]

### Impact
- Affected relationships: [What needs review]
- Downstream implications: [What else needs updating]

Phase 5: Changelog Entry

## Retrospective: [Task Name] - [Date]

### Task Summary
- Objective: [Goal]
- Outcome: [Result]
- Key learnings: [Discoveries]

### Context Network Updates

#### New Nodes Created
- [Node Name]: [Brief description]

#### Discovery Records Created
- [YYYY-MM-DD-###]: [Description]

#### Nodes Modified
- [Node Name]: [What changed]

#### New Relationships
- [Source] → [Type] → [Target]: [Why it matters]

### Patterns and Insights
- Recurring themes: [What patterns emerged]
- Process improvements: [How to do better]
- Knowledge gaps: [What's still missing]

### Follow-up Recommendations
1. [Recommendation]: [Rationale]

Execution Checklist

• [ ] Reviewed all decisions made during task
• [ ] Identified planning/architecture content created
• [ ] Checked for outdated documentation encountered
• [ ] Documented new patterns discovered
• [ ] Created/updated relevant context network nodes
• [ ] Established important relationships
• [ ] Updated navigation guides
• [ ] Created changelog entry
• [ ] Identified follow-up improvements

Quality Checks

1. Placement: All planning docs in context network? 2. Relationships: Bidirectional links documented? 3. Classification: Accurate for all nodes? 4. Navigation: Would someone else find this? 5. Future Value: Will this save time later?

Orchestration Notes

Retrospective is an end-of-cycle activity:

• Run after significant task completion
• Run at sprint boundaries
• Ensures learning is captured before context is lost

Review Code Command Reference

Code quality review for maintainability, security, and best practices.

Purpose

Review code files for quality issues, security vulnerabilities, performance problems, and adherence to best practices.

When Used in Workflow

• Task Cycle: After implementation, before PR
• Ad-hoc: Code quality check at any time

Common Invocation Patterns

review-code               # Review all code
review-code --uncommitted # Only uncommitted changes
review-code --staged      # Only staged changes
review-code --branch      # All changes in current branch vs main
review-code --security    # Enhanced security focus
review-code --performance # Enhanced performance focus

Review Focus Areas

1. Code Quality and Maintainability

• Code duplication (DRY violations)
• Overly complex functions
• Proper separation of concerns
• Appropriate abstraction levels
• Code smells and anti-patterns

2. Security Vulnerabilities

• Hardcoded secrets, API keys, passwords
• Injection vulnerabilities (SQL, command, XSS)
• Unsafe type coercion or unvalidated inputs
• Authentication/authorization issues
• Insecure data handling

3. Performance Issues

• Inefficient algorithms or data structures
• Unnecessary loops or redundant computations
• Memory leaks or resource management issues
• Improper async/await usage
• Blocking operations

4. Error Handling

• Proper error handling and recovery
• Unhandled promise rejections
• Informative error messages
• Proper logging
• Graceful degradation

5. Code Standards

• Consistent naming conventions
• Proper typing (TypeScript) or type hints
• Single responsibility functions
• Design pattern usage
• SOLID principles

Common Anti-Patterns to Flag

Hardcoded Secrets:

// BAD
const API_KEY = "sk-1234567890abcdef";

SQL Injection:

// BAD
const query = `SELECT * FROM users WHERE id = ${userId}`;

Unhandled Promises:

// BAD
async function getData() {
  const result = await fetch('/api/data');
  return result.json();  // No error handling
}

Deep Nesting:

// BAD - Pyramid of doom
if (condition1) {
  if (condition2) {
    if (condition3) {
      // do something
    }
  }
}

Magic Numbers:

// BAD
if (user.age > 17) { /* ... */ }

Quality Thresholds

• Functions longer than 50 lines
• Files longer than 500 lines
• Cyclomatic complexity > 10
• Nesting depth > 4 levels
• Commented out code blocks
• TODO/FIXME without context

Output Format

## Code Review Summary

### Critical Issues (Security/Data Loss Risk)
- [Issues that could cause vulnerabilities or data loss]

### High Priority Issues (Bugs/Crashes)
- [Issues that could cause runtime errors]

### Medium Priority Issues (Maintainability)
- [Issues affecting code maintainability]

### Low Priority Issues (Style/Convention)
- [Minor improvements]

### Statistics
- Files reviewed: X
- Critical issues: A
- High priority: B
- Medium priority: C
- Low priority: D

### Top Recommendations
1. [Most critical improvement]
2. [Second priority]
3. [Third priority]

### Positive Findings
- [Well-written patterns observed]

Orchestration Notes

Review results feed into the REVIEWS_DONE checkpoint:

• Critical issues: must address before continuing
• High issues: strongly recommend addressing
• Medium/Low: can defer to tasks via apply-recommendations

Review Tests Command Reference

Unit test quality review for isolation, meaningfulness, and best practices.

Purpose

Review test files for quality issues including tautological tests, proper mocking, meaningful assertions, and test structure.

When Used in Workflow

• Task Cycle: After implementation, alongside code review
• Ad-hoc: Test quality assessment

Common Invocation Patterns

review-tests               # Review all test files
review-tests --uncommitted # Only uncommitted changes
review-tests --staged      # Only staged changes
review-tests --branch      # All changes in current branch
review-tests --coverage 80 # Minimum coverage threshold

Review Focus Areas

1. Tautological Tests Detection

• Tests that assert the same value they just set
• Tests that only verify mocked behavior
• Tests like: expect(true).toBe(true)
• Tests that pass even when implementation is broken

2. Proper Mocking and Isolation

• External dependencies mocked (databases, APIs, file systems)
• Only unit under test uses real implementation
• Mocks properly reset between tests
• No tests depending on external state

3. Meaningful Assertions

• Tests check actual behavior, not implementation details
• Assertions test the contract/interface
• Edge cases and error conditions verified
• Error messages and types tested

4. Test Structure and Clarity

• Test names clearly describe scenarios
• Arrange-Act-Assert structure
• Tests are independent and order-agnostic
• Proper setup/teardown usage

5. Coverage Quality

• Business logic thoroughly tested
• Edge cases, error paths, boundaries covered
• Not just happy path testing

Common Anti-Patterns to Flag

Direct Tautologies:

// BAD - Testing the assignment
const result = 5;
expect(result).toBe(5);

Mock-Only Tests:

// BAD - Testing the mock, not the component
mockService.getValue.mockReturnValue(42);
const result = component.getData();
expect(result).toBe(42);

Self-Referential Tests:

// BAD - Just testing constructor assignment
const user = new User({ name: 'John' });
expect(user.name).toBe('John');

Missing Isolation:

// BAD - Depends on external state
const data = await fetchFromRealDatabase();
expect(data).toBeDefined();

Quality Checks

• Testing private methods directly
• Testing implementation details
• Snapshot tests without clear purpose
• Missing negative test cases
• Tests with no assertions
• Tests that always pass

Examples of Good Tests

// GOOD - Tests actual behavior
it('should calculate discount correctly for premium users', () => {
  const calculator = new PriceCalculator();
  const result = calculator.calculatePrice({
    basePrice: 100,
    userType: 'premium'
  });
  expect(result).toBe(80); // 20% discount
});

// GOOD - Proper mocking with behavior verification
it('should handle API errors gracefully', async () => {
  mockApi.fetch.mockRejectedValue(new Error('Network error'));
  const service = new DataService(mockApi);

  await expect(service.getData()).rejects.toThrow('Failed to fetch data');
  expect(mockLogger.error).toHaveBeenCalledWith(
    'API call failed',
    expect.any(Error)
  );
});

Output Format

## Test Quality Review Summary

### Critical Issues (High Severity)
- [Issues that break test isolation or leave functionality untested]

### Poor Practices (Medium Severity)
- [Issues that reduce test effectiveness]

### Style Improvements (Low Severity)
- [Minor improvements and consistency issues]

### Statistics
- Test files reviewed: X
- Files with issues: Y
- Tautological tests found: Z
- Missing mocks: N

### Top Recommendations
1. [Most important improvement]
2. [Second priority]
3. [Third priority]

Orchestration Notes

Test review results combine with code review for REVIEWS_DONE checkpoint:

• Tautological tests: should fix (tests provide false confidence)
• Missing isolation: should fix (tests are unreliable)
• Style issues: can defer

Status Command Reference

Project health and progress reporting.

Purpose

Provide comprehensive overview of project health, progress, risks, and recommendations.

When Used in Workflow

• Daily Morning: Quick health check
• Sprint Start: Baseline status
• Sprint End: Sprint metrics

Common Invocation Patterns

status                    # Detailed report (default)
status --brief           # Quick summary (1-2 paragraphs)
status --sprint          # Focus on current sprint
status --metrics         # Include quantitative metrics
status --risks           # Emphasize risks and blockers

Assessment Process

Phase 1: Progress Evaluation

Task Status Analysis:

• Review /tasks/ for completion rates
• Check /planning/sprint-*.md for progress
• Analyze /planning/backlog.md for remaining work

Velocity Metrics:

• Tasks completed this period
• Tasks in progress
• Tasks blocked
• Completion rate vs plan

Phase 2: Health Indicators

Code Quality:

• Recent test coverage changes
• Technical debt accumulation
• Code complexity trends
• Recent audit findings

Documentation:

• Context network currency
• Documentation coverage
• Discovery records created
• Knowledge gaps identified

Process:

• Decision velocity
• Blocker resolution time
• Collaboration effectiveness

Phase 3: Risk Assessment

Current Risks:

• Technical risks and mitigation
• Schedule risks and impact
• Resource constraints
• External dependencies

Emerging Concerns:

• New technical debt
• Architectural drift
• Process breakdowns
• Knowledge silos

Phase 4: Recommendations

Immediate Actions:

• Critical issues to address
• Quick wins available
• Blockers to resolve

Strategic Adjustments:

• Process improvements
• Architecture refinements
• Resource reallocations

Output Format

# Project Status Report - [Date]

## Executive Summary
[1-2 paragraph overview]

## Progress Overview

### Current Sprint/Milestone
- **Goal**: [Objective]
- **Progress**: X/Y tasks (Z%)
- **Days Remaining**: N
- **Status**: On Track | At Risk | Behind

### Velocity
- **This Period**: X tasks completed
- **Average**: Y tasks/period
- **Trend**: Improving | Stable | Declining

## Key Accomplishments
- [Achievement 1]
- [Achievement 2]

## Current Focus
- [Priority 1]
- [Priority 2]

## Health Indicators

### Code Quality
- **Test Coverage**: X%
- **Technical Debt**: Low/Medium/High
- **Build Status**: Passing | Failing

### Documentation
- **Currency**: X% up-to-date
- **Coverage**: Y% documented

## Risks & Blockers

### Critical Issues
1. **[Issue]**
   - Impact: [Description]
   - Action: [What to do]

### Warnings
1. **[Concern]**
   - Risk: [What might happen]
   - Mitigation: [Prevention]

## Recommendations

### Immediate (This Week)
1. [Most urgent]
2. [Second priority]

### Short-term (This Sprint)
- [Process improvement]
- [Technical adjustment]

## Upcoming Milestones
- [Date] - [Milestone 1]
- [Date] - [Milestone 2]

Status Indicators

Use consistently:

• On Track / At Risk / Behind
• Improving / Stable / Declining
• Complete / In Progress / Waiting / Blocked

Orchestration Notes

Status provides context for workflow decisions:

• Morning: informs task selection
• Sprint boundaries: guides planning
• Risk-focused: prioritizes blockers

Sync Command Reference

Reality synchronization between context network and actual project state.

Purpose

Detect and correct drift between planned/documented state and actual project reality. Identifies work that's been completed but not documented, updates task statuses, and realigns the network with current state.

When Used in Workflow

• Task Cycle: First step to ensure starting from accurate state
• Daily Morning: Reality check before starting work
• Daily Evening: Capture actual progress made
• Sprint End: Full synchronization before retrospective

Common Invocation Patterns

sync                      # Full sync of all active plans
sync --last 1d           # Only check work from last day
sync --last 1w           # Only check work from last week
sync --dry-run           # Preview changes without applying
sync --verbose           # Include detailed evidence

Sync Process

Phase 1: Reality Assessment

Scan project artifacts: 1. List files changed in the timeframe 2. Identify new files/directories created 3. Review recent commits 4. Check test files for implemented features 5. Scan configuration changes 6. Review dependency updates

Phase 2: Plan Comparison

Load active plans from context network:

• Current sprint/milestone tasks
• Active project plans
• In-progress feature specifications
• Recent task handoffs
• Pending implementation items

Phase 3: Drift Detection

Identify completion patterns:

Definitely Completed:

• Planned file exists with expected structure
• Tests exist and reference the feature
• Configuration includes the component
• Integration points are connected

Partially Completed:

• Some but not all expected files exist
• Basic structure without full implementation
• Tests exist but incomplete

Divergent Implementation:

• Implementation exists but differs from plan
• Alternative approach taken
• Scope changed during implementation

Phase 4: Evidence Gathering

For each suspected completion, document:

• Direct evidence (files, tests, config)
• Supporting evidence (imports, references, commits)
• Counter-evidence (missing files, incomplete integration)
• Confidence assessment (High/Medium/Low)

Phase 5: Network Updates

Generate updates for:

• Task status changes
• New documentation needs
• Plan adjustments

Output Format

# Context Network Sync Report

## Sync Summary
- Planned items checked: X
- Completed but undocumented: Y
- Partially completed: Z
- Divergent implementations: N

## Completed Work Discovered

### High Confidence Completions
1. **[Feature Name]**
   - Evidence: [Brief summary]
   - Implementation location: [Path]
   - Action: Mark as complete

### Medium Confidence Completions
1. **[Feature Name]**
   - Evidence: [What we found]
   - Uncertainty: [What's unclear]
   - Recommended verification: [How to confirm]

## Network Updates Required
- [ ] Update task status for [items]
- [ ] Create documentation stubs for [features]
- [ ] Update progress indicators

## Recently Completed Tasks (Last 7 Days)
[List of tasks that may still appear as available but are actually done]

Orchestration Notes

After sync completes:

• If drift detected: summarize key findings for checkpoint
• If no drift: auto-continue to next workflow step
• Update checkpoint context with sync results

Daily Phase Reference

Morning and evening workflow sequences for daily development rhythm.

Overview

Daily sequences maintain alignment and capture knowledge at natural workflow boundaries.

Morning Standup (~5 minutes)

MORNING SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --last 1d        │ ─── What actually happened yesterday?
│ --dry-run             │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --brief        │ ─── Current sprint health
│ --sprint              │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ groom --ready-only    │ ─── What's ready to work on?
└───────────┬───────────┘
            │
            ▼
         OUTPUT
    "Today's Priorities"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Sync (Reality Check)

Command: sync --last 1d --dry-run

Purpose: Understand what actually got done yesterday vs what was planned.

What to look for:

• Tasks completed but not documented
• Work in progress status
• Any drift between plan and reality

Output: Sync report showing yesterday's actual progress

---

Step 2: Status (Health Check)

Command: status --brief --sprint

Purpose: Quick sprint health overview.

What to look for:

• Sprint progress percentage
• Any critical blockers
• Risk indicators
• Velocity trend

Output: 1-2 paragraph status summary

---

Step 3: Groom (Ready Queue)

Command: groom --ready-only

Purpose: See what's immediately actionable.

What to look for:

• Tasks ready for implementation
• Priority ordering
• Any quick wins
• Blocked tasks that might unblock soon

Output: List of ready tasks with priorities

---

Morning Output

After morning sequence, you should know:

• What was actually accomplished yesterday
• Current sprint health status
• What tasks are ready to work on today
• Any blockers to address

Recommended next step: Start task cycle with highest priority ready task

---

Evening Wrap-up (~10 minutes)

EVENING SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ checklist             │ ─── Is anything important about to be lost?
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ discovery             │ ─── Capture any learnings from today
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ sync --last 1d        │ ─── Update task statuses
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Day Complete Summary"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Checklist (Work Preservation)

Command: checklist

Purpose: Ensure nothing important is lost before ending the day.

What to check:

• Uncommitted changes that should be committed
• Notes that should be documented
• Decisions that need recording
• Work in progress that needs handoff notes

Output: Checklist of items to address

---

Step 2: Discovery (Knowledge Capture)

Command: discovery

Purpose: Document any insights or learnings from the day.

What to capture:

• "Aha moments" about the codebase
• Location discoveries (where things are)
• Pattern recognitions
• Assumption corrections

Output: Discovery records created

---

Step 3: Sync (Status Update)

Command: sync --last 1d

Purpose: Update task statuses to reflect actual work done.

What to update:

• Mark completed work as done
• Update in-progress estimates
• Document any partial completions
• Note blockers encountered

Output: Updated context network reflecting reality

---

Evening Output

After evening sequence, you should have:

• No lost work or uncommitted important changes
• Today's learnings captured in discovery records
• Task statuses reflecting actual progress
• Clear state for tomorrow's morning standup

---

Quick Reference Commands

# Full morning sequence
/agile-workflow --phase daily-morning

# Full evening sequence
/agile-workflow --phase daily-evening

# Individual commands
sync --last 1d --dry-run
status --brief --sprint
groom --ready-only
checklist
discovery
sync --last 1d

Cadence Recommendations

Morning is critical because it prevents duplicate work and ensures you're working on the right things.

Evening is recommended because knowledge capture is most effective when context is fresh.

Integration with Task Cycle

Daily sequences wrap around task cycles:

┌─────────────────────────────────────────────────┐
│               WORK DAY                          │
├─────────────────────────────────────────────────┤
│                                                 │
│  Morning Standup                                │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────────────────────────┐   │
│  │  Task Cycle 1                           │   │
│  │  (implement → review → PR)              │   │
│  └─────────────────────────────────────────┘   │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────────────────────────┐   │
│  │  Task Cycle 2 (optional)                │   │
│  │  (smaller task or continuation)         │   │
│  └─────────────────────────────────────────┘   │
│       │                                         │
│       ▼                                         │
│  Evening Wrap-up                                │
│                                                 │
└─────────────────────────────────────────────────┘

Sprint Phase Reference

Sprint boundary ceremonies: start and end sequences.

Overview

Sprint sequences ensure proper planning at the start and thorough closure at the end of each sprint.

Sprint Start (~60 minutes)

SPRINT START SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --all            │ ─── Full reality alignment
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ groom --all           │ ─── Comprehensive grooming
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ plan sprint-goals     │ ─── Define sprint objectives
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --detailed     │ ─── Establish baseline
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Sprint Plan Ready"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Full Sync

Command: sync --all

Purpose: Complete alignment between documentation and reality.

Actions:

• Review all in-progress work
• Identify any undocumented completions
• Clear out stale status entries
• Ensure backlog reflects truth

Duration: ~15 minutes

---

Step 2: Comprehensive Grooming

Command: groom --all

Purpose: Prepare all tasks for the sprint.

Actions:

• Review entire backlog
• Refine vague tasks into actionable items
• Add acceptance criteria
• Estimate complexity
• Identify dependencies
• Move tasks to ready status

Duration: ~25 minutes

---

Step 3: Sprint Planning

Command: plan sprint-goals

Purpose: Define what the sprint will accomplish.

Actions:

• Set sprint objective
• Select tasks for sprint
• Identify architecture needs
• Note dependencies and risks
• Create sprint plan document

Duration: ~15 minutes

---

Step 4: Baseline Status

Command: status --detailed

Purpose: Establish metrics baseline for sprint.

Actions:

• Document starting velocity
• Note current tech debt
• Record test coverage
• Capture documentation state

Duration: ~5 minutes

---

Sprint Start Output

After sprint start, you should have:

• Clean, aligned backlog
• Groomed, ready tasks
• Clear sprint objective
• Baseline metrics for comparison
• Sprint plan document

---

Sprint End (~90 minutes)

SPRINT END SEQUENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  START
    │
    ▼
┌───────────────────────┐
│ sync --sprint         │ ─── Final sprint sync
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ retrospective         │ ─── Capture learnings
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ audit --scope sprint  │ ─── Quality review
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ status --metrics      │ ─── Sprint metrics
│ --detailed            │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ maintenance --deep    │ ─── Context network cleanup
└───────────┬───────────┘
            │
            ▼
         OUTPUT
   "Sprint Closed"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1: Final Sync

Command: sync --sprint

Purpose: Ensure all sprint work is documented.

Actions:

• Verify all completed tasks are marked done
• Identify any work that spilled over
• Update carryover items
• Clean up in-progress that finished

Duration: ~10 minutes

---

Step 2: Retrospective

Command: retrospective

Purpose: Capture sprint learnings.

Actions:

• Review accomplishments
• Document decisions made
• Capture discoveries
• Identify process improvements
• Update context network with insights
• Create retrospective record

Duration: ~25 minutes

---

Step 3: Quality Audit

Command: audit --scope sprint

Purpose: Review sprint's code quality.

Actions:

• Review all code added during sprint
• Identify quality issues
• Document technical debt added
• Note patterns (good and bad)
• Generate audit report

Duration: ~20 minutes

---

Step 4: Sprint Metrics

Command: status --metrics --detailed

Purpose: Capture sprint performance.

Actions:

• Calculate velocity (tasks/points completed)
• Compare to baseline
• Document coverage changes
• Note debt trends
• Record accomplishments

Duration: ~10 minutes

---

Step 5: Deep Maintenance

Command: maintenance --deep

Purpose: Between-sprint cleanup.

Actions:

• Audit context network structure
• Fix broken links
• Update stale content
• Archive completed work
• Improve navigation
• Clean up temporary files

Duration: ~25 minutes

---

Sprint End Output

After sprint end, you should have:

• All sprint work documented
• Learnings captured in retrospective
• Quality assessment on record
• Sprint metrics documented
• Clean context network for next sprint

---

Quick Reference Commands

# Sprint start sequence
/agile-workflow --phase sprint-start

# Sprint end sequence
/agile-workflow --phase sprint-end

# Individual commands
sync --all
groom --all
plan sprint-goals
status --detailed
sync --sprint
retrospective
audit --scope sprint
status --metrics --detailed
maintenance --deep

Cadence Recommendations

Both ceremonies are critical for maintaining:

• Clean handoffs between sprints
• Captured institutional knowledge
• Accurate velocity tracking
• Healthy context network

Sprint Rhythm

┌─────────────────────────────────────────────────────────┐
│                    SPRINT (2 weeks)                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Sprint Start (Day 1)                                   │
│       │                                                 │
│       ▼                                                 │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Week 1                                           │ │
│  │  ├── Daily Morning Standup                        │ │
│  │  ├── Task Cycles (implementation)                 │ │
│  │  └── Daily Evening Wrap-up                        │ │
│  └───────────────────────────────────────────────────┘ │
│       │                                                 │
│       ▼                                                 │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Week 2                                           │ │
│  │  ├── Daily Morning Standup                        │ │
│  │  ├── Task Cycles (implementation)                 │ │
│  │  └── Daily Evening Wrap-up                        │ │
│  └───────────────────────────────────────────────────┘ │
│       │                                                 │
│       ▼                                                 │
│  Sprint End (Last Day)                                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Integration Notes

Sprint ceremonies nest around daily and task cycles:

• Sprint Start prepares the backlog for daily work
• Daily sequences maintain rhythm within the sprint
• Task cycles are the actual implementation work
• Sprint End closes out and prepares for next iteration

State Detection Reference

Algorithms for detecting current workflow state in Gitea repositories.

Overview

The gitea-workflow skill determines current state automatically by examining multiple signals from the project environment. This enables seamless resume from any point.

Detection Signals

1. Worktree Presence

Command: git worktree list

Interpretation:

/path/to/repo                  abc1234 [main]
/path/to/repo/.worktrees/TASK-042  def5678 [task/TASK-042-feature]

2. Current Branch

Command: git branch --show-current

Interpretation:

3. Git Status

Command: git status --porcelain

Interpretation:

4. PR Status (Gitea)

Commands:

# Check if PR exists for current branch
tea pulls list --state open | grep $(git branch --show-current)

# Get PR details if exists
tea pulls

Via API Script (for more detailed info):

# Check CI status
./scripts/gitea-ci-status.sh <owner> <repo> <commit-sha>

# Check PR reviews
./scripts/gitea-pr-checks.sh <owner> <repo> <pr-number>

Interpretation:

5. Task Status Files

Location: context-network/backlog/by-status/

Files:

• ready.md - Tasks available to start
• in-progress.md - Tasks being worked on
• in-review.md - Tasks with open PRs
• completed.md - Finished tasks

Check: Look for current task ID in these files.

State Matrix

COMBINED STATE DETECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Worktree   Branch      Git Status   PR State    → Workflow State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

None       main        clean        N/A         → IDLE
                                                  Ready to start

Exists     task/*      dirty        None        → IMPLEMENTING
                                                  Active coding

Exists     task/*      clean        None        → READY_FOR_REVIEW
                                                  Can run reviews

Exists     task/*      clean        Open/Run    → AWAITING_CI
                                                  Wait for checks

Exists     task/*      clean        Open/Pass   → READY_FOR_MERGE
                                                  Can merge PR

Exists     task/*      any          Merged      → CLEANUP_NEEDED
                                                  Run pr-complete

None       main        clean        N/A         → COMPLETED
                                                  (with recent merge)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Detection Algorithm

function detectState():
  # Step 1: Check worktrees
  worktrees = gitWorktreeList()

  if no task worktree exists:
    return IDLE

  # Step 2: Extract task info
  taskId = extractTaskId(worktree.path)
  branch = worktree.branch

  # Step 3: Navigate to worktree
  cd worktree.path

  # Step 4: Check git status
  status = gitStatus()
  hasUncommitted = status.isNotEmpty()

  if hasUncommitted:
    return IMPLEMENTING

  # Step 5: Check PR status via tea CLI
  prInfo = teaPullsList(branch)

  if no PR exists:
    return READY_FOR_REVIEW

  if prInfo.merged:
    return CLEANUP_NEEDED

  # Step 6: Check CI status via API script (Gitea uses external CI)
  ciStatus = checkCIStatus(prInfo.headCommit)

  if ciStatus == "pending":
    return AWAITING_CI

  if ciStatus == "success" and prInfo.approved:
    return READY_FOR_MERGE

  if ciStatus == "success":
    return AWAITING_APPROVAL

  if ciStatus == "failure":
    return CI_FAILED

  return IN_REVIEW

State to Action Mapping

Edge Cases

Multiple Worktrees

If multiple task worktrees exist: 1. Check which has most recent commits 2. Check which matches in-progress status 3. Ask user to disambiguate if unclear

Stale Worktree

Worktree exists but task marked complete: 1. PR was merged outside workflow 2. Clean up worktree 3. Return to IDLE

Branch Without Worktree

Task branch exists on remote but no local worktree: 1. Task was started on different machine 2. Offer to create worktree from branch 3. Or start fresh

PR Closed Without Merge

PR exists but was closed (not merged): 1. Task may have been abandoned 2. Check task status file 3. Offer to reopen or start fresh

Resumption Context

When resuming from detected state, gather context:

CONTEXT FOR RESUME
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

State: [detected state]
Task: [TASK-ID] - [Title]
Branch: [branch name]
Worktree: [path]

Progress:
- Files changed: [count]
- Tests: [passing/failing/none]
- Last commit: [message] ([time ago])

PR Status: [if exists]
- Number: #[number]
- CI: [status - check via API or manually]
- Reviews: [count]

Recommended Action: [what to do next]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Verification Commands

Quick commands to check state:

# Check worktrees
git worktree list

# Check current branch
git branch --show-current

# Check for uncommitted changes
git status --short

# Check PR status (Gitea)
tea pulls list --state open

# Check task status files
cat context-network/backlog/by-status/in-progress.md

Gitea-Specific Notes

CI Status

Gitea uses external CI systems. To check CI status:

1. Via API Script:

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

2. Manually: Check your CI dashboard (Drone, Woodpecker, Jenkins, etc.)

3. Via Gitea API (if commit statuses are posted):

   curl -H "Authorization: token $GITEA_TOKEN" \
     "$GITEA_URL/api/v1/repos/owner/repo/commits/SHA/statuses"

PR Approval Status

Check if PR has required approvals:

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

Or via tea CLI:

tea pulls  # Shows current PR details including reviews