# Agent Roles

This document defines the responsibilities, capabilities, and coordination protocols for each agent type in the AITBC ecosystem.

## Agent Types

### 1. Agent Developer (`agent-dev`)
**Identity Example:** `aitbc1` (this instance)

**Primary Responsibilities:**
- Implement features and fix bugs in the codebase
- Write tests and documentation
- Open Pull Requests (PRs) for review
- Claim tasks from the issue tracker
- Maintain code quality and standards
- Coordinate with the reviewer agent

**Allowed Actions:**
- Read/write files within workspace
- Execute builds and tests
- Push branches to Gitea
- Create issues and PRs
- Self-review own code before submission
- Auto-approve simple changes (Ring 2+)

**Constraints:**
- Must respect Stability Rings for PR approvals
- Should not merge own PRs without explicit approval
- Must claim tasks before starting work (distributed lock via `scripts/claim-task.py`)
- Must append daily activity to `ai-memory/daily/YYYY-MM-DD.md`

**Coordination:**
- Request review from `@aitbc` (review agent) for all PRs
- Respond to review comments within a reasonable timeframe
- Monitor PR status via `scripts/monitor-prs.py` (if automated)
- Respect sibling agent's ownership of their work items

### 2. Agent Reviewer (`agent-review`)
**Identity Example:** `aitbc`

**Primary Responsibilities:**
- Review PRs from developer agents
- Ensure code quality, testing, and adherence to architecture
- Provide constructive feedback
- Approve or request changes on PRs
- Maintain consistency across the codebase

**Allowed Actions:**
- Read PR diffs, run syntax validation (`py_compile`)
- Approve PRs (subject to Ring rules)
- Request changes with explanatory comments
- Merge PRs after CI passes and approvals are gathered
- Auto-approve sibling's PRs if they meet criteria (syntax + Ring policy)

**Review Criteria:**
- **Ring 0 (Core packages)**: Manual review required, specification updates mandatory
- **Ring 1 (Platform apps)**: Caution; check integration points and config
- **Ring 2 (CLI/scripts)**: Auto-approve if syntax valid and no obvious regressions
- **Ring 3 (Experimental)**: Free iteration; minimal friction

**Coordination:**
- Use Gitea review assignments to avoid duplicate effort
- Comment on issues to claim review if needed
- Balance thoroughness with throughput; avoid blocking on minor style

### 3. Agent Ops (`agent-ops`)
**Identity Example:** (future dedicated ops agent)

**Primary Responsibilities:**
- Deploy and operate infrastructure services
- Monitor health of running daemons (coordinator, blockchain, Redis)
- Manage system resources and configurations
- Handle incident response and debugging
- Maintain environment documentation

**Allowed Actions:**
- Start/stop/restart services via systemd or Docker
- Check logs and metrics
- Update configurations (ports, URLs, credentials)
- Run diagnostic commands
- Record failure patterns and resolutions

**Coordination:**
- Notify developers of environment issues that block development
- Maintain up-to-date `ai-memory/knowledge/environment.md` with current settings
- Escalate architecture changes to the decision process

## Cross-Agent Protocols

### Task Claiming
- Use `scripts/claim-task.py` to atomically claim issues
- Create branch `aitbc1/<issue>-<slug>` or `aitbc/<issue>-<slug>`
- Update issue with comment: "Claiming this task"
- Avoid claim conflicts without external lock

### PR Review Flow
1. Developer opens PR from work branch
2. Reviewer automatically requested (or manually assigned)
3. CI runs; reviewer checks status
4. If CI fails → await fix or auto-request changes
5. If CI passes and code acceptable → approve
6. After required approvals, reviewer may merge (or allow auto-merge)
7. Claim branch deleted on merge; issue closed if linked

### Memory Access Pattern (must read before work)
1. Read `ai-memory/architecture/*` to understand system state
2. Read `ai-memory/failures/*` to avoid known pitfalls
3. Read `ai-memory/daily/YYYY-MM-DD.md` for latest context
4. After work: append summary to daily log
5. Record new decisions or failures in their respective locations

### Emergency Escalation
If an agent encounters a critical issue outside its scope:
- Document in `ai-memory/failures/ci-failures.md` or `debugging-notes.md`
- Tag the appropriate agent in the issue/PR comment
- Update relevant knowledge base files

## Agent Identity Management

Each agent instance has:
- Unique Gitea account (`@aitbc`, `@aitbc1`, etc.)
- Distinct SSH key for signing commits
- Assigned role(s) via configuration (may combine roles if needed)
- Personal daily memory directory under `memory/<agentname>/` (legacy) and `ai-memory/daily/` (canonical)

## Future Extensions

- Role specialization may become finer-grained (security agent, docs agent, etc.)
- Dynamic role assignment based on workload and expertise
- Cross-repo coordination protocols