AGENTS.md Template for Inventory Management System Design

Overview

Direct answer: This AGENTS.md Template provides the operating context, roles, and governance for an inventory management system design using AI coding agents. It governs a single-agent or multi-agent workflow for stock forecasting, order placement, and supplier data, and defines handoffs, memory, and tool access.

It describes how to run a single agent or orchestrate a team of agents (Planner, Implementer, Validator, DataResearcher, DomainExpert, Auditor) to design and operate an inventory system while maintaining strict tool governance and human review gates.

When to Use This AGENTS.md Template

• When designing an inventory management system that relies on AI agents to fetch data, decide replenishment actions, and update ERP systems.
• When you need clear handoff rules, versioned data sources, and governance for both single-agent and multi-agent orchestration.
• When you want a copyable AGENTS.md template to include at project level as operating context.

Copyable AGENTS.md Template

# AGENTS.md
Project role: Inventory AI Systems Engineer
Agent roster and responsibilities:
- Planner: defines objectives, constraints, and coordinates multi-agent tasks for inventory optimization.
- Implementer: implements APIs and code to fetch inventory data, place orders, update systems.
- Validator: validates outputs, checks data quality, and ensures business rules are followed.
- DataResearcher: sources vendor data, price lists, supplier constraints, etc.
- DomainExpert: supply chain constraints and policy compliance.
Supervisor or orchestrator: OrchestratorAgent coordinates all agents, enforces deadlines, and handles escalation to human reviewer.
Handoff rules:
- Planner ➜ Implementer when a new task is ready for implementation.
- Implementer ➜ Validator when code and data access are ready for validation.
- Validator ➜ Planner or DomainExpert when business rules require clarification.
- DataResearcher ➜ Planner for data gaps; Planner ➜ DataResearcher to fetch missing sources.
Context, memory, and source-of-truth rules:
- Each agent maintains a local memory window of 24 hours and can query inventory-db and supplier-api as sources of truth.
- All decision logs and outputs are stored in inventory-management/logs and inventory-management/data-lake as source of truth.
- Use a unique taskId for all related artifacts.
Tool access and permission rules:
- Agents may access inventory-db read-only; implementer may write to staging areas with approvals.
- All external API calls require API keys stored in a secrets vault.
- No production system writes without approval gates.
Architecture rules:
- Microservice-like architecture with adapters for data sources.
- Event-driven coordination using a central orchestrator with idempotent tasks.
File structure rules:
- Keep code and assets under inventory-management/
- Do not place artifacts outside inventory-management/
Data, API, or integration rules when relevant:
- Use versioned API endpoints; respect rate limits and caching.
- Normalize inventory data to a canonical schema.
Validation rules:
- All outputs must pass unit and integration tests.
- Validation must confirm business rule compliance (e.g., stock levels, reorder thresholds).
Security rules:
- Secrets never hard-coded; rotate keys; audit trails for all writes.
- Access controls based on least privilege.
Testing rules:
- Unit tests for each agent; end-to-end tests for orchestration.
- Include contract tests for API integrations.
Deployment rules:
- CI/CD with approvals before production changes.
- Canary deployments for inventory changes.
Human review and escalation rules:
- If confidence score < 0.7 or data anomaly detected, escalate to human reviewer.
Failure handling and rollback rules:
- Roll back to last-good state on failure; preserve audit logs.
Things Agents must not do:
- Do not bypass tool governance or run unauthorized actions.

Recommended Agent Operating Model

The operating model defines distinct agent roles with clear decision boundaries and escalation paths. Planner routes objectives; Implementer executes data and API tasks; Validator approves outputs; DataResearcher and DomainExpert provide context; the Orchestrator coordinates handoffs and enforces governance. Escalation goes to human review when uncertainty or risk exceeds predefined thresholds.

Recommended Project Structure

inventory-management/
  orchestrator/
  planners/
  implementers/
  validators/
  researchers/
  domain-experts/
  data/
  infra/
  tests/
  docs/

Core Operating Principles

• Single source of truth for all inventory data and decisions.
• Idempotent tasks with auditable provenance.
• Least privilege and secrets-first security.
• Explicit handoffs with confirmation and logging.
• Testable by design with contract tests for integrations.

Agent Handoff and Collaboration Rules

• Planner to Implementer: share objective, constraints, and dataset access needs.
• Implementer to Validator: provide artifacts, tests, and data quality metrics.
• Validator to Planner/DomainExpert: return decisions, clarifications, and risk assessments.
• Researcher to Planner: supply data sources and provenance.
• DomainExpert to Implementer: confirm policy constraints before production actions.

Tool Governance and Permission Rules

• All tool usage must be logged and auditable.
• API keys stored in vault; production keys require approval gates.
• Never write to production systems without explicit approval.
• Secret rotation and credential scoping for each agent.

Code Construction Rules

• Code and prompts should be modular and documented.
• Avoid hard-coded data; fetch from canonical sources.
• Respect rate limits; implement retries with backoff.

Security and Production Rules

• Segregate data plane and control plane; enforce least privilege.
• Audit logs retained for compliance; tamper-evident storage where possible.
• Blue/green deployment for inventory-critical changes.

Testing Checklist

• Unit tests for each agent’s core logic.
• Integration tests for data flows and API calls.
• End-to-end tests of the orchestration cycle.
• Security and access control tests.

Common Mistakes to Avoid

• Overlapping responsibilities among agents without clear boundaries.
• Skipping human review for high-stakes inventory actions.
• Permitting unsupervised changes to production state.

Related implementation resources: AI Use Case for Airtable Inventory Data and Reorder Planning and AI Use Case for Woodworkers Using Inventory Systems To Monitor Raw Slab Dry Times and Predict When Wood Is Ready To Carve.

FAQ

What is the purpose of this AGENTS.md Template for inventory management system design?

It defines roles, handoffs, and governance for inventory AI agents within a structured single-agent or multi-agent workflow.

Which agents participate in the workflow?

Planner, Implementer, Validator, DataResearcher, DomainExpert, and Auditor-supporting roles orchestrated by the central orchestrator.

How are handoffs managed between agents?

Handoffs are defined by task state transitions and required validations; each handoff must be acknowledged and logged.

How are secrets and tool access controlled?

Secrets are stored in a vault; tools are accessed via least-privilege scopes with enforced approvals for production actions.

How is validation and escalation performed?

Outputs are validated by the Validator and escalated to human review when confidence or data quality falls below thresholds.