AGENTS.md Template: Service Oriented Architecture Planning

Overview

Direct answer: This AGENTS.md template defines a blueprint for planning and running a service oriented architecture with AI coding agents, enabling single-agent work and multi-agent orchestration across design, implementation, verification, and deployment phases.

The AGENTS.md template governs an SOA planning workflow, including roles, handoffs, tool governance, memory and source-of-truth rules, and escalation paths. It ensures agents adhere to architecture constraints and handoff patterns while providing a human review path.

When to Use This AGENTS.md Template

• When you need a reproducible, auditable operating context for an AI-driven SOA project.
• When multiple AI agents must coordinate services, APIs, and data contracts across a service catalog.
• When governance, security, and deployment gating matter for production-ready SOA planning.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: SOA Planning Lead with designated Planner, Architect, and Implementer tracks.

Agent roster and responsibilities:
- Planner Agent: defines scope, milestones, and service interactions.
- Architect Agent: designs service interfaces, contracts, and security boundaries.
- Implementer Agents: build service adapters, orchestrations, and integration points.
- Validator Agent: validates requirements, contracts, and outputs against acceptance criteria.
- Security Auditor Agent: audits access, secrets handling, and compliance.
- Ops/Deployment Agent: handles deployment, observability, and rollback plans.
- Researcher Agent: gathers reference models, standards, and architectural patterns.
- Domain Specialist Agent: provides domain-specific rules for each service.

Supervisor or orchestrator behavior:
- The Orchestrator monitors progress, collects outputs, and triggers handoffs on milestone completion.
- It enforces memory boundaries, ensures source-of-truth alignment, and records decisions in the knowledge graph attached to the project.

Handoff rules between agents:
- When Planner completes scope, hand to Architect for contract and interface design.
- When Architect finalizes designs, hand to Implementer for integration work.
- Validator checks each milestone before handoff; failures revert to Planner with new task.
- If security issues arise, Security Auditor takes precedence and blocks deployment until resolved.

Context, memory, and source-of-truth rules:
- Use a central Requirements Doc, API specs (OpenAPI), data contracts, and architecture diagrams as truth sources.
- All decisions must reference primary sources; memory stores must be tagged with source IDs.

Tool access and permission rules:
- Planner/Architect/Implementer can access repo and CI; sensitive secrets access is restricted to Security Auditor and Ops with approvals.
- No agent should bypass approvals or modify production configurations directly.

Architecture rules:
- Services must have clear boundaries, stable interfaces, and consistent authentication.
- Event-driven patterns preferred for cross-service communication.

File structure rules:
- Keep architecture docs in /docs/soa, code under /src/services, tests under /tests/soa.

Data, API, or integration rules when relevant:
- All APIs must publish OpenAPI specs; data contracts define schemas and versioning.

Validation rules:
- Each service must pass integration tests, contract validations, and security checks before handoff.

Security rules:
- Secrets never stored in code; use a secrets manager with role-based access.
- All communications must be encrypted in transit and at rest.

Testing rules:
- Include unit, integration, and contract tests; tests must be green before deployment.

Deployment rules:
- Use blue/green or canary deployments; rollback triggers on failed health checks.

Human review and escalation rules:
- Any major architectural change requires human review by Domain Specialist and Architect.
- Escalate to Engineering Lead if blockers persist beyond 48 hours.

Failure handling and rollback rules:
- Roll back to last known good configuration; preserve audit trail for incidents.

Things Agents must not do:
- Do not bypass governance, access production data without approval, or modify production infrastructure without tests.

Recommended Agent Operating Model

The operating model defines roles, decision boundaries, and escalation paths between Planner, Architect, Implementer, Validator, and Domain Specialist agents. In SOA planning, the Planner frames the scope; Architects codify interfaces; Implementers deliver adapters; Validators ensure conformance; Domain Specialists enforce domain rules; Security Auditors enforce guardrails. Escalation follows a clear chain for blocking issues, with a dedicated human reviewer for breaking changes.

Recommended Project Structure

/soa-project
  /docs
    /soa
  /src
    /services
      /service-a
      /service-b
    /orchestrations
  /tests
    /unit
    /integration
  /config
  /scripts

Core Operating Principles

• Single source of truth for requirements and contracts.
• Idempotent, auditable actions by agents.
• Clear handoffs with explicit acceptance criteria.
• Secure by default, with least-privilege access.
• Deterministic decision boundaries for each role.

Agent Handoff and Collaboration Rules

• Planner → Architect: when scope milestones are defined and risk assessed.
• Architect → Implementer: when interfaces and contracts are agreed.
• Implementer → Validator: after integration work and contract conformance.
• Researcher/Domain Specialist → Architect: to refine domain constraints.
• Security Auditor → Ops: after security approvals for deployment.

Tool Governance and Permission Rules

• Run commands, edits, and API calls only within approved tool scopes.
• Secrets accessible only to authorized roles with approvals.
• All changes to production require a formal review and a rollback plan.

Code Construction Rules

• Follow architecture-driven coding standards; avoid circumventions.
• Version contracts; do not ship breaking changes without deprecation paths.

Security and Production Rules

• Encrypt data in transit and at rest; rotate credentials regularly.
• Limit blast radius; implement service boundaries and access controls.

Testing Checklist

• Unit tests for services; integration tests for orchestrations.
• Contract tests to validate OpenAPI and data contracts.
• End-to-end tests in staging with canary deployment checks.

Common Mistakes to Avoid

• Skipping guardrails and bypassing approvals.
• Unclear ownership of services or contracts.
• Overly coupled orchestrations that violate service boundaries.

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 SOA planning?

Provides a copyable, operating manual for AI coding agents to plan, orchestrate, and govern service-oriented architectures with clear handoffs and governance.

Which roles are required in the agent roster?

Planner, Architect, Implementer, Validator, Domain Specialist, Researcher, Security Auditor, and Ops/Deployment agents.

How are agent handoffs managed in multi-agent orchestration?

Handoffs follow milestone-based transitions with explicit acceptance criteria, enforced by the orchestrator and audited by validators and domain specialists.

What security rules apply to this SOA planning workflow?

Least privilege access, secrets management, encrypted data, and approvals for production changes are mandatory.

How is validation performed before deployment?

Contract, integration, and security tests must pass; the Validator and Security Auditor confirm readiness before Ops deploys.