AGENTS.md Template: Security Review and Remediation Agents

Overview

The AGENTS.md Template for Security Review and Remediation Agents provides a concrete, copyable operating manual to govern a security-focused workflow using AI coding agents. It covers both single-agent execution and multi-agent orchestration, including how agents collaborate, share memory, and hand off work across stages of discovery, remediation, validation, and escalation.

Direct answer: This template defines a security review and remediation workflow, its agent roles, governance, and practical instructions you can paste into an AGENTS.md file to run the project with reproducible results and auditable traces.

When to Use This AGENTS.md Template

• When starting a security remediation program that relies on AI coding agents and human oversight.
• When you need explicit handoff rules between discovery, remediation, validation, and audit phases.
• When you require tool governance, source-of-truth, and traceable decision logs for audits.
• When you want a repeatable operating model that scales to multiple assets or services.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Security Reviewer, Remediator, Orchestrator
Agent roster and responsibilities:
- Orchestrator: coordinates tasks, enforces the workflow rules, maintains the canonical memory.
- SecurityR: identifies vulnerabilities or policy gaps and catalogs evidence.
- Remediator: applies fixes, patches, configuration changes, and access control updates.
- Auditor: verifies remediation effectiveness and documentation.
- Researcher: gathers data from scanners, ticketing systems, and knowledge bases.
- Domain Specialist: provides expertise on target systems, compliance requirements, and risk context.

Supervisor or orchestrator behavior:
- The Orchestrator assigns tasks, tracks progress, and enforces escalation paths.
- Handoff rules: context and evidence must be transferred with traceable artifacts; memory must be updated in the canonical log before next handoff.

Handoff rules between agents:
- SecurityR completes discovery and hands off to Remediator with evidence, suggested changes, and validation criteria.
- Remediator provides patch details, rollback plan, and validation steps before handing back to Auditor.
- Auditor validates remediation artifacts and either closes the ticket or returns for rework.

Context, memory, and source-of-truth rules:
- Memory is stored in the project AGENTS.md repository as structured notes and artifacts.
- Source-of-truth includes vulnerability scans, ticketing system, change tickets, and remediation results.

Tool access and permission rules:
- Access to scanners, SIEM, ticketing, and secret vaults must be role-based and auditable.
- Production changes require approvals and logging; avoid hard-coded secrets.

Architecture rules:
- Changes flow through a versioned patch in CI/CD; no direct production edits without review.

File structure rules:
- Use a clear, versioned remediation directory with per-asset subfolders.
- Do not create unrelated folders; keep a single remediation domain.

Data, API, or integration rules:
- Integrations with scanners, ticketing, and vaults must be API-driven with least-privilege credentials.

Validation rules:
- Every remediation action must include explicit validation steps and evidence artifacts.

Security rules:
- Secrets must be accessed via vaults; never embed secrets in code or AGENTS.md.
- All actions are auditable.

Testing rules:
- Include unit tests for changes, integration tests for tool calls, and end-to-end checks for the remediation flow.

Deployment rules:
- Changes deployed through standard change windows with traceable outcomes.

Human review and escalation rules:
- All production changes require human review before deployment and a documented fallback plan.

Failure handling and rollback rules:
- Maintain a rollback artifact; if remediation fails, revert changes and re-validate.

Things Agents must not do:
- Do not bypass approvals, bypass tests, modify security policies outside authorized scope, or perform unsanctioned production changes.

Recommended Agent Operating Model

Roles and responsibilities are defined above. Decision boundaries: Orchestrator decides task assignment and escalation; individual agents own domain-specific actions but must defer to the orchestrator for policy decisions. Escalation paths: if validation fails or approvals are missing, escalate to SecurityLead and document rationale in the remediation record.

Recommended Project Structure

security-review-remediation/
├── agents/
│   ├── orchestrator/
│   ├── reviewer/
│   ├── remediator/
│   └── auditor/
├── policies/
├── workflows/
├── data/
├── tests/
└── infra/

Core Operating Principles

• Single source of truth for remediation context and decisions.
• Explicit handoffs with artifacts and memory traces.
• Least-privilege access across all tools and systems.
• Auditable actions with time-stamped evidence.
• Clear decision boundaries between agents and the orchestrator.

Agent Handoff and Collaboration Rules

• Planner/Orchestrator assigns tasks and manages state transitions.
• Implementer (Remediator) executes changes and logs steps with evidence.
• Reviewer/SecurityR validates changes and flags issues.
• Tester verifies remediation in a staging or test environment before production.
• Researcher, Domain Specialist provide context and risk assessment as needed.
• All agents must hand off with a summary, evidence, and next action.

Tool Governance and Permission Rules

• Command execution requires role-based permission and audit trails.
• File edits must go through a controlled patch process; no direct edits in production files.
• API calls require least-privilege tokens and secret vault references.
• Secrets: never store in code or AGENTS.md; pull from vault at runtime.
• Approval gates: require proper sign-off before production deployment.

Code Construction Rules

• Follow project-wide coding standards; write idempotent, auditable changes.
• Document every change with a remediation rationale and evidence artifacts.
• Avoid duplicating remediation steps across agents; share reusable patterns.
• Do not hard-code credentials or sensitive data.

Security and Production Rules

• Security reviews must precede any production remediation;
• All production changes are logged and recoverable via rollback artifacts;
• Run security scans and validations as part of the pipeline.

Testing Checklist

• Unit tests cover individual agent logic.
• Integration tests validate tool interactions (scanners, vault, ticketing).
• End-to-end tests simulate the full remediation flow with handoffs.
• Validation checks confirm evidence artifacts meet criteria.

Common Mistakes to Avoid

• Skipping the orchestration layer and performing unsanctioned changes.
• Dropping context between handoffs or losing evidence artifacts.
• Overriding approvals or bypassing tests to speed remediation.
• Neglecting rollback plans or traceability in logs.

FAQ

What is the purpose of this AGENTS.md Template for Security Review and Remediation?

It provides a copyable, operating manual for coordinating security review, remediation, and multi-agent orchestration with AI coding agents and human review.

Which agents are involved in this workflow?

Orchestrator, SecurityR (security reviewer), Remediator, Auditor, Researcher, and Domain Specialist coordinate to discover, remediate, validate, and document outcomes.

How are handoffs and escalation handled between agents?

Handoffs transfer context, artifacts, and memory with clear next actions. Escalation occurs when validation or approvals are blocked or when remediation fails.

What are the tool governance constraints?

Access to scanners, SIEM, ticketing, and secrets vaults is role-based and auditable; production changes require approvals and logs.

How is security ensured in the AGENTS.md workflow?

Secrets never appear in code; all actions are auditable, and security reviews validate changes before deployment.

What should I do if remediation fails?

Activate rollback artifacts, revert changes, re-run validations, and reopen the remediation task with the appropriate supervisor.