issue-core/examples/agents/README.md

# Agent Examples

This directory contains working examples of autonomous agents using the Issue Facade for coordination.

## Prerequisites

1. **Install issue-facade**:
   ```bash
   cd ../..
   pip install -e .
   ```

2. **Configure backend** (one-time setup):
   ```bash
   export GITEA_API_TOKEN="your-token"
   issue backend add myproject gitea
   # Enter: URL, owner, repo when prompted
   issue backend set-default myproject
   ```

3. **Set environment variables** for scripts:
   ```bash
   export GITEA_URL=https://gitea.example.com
   export GITEA_TOKEN=your-token
   export GITEA_OWNER=your-org
   export GITEA_REPO=your-repo
   ```

## Examples

### 1. Simple Task Executor (`simple_task_executor.py`)

**What it does:**
- Finds open issues labeled `ready`
- Claims them by assigning to itself
- Simulates work
- Closes with completion comment

**Usage:**
```bash
# Run once
python simple_task_executor.py --once

# Run continuously
python simple_task_executor.py

# Run for N iterations
python simple_task_executor.py --max-iterations 5
```

**Setup test data:**
```bash
# Create some test issues
issue create "Test task 1" --label=ready
issue create "Test task 2" --label=ready
issue create "Test task 3" --label=ready
```

### 2. Multi-Agent Pipeline (`multi_agent_pipeline.py`)

**What it does:**
Simulates a CI/CD pipeline with specialized agents:
- **Coder**: Implements features (needs-implementation → needs-review)
- **Reviewer**: Reviews code (needs-review → needs-testing)
- **Tester**: Runs tests (needs-testing → needs-deployment)
- **Deployer**: Deploys to staging (needs-deployment → deployed + closed)

**Usage:**
```bash
# Run all agents in round-robin (one process)
python multi_agent_pipeline.py --mode=roundrobin

# Or run each agent separately (in different terminals)
python multi_agent_pipeline.py --agent=coder
python multi_agent_pipeline.py --agent=reviewer
python multi_agent_pipeline.py --agent=tester
python multi_agent_pipeline.py --agent=deployer
```

**Setup test data:**
```bash
issue create "Feature: Add user profile" --label=feature --label=needs-implementation
issue create "Feature: Export data to CSV" --label=feature --label=needs-implementation
```

**Watch the pipeline:**
```bash
# In another terminal, watch progress
watch -n 2 'issue list --format=json | jq -r ".[] | [.number, .state, (.labels | map(.name) | join(\",\"))] | @tsv"'
```

### 3. Human-in-the-Loop (`human_in_loop.py`)

**What it does:**
- Finds large features labeled `needs-breakdown`
- Proposes breaking them into subtasks
- Waits for human approval via comments
- Creates subtasks only after approval

**Usage:**
```bash
# Run once
python human_in_loop.py --once

# Run continuously
python human_in_loop.py
```

**Setup test data:**
```bash
issue create "Feature: Implement complete authentication system" \
  --label=feature \
  --label=needs-breakdown \
  --description="Large feature that should be broken down into smaller tasks"
```

**Approve the agent's proposal:**
```bash
# Agent will post a proposal comment. You reply with:
issue comment <issue-number> "APPROVED"

# Or reject:
issue comment <issue-number> "REJECTED: Not the right approach"

# Or request modifications:
issue comment <issue-number> "MODIFY: Please add security audit as a subtask"
```

### 4. Monitoring Agent (`monitoring_agent.py`)

**What it does:**
- Monitors issue tracker health
- Detects stale issues (not updated in N days)
- Finds blocked issues
- Identifies unassigned priority issues
- Analyzes project velocity
- Creates alert issues when problems found

**Usage:**
```bash
# Run once (no alerts)
python monitoring_agent.py --once --no-alerts

# Run continuously with hourly checks
python monitoring_agent.py --check-interval=3600

# Run with custom stale threshold
python monitoring_agent.py --stale-days=14 --once
```

**View monitoring output:**
The agent will create issues tagged with `monitoring` and `alert` when it detects problems.

## Agent Coordination Patterns

### Pattern 1: Label-Based Roles

Agents claim issues based on label matching:

```python
AGENT_ROLES = {
    'agent:coder': ['feature', 'bug', 'refactor'],
    'agent:tester': ['needs-testing', 'test-failure'],
    'agent:reviewer': ['needs-review']
}

issues = backend.list_issues(IssueFilter(
    state='open',
    labels=[agent_type, 'feature']
))
```

### Pattern 2: State Machine

Issues flow through states:

```
open → in_progress → needs_review → closed
  ↓         ↓             ↓
blocked   blocked      blocked
```

### Pattern 3: Comment-Based Communication

Agents communicate via structured comments:

```python
# Agent posts JSON in comment
comment.body = "```agent-message\n" + json.dumps({
    'type': 'implementation_complete',
    'agent': 'agent-coder',
    'data': {'files_changed': ['auth.py'], 'tests_passing': True}
}) + "\n```"

# Other agents parse it
for comment in comments:
    if '```agent-message' in comment.body:
        msg = json.loads(extract_json(comment.body))
        if msg['type'] == 'implementation_complete':
            # React to completion
```

## Troubleshooting

### "Backend not configured"
```bash
issue backend list
# If empty:
issue backend add myproject gitea
```

### "Authentication failed"
```bash
# Check token is valid
curl -H "Authorization: token $GITEA_TOKEN" $GITEA_URL/api/v1/user
```

### "No issues found"
```bash
# Verify you have issues
issue list

# Create test data
issue create "Test" --label=ready
```

### Agent stuck/not processing
```bash
# Check what agent sees
issue list --state=open --label=needs-implementation --format=json

# Verify labels match what agent expects
issue show 42 --format=json | jq '.labels'
```

## Tips for Development

1. **Use `--once` flag during development** to run single iterations
2. **Use `--no-alerts` for monitoring agent** to avoid cluttering tracker
3. **Run agents in separate terminals** to see concurrent execution
4. **Use JSON format** for debugging: `issue list --format=json | jq`
5. **Clean up test data**: `issue list --label=agent-generated --format=json | jq -r '.[].number' | xargs -I {} issue close {}`

## Next Steps

- Modify these examples for your use case
- Add error handling and retry logic
- Implement actual work instead of `time.sleep()`
- Add logging and metrics
- Deploy as services with proper process management

See [AGENT_INTEGRATION.md](../../AGENT_INTEGRATION.md) for more patterns and strategies.