130 lines
4.8 KiB
Markdown
130 lines
4.8 KiB
Markdown
# 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 |