ClearGrow Agent Runner

Automated task orchestration system that monitors YouTrack issues and coordinates Claude Code agents to resolve them across Gitea repositories, with Woodpecker CI verification.

Overview

The Agent Runner automates the software development workflow:

Ready → In Progress → Build → Verify → Document → Review → Done
         (Developer)   (CI)    (QA)      (Librarian)
              ↑          │        ↓
              └──────────┘    Merge to main
            (on build failure)

Components

File	Purpose
runner.py	Main orchestration engine
agent.py	Claude Code subprocess pool management
youtrack_client.py	YouTrack API wrapper
gitea_client.py	Gitea API wrapper + git CLI operations
woodpecker_client.py	Woodpecker CI build monitoring
webhook_server.py	HTTP webhook receiver for real-time events
prompts/	Prompt templates for Claude agents

Agent Types

Agent	Token	Purpose
Developer	agent_tokens.developer	Code remediation and bug fixes
QA	agent_tokens.qa	Code verification and review
Librarian	agent_tokens.librarian	Documentation updates
Build	agent_tokens.build	CI build status comments

Configuration

Copy the example config and fill in your credentials:

cp config.yaml.example config.yaml
chmod 600 config.yaml

Required configuration:

• youtrack.base_url and youtrack.token
• gitea.base_url and gitea.token
• woodpecker.base_url and woodpecker.token
• agent_tokens.* for each agent type
• repos.* mapping repositories to local paths

Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure
cp config.yaml.example config.yaml
vim config.yaml

# Run
python runner.py -c config.yaml

Systemd Service

sudo cp cleargrow-agent-runner.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable cleargrow-agent-runner
sudo systemctl start cleargrow-agent-runner

Workflow

1. Ready: Issue waiting for remediation
2. In Progress: Developer agent working on fix
3. Build: Woodpecker CI building feature branch
4. Verify: QA agent reviewing changes → merges to main on success
5. Document: Librarian agent updating docs
6. Review: Human review (manual)
7. Done: Complete

Branch Convention

Feature branches follow the pattern: issue/{ISSUE_ID}

Example: Issue CG-47 → branch issue/CG-47

API Integrations

• YouTrack: Issue tracking and state management
• Gitea: Repository hosting and git operations
• Woodpecker CI: Automated builds on push

License

Proprietary - ClearGrow