stack/scripts/coordinator/README.md

Coordinator Scripts

Utility scripts for setting up and managing the autonomous coordinator system in Mosaic Stack.

Overview

The coordinator system automates issue assignment, tracking, and orchestration across AI agents. These scripts help with setup, configuration, and testing.

Scripts

Python Modules

issue_estimator.py

Formula-based context estimator for predicting token usage before issue assignment.

Prerequisites:

• Python 3.8+
• Virtual environment with dependencies (see Installation below)

Usage:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run examples
python issue_estimator.py

# Run tests
pytest test_issue_estimator.py -v

# Run with coverage
pytest test_issue_estimator.py --cov=issue_estimator --cov=models --cov-report=term-missing

Python API:

from issue_estimator import estimate_issue

# Quick estimation
result = estimate_issue(
    files=2,
    complexity="medium",
    tests="medium",
    docs="light"
)

print(f"Total estimate: {result.total_estimate:,} tokens")
print(f"Recommended agent: {result.recommended_agent}")

Documentation: See ESTIMATOR.md for complete API reference and examples.

Bash Scripts

create-gitea-bot.sh

Creates the mosaic bot user in Gitea for coordinator automation.

Prerequisites:

• Gitea admin access
• Admin API token with sufficient permissions

Usage:

# Set admin token and run
export ADMIN_TOKEN="your-gitea-admin-token"
./scripts/coordinator/create-gitea-bot.sh

# Or specify variables
ADMIN_TOKEN="token" GITEA_URL="https://gitea.example.com" \
  ./scripts/coordinator/create-gitea-bot.sh

What it does:

1. Creates mosaic bot user account
2. Sets up email: mosaic@mosaicstack.dev
3. Adds bot to mosaic/stack repository as collaborator
4. Generates API token for coordinator use
5. Tests bot authentication
6. Displays credentials for secure storage

Output: The script provides the API token and password that must be stored in your secrets vault or .env file.

test-gitea-bot.sh

Tests bot functionality and verifies all necessary permissions.

Prerequisites:

• Bot user created (run create-gitea-bot.sh first)
• GITEA_BOT_TOKEN in environment or .env file

Usage:

# Run tests with token from .env
./scripts/coordinator/test-gitea-bot.sh

# Or specify token explicitly
export GITEA_BOT_TOKEN="your-bot-token"
./scripts/coordinator/test-gitea-bot.sh

# Test against specific issue
export TEST_ISSUE="156"
./scripts/coordinator/test-gitea-bot.sh

Tests performed:

1. Bot authentication
2. Repository access
3. Issue listing
4. Issue reading
5. Issue assignment
6. Comment posting
7. Label management
8. Repository permissions

Output: Success/failure for each test with detailed error messages.

Installation

Python Environment

For the context estimator and Python-based coordinator components:

# Navigate to coordinator directory
cd scripts/coordinator

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
pytest test_issue_estimator.py -v

Bash Scripts

No installation needed for bash scripts. Just ensure they're executable:

chmod +x scripts/coordinator/*.sh

Configuration

Environment Variables

All scripts support these environment variables:

# Gitea connection
GITEA_URL                # Default: https://git.mosaicstack.dev
ADMIN_TOKEN              # Gitea admin token (required for create-gitea-bot.sh)

# Bot credentials
GITEA_BOT_TOKEN          # Bot API token (required for test-gitea-bot.sh)
GITEA_BOT_USERNAME       # Default: mosaic
GITEA_BOT_PASSWORD       # For reference only

# Repository
GITEA_REPO_OWNER         # Default: mosaic
GITEA_REPO_NAME          # Default: stack

# Testing
TEST_ISSUE               # Issue number for testing (default: 156)

.env File

Create or update .env file in project root:

# Gitea Configuration
GITEA_URL=https://git.mosaicstack.dev
GITEA_BOT_USERNAME=mosaic
GITEA_BOT_TOKEN=your-bot-token-here
GITEA_BOT_PASSWORD=your-bot-password-here
GITEA_REPO_OWNER=mosaic
GITEA_REPO_NAME=stack

Security: Never commit .env to version control. Add .env to .gitignore.

Workflow

Initial Setup

# 1. Create bot user (requires admin token)
export ADMIN_TOKEN="your-admin-gitea-token"
./scripts/coordinator/create-gitea-bot.sh

# Output will show:
# - Bot username (mosaic)
# - Bot password (save securely)
# - API token (save securely)
# - Instructions for next steps

# 2. Store credentials securely
# - Add GITEA_BOT_TOKEN to .env (don't commit)
# - Add GITEA_BOT_TOKEN to your secrets vault
# - Add GITEA_BOT_PASSWORD to your secrets vault

# 3. Update .env.example (no secrets)
# - Add template entries with placeholder values

# 4. Test bot functionality
./scripts/coordinator/test-gitea-bot.sh

Daily Use

# Run tests to verify bot is working
./scripts/coordinator/test-gitea-bot.sh

# If tests fail:
# - Check GITEA_BOT_TOKEN is valid
# - Check token hasn't expired
# - Verify bot user still exists in Gitea
# - If needed, regenerate token (see docs)

Token Rotation

When rotating the bot API token:

# 1. Generate new token in Gitea UI
#    Settings → Applications → Create new token

# 2. Update .env
export GITEA_BOT_TOKEN="new-token"

# 3. Test new token
./scripts/coordinator/test-gitea-bot.sh

# 4. Update secrets vault
# 5. Delete old token in Gitea UI

Troubleshooting

"ADMIN_TOKEN environment variable not set"

The create-gitea-bot.sh script requires a Gitea admin token.

Solution:

1. Log in to Gitea as admin
2. Go to Settings → Access Tokens
3. Create new token with api scope
4. Export and run: ADMIN_TOKEN="token" ./scripts/coordinator/create-gitea-bot.sh

"Cannot connect to Gitea"

Script can't reach the Gitea instance.

Solution:

# Verify GITEA_URL is correct
echo $GITEA_URL

# Check connectivity
curl -s https://git.mosaicstack.dev/api/v1/version | jq .

# If still failing, check:
# - Network connectivity to Gitea server
# - Firewall rules
# - VPN/proxy configuration

"Authentication failed"

Bot API token is invalid or expired.

Solution:

1. Check token in .env is correct (no extra spaces)
2. Verify token hasn't expired (90 day default)
3. Regenerate token if needed:
   • Log in as mosaic user
   • Settings → Applications → Delete old token
   • Create new token
   • Update .env and secrets vault

"Bot user already exists"

The bot user was already created.

Solution:

• Continue setup with existing user
• Verify credentials are correct
• Run tests to confirm functionality

"Permission denied" on operations

Bot doesn't have required permissions.

Solution:

1. Verify bot is added as repository collaborator
2. Check permission level (should be "push" or "admin")
3. Re-add if needed via API:

curl -X PUT \
  -H "Authorization: token $ADMIN_TOKEN" \
  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/collaborators/mosaic" \
  -d '{"permission":"push"}'

Documentation

For complete documentation on the coordinator bot:

• Gitea Coordinator Setup Guide
• Issue #156 - Create coordinator bot user
• Coordinator Architecture

Files

File	Purpose
issue_estimator.py	Context estimator implementation
models.py	Data models and enums for estimator
test_issue_estimator.py	Test suite (35 tests, 100% coverage)
ESTIMATOR.md	Complete estimator documentation
requirements.txt	Python dependencies
.coveragerc	Coverage configuration
create-gitea-bot.sh	Bot user creation script
test-gitea-bot.sh	Bot functionality tests
README.md	This file

Related Issues

• #154 - Implement context estimator ✅ COMPLETED
• #156 - Create coordinator bot user in Gitea ✅ COMPLETED
• #157 - Configure coordinator webhook in Gitea
• #158 - Implement coordinator task assignment engine
• #140 - Coordinator integration architecture

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the full documentation
3. Open an issue in the repository