Appearance
Agent Operating Model
Last updated: 2026-03-22 Canonical agent guide: AGENTS.md (root) — read that first for full workflow details
Overview
This document describes the LLM agent operating model for rustchat: which agents are authorized, what skills they use, and what scope boundaries apply. It structures the information per the LLM Development Operating Model v2.0.
The machine-readable contracts live in .governance/agent-contracts.yml. This doc is the human-readable summary.
1. Agent Roles
Three agents are defined for rustchat:
| Agent | Mode | Role |
|---|---|---|
backend-agent | bounded-write | Implements backend features and fixes |
frontend-agent | bounded-write | Implements frontend features and fixes |
compat-agent | read-only | Performs Mattermost compatibility analysis, produces design artifacts |
backend-agent
Allowed paths: backend/src/**, backend/tests/**, backend/migrations/**, push-proxy/**
Prohibited without explicit approval:
backend/src/auth/**— requires explicit human approvalbackend/src/api/v4/**— requires compat-reviewer co-approval (@zoorpha)backend/src/mattermost_compat/**— requires compat-reviewer co-approvalbackend/src/a2a/**— requires senior review.governance/**,frontend/**— always prohibited
Limits: ≤10 files, ≤300 lines per PR. Tests required. Human review required.
ADR required for: auth changes, permission changes, API contract changes.
frontend-agent
Allowed paths: frontend/src/**, frontend/e2e/**
Prohibited: backend/**, .governance/**
Limits: ≤10 files, ≤300 lines per PR. Human review required. Tests: Not required (explicitly set to false in contract).
compat-agent
Mode: Read-only — cannot write production code, cannot approve PRs.
Can read: backend/compat/**, backend/src/api/v4/**, backend/src/mattermost_compat/**, tools/mm-compat/**
Can write (analysis output only): previous-analyses/**, docs/superpowers/specs/**, docs/superpowers/plans/**Prohibited: .governance/** — always prohibited.
Applicable skills: mattermost-api-parity, mm-endpoint-contract-parity, mm-websocket-calls-parity, mm-mobile-journey-parity
2. Skills System
7 capability skills are defined in .agents/skills/:
| Skill | Domain |
|---|---|
mattermost-api-parity | Compat: Mattermost HTTP API analysis |
mm-endpoint-contract-parity | Compat: endpoint contract comparison |
mm-websocket-calls-parity | Compat: WebSocket event contract analysis |
mm-mobile-journey-parity | Compat: mobile user journey coverage |
production-readiness-gate | Quality: pre-release checklist |
user-validation | Quality: user-facing behavior verification |
ai-summarization-rag | Feature: AI summarization / RAG pipeline |
Relationship to agent contracts: Skills define how (capability, method, output format). Contracts define where (allowed paths, scope boundaries). A skill tells the agent what to do; the contract tells it where it is allowed to do it.
For compat-agent: only the 4 compat skills apply. For backend-agent and frontend-agent: any non-compat skill.
3. Workflow
All agent work follows the plan-first workflow:
1. Brainstorm → spec (docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md)
2. Write plan (docs/superpowers/plans/YYYY-MM-DD-<topic>.md)
3. Execute plan task-by-task (subagent-driven-development or executing-plans)
4. Two-stage review per task: spec compliance → code quality
5. finishing-a-development-branchNo ad-hoc changes to protected paths. No implementation without a prior spec.
4. Compatibility-First Rule
Any change to the Mattermost compatibility surface (backend/src/api/v4/**, backend/src/mattermost_compat/**, backend/compat/**) requires:
- Compat reviewer co-approval (
@zoorphaperCODEOWNERS) - Risk tier elevated (automatic per
protected-paths.yml) - Compat contract tests pass
When in doubt whether a change touches the compat surface, treat it as if it does.
5. Boundaries Summary
| Area | backend-agent | frontend-agent | compat-agent |
|---|---|---|---|
backend/src/ (non-protected) | ✅ write | ❌ | ✅ read |
backend/src/api/v4/ | ⚠️ co-approval | ❌ | ✅ read |
backend/src/auth/ | ⚠️ explicit approval | ❌ | ❌ |
backend/src/mattermost_compat/ | ⚠️ co-approval | ❌ | ✅ read |
backend/src/a2a/ | ⚠️ senior review | ❌ | ❌ |
backend/migrations/ | ✅ write | ❌ | ❌ |
backend/tests/ | ✅ write | ❌ | ❌ |
backend/compat/ | ❌ | ❌ | ✅ read |
frontend/src/ | ❌ | ✅ write | ❌ |
frontend/e2e/ | ❌ | ✅ write | ❌ |
.governance/ | ❌ | ❌ | ❌ |
docs/superpowers/specs/ | ❌ | ❌ | ✅ write |
docs/superpowers/plans/ | ❌ | ❌ | ✅ write |
6. Cross-References
- Full agent workflow guide:
AGENTS.md - Machine-readable contracts:
.governance/agent-contracts.yml - Risk tier definitions:
.governance/risk-tiers.yml - Protected paths:
.governance/protected-paths.yml - Code ownership:
.github/CODEOWNERS