AGENTS.md Template: Graceful Degradation Planning

Overview

Direct answer: This AGENTS.md template defines a graceful degradation planning workflow for AI coding agents, enabling single-agent and multi-agent orchestration during degraded scenarios. It codifies roles, handoffs, tool governance, memory, and escalation to maintain safe operation when services degrade.

The AGENTS.md template serves as a project-level operating manual for graceful degradation. It prescribes how agents collaborate to keep essential functionality, when to degrade, what to log, and how to escalate to human review. It supports both single-agent and multi-agent coordination with clear decision boundaries and audit trails.

When to Use This AGENTS.md Template

• When planning for degraded service scenarios in AI coding agent workflows.
• To formalize multi-agent orchestration and handoffs during outages or performance slowdowns.
• To define memory, source-of-truth, and tool governance for degraded modes.
• To establish escalation paths and human review gates for high-risk degradation.
• To guide secure tool usage and production-safe operations in failure modes.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Graceful Degradation Planner for AI coding agents in multi-agent orchestration.

Agent roster and responsibilities:
- Planner: designs degradation strategy, monitors signals, and updates tasks; ensures safe fallback behavior.
- Degrader: executes degradation steps to preserve core functionality when primary paths fail.
- Monitor: observes metrics, alerts, and anomaly signals; triggers escalations and validates degraded outputs.
- Executor (Implementer): applies remediation actions and enforces safe state changes in degraded mode.
- Reviewer: validates outputs and actions before promotion to degraded production state.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates planning, watchful state, and handoffs between agents.
- Enforces safety gates, timeouts, and rollbacks; logs all decisions for auditability.

Handoff rules between agents:
- Planner → Degrader: when a degradation plan is ready for execution.
- Degrader → Monitor: on degradation progress updates and validated outcomes.
- Monitor → Reviewer: when outputs require validation before promotion.
- Executor → Monitor: after actions complete, to confirm outcomes and seal state.

Context, memory, and source-of-truth rules:
- Shared memory store holds current plan, degraded state, telemetry, and logs.
- All agents read from the centralized source of truth; updates are versioned and auditable.
- Source-of-truth is the canonical log and telemetry feed; avoid duplicate state mutations.

Tool access and permission rules:
- Agents may access only approved tools and endpoints relative to degraded operations.
- Secrets must be retrieved from a vault and never stored in plain text in agents.
- Production system changes require explicit approvals and egress controls.

Architecture rules:
- Degradation state is isolated to a degraded subdomain or feature flag; primary paths remain untouched.
- Changes to production must pass through orchestrator gates and rollback hooks.

File structure rules:
- All agent code lives under graceful-degradation/ with clear separation by role.
- Use shared configs only for non-sensitive defaults; secrets are scoped per environment.

Data, API, or integration rules when relevant:
- Use telemetry streams for decisioning; avoid ad-hoc data leakage between degraded modes.
- API calls must be idempotent where possible during degradation.

Validation rules:
- All degraded outcomes must meet minimum functional acceptance criteria and be auditable.
- Degradation progress is tracked with verifiable signals and timestamped logs.

Security rules:
- Secrets must be rotated on schedule; secrets are never embedded in code.
- Access control must enforce least privilege for degraded operations.

Testing rules:
- Include unit tests for degradation logic and end-to-end tests for degraded scenarios.
- Test rollback paths and failure modes with simulated outages.

Deployment rules:
- Deploy degraded-state changes behind feature flags; monitor post-deploy signals.
- Enable quick rollback if degraded path fails safety checks.

Human review and escalation rules:
- Escalate high-risk degradation to humans; require sign-off before persistent state changes.
- Document rationale for degraded decisions and expected risk reductions.

Failure handling and rollback rules:
- Soft-fail first, then escalate; rollback to a safe known-good state if degradation worsens.
- Preserve traceability of rollback steps for auditing.

Things Agents must not do:
- Do not modify production outside approved degraded-state gates.
- Do not bypass orchestrator decisions or secret vault controls.

Recommended Agent Operating Model

The operating model defines roles, decision boundaries, and escalation paths for graceful degradation. Planners decide when to degrade; degraders execute safe fallbacks; monitors verify outcomes; reviewers validate before public release of degraded behavior; and humans review high-risk degradations during escalation. Escalation paths exist for critical failures, security concerns, or when metrics breach defined thresholds.

Recommended Project Structure

graceful-degradation/
├── planners/
├── degraders/
├── monitors/
├── executors/
├── reviewers/
├── researchers/
├── shared/
├── policies/
├── workflows/
├── tests/
└── docs/

Core Operating Principles

• Clarity of scope and bounded decisions for every agent.
• Idempotence and deterministic outcomes for degraded actions.
• Auditable decision logs and auditable memory state.
• Strict separation of concerns between planning, execution, and validation.
• Least-privilege access and secure handling of secrets.
• Explicit memory management and source-of-truth governance.
• Testable degradation paths and safe rollback options.

Agent Handoff and Collaboration Rules

• Planner defines a degradation plan with explicit success criteria and triggers.
• Implementers must log actions with timestamps and preserve idempotency.
• Reviewers validate outputs against acceptance criteria before promoting degraded state.
• Testers simulate degraded scenarios and verify recovery paths remains safe.
• Researchers contribute domain knowledge where needed; Domain Specialists approve domain-sensitive decisions.
• Planner and Orchestrator enforce gating and escalation rules for all handoffs.

Tool Governance and Permission Rules

• Commands and API calls are restricted to approved toolsets during degradation.
• Secret access via vault; never hard-coded in code or prompts.
• External service calls must be audited and rate-limited during degraded operation.
• Production changes require approval gates and rollback readiness checks.

Code Construction Rules

• Implement degradation logic with clear boundaries and explicit input validation.
• All state changes must be recorded in the source-of-truth store.
• Use deterministic retries with exponential backoff and maximum caps.
• Produce structured logs for observability and debugging.

Security and Production Rules

• Degraded paths should not expose sensitive data; implement data minimization.
• Audit trails must cover who initiated degradation, what changed, and when.
• Secret handling follows least privilege and rotates on schedule.
• Protect production endpoints during degraded operation with strict access controls.

Testing Checklist

• Unit tests for degradation routines and boundary conditions.
• Integration tests simulating outages and degraded outputs.
• End-to-end tests of the degraded workflow with rollback scenarios.
• Security and access-control tests for degraded operations.

Common Mistakes to Avoid

• Overly complex degradation logic that hiding root causes.
• Unclear handoffs leading to duplicated work or race conditions.
• Bypassing orchestrator decisions or secrets vaults.
• Assuming degraded state is permanent or risk-free.
• Neglecting rollback and auditing for degraded actions.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the purpose of this AGENTS.md Template for graceful degradation?

It provides a concrete operating manual for coordinating AI coding agents during degraded service scenarios, including roles, handoffs, tool governance, memory rules, and escalation paths.

How does graceful degradation work with multi-agent orchestration?

Agents share a canonical source of truth and follow defined handoffs and gates. The Planner triggers degradation, Degrader executes safe fallbacks, Monitor validates outcomes, and humans review high-risk cases.

How are memory and source of truth maintained during degraded operation?

A centralized memory store holds the current plan, state, telemetry, and logs; all agents read and write to the shared store with versioned updates to prevent drift.

How is a degraded state validated before going live?

Validation requires acceptance criteria met by the Monitor and, for critical changes, a Reviewer and possibly a human sign-off before promotion to degraded production.

How do you perform rollback if degradation creates risk?

Rollback uses a safe-known baseline, reverts changes via the Orchestrator, and restores the primary path while preserving audit records for post-mortems.