# AgentAtlas Production Agent Starter Kit

Reviewed 2026-07-26. Template version 1.0.0.

This consolidated edition contains all 15 files. For normal repository use, download the individual files from https://agentatlas.dev/starter-kit.

---

# File: AGENTS.md

# AGENTS.md

> Give coding agents the durable project map, commands, conventions, boundaries, and verification steps they need before changing the repository. Keep instructions concrete, scoped, and close to the files they govern.

**Decision rule:** Put stable repository-wide operating guidance in AGENTS.md. Move task-specific procedures into Skills and feature-specific intent into specifications, plans, or task records.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Project map

> Orient an agent without forcing it to rediscover the repository or infer ownership.

- **Purpose:** <Describe the product and the outcome this repository owns>
- **Important paths:** <List the directories, packages, generated files, and ownership boundaries that matter>
- **Instruction scope:** <Explain whether nested AGENTS.md files override guidance for subprojects>

## Commands and environment

> Provide exact, non-interactive commands and identify prerequisites that cannot be inferred safely.

- **Install:** <Give the dependency installation command and required runtime versions>
- **Develop:** <Give the local development command and expected URL or process>
- **Verify:** <List focused tests, full tests, type checks, linting, and build commands>

## Conventions and change policy

> State the rules that meaningfully affect implementation and review.

- **Code conventions:** <Name architecture, style, naming, and dependency rules with examples where useful>
- **Generated or protected files:** <Identify files agents must not hand-edit or overwrite>
- **Change boundaries:** <Describe acceptable scope, compatibility expectations, migrations, and documentation updates>

## Safety and completion

> Make consequential actions and the definition of done explicit.

- **Approval required:** <List external writes, deployments, secrets, destructive changes, or costs that require approval>
- **Security:** <State data-handling, authorization, dependency, and secret-management requirements>
- **Done:** <Define the evidence an agent must return before claiming the task is complete>

## Related AgentAtlas field guides

- [Agents](https://agentatlas.dev/topics/agents)
- [Specifications](https://agentatlas.dev/topics/specifications)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)

## Primary references

- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — The distinction between fixed workflows and model-directed agents, plus the recommendation to add complexity only when measured outcomes justify it.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Agent run loops, state management, continuation strategies, and the operational boundary between the SDK and application-owned state.
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks.
- [AGENTS.md specification](https://agents.md/) — Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: SKILL.md

---
name: example-skill
description: Performs one bounded, repeatable workflow. Use when the requested task matches the workflow described in this Skill.
metadata:
  version: "0.1.0"
---

# SKILL.md

> Package one bounded, repeatable workflow with a discoverable trigger, explicit inputs and outputs, ordered instructions, edge-case handling, and validation. Keep supporting references and scripts inspectable.

**Decision rule:** Create a Skill when the same specialized workflow should activate on demand across tasks or projects. Keep durable repository rules in AGENTS.md and one-off work in the task itself.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Trigger and outcome

> Make it easy for an agent to decide when the Skill applies and what successful completion means.

- **Use when:** <List the user phrases, file types, or task conditions that should activate this Skill>
- **Do not use when:** <Name nearby tasks that require a different workflow or human judgment>
- **Outcome:** <Describe the verifiable artifact or state this Skill produces>

## Inputs and outputs

> Declare required context and a stable return contract before the procedure.

- **Required inputs:** <List files, parameters, credentials, and assumptions the workflow needs>
- **Output contract:** <Define files, structured fields, messages, or evidence returned>
- **Dependencies:** <List optional scripts, references, assets, tools, and environment requirements>

## Procedure

> Write ordered steps with decision points, checkpoints, and the smallest safe tool scope.

- **Prepare:** <Describe read-only discovery and precondition checks>
- **Execute:** <List the ordered implementation steps and allowed tools>
- **Verify:** <State the checks that must pass before returning the result>

## Failures and progressive disclosure

> Keep the main file focused while making recovery and deeper material discoverable.

- **Edge cases:** <List ambiguous, malformed, missing, or unsafe inputs and the required response>
- **Recovery:** <Explain retry limits, cleanup, rollback, and escalation>
- **References:** <Link focused files under references, scripts, or assets using relative paths>

## Related AgentAtlas field guides

- [Skills](https://agentatlas.dev/topics/skills)
- [Tasks](https://agentatlas.dev/topics/tasks)
- [Tools and MCP](https://agentatlas.dev/topics/tools-mcp)

## Primary references

- [Agent Skills specification](https://agentskills.io/specification) — The portable Skill directory structure, required SKILL.md metadata, progressive disclosure, and optional resource folders.
- [Build skills for ChatGPT and Codex](https://learn.chatgpt.com/docs/build-skills) — How Skills are authored, discovered, loaded, and used across OpenAI agent surfaces.
- [Agentic SDD workflow](https://github.github.com/spec-kit/reference/agentic-sdd.html) — Generating and analyzing implementation tasks after specification and planning quality gates.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries.
- [MCP specification](https://modelcontextprotocol.io/specification/) — The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations.
- [Connect Codex to MCP servers](https://learn.chatgpt.com/docs/extend/mcp) — How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: ARCHITECTURE.md

# ARCHITECTURE.md

> Describe system boundaries, responsibilities, data and control flow, trust zones, dependencies, failure behavior, and deployment topology so changes can be evaluated against an explicit operating model.

**Decision rule:** Use architecture documentation for durable system structure and cross-cutting constraints. Keep user-facing interaction detail in DESIGN.md and feature-specific implementation choices in PLAN.md.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Scope and boundaries

> State what the system owns, what it delegates, and where trust or organizational responsibility changes.

- **System purpose:** <Describe the outcomes and users this architecture supports>
- **In scope:** <List owned capabilities and data>
- **External boundaries:** <List providers, agents, tools, protocols, and teams outside the boundary>

## Components and flows

> Make runtime responsibilities and important state transitions inspectable.

- **Components:** <List each component, owner, responsibility, and interface>
- **Data flow:** <Describe inputs, persisted state, context assembly, outputs, and sensitive data movement>
- **Control flow:** <Describe orchestration, delegation, approvals, retries, and termination>

## Quality attributes and decisions

> Connect architecture choices to measurable constraints instead of framework preference.

- **Targets:** <Record reliability, latency, cost, security, privacy, and scale objectives>
- **Key decisions:** <Link the decision records that justify important tradeoffs>
- **Constraints:** <State provider, compliance, deployment, compatibility, and team constraints>

## Operations and evolution

> Explain how the system fails, recovers, changes, and proves compatibility.

- **Failure modes:** <List dependency, model, tool, data, queue, and authorization failures>
- **Deployment:** <Describe environments, release units, migration order, and rollback>
- **Evolution:** <Define compatibility promises, deprecation, and architecture review triggers>

## Related AgentAtlas field guides

- [Agent architecture](https://agentatlas.dev/topics/architecture)
- [Tools and MCP](https://agentatlas.dev/topics/tools-mcp)
- [Deployment and operations](https://agentatlas.dev/topics/deployment-operations)

## Primary references

- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes.
- [MCP specification](https://modelcontextprotocol.io/specification/) — The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations.
- [Connect Codex to MCP servers](https://learn.chatgpt.com/docs/extend/mcp) — How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: DESIGN.md

# DESIGN.md

> Design the human experience around bounded outcomes, visible system state, calibrated uncertainty, approval moments, recovery, and accessibility rather than treating the agent as an unrestricted chat box.

**Decision rule:** Use DESIGN.md to specify user interaction, feedback, control, and recovery. Keep system boundaries in architecture and implementation sequencing in the plan.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Users, jobs, and outcomes

> Anchor the experience in a real user job and an observable, verifiable measure of success.

- **Primary user:** <Describe role, expertise, incentives, and constraints>
- **Job:** <State the workflow and current pain without prescribing a solution>
- **Outcome:** <Define what the user can verify when the experience succeeds>

## Interaction and system state

> Show what the system knows, plans, is doing, and needs from the user.

- **Entry points:** <List triggers, inputs, defaults, and required context>
- **State model:** <Define idle, preparing, running, waiting, failed, canceled, and completed states>
- **Feedback:** <Describe progress, evidence, uncertainty, and tool activity shown to the user>

## Control and trust

> Place human judgment where authority or consequence changes.

- **Approvals:** <Name actions requiring preview, confirmation, or a second reviewer>
- **Corrections:** <Explain edit, retry, undo, cancel, and feedback behavior>
- **Disclosure:** <State how sources, sponsorship, limitations, and automation are labeled>

## Edge states and accessibility

> Design realistic failure and alternate-access paths before polish.

- **Empty and partial states:** <Describe missing context, no results, incomplete outputs, and degraded dependencies>
- **Failure recovery:** <Define actionable messages, retained work, escalation, and safe fallback>
- **Accessibility:** <Record keyboard, screen-reader, contrast, motion, focus, and language requirements>

## Related AgentAtlas field guides

- [Agent product design](https://agentatlas.dev/topics/agent-product-design)
- [Human approval](https://agentatlas.dev/topics/human-approval)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)

## Primary references

- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: SPEC.md

# SPEC.md

> Turn an intended outcome into testable behavior, requirements, constraints, non-goals, edge cases, and acceptance evidence before selecting implementation details or decomposing the work.

**Decision rule:** Specify what and why before deciding how. If a statement cannot be verified, clarified, or traced to a user outcome, tighten it before planning.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Problem and outcome

> Define the user-visible change and the evidence that it matters.

- **Problem:** <Describe the current workflow, pain, and affected user>
- **Desired outcome:** <State the observable behavior or state change>
- **Success measures:** <List product, quality, safety, and operational measures>

## Requirements and scenarios

> Write behavior precisely enough that each scenario can become an objective acceptance test.

- **Primary scenarios:** <List trigger, inputs, expected behavior, and output for each core path>
- **Edge scenarios:** <Cover missing, malformed, conflicting, unauthorized, canceled, and repeated actions>
- **Data:** <Define required fields, provenance, retention, correction, and deletion>

## Constraints and non-goals

> Prevent the implementation from silently expanding or violating a hard boundary.

- **Constraints:** <State security, privacy, compatibility, latency, cost, and compliance limits>
- **Non-goals:** <List plausible adjacent work explicitly excluded>
- **Open questions:** <Record unresolved ambiguity, owner, and deadline for each answer>

## Acceptance and traceability

> Connect each requirement to evidence and later implementation work.

- **Acceptance checks:** <Write objective checks for every required behavior and important failure path>
- **Approval:** <Name the product, design, security, legal, or operations reviewers required>
- **Traceability:** <Link plan decisions, tasks, tests, eval cases, telemetry, and release evidence>

## Related AgentAtlas field guides

- [Specifications](https://agentatlas.dev/topics/specifications)
- [Agent product design](https://agentatlas.dev/topics/agent-product-design)
- [Evals and verification](https://agentatlas.dev/topics/evals-verification)

## Primary references

- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks.
- [AGENTS.md specification](https://agents.md/) — Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents.
- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Pause, inspect, approve, reject, persist, and resume patterns for consequential tool calls across agent runs.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes.
- [Evaluation best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices) — Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes.
- [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) — Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: PLAN.md

# PLAN.md

> Translate an approved specification into a reversible technical approach, decision sequence, dependency-aware phases, validation strategy, deployment path, and rollback plan.

**Decision rule:** Plan the smallest sequence that proves the riskiest assumptions early. Keep the plan linked to the specification and regenerate tasks when the approach changes materially.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Approach and decisions

> Explain the implementation strategy and why it satisfies the specification.

- **Approach:** <Summarize components, data changes, interfaces, and control flow>
- **Key decisions:** <Record selected options, alternatives, tradeoffs, and evidence>
- **Assumptions:** <List assumptions to prove before broad implementation>

## Phases and dependencies

> Sequence work around risk, independently verifiable outputs, and real blockers.

- **Foundation:** <List blocking setup, schemas, contracts, and test harnesses>
- **Vertical slices:** <Define incremental user-visible or end-to-end capabilities>
- **Dependency order:** <Map blockers, parallel work, integration points, and owners>

## Verification and rollout

> Decide how each phase proves correctness before work begins.

- **Verification:** <Map unit, integration, end-to-end, eval, security, and manual checks to phases>
- **Observability:** <Name logs, metrics, traces, dashboards, and release signals>
- **Rollout:** <Describe migration, feature flags, cohorts, compatibility, and success gates>

## Risk and recovery

> Make failure containment and plan updates part of the implementation.

- **Risks:** <Rank technical, product, safety, privacy, cost, and schedule risks>
- **Mitigations:** <Assign preventive controls, owners, evidence, and review dates>
- **Rollback:** <Define stop conditions, reversible steps, data recovery, and communication>

## Related AgentAtlas field guides

- [Plans](https://agentatlas.dev/topics/planning)
- [Agent architecture](https://agentatlas.dev/topics/architecture)
- [Deployment and operations](https://agentatlas.dev/topics/deployment-operations)

## Primary references

- [Agentic SDD workflow](https://github.github.com/spec-kit/reference/agentic-sdd.html) — The ordered specification, clarification, planning, tasking, analysis, implementation, and convergence workflow.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: TASKS.md

# TASKS.md

> Decompose the plan into dependency-ordered work units with explicit inputs, scope, outputs, acceptance checks, ownership, status, and integration evidence suitable for people or delegated agents.

**Decision rule:** Create a separate task only when its output can be verified independently or its ownership and dependencies need explicit coordination. Avoid task fragmentation without a review boundary.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Task contract

> Use the same minimum outcome, scope, and verification contract for every work item.

- **Outcome:** <State the artifact or state change that completes the task>
- **Inputs and scope:** <List required context, allowed paths, dependencies, and explicit exclusions>
- **Acceptance:** <Define commands, tests, inspection, or evidence that verifies the output>

## Phases and dependencies

> Keep the executable queue aligned with the plan and specification.

- **Setup:** <List environment and harness tasks that unblock later work>
- **Foundational:** <List shared contracts, data, security, and architecture tasks>
- **Delivery phases:** <Group vertical work by user outcome and mark parallel-safe tasks>

## Work queue

> Make state, ownership, and handoffs visible without hiding unfinished work.

- **Ready:** <List unblocked tasks with owner and priority>
- **In progress:** <List active tasks, current evidence, and blocking questions>
- **Done:** <Record verification evidence, integration result, and links to changes>

## Integration and convergence

> Check the complete integrated outcome after every individual task and local verification passes.

- **Integration order:** <State merge, migration, release, and cross-task verification order>
- **Gap analysis:** <Compare completed work with the specification, plan, and acceptance checks>
- **Follow-up:** <Append discovered gaps with owners rather than hiding them in completion notes>

## Related AgentAtlas field guides

- [Tasks](https://agentatlas.dev/topics/tasks)
- [Plans](https://agentatlas.dev/topics/planning)
- [Multi-agent systems](https://agentatlas.dev/topics/multi-agent)

## Primary references

- [Agentic SDD workflow](https://github.github.com/spec-kit/reference/agentic-sdd.html) — The ordered specification, clarification, planning, tasking, analysis, implementation, and convergence workflow.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Planning transparency, composable workflow patterns, and matching orchestration complexity to task requirements.
- [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) — Subagent configuration, scoped roles, delegation behavior, and parallel work inside Codex.
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents) — Specialized subagent configuration, context isolation, tools, permissions, and delegation patterns.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: CONTEXT.md

# CONTEXT.md

> Control which instructions, examples, tools, retrieved facts, messages, and summaries reach the model; record their authority, provenance, freshness, token cost, and intended decision.

**Decision rule:** Include context only when it changes a named decision or reduces a measured failure. Retrieve current authoritative evidence instead of accumulating every available token.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Context inventory

> Identify every source of runtime tokens and the specific decision or behavior it supports.

- **Always loaded:** <List system instructions, repository policy, schemas, and stable constraints>
- **Retrieved:** <List knowledge stores, search, tools, ranking, and freshness requirements>
- **Runtime:** <List user input, session history, tool output, scratch state, and summaries>

## Selection and budget

> Prioritize relevant and authoritative context under realistic limits.

- **Budget:** <Allocate tokens or size limits by instruction, history, retrieval, tools, and output>
- **Ranking:** <Define relevance, authority, recency, diversity, and conflict rules>
- **Compaction:** <Describe summarization, truncation, checkpointing, and information that must survive>

## Provenance and conflict

> Make it possible to inspect why information was present and which source wins.

- **Provenance:** <Attach source, owner, timestamp, version, and retrieval reason>
- **Authority order:** <Define precedence for user intent, project policy, retrieved evidence, and model inference>
- **Sensitive context:** <State redaction, isolation, retention, and export restrictions>

## Evaluation

> Measure whether the context system helps rather than assuming more is better.

- **Quality:** <Test retrieval precision, groundedness, conflict resolution, and task success>
- **Efficiency:** <Measure tokens, latency, cache effectiveness, and repeated retrieval>
- **Failure cases:** <Test stale facts, prompt injection, distraction, compaction loss, and missing context>

## Related AgentAtlas field guides

- [Context engineering](https://agentatlas.dev/topics/context-engineering)
- [Memory and context](https://agentatlas.dev/topics/memory-context)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)

## Primary references

- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Treating context as a finite resource and curating instructions, tools, external data, history, and summaries across long-running agents.
- [How Claude remembers your project](https://code.claude.com/docs/en/memory) — Repository instruction hierarchy, project memory, scoped rules, and how persistent context is discovered and loaded.
- [Sessions](https://openai.github.io/openai-agents-python/sessions/) — Session memory, storage choices, history limits, compaction, resumption, and operational persistence patterns.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: MEMORY.md

# MEMORY.md

> Define what the system remembers across turns or runs, why each memory type exists, how identity and provenance are preserved, and how information is corrected, expired, deleted, and evaluated.

**Decision rule:** Persist information only when it has a defined future use, owner, retention rule, and correction path. Do not treat a conversation transcript as an undifferentiated memory system.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Memory taxonomy

> Separate state with different authority, lifetime, and privacy properties.

- **Session state:** <Define transient conversation and workflow state>
- **Durable facts:** <Define user, project, organizational, and domain knowledge worth persisting>
- **Derived memory:** <Define summaries, preferences, patterns, and their confidence or source>

## Identity and storage

> Prevent memory from crossing the wrong user, workspace, tenant, or authority boundary.

- **Identity keys:** <Define user, session, project, tenant, and agent identifiers>
- **Storage:** <List systems of record, indexes, encryption, access policy, and backups>
- **Retrieval:** <Define queries, ranking, scope, confidence, and empty-result behavior>

## Lifecycle and control

> Give users and operators meaningful control over remembered information.

- **Write policy:** <State what can be written automatically and what requires confirmation>
- **Correction:** <Describe inspection, edit, contradiction, source update, and invalidation>
- **Retention:** <Define expiration, deletion, legal hold, export, and downstream cleanup>

## Quality and privacy

> Evaluate benefits and harms using realistic longitudinal cases.

- **Quality tests:** <Measure retrieval precision, stale-memory behavior, correction, and compaction loss>
- **Privacy tests:** <Test tenant isolation, consent, sensitive inference, deletion, and data minimization>
- **Operational signals:** <Monitor write volume, retrieval use, conflicts, corrections, and deletion failures>

## Related AgentAtlas field guides

- [Memory and context](https://agentatlas.dev/topics/memory-context)
- [Governance](https://agentatlas.dev/topics/governance)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)

## Primary references

- [Sessions](https://openai.github.io/openai-agents-python/sessions/) — Session memory, storage choices, history limits, compaction, resumption, and operational persistence patterns.
- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Treating context as a finite resource and curating instructions, tools, external data, history, and summaries across long-running agents.
- [AGENTS.md specification](https://agents.md/) — Versioned repository instructions that make build, test, style, and contribution requirements available to agents.
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: TOOLS.md

# TOOLS.md

> Inventory model-callable capabilities and make schemas, descriptions, authentication, authorization, side effects, idempotency, errors, timeouts, output limits, and approval requirements explicit.

**Decision rule:** Expose the narrowest capability that supports a named workflow. Use MCP for reusable cross-system access and ordinary application functions for capabilities owned inside one product boundary.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Tool inventory and contract

> Make tool selection and consequences understandable to both models and reviewers.

- **Capability:** <Name the user outcome and why a model needs this tool>
- **Schema:** <Define narrow typed inputs, outputs, defaults, and validation>
- **Side effects:** <Classify read-only, reversible, external write, financial, destructive, or privileged behavior>

## Identity and authority

> Keep authentication separate from the permission to perform a specific action.

- **Authentication:** <Define caller, user, service, tenant, and credential lifecycle>
- **Authorization:** <Define resource- and action-level policy checked at execution time>
- **Approval:** <List arguments and actions requiring preview, confirmation, or a second reviewer>

## Reliability and observability

> Specify predictable behavior under repetition, delay, partial failure, and large outputs.

- **Failure contract:** <Define typed errors, retryability, timeout, cancellation, and partial results>
- **Idempotency:** <Define duplicate detection, keys, replay, and exactly-once assumptions>
- **Telemetry:** <Record tool name, sanitized arguments, authorization, latency, result, and correlation identifiers>

## Verification

> Test the contract as adversarially as the model and external systems will use it.

- **Contract tests:** <Cover valid, malformed, boundary, oversized, and unsupported inputs>
- **Safety tests:** <Cover prompt injection, confused deputy, cross-tenant, approval bypass, and revocation>
- **Operational tests:** <Cover timeout, retry, duplicate execution, dependency failure, and recovery>

## Related AgentAtlas field guides

- [Tools and MCP](https://agentatlas.dev/topics/tools-mcp)
- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)
- [Observability](https://agentatlas.dev/topics/observability)

## Primary references

- [MCP specification](https://modelcontextprotocol.io/specification/) — The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations.
- [Connect Codex to MCP servers](https://learn.chatgpt.com/docs/extend/mcp) — How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities.
- [Codex security](https://developers.openai.com/codex/security) — Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration.
- [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) — Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: DELEGATION.md

# DELEGATION.md

> Define when work may be delegated, which specialized agents exist, what context and authority each receives, how handoffs are structured, and who verifies and synthesizes the returned work.

**Decision rule:** Delegate only when a subtask has a bounded input and independently verifiable output or requires a distinct trust boundary. Keep tightly coupled reasoning in one context.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Delegation policy

> Prevent multi-agent coordination cost and fragmented context from becoming the default architecture.

- **Delegate when:** <List clean partitions, expertise needs, isolation, or parallelism that justify delegation>
- **Do not delegate when:** <List shared-state, tightly coupled, high-context, or authority-sensitive work>
- **Budget:** <Define maximum agents, turns, time, tokens, cost, and retry limits>

## Agent roster

> Describe specialization without granting unnecessary tools or context.

- **Role:** <Name each agent's bounded responsibility and expected output>
- **Context:** <List instructions, files, data, and history the agent receives>
- **Authority:** <List tools, resources, writes, approvals, and prohibited actions>

## Handoff contract

> Make delegated work reviewable without replaying hidden reasoning.

- **Input contract:** <Define objective, scope, dependencies, constraints, and acceptance evidence>
- **Return contract:** <Define artifacts, findings, uncertainties, checks, and unresolved blockers>
- **Failure contract:** <Define timeout, partial return, escalation, cancellation, and cleanup>

## Synthesis and verification

> Assign responsibility for overlap, contradictions, integration, and whole-system quality.

- **Synthesizer:** <Name the agent or person that owns the combined result>
- **Conflict resolution:** <Define authority order and evidence required when outputs disagree>
- **Final verification:** <Test the integrated outcome, permissions, traceability, and acceptance checks>

## Related AgentAtlas field guides

- [Multi-agent systems](https://agentatlas.dev/topics/multi-agent)
- [Tasks](https://agentatlas.dev/topics/tasks)
- [Agents](https://agentatlas.dev/topics/agents)

## Primary references

- [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) — Subagent configuration, scoped roles, delegation behavior, and parallel work inside Codex.
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents) — Specialized subagent configuration, context isolation, tools, permissions, and delegation patterns.
- [Agentic SDD workflow](https://github.github.com/spec-kit/reference/agentic-sdd.html) — Generating and analyzing implementation tasks after specification and planning quality gates.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — The distinction between fixed workflows and model-directed agents, plus the recommendation to add complexity only when measured outcomes justify it.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Agent run loops, state management, continuation strategies, and the operational boundary between the SDK and application-owned state.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: EVALS.md

# EVALS.md

> Define representative tasks, outcomes, failure taxonomies, graders, human review, operational metrics, release thresholds, and regression processes for behavior that varies across models and environments.

**Decision rule:** Evaluate the complete workflow against realistic outcomes and failure paths. Use deterministic checks where possible and calibrated human or model judgment where necessary.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Outcomes and failure taxonomy

> Measure the behavior that matters instead of a convenient proxy.

- **Success:** <Define task completion, quality, safety, latency, cost, and user-correction outcomes>
- **Failures:** <Classify instruction, context, reasoning, tool, authorization, data, and recovery failures>
- **Severity:** <Define critical, major, minor, and acceptable variance with examples>

## Evaluation set

> Represent normal use, boundaries, adversarial cases, and longitudinal behavior.

- **Cases:** <List source, owner, input, expected evidence, and protected data classification>
- **Coverage:** <Map cases to requirements, tools, users, languages, failures, and risk levels>
- **Versioning:** <Define frozen sets, hidden sets, additions from incidents, and contamination controls>

## Graders and metrics

> Make every score interpretable and periodically calibrate judgment.

- **Deterministic checks:** <List schemas, exact properties, tests, policy checks, and artifact inspection>
- **Judgment:** <Define rubric, human reviewers, model graders, blind review, and disagreement handling>
- **Operational metrics:** <Track completion, correction, retries, tool errors, latency, tokens, cost, and abandonment>

## Release and regression

> Turn evaluation into a shipping control rather than a report.

- **Thresholds:** <Define minimums, critical-case zero tolerance, confidence, and comparison baseline>
- **Release gate:** <State when a change blocks, warns, rolls out gradually, or requires sign-off>
- **Regression loop:** <Add incidents and user corrections, assign owners, and verify fixes across supported models>

## Related AgentAtlas field guides

- [Evals and verification](https://agentatlas.dev/topics/evals-verification)
- [Observability](https://agentatlas.dev/topics/observability)
- [Tasks](https://agentatlas.dev/topics/tasks)

## Primary references

- [Evaluation best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices) — Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes.
- [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) — Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement.
- [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) — Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls.
- [Agentic SDD workflow](https://github.github.com/spec-kit/reference/agentic-sdd.html) — Generating and analyzing implementation tasks after specification and planning quality gates.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: SAFETY.md

# SAFETY.md

> Document threats, assets, identities, authority boundaries, least-privilege controls, approval policies, data protections, abuse cases, and incident response for agent behavior and tool use.

**Decision rule:** Grant the minimum authority required for the current outcome and re-check authorization at the action boundary. Add human approval when consequences exceed delegated authority.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Threat model

> Identify what must be protected and how the agent can be manipulated or misused.

- **Assets:** <List data, credentials, money, systems, reputation, and human safety concerns>
- **Actors:** <List users, operators, external content authors, attackers, services, and agents>
- **Threats:** <Cover prompt injection, exfiltration, privilege escalation, fraud, destructive action, and unsafe advice>

## Identity and permissions

> Bind every action to an authenticated actor and current resource-level authority.

- **Identity:** <Define user, service, tenant, session, agent, and delegated identity>
- **Permission model:** <Map roles or attributes to tools, resources, actions, and environments>
- **Credential handling:** <Define issuance, scoping, storage, rotation, revocation, and audit>

## Approvals and safeguards

> Use deterministic controls and meaningful approval previews before consequential action.

- **Approval matrix:** <Map risk tiers to preview, confirmation, second reviewer, or prohibited status>
- **Runtime controls:** <Define allowlists, limits, sandboxing, validation, output filtering, and rate controls>
- **User control:** <Provide inspect, edit, cancel, undo, revoke, delete, and escalation paths>

## Verification and response

> Continuously test controls and prepare for containment and recovery.

- **Safety tests:** <List adversarial, cross-tenant, approval-bypass, data-leak, and unsafe-action cases>
- **Monitoring:** <Define high-risk action, denial, anomaly, policy, and audit signals>
- **Incident response:** <Define containment, credential revocation, evidence preservation, communication, and follow-up>

## Related AgentAtlas field guides

- [Safety and permissions](https://agentatlas.dev/topics/safety-permissions)
- [Human approval](https://agentatlas.dev/topics/human-approval)
- [Governance](https://agentatlas.dev/topics/governance)

## Primary references

- [Codex security](https://developers.openai.com/codex/security) — Operational authority boundaries enforced through sandboxing, permissions, approvals, and network controls.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution.
- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals.
- [AGENTS.md specification](https://agents.md/) — Versioned repository instructions that make build, test, style, and contribution requirements available to agents.
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: RUNBOOK.md

# RUNBOOK.md

> Give operators a tested path from alert to diagnosis, containment, rollback, recovery, communication, and follow-up using the signals and failure modes of the complete agent workflow.

**Decision rule:** Write a runbook for failures that require timely coordinated action or specialized diagnosis. Keep routine automatic recovery in the system and record its limits here.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Service ownership and dependencies

> Make the operating boundary and escalation path available before an incident.

- **Owners:** <List primary, secondary, security, data, product, and vendor contacts>
- **Dependencies:** <List models, tools, queues, databases, auth, providers, and critical limits>
- **Environments:** <List production, staging, regions, release identifiers, and access procedure>

## Signals and diagnosis

> Connect every alert to a workflow stage, user impact, and known failure mode.

- **Service indicators:** <Define completion, correctness, safety, latency, cost, and availability signals>
- **Dashboards and traces:** <Link workflow, model, tool, queue, authorization, and business views>
- **Diagnostic sequence:** <List the fastest read-only checks and evidence to preserve>

## Containment and recovery

> Provide exact reversible actions with authority and stop conditions.

- **Contain:** <Define feature disablement, permission revocation, queue pause, isolation, and traffic controls>
- **Rollback:** <Define code, configuration, prompt, model, schema, and data rollback>
- **Recover:** <Define validation, replay, reconciliation, re-enable order, and customer remediation>

## Communication and learning

> Keep stakeholders informed and convert failures into maintained controls.

- **Updates:** <Define internal, user, vendor, legal, and regulatory communication owners and cadence>
- **Closure evidence:** <State the signals and reviewers required to close the incident>
- **Follow-up:** <Add eval cases, tasks, architecture decisions, documentation, and owner deadlines>

## Related AgentAtlas field guides

- [Deployment and operations](https://agentatlas.dev/topics/deployment-operations)
- [Observability](https://agentatlas.dev/topics/observability)
- [Human approval](https://agentatlas.dev/topics/human-approval)

## Primary references

- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls.
- [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) — Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry.
- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals.
- [Configure permissions](https://code.claude.com/docs/en/permissions) — Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.


---

# File: DECISIONS.md

# DECISIONS.md

> Keep important product, model, architecture, data, protocol, safety, and operating decisions traceable to context, alternatives, evidence, consequences, owners, and review triggers.

**Decision rule:** Record a decision when reversing it later would be costly, when multiple teams or agents depend on it, or when the tradeoff cannot be understood from code alone.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Decision index

> Make active, proposed, superseded, and rejected decisions easy to discover.

- **Identifier:** <Assign a stable ADR or decision number and short title>
- **Status:** <Mark proposed, accepted, deprecated, superseded, or rejected>
- **Ownership:** <Name decider, consulted reviewers, date, and affected systems>

## Decision record

> Capture the decision in enough context to understand it later.

- **Context:** <Describe the problem, constraints, forces, and urgency>
- **Decision:** <State what is being chosen and the scope of that commitment>
- **Consequences:** <List benefits, costs, risks, follow-up work, and compatibility impact>

## Alternatives and evidence

> Show why the choice was reasonable without pretending uncertainty disappeared.

- **Alternatives:** <List viable options, including keeping the current state>
- **Evaluation:** <Compare options against explicit product, quality, safety, cost, and operating criteria>
- **Evidence:** <Link prototypes, benchmarks, evals, incidents, primary sources, and stakeholder input>

## Review and supersession

> Define when new evidence requires the decision to be revisited.

- **Review triggers:** <Name thresholds, incidents, provider changes, scale, cost, or regulatory events>
- **Review date:** <Set a date when uncertainty or change rate makes scheduled review useful>
- **Supersession:** <Link the replacement decision and migration or cleanup work without rewriting history>

## Related AgentAtlas field guides

- [Agent architecture](https://agentatlas.dev/topics/architecture)
- [Governance](https://agentatlas.dev/topics/governance)
- [Model strategy](https://agentatlas.dev/topics/model-strategy)

## Primary references

- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes.
- [AGENTS.md specification](https://agents.md/) — Versioned repository instructions that make build, test, style, and contribution requirements available to agents.
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts.
- [Codex security](https://developers.openai.com/codex/security) — Operational authority boundaries enforced through sandboxing, permissions, approvals, and network controls.
- [GPT-5.4 model guide](https://developers.openai.com/api/docs/models/gpt-5.4) — Current OpenAI model capabilities, context, tool support, controls, and operational characteristics.
- [Claude prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) — Current Claude prompting controls and provider-specific practices that should be evaluated rather than generalized across models.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.