generated from coulomb/repo-seed
feat: transform to agent coordination platform with comprehensive documentation
Transform Issue Facade from a universal CLI tool into an agent coordination platform with comprehensive documentation and enhanced capabilities for autonomous coding agents. Major Changes: - Complete README rewrite focusing on agent-driven coordination - New comprehensive documentation (AGENT_INTEGRATION.md, CLAUDE.md, ROADMAP.md) - Capability integration setup with CAPABILITY.yaml and integration scripts - Enhanced Makefile with local development targets for easier workflows Bug Fixes: - Fix schema initialization using executescript() for multi-line SQL support - Disable FTS5 triggers due to compatibility issues (documented for future re-enablement) Features: - Enhanced CLI list command with full parameter passthrough - New examples directory with agent integration patterns - New comprehensive test suite (test_core_models.py, test_local_backend.py) Code Quality: - Remove @cached_property decorators for Label properties (simplification) - Clean up test organization (removed old test_gitea_integration.py) This milestone establishes Issue Facade as a production-ready coordination layer for multi-agent software development, with clear integration paths and comprehensive developer documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
252
examples/agents/README.md
Normal file
252
examples/agents/README.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user