AGENTS.md Template for Construction Site Coordination Agents

Overview

The AGENTS.md template is an operating manual for AI coding agents that coordinate a construction project. It defines how a single agent or a team of agents collaborate across design, procurement, planning, site execution, and handoffs to human staff. It provides concrete operating context for both individual agents and multi-agent orchestration patterns.

When to Use This AGENTS.md Template

• Starting a new construction project coordination workflow that involves multiple agents (planner, implementer, researcher, domain specialist, reviewer, tester, orchestrator).
• Codifying handoffs and responsibility boundaries between design phase, procurement, scheduling, safety checks, and field execution.
• Enforcing tool governance, access controls, and escalation to human review at decision gates.

Copyable AGENTS.md Template

# AGENTS.md

Project: Construction Site Coordination

Agent roster and responsibilities:
- Planner: defines the plan, milestones, dependencies, and risk controls.
- Implementer: translates plans into executable field actions and trackable tasks.
- Researcher: sources standards, codes, site data, and supplier information.
- Domain Specialist: provides expert review on structural, safety, and compliance issues.
- Reviewer: validates outputs, checks for quality and consistency.
- Tester: runs validation checks and simulates outcomes.
- Orchestrator: coordinates task assignment, monitors progress, and enforces handoffs.

Supervisor / orchestrator behavior:
- Maintain project state, coordinate agents, and resolve conflicts.
- Escalate to human supervisor when risk exceeds threshold or policy is violated.

Handoff rules:
- Planner -> Implementer: deliver plan and task list with acceptance criteria.
- Implementer -> Reviewer: deliver completed tasks for review at milestones.
- Researcher -> Planner/Domain Specialist: supply sources and constraints when requested.
- Domain Specialist -> All: provide expert guidance when needed.

Context, memory, and truth:
- Keep a single source of truth for plan, tasks, and decisions.
- Memory store keyed by project id; retain last N tasks and sources.
- Do not rely on ephemeral context for critical decisions.

Tool access and permission rules:
- Use only approved tools (CAD viewer, BIM API, project management API).
- Secrets stored in secure vault; never print credentials in messages.
- All tool actions logged with timestamp and agent identifiers.

Architecture rules:
- Micro-service style with a clear boundary between planners, executors, and reviewers.
- Use an event bus to communicate task state changes.

File structure rules:
- agents/
- workflows/
- data/
- tools/
- docs/

Data, API, or integration rules:
- Standardize input/output schemas; validate with a schema before API calls.
- Use BIM/ERP or project management APIs for data sources.
- Respect rate limits and retry with exponential backoff.

Validation rules:
- All outputs must meet acceptance criteria; unit tests verify format and content integrity.

Security rules:
- Principle of least privilege; rotate credentials; audit logs retained.

Testing rules:
- Include unit, integration, and end-to-end tests for handoffs and failure modes.

Deployment rules:
- CI/CD with canary deployments; monitor health; rollback on anomaly.

Human review and escalation rules:
- Escalate critical issues to human reviewer; require sign-off before production changes.

Failure handling and rollback rules:
- If a task fails, revert to the previous stable state and notify the orchestrator.
- Do not publish artifacts that are in error state.

Things Agents must not do:
- Do not bypass approvals or governance gates.
- Do not modify project scope without change control.
- Do not share secrets in messages.
- Do not perform destructive operations without backup and approval.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support reliable planning, execution, and quality assurance in construction site coordination. The Planner has final say on plan changes; the Orchestrator enforces rules and escalates when needed; Implementer handles field execution; Domain Specialist and Researcher provide subject-matter support; Reviewer and Tester validate outputs and acceptance criteria. Escalation paths move from automated checks to human review when risk, safety, or compliance thresholds are reached.

Recommended Project Structure

construction-site-coordination/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── researcher/
│   ├── domain-specialist/
│   ├── reviewer/
│   ├── tester/
│   └── orchestrator/
├── workflows/
│   └── construction-site-coordination/
│       ├── tasks/
│       ├── models/
│       ├── data/
│       └── outputs/
├── data/
├── tools/
├── docs/
└── scripts/

Core Operating Principles

• Operate with explicit handoffs and accountability at each stage.
• Preserve a single source of truth and traceable decision history.
• Limit tool access by role and enforce secure credential handling.
• Prefer declarative outputs and observable state changes over opaque actions.
• Escalate to human review for safety, compliance, or major scope changes.

Agent Handoff and Collaboration Rules

• Planner defines the plan; Implementer executes tasks; Reviewer validates outcomes.
• Researcher provides sources and constraints to Planner and Domain Specialist.
• Orchestrator resolves conflicts and routes tasks to appropriate agents.
• All handoffs require a defined acceptance criterion and a status update.

Tool Governance and Permission Rules

• Only approved tools may be invoked; access controlled by role.
• All API calls require authentication; store credentials securely.
• Secrets never appear in logs or messages.
• Changes to production data require approval and auditing.
• External tool access is logged and can be revoked at any time.

Code Construction Rules

• Follow the AGENTS.md template for all new workflows.
• Define clear input/output schemas for all tool interactions.
• Write idempotent steps and ensure repeatable results.
• Avoid hard coding project-specific data; parameterize by project id.

Security and Production Rules

• Enforce least privilege and role-based access control for all agents.
• Store secrets in a vault; rotate periodically.
• Log all actions; monitor for anomalies; implement automated alerts.
• Back up state before production changes; implement rollback procedures.

Testing Checklist

• Unit tests for each agent function; contract tests for tool calls.
• Integration tests for handoffs and state transitions.
• End-to-end tests simulating construction site scenarios.
• Security tests for credential handling and data access.
• Regression tests after workflow changes.

Common Mistakes to Avoid

• Skipping human review for safety-critical decisions.
• Overloading agents with tasks beyond their domain.
• Weak versioning of the AGENTS.md template leading to drift.
• Ignoring data governance and secrets handling in multi-agent setups.

FAQ

What is the AGENTS.md Template for Construction Site Coordination?

The AGENTS.md Template defines a concrete operating model for AI coding agents coordinating a construction project, including roles, handoffs, tools, and governance.

How does multi-agent orchestration handle handoffs between design, planning, and field tasks?

Orchestrator coordinates task state, enforces handoff criteria, and routes outputs to the next agent stage with a verifiable acceptance check.

How are secrets and tool access controlled in this template?

Access is restricted by role, credentials are stored in a secure vault, and all tool actions are logged for auditability.

Where does human review fit in the automation?

Human review is required at safety, compliance, or high-risk decision gates; automated checks surface issues and route for sign-off.

How do you validate outputs and rollback changes?

Validation checks ensure criteria are met; on failure, state is rolled back and the orchestrator reassigns tasks or escalates.