Agent Handbook & Conventions

Behaviors and conventions from CLAUDE.md and AGENTS.md that govern all agent activity.

Critical Rules (Always Follow)

Retrieve behaviors before every task — behaviors.getForTask ensures behavior-conditioned execution
Use MCP tools over CLI/API — Consistent schemas, automatic telemetry
Use Raze for all logging — Centralized, queryable, context-enriched
Use BreakerAmp for environments — Blueprint-driven, compliance hooks
Never hardcode secrets — Security and auditability
Run pre-commit before pushing — Catches secret leaks before git
Update docs after API/workflow 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) — Observe 3+ recurring patterns
PROPOSE (Strategist) — Draft behavior with procedural steps
APPROVE (Teacher) — Validate quality on test cases
INTEGRATE (All) — Add to handbook, update retrieval index

Behavior Retrieval

# MCP (preferred)
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.