oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2d68f66405043259f801235420cc1bfaa2d69030
aitbc/ai-memory/decisions/protocol-decisions.md

6.8 KiB
Raw Blame History

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/<issue-number>-<slugified-title>.
    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: <agent>/<issue>-<slug> (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.