Agent Handbook & Conventions

Behaviors and conventions from AGENTS.md that govern all agent activity. This is the authoritative reference for agent rules, roles, and behavior lifecycle.

Critical Rules (Always Follow)

Rule	Behavior	Why
Retrieve behaviors before every task	`behaviors.getForTask`	Behavior-conditioned execution
Use MCP tools over CLI/API	`behavior_prefer_mcp_tools`	Consistent schemas, automatic telemetry
Use Raze for all logging	`behavior_use_raze_for_logging`	Centralized, queryable, context-enriched
Use BreakerAmp for environments	`behavior_use_breakeramp_for_environments`	Blueprint-driven, compliance hooks
Never hardcode secrets	`behavior_prevent_secret_leaks`	Security, auditability
Run pre-commit before pushing	`behavior_prevent_secret_leaks`	Catches leaks before git
Update docs after API/workflow changes	`behavior_update_docs_after_changes`	Keeps team aligned

Role Declaration Protocol

Every task must start with a role declaration:

Role	Symbol	Responsibility
Student	📖	Execute established behaviors; cite behavior + rationale
Teacher	🎓	Create examples, templates, docs; validate quality
Metacognitive Strategist	🧠	Analyze patterns (3+ occurrences), reflect on traces, propose behaviors

Escalation Triggers

Student → Teacher: Teaching others, writing docs, reviewing quality
Student → Strategist: Pattern observed 3+ times, root cause needed, no behavior fits
Teacher → Strategist: Behavior gaps discovered, quality patterns need extraction

Behavior Lifecycle

DISCOVER (Student)  →  PROPOSE (Strategist)  →  APPROVE (Teacher)  →  INTEGRATE (All)
  Observe 3+           Draft behavior with       Validate quality      Add to handbook
  occurrences          procedural steps          on test cases         + retrieval index

DISCOVER: Student observes recurring pattern 3+ times
PROPOSE: Strategist drafts behavior using behavior_<verb>_<noun> naming
APPROVE: Teacher validates (auto-approve if confidence ≥ 0.8)
INTEGRATE: Add to AGENTS.md, seed to BehaviorService, update retrieval index

Behavior Retrieval

# MCP (preferred — works in VS Code Copilot Chat)
mcp_amprealize_behaviors_getfortask(task_description="...", role="Student")

# CLI (fallback)
amprealize behaviors get-for-task "..." --role Student

# REST API (programmatic)
POST /v1/behaviors:getForTask {"task_description": "...", "role": "Student"}

Achieves ~46% token reduction by reusing proven procedural knowledge.

Quick Triggers

Scan before starting any task. If keywords match, follow the linked behavior:

Keywords	Behavior	Role
logging, telemetry	`behavior_use_raze_for_logging`	📖
environment, container	`behavior_use_breakeramp_for_environments`	📖
secret, credential, token	`behavior_prevent_secret_leaks`	📖
MCP tool, IDE extension	`behavior_prefer_mcp_tools`	📖
API design, OpenAPI	`behavior_design_api_contract`	🎓
test strategy, coverage	`behavior_design_test_strategy`	🎓
incident, outage, alert	`behavior_triage_incident`	📖
postmortem, root cause	`behavior_write_postmortem`	🎓
migration, schema change	`behavior_migrate_postgres_schema`	📖

For the complete trigger table, see AGENTS.md § Quick Triggers.