Bulkhead Isolation AGENTS.md Template

Overview

Direct answer: This AGENTS.md template defines a formal operating context for AI coding agents to implement and govern a bulkhead isolation architecture. It supports both individual agents and multi-agent orchestration, ensuring fault containment, bounded memory, and clear escalation paths.

It documents the agent workflow, decision boundaries, handoff rules, tool governance, and source-of-truth strategy needed to operate across isolated service compartments. Use it as a project-level operating context for designing, validating, and deploying bulkhead-safe AI workflows.

When to Use This AGENTS.md Template

• You are coordinating multiple AI agents across isolated service boundaries (bulkheads) to prevent cascading failures.
• You need explicit handoff rules and a centralized orchestrator to maintain state, context, and traceability.
• You require prescriptive tool governance, secrets handling, and production safeguards for AI calls.
• You want a reusable, paste-ready template to onboard new agents and scale the workflow.
• You must enforce security, validation, and rollback protocols in a multi-agent pipeline.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Bulkhead Isolation Architecture Project: orchestrate safe, fault-tolerant execution across isolated service compartments using AI coding agents.

Agent Roster and Responsibilities
- Planner: designs workflow, scope, and bulkhead boundaries; creates task plans with clear exit conditions.
- Implementer: builds agent routines, integrates service calls, and enforces boundary constraints between bulkheads.
- Reviewer: validates outputs against acceptance criteria and ensures conformance to architecture rules.
- Tester: executes unit/integration tests, simulates fault scenarios, and verifies recovery paths.
- Researcher: gathers performance data, failure modes, and improvement opportunities; maintains knowledge for optimization.
- Domain Specialist: provides subject-matter expertise (security, data standards, network isolation) for the workload.
- Orchestrator (Supervisor): enforces governance, routes tasks, and coordinates handoffs with logging and traceability.

Supervisor or Orchestrator Behavior
- Maintain a stateful task queue with per-bulkhead context; apply rate limits and circuit-breakers as needed.
- Enforce least-privilege policies; approve tool use and secret access based on role.
- Enforce escalation to human reviewers when risk thresholds are exceeded or when context is ambiguous.
- Log all handoffs, decisions, and outcomes for auditability.

Handoff Rules Between Agents
- Planner ➜ Implementer: pass a concrete task spec and context; require confirmation of boundary compliance.
- Implementer ➜ Reviewer: deliver artifacts and test results; wait for validation before promotion.
- Reviewer ➜ Orchestrator: report issues and request decisions; orchestrator decides on remediation or escalation.
- Researcher/Domain Specialist: can annotate data or provide policy guidance during any handoff.

Context, Memory, and Source-of-Truth Rules
- Central data store (SOT) holds canonical state; agents may cache ephemeral context only during a task.
- Memory is cleared after handoff completion or task termination; no cross-bulkhead leakage of data.
- All external interactions should be logged with a Source-of-Truth reference.

Tool Access and Permission Rules
- Tools are access-controlled; use is granted by the Orchestrator with role-based permissions.
- Secrets are accessed via a vault; rotate and audit every usage.
- Production system calls require approval gates and can only be executed by authorized agents.

Architecture Rules
- Bulkheads provide fault isolation; failure in one does not propagate to others.
- Deterministic task execution with well-defined timeouts; implement backpressure handling.
- Idempotent operations where possible; use idempotent APIs and idempotent data writes.

File Structure Rules
- Keep all artifacts under a single workflow-directory tree; avoid cross-workflow dependencies.
- Store task plans, results, and logs under per-bulkhead namespaces.

Data, API, or Integration Rules
- Clear data contracts; validate inputs/outputs against schema; use versioned APIs.
- All API calls must be auditable with request/response traces.

Validation Rules
- Each handoff must have a pass/fail criterion; require evidence for acceptance before handoff.
- Outputs must meet defined schema and invariants.

Security Rules
- Least privilege for tool access; rotate credentials; audit all access events.
- PII/PHI handling must comply with policy; data must be masked where appropriate.

Testing Rules
- Unit tests for individual agents; integration tests for inter-agent handoffs; end-to-end tests of the bulkhead workflow.
- Simulate fault injection and recovery paths; validate rollback procedures.

Deployment Rules
- Use versioned deployments; tag and roll back safely if health checks fail.
- Immutable artifacts; deploy with health checks and staged rollout.

Human Review and Escalation Rules
- Escalate to a human reviewer when risk thresholds are exceeded or when ambiguous context blocks progress.
- Document rationale for escalations and track resolution.

Failure Handling and Rollback Rules
- Short-circuit and rollback to a known-good snapshot when a bulkhead fails.
- Replay or replay-with-guardrails to avoid duplicate effects.

Things Agents Must Not Do
- Do not violate bulkhead boundaries or access outside allowed scopes.
- Do not share secrets in plain text; do not perform unsanctioned API calls.
- Do not bypass orchestrator governance; do not perform end-run around validation.

Recommended Agent Operating Model

The operating model defines each agent’s scope within the bulkhead isolation workflow, decision boundaries, and escalation paths. It ensures predictable, auditable behavior when coordinating across multiple isolated services.

• Planner sets explicit entry/exit criteria and keeps bulkhead boundaries tight to contain failures.
• Implementers translate plans into concrete agent routines with strict boundary checks.
• Reviewers verify conformance to architecture rules and data contracts before progression.
• Orchestrator enforces governance, routes tasks, and handles cross-bulkhead handoffs with traceability.
• Handoff paths are deterministic and require evidence of success before transition.
• Domain specialists and researchers provide input for compliance and performance optimization when needed.

Recommended Project Structure

bulkhead-isolation/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├── orchestrator/
├── services/
│   └── bulkhead-domain/
├── workflows/
│   └── bulkhead-isolation.md
├── configs/
├── data/
├── logs/
├── tests/
└── docs/

Core Operating Principles

• Strict bulkhead boundaries with bounded concurrency per service.
• Deterministic planning, execution, and escalation flows.
• Transparent, auditable decision and handoff traceability.
• Least-privilege access for tools and production integrations.
• Fail-fast, recover gracefully, and rollback safely.

Agent Handoff and Collaboration Rules

• Planner → Implementer: hand off plan, context, and acceptance criteria.
• Implementer → Reviewer: deliver artifacts and test results; await validation.
• Reviewer → Orchestrator: report issues and request remediation decisions.
• Researcher/Domain Specialist: annotate data or policy guidance during any handoff.

Tool Governance and Permission Rules

• Tools usage is gated by the Orchestrator; access is role-based and auditable.
• Secrets are stored in a vault; only authorized agents may access them; rotate regularly.
• Production calls require explicit approval gates; implement guardrails and health checks.

Code Construction Rules

• Write idempotent operations; avoid side effects on retries.
• Prefer stateless components; teardown after task completion.
• Document interfaces and contracts clearly; version all APIs used by agents.

Security and Production Rules

• Encrypt data in transit and at rest; enforce access controls and least privilege.
• Audit trails for all agent actions; monitor anomalies in real time.
• Limit blast radius in bulkheads; implement circuit breakers and timeouts.

Testing Checklist

• Unit tests for each agent; integration tests for handoffs; end-to-end tests for bulkhead workflow.
• Fault injection, resilience tests, and rollback validation.
• Security and secret-management tests; confirm restricted access policies.

Common Mistakes to Avoid

• Ignoring bulkhead boundaries; allowing data leakage across compartments.
• Unclear handoff criteria or missing evidence for transitions.
• Over-provisioning tools or bypassing governance gates.
• Avoiding rollback paths or insufficient rollback tests.

Related implementation resources: AI Agent Use Case for Manufacturing Buyers Using Supplier Lead Time Trends To Automatically Adjust Raw Material Reorder Dates and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for Bulkhead Isolation?

It provides a formal operating manual for AI coding agents to implement, govern, and orchestrate a bulkhead isolation pattern with clear roles, handoffs, and rules.

How does the orchestrator handle agent handoffs in this template?

The orchestrator enforces documented handoff rules, ensures context propagation is bounded by the current bulkhead, and logs decisions for traceability.

What are the security constraints for tool access in this workflow?

Access to tools, secrets, and production systems is gated, auditable, and restricted to authorized agents with least-privilege permissions.

How should memory and source-of-truth be managed?

Source of truth resides in a canonical store; agents cache only ephemeral context during tasks and clear memory on handoff or completion.

What happens if an agent fails or a handoff is blocked?

The template defines rollback and escalation to human review with a safe remediation path and state restoration.