AGENTS.md Template for News Feed Architecture

Overview

This AGENTS.md template for News Feed Architecture provides a copyable operating manual for coordinating AI coding agents in a multi-agent news feed workflow. It defines roles, handoffs, context, and governance for both single-agent and multi-agent orchestration.

Direct answer: Use this as the project-level operating context to govern ingest, curation, ranking, and publishing with clear handoffs and a central source of truth.

When to Use This AGENTS.md Template

When building an AI-powered news feed that requires coordinated actions across multiple agents.
When you need strict handoff rules, a single source of truth, and auditable decisions.
When your team requires reproducible project-wide operating context for tooling, data sources, and APIs.
When integrating content ingestion, ranking, recommendation signals, and publishing pipelines.
When you want a copyable template to bootstrap a news feed workflow in AGENTS.md.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: News Feed Orchestrator for AI coding agents in a multi-agent news feed architecture.

Agent roster:
- IngestAgent: fetches sources, deduplicates, normalizes, stores raw items in the Source of Truth.
- CurationAgent: evaluates items for quality, safety, and policy compliance.
- RankingAgent: scores and ranks items for feed placement.
- PublisherAgent: formats and publishes feed items to downstream systems.
- MonitorAgent: observes system health, metrics, and alert on anomalies.
- Orchestrator: coordinates all agents, enforces handoffs, memory boundaries, and state consistency.

Supervisor or orchestrator behavior:
- The Orchestrator enforces sequence: Ingest → Curation → Ranking → Publisher.
- Triggers parallel tasks where possible, but preserves deterministic order for gating.
- Maintains a per-feed memory and a central Source of Truth; ensures idempotency.

Handoff rules between agents:
- IngestAgent → CurationAgent with item metadata and provenance.
- CurationAgent → RankingAgent with quality gate outcomes and scoring hints.
- RankingAgent → PublisherAgent with final ranking decisions and formatting data.
- If any step fails, escalate to MonitorAgent and trigger rollback or re-ingest as appropriate.

Context, memory, and source-of-truth rules:
- All agents read/write to a central NewsFeedDB (Source of Truth).
- Memory scope is per-feed; items tracked by id; memory entries expire after 30 days unless archived.
- Provenance data includes source, ingestion timestamp, and agent version.

Tool access and permission rules:
- Agents may call fetch APIs, content APIs, and ranking services; API keys in Secrets vault.
- All tool actions are logged with agent id and timestamp.
- Do not expose secrets in logs or outputs.

Architecture rules:
- Microservice-like components; idempotent operations; event-driven where feasible; structured JSON payloads.
- Prefer stateless compute; use queues for coordination; enforce versioned contracts.

File structure rules:
- news-feed/
  - agents/
    - ingest/
      - ingest_agent.py
      - ingest_config.json
    - curate/
      - curate_agent.py
    - rank/
      - ranking_agent.py
    - publish/
      - publisher_agent.py
  - orchestrator/
    - orchestrator.py
  - configs/
    - default.yaml
  - data/
    - sources/
  - tests/
    - unit/
    - integration/
  - docs/

Data, API, or integration rules when relevant:
- Data types: NewsItem {id, title, body, url, source, published_at, categories, score}
- Respect per-source quotas; backoff on 429s; schema validation before ingest.

Validation rules:
- Validate item schema before ingest; enforce unique IDs; required fields must exist.

Security rules:
- Secrets stored securely; no secrets in logs; access control per agent; auditable actions.

Testing rules:
- Unit tests for each agent; integration tests for end-to-end flows; simulate failures and retries.

Deployment rules:
- CI/CD with feature flags; canary deployments; rollback plan and memory snapshots.

Human review and escalation rules:
- Flagged content or policy violations escalate to human editor; publish only after approval.

Failure handling and rollback rules:
- Retry with exponential backoff; if persistent failures, rollback to last good feed snapshot.

Things Agents must not do:
- Do not bypass the Source of Truth; do not leak secrets; do not mutate shared memory outside scoped boundaries.
- Do not perform unsanctioned publishing or config changes.

Recommended Agent Operating Model

The operator model defines clear agent roles, decision boundaries, and escalation paths to enable reliable, auditable multi-agent behavior in a news feed workflow.

IngestAgent captures and fingerprints items; boundary: only ingest sources on allowed domains.
CurationAgent enforces quality and policy constraints; boundary: only approve items meeting safety and policy rules.
RankingAgent exposes configurable scoring signals; boundary: rank within allowed score range; respects fairness constraints.
PublisherAgent publishes to downstream systems; boundary: cannot publish without prior approvals and scoring.
Orchestrator handles inter-agent handoffs, error handling, and state consistency; escalation to Human Review when needed.

Recommended Project Structure

news-feed/
  agents/
    ingest/
      ingest_agent.py
      ingest_config.json
    curate/
      curate_agent.py
    rank/
      ranking_agent.py
    publish/
      publisher_agent.py
  orchestrator/
    orchestrator.py
  configs/
    default.yaml
  data/
    sources/
  tests/
    unit/
    integration/
  docs/

Core Operating Principles

Idempotent actions and deterministic decisions across agents.
Single source of truth with per-feed memory scope.
Explicit handoffs with provenance and versioned contracts.
Observability: structured logs, metrics, and traces for all agents.
Least-privilege tool access and secrets management.

Agent Handoff and Collaboration Rules

Planner/Orchestrator: defines task graph, validates preconditions, assigns agents to tasks.
Implementer: executes specific actions per agent, adheres to memory boundaries.
Reviewer: validates outputs against schema and policy rules; approves for publishing or escalates.
Tester: runs end-to-end checks and regression tests for new changes.
Researcher/Domain Specialist: provides content-related constraints, sources, and policy guidance.

Tool Governance and Permission Rules

Command execution is scoped per agent role; secrets never appear in outputs.
File edits must be tracked; API calls require approval gates when necessary.
Production endpoints require explicit feature flags and testing in staging first.
All tool usage is auditable; status and outcomes are recorded in the central feed log.

Code Construction Rules

Write modular, composable agents with clear interfaces and contracts.
Follow versioned schemas for data interchange; avoid breaking changes without deprecation plan.
Use idempotent ingestions and safe retries with backoff.
Document all dependencies and side effects in code comments and AGENTS.md.

Security and Production Rules

Secrets are stored in a vault; never hard-coded in code or logs.
Access to production systems is gated; require approval for deployments and rollbacks.
All outputs are sandboxed; prevent data leakage across feeds or users.

Testing Checklist

Unit tests for each agent’s logic and validation rules.
Integration tests covering end-to-end ingest, curate, rank, publish cycles.
Contract tests for API calls and data formats.
End-to-end tests with simulated failure scenarios and rollback checks.

Common Mistakes to Avoid

Skipping source-of-truth enforcement and enabling context drift.
Overlapping memory writes or unchecked handoffs causing duplicate items.
Unsafe tool access or leaking credentials in logs.
Unversioned schema changes without a deprecation policy.

FAQ

What is the purpose of this AGENTS.md Template for News Feed Architecture?

To provide a copyable, project-level operating manual that governs single-agent and multi-agent workflows for a news feed pipeline, including roles, handoffs, and governance.

How does multi-agent orchestration handle content freshness and ranking?

IngestAgent pulls items, CurationAgent validates quality, RankingAgent scores and orders, and PublisherAgent publishes results. Orchestrator enforces sequence and consistency with a central source of truth.

Who handles human review and escalation?

Human Review is invoked by the Reviewer when policy or quality concerns arise; escalation paths are defined in the AGENTS.md template and can trigger a staged publish.

How are tool permissions and secrets managed?

Secrets live in a vault, access is role-based, and outputs are scrubbed of sensitive data before logging. All tool calls are auditable.

How do agents recover from a failure or rollback?

Failures trigger retries with exponential backoff; persistent failures rollback to the last good feed snapshot and alert the MonitorAgent for remediation.

Target User

Use Cases