feat: implement structured agent memory architecture

ai-memory/architecture/agent-roles.md

@@ -0,0 +1,130 @@
+# 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