AGENTS.md Template for offline first design

Overview

Direct answer style summary: This AGENTS.md Template defines a repeatable operating manual for an offline-first design workflow using AI coding agents and multi-agent orchestration. It prescribes agent roles, handoffs, context handling, tool governance, and escalation to ensure consistent offline data sync, conflict resolution, and user experience parity when connectivity is unavailable.

When to Use This AGENTS.md Template

When designing and orchestrating offline-first apps where devices intermittently lose connectivity.
When multiple AI coding agents collaborate to design data sync strategies, conflict resolution, and UI fallbacks.
When you need a repeatable operating model for single-agent or multi-agent workflows with clear handoffs and governance.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Product Architect for offline-first design

Agent Roster and Responsibilities:
- Planner: Define offline data model, sync rules, and conflict resolution strategy.
- Implementer: Implement offline-first components, data storage, and sync adapters.
- Researcher: Gather constraints, edge cases, and platform-specific behaviors.
- Reviewer: Validate architectural decisions and data consistency guarantees.
- Tester: Validate sync correctness, conflict handling, and UX fallbacks.
- Domain Specialist: Provide domain rules for data ownership and privacy.

Supervisor/Orchestrator Behaviour:
- Holds the single source of truth for design decisions and coordinates agent handoffs.
- Enforces memory, context, and tool governance rules.
- Initiates rollbacks for failed syncs and escalates to human review when required.

Handoff Rules Between Agents:
- Planner -> Implementer: hand off model, specs, and sync protocol.
- Implementer -> Tester: provide testable components and integration hooks.
- Researcher -> Planner: share constraints and updated edge cases.
- Domain Specialist -> All: inject policy constraints as needed.

Context, Memory, and Source-of-Truth Rules:
- Maintain a centralized design log with versioned decisions.
- Use explicit references to data schemas, API specs, and auth scopes.
- All changes are captured in the AGENTS.md template and the project wiki.

Tool Access and Permission Rules:
- Implementer has write access to source code repository within approved branches.
- All tool calls are logged and auditable.
- Secrets are not hard-coded; use secure vaults.

Architecture Rules:
- Client offline cache with conflict-free replicated data types (CRDTs) or pruning-based sync.
- Idempotent sync adapters and deterministic merges.
- Clear separation between UI, data layer, and sync orchestrator.

File Structure Rules:
- /src
- /src/offline
- /src/ui
- /src/sync
- /docs
- AGENTS.md

Data, API, or Integration Rules:
- Use REST/GraphQL for server sync; ensure offline-first queues persist locally.
- Versioned API contracts; apply feature flags for migration.

Validation Rules:
- All sync paths must be idempotent and deterministic.
- Data conflicts must be detectible and resolvable via defined rules.

Security Rules:
- Data at rest on device encrypted; transit TLS 1.2+.
- Respect user privacy by pruning PII on sync when not needed.

Testing Rules:
- Offline data parity checks; simulated disconnects; deterministic test fixtures.
- End-to-end offline-first flow tests with mock servers.

Deployment Rules:
- Feature-flagged deployment; staged rollout for offline sync features.
- Canary tests for sync latency and conflict resolution.

Human Review and Escalation Rules:
- Escalate to product owner for data ownership questions.
- Critical sync failures require human-in-the-loop review.

Failure Handling and Rollback Rules:
- On sync failure, retry with backoff; rollback to last consistent state.
- Preserve user edits while resolving conflicts.

Things Agents Must Not Do:
- Do not bypass governance or hardcode secrets.
- Do not alter the central memory without planner approval.
- Do not perform destructive data operations without validation.

Recommended Agent Operating Model

Agent roles: Planner, Implementer, Researcher, Tester, Reviewer, Domain Specialist. Each has decision boundaries and escalation paths. The Planner coordinates multi-agent handoffs and ensures offline-first guarantees. The Implementer handles data storage, sync adapters, and UI fallbacks. The Researcher gathers edge cases and platform constraints. The Tester validates sync correctness and UX. The Reviewer ensures architectural integrity. The Domain Specialist enforces data governance and policy constraints. Handoffs are explicit, with source-of-truth updates queued in a central log. Escalations go to the Planner or Product Owner when policy or data ownership questions arise. This AGENTS.md Template supports both single-agent and multi-agent orchestration in an offline-first design workflow, aligning with AI coding agents and human review as needed.

Recommended Project Structure

project-root/
├── docs/
├── src/
│   ├── offline/
│   │   ├── cache/
│   │   ├── sync/
│   │   └── adapters/
│   ├── ui/
│   │   ├── components/
│   │   └── screens/
│   └── index.ts
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── AGENTS.md

Core Operating Principles

Explicit handoffs and auditable decisions.
Single source of truth for design decisions and memory.
End-to-end offline guarantees with deterministic sync.
Security-by-default for offline data and sync.
Frequent validation, testing, and human review when needed.

Agent Handoff and Collaboration Rules

Planner coordinates; Implementer carries out design; Researcher uncovers edge cases; Reviewer validates; Tester tests; Domain Specialist enforces policy. Handoffs are triggered by explicit events and logged in the central memory.

Tool Governance and Permission Rules

Only approved branches may be modified by agents; all tool actions are auditable.
Secrets must be retrieved from vaults; no hard-coding.
Production system changes require sign-off from a human reviewer.

Code Construction Rules

Write idempotent, deterministic code for offline sync paths.
Document all assumptions about data formats and edge cases.
Do not introduce race conditions in multi-agent interactions.

Security and Production Rules

Encrypt data at rest; keys rotated; least privilege access.
Audit logs for all user-impacting actions in offline mode.
Require elevated approvals for production rollouts of offline features.

Testing Checklist

Unit tests for sync adapters; integration tests for offline paths.
Simulated disconnects and conflict scenarios; end-to-end tests.
Performance tests for sync latency; regression checks after changes.

Common Mistakes to Avoid

Overindexing on one agent; under-specifying handoffs.
Ignoring memory constraints and offline conflicts early.
Skipping human review for policy-sensitive decisions.

FAQ

What is the purpose of an AGENTS.md Template for offline-first design?

This template standardizes how AI coding agents collaborate to design, implement, and validate offline-first data sync and UI fallback strategies, ensuring repeatable governance and handoffs.

Which agents are involved in offline-first orchestration?

Planner, Implementer, Researcher, Tester, Reviewer, Domain Specialist, each with clear responsibilities and handoff rules.

How are memory and source-of-truth managed?

All decisions are logged in a central memory with versioned decisions and explicit references to data schemas and API specs.

What constitutes a valid handoff between agents?

Handoffs are explicit events with artifact transfer, environment context, and updated source-of-truth entries; they are auditable.

What about security and production changes?

Secrets are stored in vaults, production changes require approvals, and data at rest is encrypted with least-privilege access.

Target User

Use Cases