# Protocol Decisions This document records decisions about agent coordination protocols, communication standards, and operational procedures. --- ## Decision 1: Memory Access Protocol **Date**: 2026-03-15 **Protocol**: Before any task, agents must read: 1. `ai-memory/architecture/system-overview.md` 2. `ai-memory/failures/debugging-notes.md` (or relevant failure logs) 3. `ai-memory/daily/YYYY-MM-DD.md` (today's entry; if none, create it) After completing a task, agents must: - Append a concise summary to `ai-memory/daily/YYYY-MM-DD.md` - Use a new bullet point with timestamp or section as needed **Rationale**: Ensures agents operate with current context and avoid repeating mistakes. Creates a persistent, searchable audit trail. --- ## Decision 2: Failure Recording Protocol **Date**: 2026-03-15 **Protocol**: When an agent discovers a new failure pattern (bug, misconfiguration, CI break): 1. Append to `ai-memory/failures/failure-archive.md` in the format: ``` ## Failure: [Short title] – [Date] - **Symptom**: ... - **Cause**: ... - **Resolution**: ... ``` 2. If the failure is CI-specific, also append to `ci-failures.md` 3. If the failure involves debugging steps, also append to `debugging-notes.md` **Rationale**: Centralizes troubleshooting knowledge; agents can proactively consult before debugging similar issues. --- ## Decision 3: Decision Logging Protocol **Date**: 2026-03-15 **Protocol**: When an agent makes an architectural decision (affecting system structure, APIs, dependencies): 1. Record in `ai-memory/decisions/architectural-decisions.md` using the ADR format (Decision, Date, Context, Alternatives, Reason, Impact) 2. Keep entries concise but complete enough for future readers **Rationale**: Prevents re-debating settled questions; preserves reasoning for new agents. --- ## Decision 4: Task Claiming Protocol (Distributed Lock) **Date**: 2026-03-15 **Protocol**: - Issues must have label `task`, `bug`, `feature`, or `good-first-task-for-agent` to be claimable. - Agent runs `scripts/claim-task.py` periodically (cron every 5 minutes). - Script: 1. Fetches open, unassigned issues with eligible labels. 2. Skips issues already associated with the agent's branch or claimed by another agent. 3. Picks highest-scoring issue (simple scoring: label priority + age). 4. Creates an atomic Git branch: `aitbc1/-`. 5. If branch creation succeeds, posts comment on issue: "Claiming this task (branch: ...)" 6. Works on the issue in that branch. - Claim is released when the branch is deleted (PR merged or closed). **Rationale**: Uses Git's atomic branch creation as a distributed mutex. No central coordinator needed; agents can run independently. --- ## Decision 5: PR Review Protocol **Date**: 2026-03-15 **Protocol**: - All PRs must request review from `@aitbc` (the reviewer agent). - Reviewer runs `scripts/monitor-prs.py` every 10 minutes (cron). - For **sibling PRs** (author ≠ self): - Fetch branch, run `py_compile` on changed Python files. - If syntax fails: request changes with comment "Syntax error detected." - If syntax passes: - Check Stability Ring of modified paths. - Ring 0: cannot auto-approve; manual review required (request changes or comment) - Ring 1: auto-approve with caution (approve + comment "Auto-approved Ring 1") - Ring 2: auto-approve (approve) - Ring 3: auto-approve (approve) - For **own PRs**: script auto-requests review from `@aitbc`. - CI status is monitored; failing CI triggers comment "CI failed; please fix." - After approvals and CI pass, reviewer may merge (or allow auto-merge if configured). - On merge: delete the claim branch; close linked issues. **Rationale**: Automates routine reviews while preserving human attention for critical areas. Enforces Ring policy consistently. --- ## Decision 6: Memory File Naming and Format **Date**: 2026-03-15 **Protocol**: - Daily memory: `ai-memory/daily/YYYY-MM-DD.md` (one file per day, Markdown) - Append-only: never edit or delete past entries; only add new bullets at the end. - Timestamps optional but helpful: use headings like `## 15:00–15:59 UTC Update` or bullet with time. - Each entry should be concise but informative: what was done, what was learned, any blockers. - Today's file must exist when needed; create it if absent. **Rationale**: Chronological, easy to scan. Append-only prevents tampering with history. --- ## Decision 7: Commit Message Convention **Date**: 2026-03-15 **Protocol**: Use Conventional Commits format: - `feat: ...` for new features - `fix: ...` for bug fixes - `docs: ...` for documentation only - `refactor: ...` for code restructuring - `test: ...` for adding tests - `chore: ...` for trivial/maintenance changes Optionally add scope in parentheses: `feat(coordinator): add job cancellation` **Rationale**: Enables automated changelog generation and quick scanning of history. --- ## Decision 8: Issue and PR Naming **Date**: 2026-03-15 **Protocol**: - Issue title: concise summary, optionally with label prefix: `[Bug] CLI crashes on import` - PR title: `Fix: resolve CLI service imports` or `feat: implement claim-task script` - Branch name: `/-` (e.g., `aitbc1/3-add-tests-for-aitbc-core`) - Branch naming enforces claim linkage to issue. **Rationale**: Consistent naming makes it easy to trace work items to code changes. --- ## Decision 9: Agent Identity in Communications **Date**: 2026-03-15 **Protocol**: - In Gitea comments and issues, sign as the agent identity (e.g., "— aitbc1"). - Use the same identity in daily memory entries. - When collaborating with sibling agent, mention `@aitbc` or `@aitbc1` appropriately. **Rationale**: Clear attribution for accountability and coordination. --- ## Decision 10: Emergency Protocol for Critical CI Failure **Date**: 2026-03-15 **Protocol**: - If a PR's CI fails due to infrastructure (not code), the agent who owns the PR should: 1. Investigate via `ai-memory/failures/ci-failures.md` and `debugging-notes.md` 2. If new failure pattern, record it immediately. 3. Comment on the PR with diagnosis and ETA. 4. If unable to resolve quickly, escalate to human via other channels (outside scope). **Rationale**: CI failures block all work; swift response is critical. Documentation prevents duplicated troubleshooting. --- ## Decision 11: Environment Configuration Drift Detection **Date**: 2026-03-15 **Protocol**: - `ai-memory/knowledge/environment.md` must reflect the current dev environment (ports, URLs, credentials placeholders). - If an agent changes a configuration (e.g., port, database path), they must update this file immediately. - Before starting a task, agents should verify that their environment matches the documented settings. **Rationale**: Prevents "works on my machine" issues and keeps knowledge current. --- *Add subsequent protocol decisions below.*