Schema: AI agent profiles, permissions, and escalation

[rajanbor]

Goal

Define library/schemas/agent.schema.json so agent roles are portable across vendors and safe by default.

Human contract

Document mission, inputs, outputs, instruction order, allowed tools, denied actions, side-effect policy, budgets, verification, escalation, and handoff. Include implementer and read-only reviewer examples.

Machine contract

Model capabilities independently from vendors. Permissions default-deny for side effects and distinguish read, write, execute, network, and external communication. References to rules, workflows, evals, and tools use typed IDs.

Acceptance criteria

• Schema, guide, two valid profiles, and security-focused invalid fixtures exist.
• Missing side-effect policy cannot silently grant permission.
• Referenced contracts are checked for existence.
• Adapters can degrade unsupported fields without changing meaning.
• The repository operating-principles profile validates.

Depends on the document envelope; should land before workflows and tools.