Permissioned Agent Pilot Pack (Checklist + Templates)

Goal: ship an agent that takes real actions without expanding your incident surface area.

1) Pick the workflow (Scope Template)
- Workflow name:
- Systems touched (APIs only; list exact endpoints or operations):
- Allowed actions (verbs only: create/update/comment/close):
- Disallowed actions (delete/export/bulk updates by default):
- Expected artifacts (ticket ID, PR URL, record IDs, diff, log bundle):
- Rollback plan (what “undo” means for each action):

2) Identity & Access Checklist
- Create a dedicated principal for the agent (IAM role / OAuth client).
- Enforce least privilege: restrict to allowlisted repos/projects/records.
- Use short-lived tokens (STS/OAuth) with expiration and revocation.
- No long-lived keys in env vars; store secrets in your standard secret manager.
- Separation of duties: high-risk actions require a second identity or approval.

3) Tool Contract Template (per tool)
- Tool name:
- Description:
- Input schema (required fields + validation rules):
- Output schema (include external IDs and exact changes made):
- Refusal modes (what the tool will reject, and how it reports refusal):
- Dry-run support (what it returns without making changes):
- Idempotency key strategy (avoid duplicate actions):

4) Policy Enforcement Requirements
- Policy must be enforced outside the model (gateway/service layer).
- Define a risk level per action: low/medium/high.
- Human approval required for: irreversible changes, legal/compliance actions, billing-impacting changes, production deploys.
- Record every denied action as an auditable event.

5) Audit Log Minimum Viable Spec
Every agent run should produce an append-only log with:
- run_id, timestamp, agent_principal
- user/request that initiated the run
- tool_calls[]: tool_name, validated_input, output, external IDs, success/failure
- approvals[]: who approved, what was approved, when
- final outcome: what changed, links to artifacts

6) Graduation Gate (when to expand privileges)
Do not expand scope after a demo. Expand only after:
- Stable operation under real load for a sustained period
- Clear evidence you can reconstruct runs end-to-end
- A tested rollback for each allowed action
- Documented on-call playbook: how to pause the agent, revoke tokens, and replay a run

Copy-paste rule: If you can’t paste the tool schema and policy into a code review and have security sign off, the agent isn’t ready for real permissions.