AGENTS.md Template: Key Management System Design

Overview

Direct answer: This AGENTS.md template defines roles, boundaries, and operating norms for a key management system design using AI coding agents and multi-agent orchestration. It supports both single-agent execution and multi-agent coordination by establishing an agreed-upon memory model, sources of truth, and handoff protocols.

In short, this template acts as a project-level operating context for the KMS workflow, guiding how agents interact, what outputs are produced, and how governance is enforced.

When to Use This AGENTS.md Template

• Use when designing a key management system workflow that uses AI coding agents to manage cryptographic material, keys, and access controls.
• Use to codify handoffs between planner, implementer, reviewer, tester, researcher, and domain specialist agents.
• Use to enforce tool governance, secrets handling, and production deployment safeguards.
• Use to provide a reusable operating manual for both single-agent and multi-agent orchestration.
• Use when migrating from ad hoc scripts to a structured agent-based design with auditable decisions.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Enterprise Key Management System Design using AI coding agents

Agent roster and responsibilities:
- Planner: defines the high level strategy and milestones for KMS tasks
- Implementer: writes code and integrates tools for key management operations
- Reviewer: validates designs, security, and correctness of outputs
- Tester: creates and runs test scenarios, including failure modes
- Researcher: probes external services, standards, and collects sources
- Domain Specialist: provides security and compliance expertise for KMS

Supervisor or orchestrator behavior:
- The orchestrator maintains the task queue, triggers agent actions, and enforces handoffs and memory boundaries
- All outputs are logged with a verifiable source of truth and versioning

Handoff rules between agents:
- Planner to Implementer: hand off plans, requirements, and design decisions
- Implementer to Reviewer: deliver code, architecture diagrams, and test results
- Reviewer to Tester: hand off validated artifacts for testing
- Researcher to Domain Specialist: share standards considerations and risk findings

Context, memory, and source-of-truth rules:
- Use a single memory store per project; do not duplicate memory across agents
- All sources, results, and decisions must be timestamped and stored in the memory
- Source-of-truth: design documents, code repos, and test results

Tool access and permission rules:
- Only assigned agents may call tools; sensitive tools require approval
- Secrets must be read from a secure vault; keys must never be printed

Architecture rules:
- Microservice oriented with clear API boundaries; prefer event driven interactions
- Idempotent operations; no destructive changes without explicit handoff

File structure rules:
- Place code under src/, tests/; keep domain specific modules under kms/ domain folders
- Avoid duplicating artifacts across agents; share a common library only through the orchestrator

Data, API, or integration rules:
- All external calls are logged; use mocks in tests
- API keys and secrets are never embedded in code or prompts

Validation rules:
- Must pass unit tests, integration tests, and security checks
- Output must be reproducible and auditable

Security rules:
- Enforce least privilege and encryption at rest and in transit
- Rotate keys and validate authorization for each operation

Testing rules:
- Include failure mode tests; simulate key compromise scenarios
- Ensure idempotency and deterministic outputs

Deployment rules:
- Use feature flags; require audit log snapshots for production deploys
- Rollback path documented with steps

Human review and escalation rules:
- Escalate to Security Review if a design changes cryptographic material handling
- In crisis, trigger manual override via supervisor

Failure handling and rollback rules:
- If a step fails, rollback to the last known good state and replan

Things Agents must not do:
- Do not exfiltrate keys, reveal secrets, or bypass approvals

Recommended Agent Operating Model

The agent operating model defines clear roles and decision boundaries to ensure secure, auditable, and coordinated action across a KMS design workflow.

• Planner role determines strategy, milestones, and acceptance criteria; boundary: cannot execute cryptographic operations without Implementer.
• Implementer role executes tasks, calls tools, and produces code and artifacts; boundary: outputs must be reviewed before deployment.
• Reviewer role checks for security, correctness, and compliance; boundary: cannot bypass tests or risk approvals.
• Tester role creates test plans and validates outcomes; boundary: must use approved test data and run in sandbox.
• Researcher role gathers standards and references; boundary: must avoid leaking confidential references into production.
• Domain Specialist role ensures cryptographic and regulatory alignment; boundary: only provides guidance, not direct code changes without Plan.

Recommended Project Structure

kms-project/
├── planners/
├── implementers/
├── reviewers/
├── testers/
├── researchers/
├── domain-specialists/
├── orchestrator/
├── memory/
├── tools/
├── src/
├── tests/
└── docs/

Core Operating Principles

• Explicit handoffs with traceable outputs
• Least privilege and secure secrets management
• Single source of truth per project
• Idempotent operations and auditable changes
• Clear decision boundaries and escalation paths

Agent Handoff and Collaboration Rules

• Planner to Implementer: hand off plan, requirements, and design decisions
• Implementer to Reviewer: hand off code, architecture diagrams, and test results
• Reviewer to Tester: hand off validated artifacts for testing
• Researcher to Domain Specialist: share standards considerations and risk findings

Tool Governance and Permission Rules

• Tool calls require role authorization and, for sensitive tools, explicit approval
• Secrets must be accessed from secure vaults; never hard-coded
• Production changes require approval gates and audits

Code Construction Rules

• Follow project structure; modular, testable components
• Ensure deterministic outputs for cryptographic-related tasks

Security and Production Rules

• Implement TLS everywhere; rotate keys regularly
• Audit logs retained and immutable where possible

Testing Checklist

• Unit tests for each module
• Integration tests for agent handoffs
• Security tests for key management flows
• End-to-end tests in sandbox before production

Common Mistakes to Avoid

• Skipping security reviews for cryptographic operations
• Bypassing planned handoffs or versioning
• Duplicating memory or secrets across agents

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for Key Management System Design?

To define roles, workflows, and governance for AI coding agents designing and operating a KMS.

How does multi-agent orchestration work in this template?

It defines planner, implementer, reviewer, tester, researcher, and domain specialist roles and handoff rules to coordinate activities and maintain security.

Where are keys and secrets stored?

Secrets must be stored in hardware security modules or secret managers with least privilege access; never print secrets.

How are tool access and production changes governed?

Access is controlled with role-based permissions, explicit approvals, and auditable change logs.

What happens on agent failure or misbehavior?

Failure triggers rollback, re-planning, and potentially escalation to human review.