AGENTS.md Template for Documentation and Technical Writing Agents

Overview

Direct answer: This AGENTS.md template defines the operating model for AI coding agents in documentation and technical writing workflows. It supports both single-agent and multi-agent orchestration, with clear roles, handoffs, memory, and governance rules to keep outputs aligned with a single source of truth.

When to Use This AGENTS.md Template

• When establishing a documented, copyable operating context for AI coding agents in a software project.
• When you need to enable scalable multi-agent orchestration across planning, implementation, review, testing, and domain-specific tasks.
• When enforcing tool governance, memory management, and escalation paths for technical writing and documentation work.

Copyable AGENTS.md Template

Below is a ready-to-copy AGENTS.md template block you can paste into your repo as AGENTS.md to establish project-level operating context for single-agent and multi-agent work.

# AGENTS.md

Project Role: Documentation and Technical Writing Lead for AI coding agents

Agent roster:
- DocA: Documentation agent responsible for maintaining docs and ensuring style and cross-references
- ResA: Research agent gathering sources, API references, and external docs
- PlanA: Planner agent providing high-level strategy and orchestrating tasks
- ImplA: Implementer agent executing tasks and producing artifacts
- RevA: Reviewer agent validating quality, style, and compliance
- TestA: Tester agent running checks and reporting results
- DSA: Domain Specialist providing domain-specific validation

Supervisor / Orchestrator: Orchestrator coordinates tasks, maintains memory, enforces policy, and triggers handoffs

Handoff rules:
- PlanA → ImplA for implementation tasks with clear success criteria
- ImplA → RevA for review and quality checks
- RevA → TestA for validation and testing
- TestA → PlanA if re-planning is required or issues arise
- DSA → PlanA for domain-specific decisions and constraints
- All handoffs must log state to memory and reference sources of truth

Context, memory, and source of truth:
- Primary memory: docs/ai-skills/agents-md-templates/md or memory/store.json
- All outputs must cite sources in memory/sources.json and reference the canonical repo paths

Tool access and permission rules:
- Tools allowed: read_docs, write_docs, run_tests, fetch_sources
- Secrets must be stored in a secure vault; never print in logs
- Production changes only via approved deployment agents and gated approvals

Architecture rules:
- Separate concerns: planner, implementer, reviewer, tester, researcher, and domain specialist
- Idempotent operations and deterministic results for given inputs
- Use versioned interfaces and formal handoffs

File structure rules:
- Store agent-facing artifacts under ai-coding-agents/docs and ai-coding-agents/workflows
- Place memory and sources under ai-coding-agents/memory and ai-coding-agents/sources

Data, API, or integration rules:
- All external calls must be logged; use authenticated endpoints
- Validate data formats and handle failures gracefully

Validation rules:
- Outputs must conform to the defined AGENTS.md schema and templates
- Inputs validated for type and range; outputs deterministic

Security rules:
- No plaintext secrets in code or logs
- Enforce environment isolation for staging and production

Testing rules:
- Unit tests for each agent type
- Integration tests for multi-agent handoffs
- End-to-end acceptance checks

Deployment rules:
- Deploy agent templates with version tagging; document changes in CHANGELOG
- Rollback procedures documented and tested

Human review and escalation rules:
- High-risk outputs require human review before publication
- Escalation path to engineering lead when issues cannot be resolved by agents

Failure handling and rollback rules:
- On failure, revert memory changes to last good state and rollback changes

Things Agents must not do:
- Do not reveal secret keys or tokens
- Do not hand off without logging and traceability
- Do not drift from the defined architecture or memory state
- Do not deploy to production without proper approvals

Recommended Agent Operating Model

Agents and roles, decision boundaries, and escalation paths define who can decide what and when to escalate.

• Planner (PlanA): defines goals, constraints, and task plan; assigns work to Implementer and Researcher; decides when to escalate to Domain Specialist.
• Implementer (ImplA): executes tasks, produces artifacts, updates memory and sources; raises blockers when inputs are missing.
• Researcher (ResA): collects sources, ensures references are current, and provides context for the plan and implementer.
• Reviewer (RevA): validates accuracy, style, compliance, and alignment with sources of truth.
• Tester (TestA): runs unit, integration, and end-to-end checks; reports failures with reproducible steps.
• Domain Specialist (DSA): validates domain-specific accuracy and constraints; escalates for risk signals.
• Orchestrator: coordinates handoffs, enforces memory/state consistency, and triggers escalations when needed.

Recommended Project Structure

ai-coding-agents/
  docs/
    agents-md-template.md
  workflows/
    ai-coding/
      planner/
      implementer/
      reviewer/
      tester/
      researcher/
      domain-specialist/
  memory/
  sources/
  tests/

Core Operating Principles

• Single source of truth for all agent outputs and decisions.
• Explicit handoffs with clear inputs, outputs, and success criteria.
• Memory and sources kept in a versioned, auditable store.
• Security-first: protect secrets and restrict tool access.
• Idempotence and determinism for repeatable results.
• Continuous validation and edge-case handling.

Agent Handoff and Collaboration Rules

Define concrete rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents.

• Planner creates a task docket with inputs, constraints, required sources, and acceptance criteria.
• Implementer produces artifacts with traceable references to sources and memory keys.
• Reviewer approves outputs or returns them with actionable feedback.
• Tester executes unit, integration, and end-to-end tests; reports coverage and results.
• Researcher inserts up-to-date sources and validates references in outputs.
• Domain Specialist validates domain-specific accuracy and regulatory considerations.

Tool Governance and Permission Rules

• Commands and edits are allowed only within approved directories and tools.
• API calls require tokens from secure vaults; never log secrets.
• Secrets, credentials, and production endpoints are restricted to authorized agents.
• All production changes require an approval gate and audit trail.

Code Construction Rules

• Write modular, well-documented code blocks; keep changes minimal and traceable.
• Follow defined memory keys and sources; avoid duplicate content.
• Use deterministic inputs and outputs; document any non-deterministic behavior.
• Validate schemas before commit; fail fast on schema violations.

Security and Production Rules

• Isolate environments; keep staging and production separate and protected.
• Audit all actions; maintain an immutable log of agent interactions.
• Do not expose secrets in code, logs, or outputs.
• Enforce least-privilege access for all agents.

Testing Checklist

• Unit tests for each agent type.
• Integration tests for multi-agent handoffs.
• End-to-end acceptance tests for the workflow.
• Security and vault access checks.
• Regression tests for changes in the AGENTS.md template.

Common Mistakes to Avoid

• Overloading one agent with tasks outside its scope.
• Unlogged handoffs or missing memory updates.
• Ignoring sources of truth or allowing drift in outputs.
• Releasing to production without approvals or security reviews.

FAQ

What is this AGENTS.md Template for?

This AGENTS.md Template provides a complete operating manual for AI coding agents in documentation and technical writing workflows, supporting single-agent and multi-agent orchestration with defined roles and governance.

Can I use this AGENTS.md Template for different workflows?

Yes, it is designed to support documentation and technical writing tasks across an agent roster (planner, implementer, reviewer, tester, researcher, domain specialist) and to enable multi-agent collaboration.

How are agent handoffs defined in this AGENTS.md Template?

Handoff rules specify when and how outputs are passed between planner, implementer, reviewer, tester, and domain specialist, including memory updates and sources of truth alignment.

What about security and production guidance?

Secrets are stored in a vault; environment isolation is enforced for staging and production; and production changes require gated approvals and audit trails.

How do I validate agent outputs?

Validation uses defined rules: schema checks, automated tests (unit, integration, E2E), and human review for high-risk outputs.