AGENTS.md Template for Full Text Search System Design

Overview

AGENTS.md template for full text search system design provides a copyable operating manual that governs AI coding agents in a multi-agent orchestration pattern. It describes the agent workflow, governance, memory, handoffs, and validation rules needed to build a reliable full-text search system. It serves both single-agent and multi-agent orchestration scenarios and delivers a concrete template you can paste into an AGENTS.md file to establish project-level operating context.

When to Use This AGENTS.md Template

When designing a full-text search system that relies on multiple AI agents working together
When you need explicit roles, handoff rules, and governance to avoid context drift
When you must enforce security, data handling, and deployment controls
When you want a copyable baseline that teams can adapt to their data sources and indexing stacks

Copyable AGENTS.md Template

# AGENTS.md
Project role: The AI coding agents are organized to design, implement, and govern a full-text search system using multi-agent orchestration. All agents share a common context and adhere to strict handoff rules and security requirements.
Agent roster and responsibilities:
- Planner: defines the overall task plan for indexing, query planning, ranking, and evaluation.
- Ingestor: ingests data from sources, normalizes, deduplicates, and validates quality.
- Indexer: builds and updates the inverted index and ensures consistency with the data source.
- Retriever: executes search queries and surfaces candidate results to the ranking model.
- RelevanceModel: re-ranks results based on features including context, recency, and quality signals.
- Evaluator: monitors quality metrics, drift, and SLA compliance.
- Orchestrator: coordinates across agents, maintains memory, enforces governance, and drives escalation.
- Researcher: provides validation data, test corpora, and external references.
- Domain Specialist: provides domain constraints and domain-specific ranking cues.
Supervisor or orchestrator behavior:
- The Orchestrator maintains the master task plan, ensures memory consistency, applies versioning, and enforces SLAs. It mediates conflicts and escalates issues to human review when needed.
Handoff rules between agents:
- Planner outputs a TaskPlan to Ingestor and Indexer. Ingestor returns IngestResults to Indexer. Indexer updates the Index. Retriever uses the updated Index and passes results to RelevanceModel. RelevanceModel returns ranked results to Evaluator. Evaluator flags quality issues and triggers Escalation if needed.
Context memory and source-of-truth rules:
- A central Context store provides shared state and memory with versioned snapshots. The canonical data source is the data lake and the index store; all agents reference strict IDs and a single source of truth.
Tool access and permission rules:
- Agents may call ingestion, indexing, and search APIs only via the Orchestrator. Secrets must be retrieved from a secure vault. Production changes require explicit supervisor approval. No direct shell or destructive actions.
Architecture rules:
- Modular, with well-defined interfaces between Planner, Ingestor, Indexer, Retriever, RelevanceModel, and Evaluator. Idempotent operations, deterministic outputs, and auditable traces.
File structure rules:
- Place agent implementations under agents/ and maintain a shared core under core. Do not create unrelated folders.
Data API and integration rules:
- Use JSON Lines for data input; preserve IDs; standardize metadata; respect rate limits; ensure data provenance.
Validation rules:
- Validate input against schema; test index integrity; verify query latency below thresholds.
Security rules:
- Encrypt data at rest and in transit; restrict access; audit every action; protect secrets.
Testing rules:
- Unit tests for each agent; integration tests across the pipeline; end-to-end tests with realistic workloads.
Deployment rules:
- CI/CD with canary deployments; rollback paths; feature flags; automated health checks.
Human review and escalation rules:
- Configure explicit triggers for human review when drift, failure, or policy violations occur.
Failure handling and rollback rules:
- If a failure occurs, revert to the last good index, restore data integrity, and replay tasks from the last checkpoint.
Things Agents must not do:
- Do not bypass governance, bypass memory isolation, or perform unsupervised production changes.

Recommended Agent Operating Model

The agent operating model assigns clear ownership and decision boundaries. The Planner defines objectives and task plans; Ingestor and Indexer execute data preparation and indexing; Retriever and RelevanceModel manage search quality; Evaluator monitors metrics and triggers escalation; the Orchestrator enforces governance, memory, and handoffs. Escalation paths exist for drift, SLA violations, or policy breaches.

Recommended Project Structure

project-fts/
  agents/
    planner/
    ingestor/
    indexer/
    retriever/
    reranker/
    evaluator/
    tester/
    domain_specialist/
    researcher/
  orchestrator/
  models/
  data/
  configs/
  deployments/
  tests/
  docs/
  workflows/

Core Operating Principles

Single source of truth across all agents
Explicit, auditable handoffs with versioned context
Idempotent, deterministic actions
Clear memory boundaries and sandboxed contexts
Observability with metrics and traces
Secure handling of data, secrets, and access controls

Agent Handoff and Collaboration Rules

Planner communicates TaskPlan to Ingestor and Indexer; Implementers must publish completion status back to Orchestrator
Ingestor hands off validated data to Indexer or Retriever when ready
Indexer hands off updated index to Retriever and RelevanceModel for query processing
RelevanceModel yields ranked results to Evaluator; Evaluator may request human review for anomalies
Domain Specialist and Researcher provide domain-specific cues and data during evaluation

Tool Governance and Permission Rules

All tool calls pass through the Orchestrator; direct access to production services is prohibited
Secrets must be retrieved from a secure vault; secret rotation is enforced
All changes are logged and auditable; approvals required for production deployments
Access to indexing, search, and data ingestion tools is restricted by role

Code Construction Rules

Write modular, testable code with clear interfaces
Keep functions small, deterministic, and idempotent
Version all artifacts and configurations
Avoid hidden side effects and context drift
Do not duplicate work across agents; share common utilities

Security and Production Rules

Encrypt data at rest and in transit; use least privilege access
Audit trails for all actions; monitor for anomalous activity
Deployment must pass runbooks and human approval in production

Testing Checklist

Unit tests for each agent
Integration tests across Planner, Ingestor, Indexer, Retriever, RelevanceModel, Evaluator
End-to-end tests with realistic workloads
Performance tests for indexing and query latency
Security and QA checks before deployment

Common Mistakes to Avoid

Assuming single-agent suffices for a multi-step workflow
Unbounded memory or state drift across agents
Lax handoffs and missing provenance
Overlooking security and access controls

FAQ

What is the purpose of this AGENTS.md template for full text search system design?

This AGENTS.md template defines the operating manual for AI coding agents to design, implement, and govern a full text search workflow with multi agent orchestration.

Who are the agents and what are their responsibilities?

The template lists Planner, Ingestor, Indexer, Retriever, RelevanceModel, Evaluator, Orchestrator, Researcher, and Domain Specialist, each with explicit duties and handoff rules.

How are handoffs and state shared between agents?

Handoffs are governed by TaskPlan objects, shared Context memory, and a canonical source of truth. The Orchestrator enforces sequence and versioning to avoid drift.

What are the security and data-handling rules?

Data handling emphasizes encryption, access controls, secrets management, audit logging, and avoidance of PII leakage. Production actions require approvals.

How is testing and deployment governed?

The template requires unit, integration, and end-to-end tests; controlled deployments with canary and rollback paths; and monitoring to trigger human review if SLA is breached.

Target User

Use Cases