AGENTS.md Template for AGENTS.md template for Product Discovery Teams

Overview

Direct answer: This AGENTS.md template is a living operating manual for product discovery teams using AI coding agents. It governs a product discovery workflow across single-agent and multi-agent orchestration, detailing roles, governance, memory, and handoffs.

In this template, you can paste into an AGENTS.md file to establish project-level operating context for both standalone agents and collaborative, multi-agent setups. It defines the roster, responsibilities, rules, and references for tool access, memory, and source-of-truth to keep outputs auditable and reusable.

When to Use This AGENTS.md Template

• When starting a new product discovery initiative that will use AI agents to research, analyze, and validate hypotheses.
• When you need clear handoff rules between planners, researchers, and validators in a multi-agent setup.
• When establishing tool governance, memory, and source-of-truth to avoid context drift.
• When you want a copyable project-level operating context that engineers and researchers can share and review.

Copyable AGENTS.md Template

# AGENTS.md

Template: AGENTS.md template for Product Discovery

Project Role
- Product Discovery Platform Team: Orchestrator responsible for aligning single-agent and multi-agent workflows across research, market analysis, and hypothesis validation.

Agent roster and responsibilities
- PlannerAgent: Defines workflow plan, task sequencing, and handoffs.
- ResearcherAgent: Gathers user, stakeholder, and market insights; maintains memory of sources.
- InterviewAgent: Schedules and conducts user interviews; extracts actionable signals.
- MarketAnalystAgent: Analyzes market trends, competitors, and opportunities.
- HypothesisAgent: Proposes, ranks, and updates product hypotheses based on evidence.
- ImplementerAgent: Executes experiments, prototypes, or data collection tasks.
- ValidatorAgent: Validates outputs against acceptance criteria and success metrics.
- ReviewerAgent: Performs quality review before final publication or decision.
- DataBridgeAgent: Handles data integrations and ensures data provenance.
- DomainExpertAgent: Provides domain-specific guidance and checks compliance with domain constraints.

Supervisor or orchestrator behavior
- The PlannerAgent coordinates all work, assigns tasks, and triggers handoffs to researchers, analysts, and implementers.
- The orchestrator enforces cadence, ensures memory updates, and preserves source-of-truth across tools and outputs.
- The supervisor raises escalation prompts if outputs deviate from acceptance criteria or if a risk is detected.

Handoff rules between agents
- Planner > Researcher: Provide research plan, sources, and questions to answer.
- Researcher > Interviewer: Share interview guides and transcripts; escalate ambiguous signals.
- Interviewer > MarketAnalyst: Share market signals and competitor references.
- MarketAnalyst > HypothesisAgent: Propose hypotheses and tie to evidence.
- HypothesisAgent > Implementer: Translate hypotheses into experiments or data collection tasks.
- Implementer > Validator: Report results, raw data, and observed effects.
- Validator > Reviewer: Confirm pass/fail and suggest improvements.
- DataBridgeAgent > all: Ensure data provenance and access controls are preserved during handoffs.

Context, memory, and source-of-truth rules
- All outputs are appended to a central memory store with citations to sources.
- Memory entries are tagged with task IDs, agent roles, and timestamps.
- Source-of-truth is the canonical document or dataset used to justify decisions; references must be preserved in each artifact.

Tool access and permission rules
- Agents may call external APIs within approved scopes.
- Secrets must be accessed via a secure vault and never hard-coded.
- Write access is restricted to designated agents per area (planner, implementer, validator, etc.).
- All tool usage is logged and auditable.

Architecture rules
- Use a modular, open-core architecture with a pluggable planner, rosters, and memory adapters.
- Outputs should be versioned and traceable to their sources.

File structure rules
- Keep outputs organized under an agents/ directory with one folder per agent.
- Memory and provenance data stored under memory/.
- Configs and policies under config/.

Data, API, or integration rules when relevant
- Data collection must follow privacy and consent guidelines.
- All API calls must include trace IDs and be idempotent where possible.
- Integrations should be decoupled behind adapters.

Validation rules
- All hypotheses, experiments, and outputs must be verifiable against acceptance criteria.
- Validation must include success metrics and link back to evidence.

Security rules
- Secrets in a dedicated vault; rotate monthly or upon risk.
- Access rights follow least privilege.
- Production keys never embedded in code.

Testing rules
- Unit tests for each agent’s logic; integration tests for handoffs.
- End-to-end tests simulate multi-agent discovery flow.

Deployment rules
- Deploy changes to agent templates via versioned releases.
- Rollback plan documented for each deployment.

Human review and escalation rules
- Any uncertain decision or high-risk hypothesis requires human review before adoption.
- Escalation to a product manager or founder when confidence is below threshold.

Failure handling and rollback rules
- If an experiment fails, revert changes, preserve evidence, and notify stakeholders.
- Rollbacks must preserve memory integrity and source-of-truth references.

Things Agents must not do
- Do not access production user data without explicit authorization.
- Do not mutate canonical sources without traceable approvals.
- Do not delete historical evidence without a retention plan.

Recommended Agent Operating Model

Roles and decision boundaries: Planner orchestrates and delegates; Researchers, Analysts, and Implementers execute tasks within defined guardrails. Reviewers and Validators ensure quality and compliance. Escalations move to Human Review when confidence drops below predefined thresholds.

Recommended Project Structure

project-root/
  /agents
    /planner
    /researcher
    /interviewer
    /market-analyst
    /hypothesis
    /implementer
    /validator
    /reviewer
    /data-bridge
    /domain-expert
  /memory
  /data
  /docs
  /tests
  /scripts
  /config

Core Operating Principles

• Operate with clear ownership and auditable decisions.
• Maintain a single source of truth for each product discovery artifact.
• Suppress drift with strict handoffs and memory tagging.
• Prioritize privacy, security, and compliance in every inquiry.
• Validate hypotheses with replicable experiments and evidence.

Agent Handoff and Collaboration Rules

Rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents:

• Planner coordinates all handoffs; keeps memory updated with task and result IDs.
• Researcher feeds evidence with sources; handoffs to Interviewer and MarketAnalyst when concrete signals emerge.
• Interviewer collects user feedback; passes to MarketAnalyst and HypothesisAgent with clear user signals.
• MarketAnalyst ties signals to market context; suggests hypotheses to HypothesisAgent.
• HypothesisAgent translates hypotheses into testable experiments for Implementer.
• Implementer runs experiments; returns data and observations to Validator.
• Validator checks results against criteria; if pass, signals Reviewer for final quality check.
• DomainExpert verifies domain-specific constraints and regulatory alignment where applicable.

Tool Governance and Permission Rules

• Commands, edits, and API calls require role-based permission and logging.
• Secrets stored in vault; never hard-coded.
• Production systems protected by approval gates and audit logs.
• No circumventing governance; all integrations pass through adapters.

Code Construction Rules

• Follow the AGENTS.md structure and maintain one canonical AGENTS.md per workflow.
• Do not introduce direct edits to production data or artifacts without tests and approvals.
• Keep outputs deterministic; avoid non-deterministic prompts in critical steps.
• Document all decisions with sources and evidence in memory.

Security and Production Rules

Security-first workflow with least privilege, secret management, and monitored deployments. Use sane defaults and audit trails for all discovery outputs.

Testing Checklist

• Unit tests for each agent logic.
• Integration tests for handoffs between Planner, Researcher, and Implementer.
• End-to-end tests simulating a product discovery sprint.
• Manual smoke tests for new templates in a staging environment.

Common Mistakes to Avoid

• Skipping memory tagging or source-of-truth references.
• Allowing handoffs to drift without explicit criteria.
• Hiding decisions from stakeholders or bypassing human review when risk is high.
• Overly coupling agents to production systems without safe gating.

FAQ

What is an AGENTS.md Template for Product Discovery?

The template provides a full operating manual for product discovery teams using AI coding agents, enabling single-agent and multi-agent orchestration with clear roles, handoffs, and governance.

How does multi-agent orchestration work in this template?

It defines a planner that sequences work, researchers and analysts that gather evidence, implementers that run experiments, and validators/reviewers that ensure quality and compliance, with explicit handoff rules and memory management.

How are handoffs between agents managed?

Handoffs are defined as Planner > Researcher, Researcher > Interviewer/MarketAnalyst, MarketAnalyst > HypothesisAgent, HypothesisAgent > Implementer, Implementer > Validator, Validator > Reviewer, with DataBridge ensuring provenance on all transitions.

What are the security considerations for product discovery agents?

Secrets must be stored in a vault, access granted on least privilege, and all production integrations gated and auditable.

How do you validate discoveries before shipping?

All hypotheses and experiments must meet acceptance criteria and be supported by verifiable evidence linked to sources in memory.