{"schemaVersion":1,"id":"agentatlas-knowledge-catalog","name":"AgentAtlas knowledge catalog","license":"Editorial summaries by AgentAtlas; linked sources retain their own terms.","editorialPolicy":"Primary documentation first. Provider-specific behavior is labeled. Every guide separates probabilistic instructions from deterministic controls.","recommendations":{"canonicalUrl":"https://agentatlas.dev/start","apiUrl":"https://agentatlas.dev/api/recommendations","defaultGoal":"start","policy":"Deterministic, non-personalized editorial routing with no sponsor influence.","paths":[{"goal":"start","title":"Build a production agent","question":"I am starting an agent project. What should I add first?","isDefault":true,"url":"https://agentatlas.dev/start#start","apiUrl":"https://agentatlas.dev/api/recommendations?goal=start"},{"goal":"choose-model","title":"Choose and operate a model","question":"Which model family and operating pattern fits my workload?","isDefault":false,"url":"https://agentatlas.dev/start#choose-model","apiUrl":"https://agentatlas.dev/api/recommendations?goal=choose-model"},{"goal":"connect-tools","title":"Connect tools and data","question":"Should this capability be a Skill, plugin, or MCP integration?","isDefault":false,"url":"https://agentatlas.dev/start#connect-tools","apiUrl":"https://agentatlas.dev/api/recommendations?goal=connect-tools"},{"goal":"coordinate-agents","title":"Coordinate multiple agents","question":"Do I need subagents, automations, MCP, or A2A?","isDefault":false,"url":"https://agentatlas.dev/start#coordinate-agents","apiUrl":"https://agentatlas.dev/api/recommendations?goal=coordinate-agents"},{"goal":"manage-context","title":"Manage instructions and memory","question":"Where should durable context, learned memory, and event logic live?","isDefault":false,"url":"https://agentatlas.dev/start#manage-context","apiUrl":"https://agentatlas.dev/api/recommendations?goal=manage-context"},{"goal":"automate-workflows","title":"Automate repeatable work","question":"How should I turn a successful agent run into a repeatable system?","isDefault":false,"url":"https://agentatlas.dev/start#automate-workflows","apiUrl":"https://agentatlas.dev/api/recommendations?goal=automate-workflows"},{"goal":"ship-safely","title":"Ship with evidence and guardrails","question":"What is the minimum safety and quality layer for production?","isDefault":false,"url":"https://agentatlas.dev/start#ship-safely","apiUrl":"https://agentatlas.dev/api/recommendations?goal=ship-safely"},{"goal":"enable-commerce","title":"Enable agent commerce","question":"How should an agent discover offers and authorize transactions?","isDefault":false,"url":"https://agentatlas.dev/start#enable-commerce","apiUrl":"https://agentatlas.dev/api/recommendations?goal=enable-commerce"}]},"collections":{"templates":{"canonicalUrl":"https://agentatlas.dev/starter-kit","apiUrl":"https://agentatlas.dev/api/catalog/templates","reviewedAt":"2026-07-26","reviewCadenceDays":30,"generatorVersion":"1.0.0","items":[{"slug":"agent-instructions","fileName":"AGENTS.md","title":"Repository agent instructions","category":"Direction","summary":"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.","decisionRule":"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.","topicSlugs":["agents","specifications","safety-permissions"],"sections":[{"heading":"Project map","guidance":"Orient an agent without forcing it to rediscover the repository or infer ownership.","fields":[{"label":"Purpose","prompt":"Describe the product and the outcome this repository owns"},{"label":"Important paths","prompt":"List the directories, packages, generated files, and ownership boundaries that matter"},{"label":"Instruction scope","prompt":"Explain whether nested AGENTS.md files override guidance for subprojects"}]},{"heading":"Commands and environment","guidance":"Provide exact, non-interactive commands and identify prerequisites that cannot be inferred safely.","fields":[{"label":"Install","prompt":"Give the dependency installation command and required runtime versions"},{"label":"Develop","prompt":"Give the local development command and expected URL or process"},{"label":"Verify","prompt":"List focused tests, full tests, type checks, linting, and build commands"}]},{"heading":"Conventions and change policy","guidance":"State the rules that meaningfully affect implementation and review.","fields":[{"label":"Code conventions","prompt":"Name architecture, style, naming, and dependency rules with examples where useful"},{"label":"Generated or protected files","prompt":"Identify files agents must not hand-edit or overwrite"},{"label":"Change boundaries","prompt":"Describe acceptable scope, compatibility expectations, migrations, and documentation updates"}]},{"heading":"Safety and completion","guidance":"Make consequential actions and the definition of done explicit.","fields":[{"label":"Approval required","prompt":"List external writes, deployments, secrets, destructive changes, or costs that require approval"},{"label":"Security","prompt":"State data-handling, authorization, dependency, and secret-management requirements"},{"label":"Done","prompt":"Define the evidence an agent must return before claiming the task is complete"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/agent-instructions","downloadUrl":"https://agentatlas.dev/starter-kit/files/AGENTS.md","sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"The distinction between fixed workflows and model-directed agents, plus the recommendation to add complexity only when measured outcomes justify it."},{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Agent run loops, state management, continuation strategies, and the operational boundary between the SDK and application-owned state."},{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."}]},{"slug":"agent-skill","fileName":"SKILL.md","title":"Portable Agent Skill","category":"Execution","summary":"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.","decisionRule":"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.","topicSlugs":["skills","tasks","tools-mcp"],"frontMatter":{"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"}},"sections":[{"heading":"Trigger and outcome","guidance":"Make it easy for an agent to decide when the Skill applies and what successful completion means.","fields":[{"label":"Use when","prompt":"List the user phrases, file types, or task conditions that should activate this Skill"},{"label":"Do not use when","prompt":"Name nearby tasks that require a different workflow or human judgment"},{"label":"Outcome","prompt":"Describe the verifiable artifact or state this Skill produces"}]},{"heading":"Inputs and outputs","guidance":"Declare required context and a stable return contract before the procedure.","fields":[{"label":"Required inputs","prompt":"List files, parameters, credentials, and assumptions the workflow needs"},{"label":"Output contract","prompt":"Define files, structured fields, messages, or evidence returned"},{"label":"Dependencies","prompt":"List optional scripts, references, assets, tools, and environment requirements"}]},{"heading":"Procedure","guidance":"Write ordered steps with decision points, checkpoints, and the smallest safe tool scope.","fields":[{"label":"Prepare","prompt":"Describe read-only discovery and precondition checks"},{"label":"Execute","prompt":"List the ordered implementation steps and allowed tools"},{"label":"Verify","prompt":"State the checks that must pass before returning the result"}]},{"heading":"Failures and progressive disclosure","guidance":"Keep the main file focused while making recovery and deeper material discoverable.","fields":[{"label":"Edge cases","prompt":"List ambiguous, malformed, missing, or unsafe inputs and the required response"},{"label":"Recovery","prompt":"Explain retry limits, cleanup, rollback, and escalation"},{"label":"References","prompt":"Link focused files under references, scripts, or assets using relative paths"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/agent-skill","downloadUrl":"https://agentatlas.dev/starter-kit/files/SKILL.md","sources":[{"label":"Agent Skills specification","publisher":"Agent Skills","url":"https://agentskills.io/specification","supports":"The portable Skill directory structure, required SKILL.md metadata, progressive disclosure, and optional resource folders."},{"label":"Build skills for ChatGPT and Codex","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/build-skills","supports":"How Skills are authored, discovered, loaded, and used across OpenAI agent surfaces."},{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"Generating and analyzing implementation tasks after specification and planning quality gates."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries."},{"label":"MCP specification","publisher":"Model Context Protocol","url":"https://modelcontextprotocol.io/specification/","supports":"The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations."},{"label":"Connect Codex to MCP servers","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/extend/mcp","supports":"How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities."}]},{"slug":"architecture","fileName":"ARCHITECTURE.md","title":"Agent system architecture","category":"Design","summary":"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.","decisionRule":"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.","topicSlugs":["architecture","tools-mcp","deployment-operations"],"sections":[{"heading":"Scope and boundaries","guidance":"State what the system owns, what it delegates, and where trust or organizational responsibility changes.","fields":[{"label":"System purpose","prompt":"Describe the outcomes and users this architecture supports"},{"label":"In scope","prompt":"List owned capabilities and data"},{"label":"External boundaries","prompt":"List providers, agents, tools, protocols, and teams outside the boundary"}]},{"heading":"Components and flows","guidance":"Make runtime responsibilities and important state transitions inspectable.","fields":[{"label":"Components","prompt":"List each component, owner, responsibility, and interface"},{"label":"Data flow","prompt":"Describe inputs, persisted state, context assembly, outputs, and sensitive data movement"},{"label":"Control flow","prompt":"Describe orchestration, delegation, approvals, retries, and termination"}]},{"heading":"Quality attributes and decisions","guidance":"Connect architecture choices to measurable constraints instead of framework preference.","fields":[{"label":"Targets","prompt":"Record reliability, latency, cost, security, privacy, and scale objectives"},{"label":"Key decisions","prompt":"Link the decision records that justify important tradeoffs"},{"label":"Constraints","prompt":"State provider, compliance, deployment, compatibility, and team constraints"}]},{"heading":"Operations and evolution","guidance":"Explain how the system fails, recovers, changes, and proves compatibility.","fields":[{"label":"Failure modes","prompt":"List dependency, model, tool, data, queue, and authorization failures"},{"label":"Deployment","prompt":"Describe environments, release units, migration order, and rollback"},{"label":"Evolution","prompt":"Define compatibility promises, deprecation, and architecture review triggers"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/architecture","downloadUrl":"https://agentatlas.dev/starter-kit/files/ARCHITECTURE.md","sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes."},{"label":"MCP specification","publisher":"Model Context Protocol","url":"https://modelcontextprotocol.io/specification/","supports":"The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations."},{"label":"Connect Codex to MCP servers","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/extend/mcp","supports":"How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities."},{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis."}]},{"slug":"product-design","fileName":"DESIGN.md","title":"Agent product design","category":"Design","summary":"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.","decisionRule":"Use DESIGN.md to specify user interaction, feedback, control, and recovery. Keep system boundaries in architecture and implementation sequencing in the plan.","topicSlugs":["agent-product-design","human-approval","safety-permissions"],"sections":[{"heading":"Users, jobs, and outcomes","guidance":"Anchor the experience in a real user job and an observable, verifiable measure of success.","fields":[{"label":"Primary user","prompt":"Describe role, expertise, incentives, and constraints"},{"label":"Job","prompt":"State the workflow and current pain without prescribing a solution"},{"label":"Outcome","prompt":"Define what the user can verify when the experience succeeds"}]},{"heading":"Interaction and system state","guidance":"Show what the system knows, plans, is doing, and needs from the user.","fields":[{"label":"Entry points","prompt":"List triggers, inputs, defaults, and required context"},{"label":"State model","prompt":"Define idle, preparing, running, waiting, failed, canceled, and completed states"},{"label":"Feedback","prompt":"Describe progress, evidence, uncertainty, and tool activity shown to the user"}]},{"heading":"Control and trust","guidance":"Place human judgment where authority or consequence changes.","fields":[{"label":"Approvals","prompt":"Name actions requiring preview, confirmation, or a second reviewer"},{"label":"Corrections","prompt":"Explain edit, retry, undo, cancel, and feedback behavior"},{"label":"Disclosure","prompt":"State how sources, sponsorship, limitations, and automation are labeled"}]},{"heading":"Edge states and accessibility","guidance":"Design realistic failure and alternate-access paths before polish.","fields":[{"label":"Empty and partial states","prompt":"Describe missing context, no results, incomplete outputs, and degraded dependencies"},{"label":"Failure recovery","prompt":"Define actionable messages, retained work, escalation, and safe fallback"},{"label":"Accessibility","prompt":"Record keyboard, screen-reader, contrast, motion, focus, and language requirements"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/product-design","downloadUrl":"https://agentatlas.dev/starter-kit/files/DESIGN.md","sources":[{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."}]},{"slug":"specification","fileName":"SPEC.md","title":"Feature specification","category":"Direction","summary":"Turn an intended outcome into testable behavior, requirements, constraints, non-goals, edge cases, and acceptance evidence before selecting implementation details or decomposing the work.","decisionRule":"Specify what and why before deciding how. If a statement cannot be verified, clarified, or traced to a user outcome, tighten it before planning.","topicSlugs":["specifications","agent-product-design","evals-verification"],"sections":[{"heading":"Problem and outcome","guidance":"Define the user-visible change and the evidence that it matters.","fields":[{"label":"Problem","prompt":"Describe the current workflow, pain, and affected user"},{"label":"Desired outcome","prompt":"State the observable behavior or state change"},{"label":"Success measures","prompt":"List product, quality, safety, and operational measures"}]},{"heading":"Requirements and scenarios","guidance":"Write behavior precisely enough that each scenario can become an objective acceptance test.","fields":[{"label":"Primary scenarios","prompt":"List trigger, inputs, expected behavior, and output for each core path"},{"label":"Edge scenarios","prompt":"Cover missing, malformed, conflicting, unauthorized, canceled, and repeated actions"},{"label":"Data","prompt":"Define required fields, provenance, retention, correction, and deletion"}]},{"heading":"Constraints and non-goals","guidance":"Prevent the implementation from silently expanding or violating a hard boundary.","fields":[{"label":"Constraints","prompt":"State security, privacy, compatibility, latency, cost, and compliance limits"},{"label":"Non-goals","prompt":"List plausible adjacent work explicitly excluded"},{"label":"Open questions","prompt":"Record unresolved ambiguity, owner, and deadline for each answer"}]},{"heading":"Acceptance and traceability","guidance":"Connect each requirement to evidence and later implementation work.","fields":[{"label":"Acceptance checks","prompt":"Write objective checks for every required behavior and important failure path"},{"label":"Approval","prompt":"Name the product, design, security, legal, or operations reviewers required"},{"label":"Traceability","prompt":"Link plan decisions, tasks, tests, eval cases, telemetry, and release evidence"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/specification","downloadUrl":"https://agentatlas.dev/starter-kit/files/SPEC.md","sources":[{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents."},{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Pause, inspect, approve, reject, persist, and resume patterns for consequential tool calls across agent runs."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes."},{"label":"Evaluation best practices","publisher":"OpenAI","url":"https://developers.openai.com/api/docs/guides/evaluation-best-practices","supports":"Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes."},{"label":"Demystifying evals for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents","supports":"Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement."}]},{"slug":"implementation-plan","fileName":"PLAN.md","title":"Implementation plan","category":"Direction","summary":"Translate an approved specification into a reversible technical approach, decision sequence, dependency-aware phases, validation strategy, deployment path, and rollback plan.","decisionRule":"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.","topicSlugs":["planning","architecture","deployment-operations"],"sections":[{"heading":"Approach and decisions","guidance":"Explain the implementation strategy and why it satisfies the specification.","fields":[{"label":"Approach","prompt":"Summarize components, data changes, interfaces, and control flow"},{"label":"Key decisions","prompt":"Record selected options, alternatives, tradeoffs, and evidence"},{"label":"Assumptions","prompt":"List assumptions to prove before broad implementation"}]},{"heading":"Phases and dependencies","guidance":"Sequence work around risk, independently verifiable outputs, and real blockers.","fields":[{"label":"Foundation","prompt":"List blocking setup, schemas, contracts, and test harnesses"},{"label":"Vertical slices","prompt":"Define incremental user-visible or end-to-end capabilities"},{"label":"Dependency order","prompt":"Map blockers, parallel work, integration points, and owners"}]},{"heading":"Verification and rollout","guidance":"Decide how each phase proves correctness before work begins.","fields":[{"label":"Verification","prompt":"Map unit, integration, end-to-end, eval, security, and manual checks to phases"},{"label":"Observability","prompt":"Name logs, metrics, traces, dashboards, and release signals"},{"label":"Rollout","prompt":"Describe migration, feature flags, cohorts, compatibility, and success gates"}]},{"heading":"Risk and recovery","guidance":"Make failure containment and plan updates part of the implementation.","fields":[{"label":"Risks","prompt":"Rank technical, product, safety, privacy, cost, and schedule risks"},{"label":"Mitigations","prompt":"Assign preventive controls, owners, evidence, and review dates"},{"label":"Rollback","prompt":"Define stop conditions, reversible steps, data recovery, and communication"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/implementation-plan","downloadUrl":"https://agentatlas.dev/starter-kit/files/PLAN.md","sources":[{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"The ordered specification, clarification, planning, tasking, analysis, implementation, and convergence workflow."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes."},{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis."}]},{"slug":"task-system","fileName":"TASKS.md","title":"Agent-ready task system","category":"Direction","summary":"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.","decisionRule":"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.","topicSlugs":["tasks","planning","multi-agent"],"sections":[{"heading":"Task contract","guidance":"Use the same minimum outcome, scope, and verification contract for every work item.","fields":[{"label":"Outcome","prompt":"State the artifact or state change that completes the task"},{"label":"Inputs and scope","prompt":"List required context, allowed paths, dependencies, and explicit exclusions"},{"label":"Acceptance","prompt":"Define commands, tests, inspection, or evidence that verifies the output"}]},{"heading":"Phases and dependencies","guidance":"Keep the executable queue aligned with the plan and specification.","fields":[{"label":"Setup","prompt":"List environment and harness tasks that unblock later work"},{"label":"Foundational","prompt":"List shared contracts, data, security, and architecture tasks"},{"label":"Delivery phases","prompt":"Group vertical work by user outcome and mark parallel-safe tasks"}]},{"heading":"Work queue","guidance":"Make state, ownership, and handoffs visible without hiding unfinished work.","fields":[{"label":"Ready","prompt":"List unblocked tasks with owner and priority"},{"label":"In progress","prompt":"List active tasks, current evidence, and blocking questions"},{"label":"Done","prompt":"Record verification evidence, integration result, and links to changes"}]},{"heading":"Integration and convergence","guidance":"Check the complete integrated outcome after every individual task and local verification passes.","fields":[{"label":"Integration order","prompt":"State merge, migration, release, and cross-task verification order"},{"label":"Gap analysis","prompt":"Compare completed work with the specification, plan, and acceptance checks"},{"label":"Follow-up","prompt":"Append discovered gaps with owners rather than hiding them in completion notes"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/task-system","downloadUrl":"https://agentatlas.dev/starter-kit/files/TASKS.md","sources":[{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"The ordered specification, clarification, planning, tasking, analysis, implementation, and convergence workflow."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Planning transparency, composable workflow patterns, and matching orchestration complexity to task requirements."},{"label":"Codex subagents","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/agent-configuration/subagents","supports":"Subagent configuration, scoped roles, delegation behavior, and parallel work inside Codex."},{"label":"Create custom subagents","publisher":"Anthropic","url":"https://code.claude.com/docs/en/sub-agents","supports":"Specialized subagent configuration, context isolation, tools, permissions, and delegation patterns."}]},{"slug":"context-system","fileName":"CONTEXT.md","title":"Context engineering system","category":"Design","summary":"Control which instructions, examples, tools, retrieved facts, messages, and summaries reach the model; record their authority, provenance, freshness, token cost, and intended decision.","decisionRule":"Include context only when it changes a named decision or reduces a measured failure. Retrieve current authoritative evidence instead of accumulating every available token.","topicSlugs":["context-engineering","memory-context","safety-permissions"],"sections":[{"heading":"Context inventory","guidance":"Identify every source of runtime tokens and the specific decision or behavior it supports.","fields":[{"label":"Always loaded","prompt":"List system instructions, repository policy, schemas, and stable constraints"},{"label":"Retrieved","prompt":"List knowledge stores, search, tools, ranking, and freshness requirements"},{"label":"Runtime","prompt":"List user input, session history, tool output, scratch state, and summaries"}]},{"heading":"Selection and budget","guidance":"Prioritize relevant and authoritative context under realistic limits.","fields":[{"label":"Budget","prompt":"Allocate tokens or size limits by instruction, history, retrieval, tools, and output"},{"label":"Ranking","prompt":"Define relevance, authority, recency, diversity, and conflict rules"},{"label":"Compaction","prompt":"Describe summarization, truncation, checkpointing, and information that must survive"}]},{"heading":"Provenance and conflict","guidance":"Make it possible to inspect why information was present and which source wins.","fields":[{"label":"Provenance","prompt":"Attach source, owner, timestamp, version, and retrieval reason"},{"label":"Authority order","prompt":"Define precedence for user intent, project policy, retrieved evidence, and model inference"},{"label":"Sensitive context","prompt":"State redaction, isolation, retention, and export restrictions"}]},{"heading":"Evaluation","guidance":"Measure whether the context system helps rather than assuming more is better.","fields":[{"label":"Quality","prompt":"Test retrieval precision, groundedness, conflict resolution, and task success"},{"label":"Efficiency","prompt":"Measure tokens, latency, cache effectiveness, and repeated retrieval"},{"label":"Failure cases","prompt":"Test stale facts, prompt injection, distraction, compaction loss, and missing context"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/context-system","downloadUrl":"https://agentatlas.dev/starter-kit/files/CONTEXT.md","sources":[{"label":"Effective context engineering for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","supports":"Treating context as a finite resource and curating instructions, tools, external data, history, and summaries across long-running agents."},{"label":"How Claude remembers your project","publisher":"Anthropic","url":"https://code.claude.com/docs/en/memory","supports":"Repository instruction hierarchy, project memory, scoped rules, and how persistent context is discovered and loaded."},{"label":"Sessions","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/sessions/","supports":"Session memory, storage choices, history limits, compaction, resumption, and operational persistence patterns."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."}]},{"slug":"memory-system","fileName":"MEMORY.md","title":"Agent memory system","category":"Design","summary":"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.","decisionRule":"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.","topicSlugs":["memory-context","governance","safety-permissions"],"sections":[{"heading":"Memory taxonomy","guidance":"Separate state with different authority, lifetime, and privacy properties.","fields":[{"label":"Session state","prompt":"Define transient conversation and workflow state"},{"label":"Durable facts","prompt":"Define user, project, organizational, and domain knowledge worth persisting"},{"label":"Derived memory","prompt":"Define summaries, preferences, patterns, and their confidence or source"}]},{"heading":"Identity and storage","guidance":"Prevent memory from crossing the wrong user, workspace, tenant, or authority boundary.","fields":[{"label":"Identity keys","prompt":"Define user, session, project, tenant, and agent identifiers"},{"label":"Storage","prompt":"List systems of record, indexes, encryption, access policy, and backups"},{"label":"Retrieval","prompt":"Define queries, ranking, scope, confidence, and empty-result behavior"}]},{"heading":"Lifecycle and control","guidance":"Give users and operators meaningful control over remembered information.","fields":[{"label":"Write policy","prompt":"State what can be written automatically and what requires confirmation"},{"label":"Correction","prompt":"Describe inspection, edit, contradiction, source update, and invalidation"},{"label":"Retention","prompt":"Define expiration, deletion, legal hold, export, and downstream cleanup"}]},{"heading":"Quality and privacy","guidance":"Evaluate benefits and harms using realistic longitudinal cases.","fields":[{"label":"Quality tests","prompt":"Measure retrieval precision, stale-memory behavior, correction, and compaction loss"},{"label":"Privacy tests","prompt":"Test tenant isolation, consent, sensitive inference, deletion, and data minimization"},{"label":"Operational signals","prompt":"Monitor write volume, retrieval use, conflicts, corrections, and deletion failures"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/memory-system","downloadUrl":"https://agentatlas.dev/starter-kit/files/MEMORY.md","sources":[{"label":"Sessions","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/sessions/","supports":"Session memory, storage choices, history limits, compaction, resumption, and operational persistence patterns."},{"label":"Effective context engineering for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","supports":"Treating context as a finite resource and curating instructions, tools, external data, history, and summaries across long-running agents."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Versioned repository instructions that make build, test, style, and contribution requirements available to agents."},{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."}]},{"slug":"tool-contracts","fileName":"TOOLS.md","title":"Tool and MCP contracts","category":"Execution","summary":"Inventory model-callable capabilities and make schemas, descriptions, authentication, authorization, side effects, idempotency, errors, timeouts, output limits, and approval requirements explicit.","decisionRule":"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.","topicSlugs":["tools-mcp","safety-permissions","observability"],"sections":[{"heading":"Tool inventory and contract","guidance":"Make tool selection and consequences understandable to both models and reviewers.","fields":[{"label":"Capability","prompt":"Name the user outcome and why a model needs this tool"},{"label":"Schema","prompt":"Define narrow typed inputs, outputs, defaults, and validation"},{"label":"Side effects","prompt":"Classify read-only, reversible, external write, financial, destructive, or privileged behavior"}]},{"heading":"Identity and authority","guidance":"Keep authentication separate from the permission to perform a specific action.","fields":[{"label":"Authentication","prompt":"Define caller, user, service, tenant, and credential lifecycle"},{"label":"Authorization","prompt":"Define resource- and action-level policy checked at execution time"},{"label":"Approval","prompt":"List arguments and actions requiring preview, confirmation, or a second reviewer"}]},{"heading":"Reliability and observability","guidance":"Specify predictable behavior under repetition, delay, partial failure, and large outputs.","fields":[{"label":"Failure contract","prompt":"Define typed errors, retryability, timeout, cancellation, and partial results"},{"label":"Idempotency","prompt":"Define duplicate detection, keys, replay, and exactly-once assumptions"},{"label":"Telemetry","prompt":"Record tool name, sanitized arguments, authorization, latency, result, and correlation identifiers"}]},{"heading":"Verification","guidance":"Test the contract as adversarially as the model and external systems will use it.","fields":[{"label":"Contract tests","prompt":"Cover valid, malformed, boundary, oversized, and unsupported inputs"},{"label":"Safety tests","prompt":"Cover prompt injection, confused deputy, cross-tenant, approval bypass, and revocation"},{"label":"Operational tests","prompt":"Cover timeout, retry, duplicate execution, dependency failure, and recovery"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/tool-contracts","downloadUrl":"https://agentatlas.dev/starter-kit/files/TOOLS.md","sources":[{"label":"MCP specification","publisher":"Model Context Protocol","url":"https://modelcontextprotocol.io/specification/","supports":"The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations."},{"label":"Connect Codex to MCP servers","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/extend/mcp","supports":"How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."},{"label":"OpenTelemetry semantic conventions","publisher":"OpenTelemetry","url":"https://opentelemetry.io/docs/specs/semconv/","supports":"Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls."}]},{"slug":"delegation","fileName":"DELEGATION.md","title":"Multi-agent delegation","category":"Execution","summary":"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.","decisionRule":"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.","topicSlugs":["multi-agent","tasks","agents"],"sections":[{"heading":"Delegation policy","guidance":"Prevent multi-agent coordination cost and fragmented context from becoming the default architecture.","fields":[{"label":"Delegate when","prompt":"List clean partitions, expertise needs, isolation, or parallelism that justify delegation"},{"label":"Do not delegate when","prompt":"List shared-state, tightly coupled, high-context, or authority-sensitive work"},{"label":"Budget","prompt":"Define maximum agents, turns, time, tokens, cost, and retry limits"}]},{"heading":"Agent roster","guidance":"Describe specialization without granting unnecessary tools or context.","fields":[{"label":"Role","prompt":"Name each agent's bounded responsibility and expected output"},{"label":"Context","prompt":"List instructions, files, data, and history the agent receives"},{"label":"Authority","prompt":"List tools, resources, writes, approvals, and prohibited actions"}]},{"heading":"Handoff contract","guidance":"Make delegated work reviewable without replaying hidden reasoning.","fields":[{"label":"Input contract","prompt":"Define objective, scope, dependencies, constraints, and acceptance evidence"},{"label":"Return contract","prompt":"Define artifacts, findings, uncertainties, checks, and unresolved blockers"},{"label":"Failure contract","prompt":"Define timeout, partial return, escalation, cancellation, and cleanup"}]},{"heading":"Synthesis and verification","guidance":"Assign responsibility for overlap, contradictions, integration, and whole-system quality.","fields":[{"label":"Synthesizer","prompt":"Name the agent or person that owns the combined result"},{"label":"Conflict resolution","prompt":"Define authority order and evidence required when outputs disagree"},{"label":"Final verification","prompt":"Test the integrated outcome, permissions, traceability, and acceptance checks"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/delegation","downloadUrl":"https://agentatlas.dev/starter-kit/files/DELEGATION.md","sources":[{"label":"Codex subagents","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/agent-configuration/subagents","supports":"Subagent configuration, scoped roles, delegation behavior, and parallel work inside Codex."},{"label":"Create custom subagents","publisher":"Anthropic","url":"https://code.claude.com/docs/en/sub-agents","supports":"Specialized subagent configuration, context isolation, tools, permissions, and delegation patterns."},{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"Generating and analyzing implementation tasks after specification and planning quality gates."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"The distinction between fixed workflows and model-directed agents, plus the recommendation to add complexity only when measured outcomes justify it."},{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Agent run loops, state management, continuation strategies, and the operational boundary between the SDK and application-owned state."}]},{"slug":"evaluation-system","fileName":"EVALS.md","title":"Agent evaluation system","category":"Assurance","summary":"Define representative tasks, outcomes, failure taxonomies, graders, human review, operational metrics, release thresholds, and regression processes for behavior that varies across models and environments.","decisionRule":"Evaluate the complete workflow against realistic outcomes and failure paths. Use deterministic checks where possible and calibrated human or model judgment where necessary.","topicSlugs":["evals-verification","observability","tasks"],"sections":[{"heading":"Outcomes and failure taxonomy","guidance":"Measure the behavior that matters instead of a convenient proxy.","fields":[{"label":"Success","prompt":"Define task completion, quality, safety, latency, cost, and user-correction outcomes"},{"label":"Failures","prompt":"Classify instruction, context, reasoning, tool, authorization, data, and recovery failures"},{"label":"Severity","prompt":"Define critical, major, minor, and acceptable variance with examples"}]},{"heading":"Evaluation set","guidance":"Represent normal use, boundaries, adversarial cases, and longitudinal behavior.","fields":[{"label":"Cases","prompt":"List source, owner, input, expected evidence, and protected data classification"},{"label":"Coverage","prompt":"Map cases to requirements, tools, users, languages, failures, and risk levels"},{"label":"Versioning","prompt":"Define frozen sets, hidden sets, additions from incidents, and contamination controls"}]},{"heading":"Graders and metrics","guidance":"Make every score interpretable and periodically calibrate judgment.","fields":[{"label":"Deterministic checks","prompt":"List schemas, exact properties, tests, policy checks, and artifact inspection"},{"label":"Judgment","prompt":"Define rubric, human reviewers, model graders, blind review, and disagreement handling"},{"label":"Operational metrics","prompt":"Track completion, correction, retries, tool errors, latency, tokens, cost, and abandonment"}]},{"heading":"Release and regression","guidance":"Turn evaluation into a shipping control rather than a report.","fields":[{"label":"Thresholds","prompt":"Define minimums, critical-case zero tolerance, confidence, and comparison baseline"},{"label":"Release gate","prompt":"State when a change blocks, warns, rolls out gradually, or requires sign-off"},{"label":"Regression loop","prompt":"Add incidents and user corrections, assign owners, and verify fixes across supported models"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/evaluation-system","downloadUrl":"https://agentatlas.dev/starter-kit/files/EVALS.md","sources":[{"label":"Evaluation best practices","publisher":"OpenAI","url":"https://developers.openai.com/api/docs/guides/evaluation-best-practices","supports":"Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes."},{"label":"Demystifying evals for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents","supports":"Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement."},{"label":"OpenTelemetry semantic conventions","publisher":"OpenTelemetry","url":"https://opentelemetry.io/docs/specs/semconv/","supports":"Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls."},{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"Generating and analyzing implementation tasks after specification and planning quality gates."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries."}]},{"slug":"safety-system","fileName":"SAFETY.md","title":"Safety and permission system","category":"Assurance","summary":"Document threats, assets, identities, authority boundaries, least-privilege controls, approval policies, data protections, abuse cases, and incident response for agent behavior and tool use.","decisionRule":"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.","topicSlugs":["safety-permissions","human-approval","governance"],"sections":[{"heading":"Threat model","guidance":"Identify what must be protected and how the agent can be manipulated or misused.","fields":[{"label":"Assets","prompt":"List data, credentials, money, systems, reputation, and human safety concerns"},{"label":"Actors","prompt":"List users, operators, external content authors, attackers, services, and agents"},{"label":"Threats","prompt":"Cover prompt injection, exfiltration, privilege escalation, fraud, destructive action, and unsafe advice"}]},{"heading":"Identity and permissions","guidance":"Bind every action to an authenticated actor and current resource-level authority.","fields":[{"label":"Identity","prompt":"Define user, service, tenant, session, agent, and delegated identity"},{"label":"Permission model","prompt":"Map roles or attributes to tools, resources, actions, and environments"},{"label":"Credential handling","prompt":"Define issuance, scoping, storage, rotation, revocation, and audit"}]},{"heading":"Approvals and safeguards","guidance":"Use deterministic controls and meaningful approval previews before consequential action.","fields":[{"label":"Approval matrix","prompt":"Map risk tiers to preview, confirmation, second reviewer, or prohibited status"},{"label":"Runtime controls","prompt":"Define allowlists, limits, sandboxing, validation, output filtering, and rate controls"},{"label":"User control","prompt":"Provide inspect, edit, cancel, undo, revoke, delete, and escalation paths"}]},{"heading":"Verification and response","guidance":"Continuously test controls and prepare for containment and recovery.","fields":[{"label":"Safety tests","prompt":"List adversarial, cross-tenant, approval-bypass, data-leak, and unsafe-action cases"},{"label":"Monitoring","prompt":"Define high-risk action, denial, anomaly, policy, and audit signals"},{"label":"Incident response","prompt":"Define containment, credential revocation, evidence preservation, communication, and follow-up"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/safety-system","downloadUrl":"https://agentatlas.dev/starter-kit/files/SAFETY.md","sources":[{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Operational authority boundaries enforced through sandboxing, permissions, approvals, and network controls."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution."},{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Versioned repository instructions that make build, test, style, and contribution requirements available to agents."},{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts."}]},{"slug":"operations-runbook","fileName":"RUNBOOK.md","title":"Agent operations runbook","category":"Assurance","summary":"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.","decisionRule":"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.","topicSlugs":["deployment-operations","observability","human-approval"],"sections":[{"heading":"Service ownership and dependencies","guidance":"Make the operating boundary and escalation path available before an incident.","fields":[{"label":"Owners","prompt":"List primary, secondary, security, data, product, and vendor contacts"},{"label":"Dependencies","prompt":"List models, tools, queues, databases, auth, providers, and critical limits"},{"label":"Environments","prompt":"List production, staging, regions, release identifiers, and access procedure"}]},{"heading":"Signals and diagnosis","guidance":"Connect every alert to a workflow stage, user impact, and known failure mode.","fields":[{"label":"Service indicators","prompt":"Define completion, correctness, safety, latency, cost, and availability signals"},{"label":"Dashboards and traces","prompt":"Link workflow, model, tool, queue, authorization, and business views"},{"label":"Diagnostic sequence","prompt":"List the fastest read-only checks and evidence to preserve"}]},{"heading":"Containment and recovery","guidance":"Provide exact reversible actions with authority and stop conditions.","fields":[{"label":"Contain","prompt":"Define feature disablement, permission revocation, queue pause, isolation, and traffic controls"},{"label":"Rollback","prompt":"Define code, configuration, prompt, model, schema, and data rollback"},{"label":"Recover","prompt":"Define validation, replay, reconciliation, re-enable order, and customer remediation"}]},{"heading":"Communication and learning","guidance":"Keep stakeholders informed and convert failures into maintained controls.","fields":[{"label":"Updates","prompt":"Define internal, user, vendor, legal, and regulatory communication owners and cadence"},{"label":"Closure evidence","prompt":"State the signals and reviewers required to close the incident"},{"label":"Follow-up","prompt":"Add eval cases, tasks, architecture decisions, documentation, and owner deadlines"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/operations-runbook","downloadUrl":"https://agentatlas.dev/starter-kit/files/RUNBOOK.md","sources":[{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls."},{"label":"OpenTelemetry semantic conventions","publisher":"OpenTelemetry","url":"https://opentelemetry.io/docs/specs/semconv/","supports":"Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry."},{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution."}]},{"slug":"decision-log","fileName":"DECISIONS.md","title":"Architecture decision log","category":"Assurance","summary":"Keep important product, model, architecture, data, protocol, safety, and operating decisions traceable to context, alternatives, evidence, consequences, owners, and review triggers.","decisionRule":"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.","topicSlugs":["architecture","governance","model-strategy"],"sections":[{"heading":"Decision index","guidance":"Make active, proposed, superseded, and rejected decisions easy to discover.","fields":[{"label":"Identifier","prompt":"Assign a stable ADR or decision number and short title"},{"label":"Status","prompt":"Mark proposed, accepted, deprecated, superseded, or rejected"},{"label":"Ownership","prompt":"Name decider, consulted reviewers, date, and affected systems"}]},{"heading":"Decision record","guidance":"Capture the decision in enough context to understand it later.","fields":[{"label":"Context","prompt":"Describe the problem, constraints, forces, and urgency"},{"label":"Decision","prompt":"State what is being chosen and the scope of that commitment"},{"label":"Consequences","prompt":"List benefits, costs, risks, follow-up work, and compatibility impact"}]},{"heading":"Alternatives and evidence","guidance":"Show why the choice was reasonable without pretending uncertainty disappeared.","fields":[{"label":"Alternatives","prompt":"List viable options, including keeping the current state"},{"label":"Evaluation","prompt":"Compare options against explicit product, quality, safety, cost, and operating criteria"},{"label":"Evidence","prompt":"Link prototypes, benchmarks, evals, incidents, primary sources, and stakeholder input"}]},{"heading":"Review and supersession","guidance":"Define when new evidence requires the decision to be revisited.","fields":[{"label":"Review triggers","prompt":"Name thresholds, incidents, provider changes, scale, cost, or regulatory events"},{"label":"Review date","prompt":"Set a date when uncertainty or change rate makes scheduled review useful"},{"label":"Supersession","prompt":"Link the replacement decision and migration or cleanup work without rewriting history"}]}],"canonicalUrl":"https://agentatlas.dev/starter-kit/decision-log","downloadUrl":"https://agentatlas.dev/starter-kit/files/DECISIONS.md","sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Versioned repository instructions that make build, test, style, and contribution requirements available to agents."},{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Operational authority boundaries enforced through sandboxing, permissions, approvals, and network controls."},{"label":"GPT-5.4 model guide","publisher":"OpenAI","url":"https://developers.openai.com/api/docs/models/gpt-5.4","supports":"Current OpenAI model capabilities, context, tool support, controls, and operational characteristics."},{"label":"Claude prompting best practices","publisher":"Anthropic","url":"https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices","supports":"Current Claude prompting controls and provider-specific practices that should be evaluated rather than generalized across models."}]}]},"topics":{"canonicalUrl":"https://agentatlas.dev/topics","apiUrl":"https://agentatlas.dev/api/catalog/topics","reviewedAt":"2026-07-26","reviewCadenceDays":30,"publishCadenceDays":7,"items":[{"slug":"agents","name":"Agents","category":"Foundations","summary":"Agents combine models, instructions, tools, state, and an execution loop so the system can decide how to pursue an outcome. The important design choice is not whether to use the label agent, but how much control the model receives and where deterministic boundaries remain.","decisionRule":"Start with a direct model call or fixed workflow. Introduce an agent only when the task genuinely requires model-directed sequencing, tool selection, or adaptation across multiple steps.","questions":["What decisions may the model make during a run?","Which outcomes require deterministic checks or human approval?","How will the run stop, recover, and report partial progress?"],"artifacts":["agent definition","run policy","tool registry","completion contract"],"lifecycle":[{"stage":"Define","practice":"Write the outcome, allowed decisions, stop conditions, and accountable owner."},{"stage":"Build","practice":"Use the simplest loop and smallest tool surface that can complete a representative task."},{"stage":"Verify","practice":"Trace the run and test success, refusal, timeout, and partial-failure paths."}],"relatedPaths":["/start","/agent-stack","/agent-stack/evals-verification"],"sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"The distinction between fixed workflows and model-directed agents, plus the recommendation to add complexity only when measured outcomes justify it."},{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Agent run loops, state management, continuation strategies, and the operational boundary between the SDK and application-owned state."}],"canonicalUrl":"https://agentatlas.dev/topics/agents"},{"slug":"skills","name":"Skills","category":"Foundations","summary":"Skills package reusable instructions, examples, scripts, and resources for a repeatable workflow. They should stay focused enough to load only when relevant and concrete enough that another agent can follow the procedure without rediscovering it.","decisionRule":"Create a Skill after a workflow repeats and its inputs, steps, outputs, and validation rules are stable. Keep repository-wide truth in repository instructions instead.","questions":["What repeated workflow does the Skill make cheaper or more reliable?","Which files are instructions, executable helpers, references, or templates?","How will an agent know when the Skill applies and when it does not?"],"artifacts":["SKILL.md","scripts/","references/","assets/"],"lifecycle":[{"stage":"Define","practice":"Name one repeatable outcome and document its trigger conditions."},{"stage":"Build","practice":"Keep the core workflow concise and move optional detail into linked resources."},{"stage":"Verify","practice":"Run the Skill from a fresh context and validate the produced artifact or action."}],"relatedPaths":["/skills","/agent-stack/skills","/compare/agents-md-vs-skills"],"sources":[{"label":"Agent Skills specification","publisher":"Agent Skills","url":"https://agentskills.io/specification","supports":"The portable Skill directory structure, required SKILL.md metadata, progressive disclosure, and optional resource folders."},{"label":"Build skills for ChatGPT and Codex","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/build-skills","supports":"How Skills are authored, discovered, loaded, and used across OpenAI agent surfaces."}],"canonicalUrl":"https://agentatlas.dev/topics/skills"},{"slug":"architecture","name":"Agent architecture","category":"Foundations","summary":"Agent architecture assigns responsibility across models, deterministic code, tools, state stores, queues, human reviewers, and independently operated agents. A useful architecture makes control flow, trust boundaries, and recovery behavior visible before framework details.","decisionRule":"Choose the least distributed architecture that meets the workflow's autonomy, latency, reliability, and ownership requirements. Add services or agents only for a named boundary.","questions":["Where does control flow live: code, one agent, or multiple agents?","Which state must survive retries, deployments, or handoffs?","Which boundaries cross teams, credentials, networks, or legal responsibility?"],"artifacts":["system context diagram","decision record","trust-boundary map","failure matrix"],"lifecycle":[{"stage":"Define","practice":"Map actors, systems, data, decisions, and side effects before choosing components."},{"stage":"Build","practice":"Implement one end-to-end path with explicit contracts at every boundary."},{"stage":"Verify","practice":"Exercise dependency failure, retry, duplicate, timeout, and degraded-mode scenarios."}],"relatedPaths":["/start","/agent-stack","/compare"],"sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes."}],"canonicalUrl":"https://agentatlas.dev/topics/architecture"},{"slug":"agent-product-design","name":"Agent product design","category":"Delivery","summary":"Agent product design turns uncertain model behavior into an understandable user experience. It defines what the agent can do, how it communicates progress and uncertainty, when users can inspect or interrupt work, and what recovery looks like after failure.","decisionRule":"Design the review, interruption, and recovery experience alongside the happy path. Never make autonomy invisible when the agent can create consequential side effects.","questions":["What can the user preview, edit, approve, reject, or undo?","How are plans, tool calls, evidence, and uncertainty communicated?","What remains useful when the agent cannot complete the full request?"],"artifacts":["interaction flow","approval states","error and recovery copy","prototype"],"lifecycle":[{"stage":"Define","practice":"Describe user intent, consequences, review moments, and accessibility requirements."},{"stage":"Build","practice":"Expose meaningful state without overwhelming users with raw internal traces."},{"stage":"Verify","practice":"Test interruption, rejection, correction, resumption, and incomplete-result experiences."}],"relatedPaths":["/start","/agent-stack/permissions-safety","/topics/human-approval"],"sources":[{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Pause, inspect, approve, reject, persist, and resume patterns for consequential tool calls across agent runs."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes."}],"canonicalUrl":"https://agentatlas.dev/topics/agent-product-design"},{"slug":"specifications","name":"Specifications","category":"Delivery","summary":"Specifications convert intent into reviewable requirements, acceptance scenarios, constraints, and non-goals. For agent-assisted delivery, a specification should be precise enough to guide planning and validation without pretending that uncertain decisions are already settled.","decisionRule":"Write a specification when multiple implementations could satisfy the request or when acceptance depends on constraints that must survive across models, sessions, and contributors.","questions":["What user outcome and acceptance scenarios define completion?","Which constraints and non-goals prevent plausible but wrong implementations?","How will requirement changes propagate to plans, tasks, tests, and documentation?"],"artifacts":["spec.md","PRD","acceptance scenarios","non-functional requirements"],"lifecycle":[{"stage":"Define","practice":"Capture outcomes, actors, scenarios, constraints, non-goals, and unresolved questions."},{"stage":"Refine","practice":"Remove ambiguity and contradictions before generating detailed implementation work."},{"stage":"Verify","practice":"Trace tests and shipped behavior back to explicit acceptance scenarios."}],"relatedPaths":["/prd","/topics/planning","/topics/tasks"],"sources":[{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks."},{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents."}],"canonicalUrl":"https://agentatlas.dev/topics/specifications"},{"slug":"planning","name":"Plans","category":"Delivery","summary":"A plan translates approved intent into technical decisions, dependencies, sequencing, migration strategy, and verification. Strong plans preserve the why behind choices and identify uncertainty before work is fragmented into tasks.","decisionRule":"Create a plan when implementation spans multiple boundaries, carries migration or rollback risk, or needs decisions that should be reviewed before code changes begin.","questions":["Which technical decisions and dependencies determine the implementation order?","What can proceed in parallel and what has a hard dependency?","How will migration, rollback, observability, and validation work?"],"artifacts":["plan.md","architecture decisions","dependency graph","rollout plan"],"lifecycle":[{"stage":"Design","practice":"Map each requirement to a technical decision and an explicit rationale."},{"stage":"Sequence","practice":"Order work around contracts, risk reduction, and independently verifiable increments."},{"stage":"Review","practice":"Challenge assumptions, missing dependencies, rollout risk, and validation coverage."}],"relatedPaths":["/topics/specifications","/topics/tasks","/topics/architecture"],"sources":[{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"The ordered specification, clarification, planning, tasking, analysis, implementation, and convergence workflow."},{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"Planning transparency, composable workflow patterns, and matching orchestration complexity to task requirements."}],"canonicalUrl":"https://agentatlas.dev/topics/planning"},{"slug":"tasks","name":"Tasks","category":"Delivery","summary":"Tasks turn a plan into bounded units with inputs, outputs, dependencies, acceptance checks, and ownership. Agent-ready tasks minimize hidden context and produce results that can be verified and integrated without replaying the entire reasoning process.","decisionRule":"Split work where outputs can be reviewed independently and dependencies are explicit. Do not create tiny tasks that add coordination cost without creating a meaningful verification boundary.","questions":["What concrete artifact or state change completes this task?","Which context and dependencies must be supplied rather than rediscovered?","Can the result be verified and integrated independently?"],"artifacts":["tasks.md","issue","acceptance checklist","dependency map"],"lifecycle":[{"stage":"Decompose","practice":"Create tasks around independently testable outputs rather than arbitrary file boundaries."},{"stage":"Execute","practice":"Provide required context, allowed scope, and a clear completion contract."},{"stage":"Integrate","practice":"Verify the output, reconcile dependencies, and update the parent plan."}],"relatedPaths":["/topics/planning","/agent-stack/subagents","/compare/subagents-vs-automations"],"sources":[{"label":"Agentic SDD workflow","publisher":"GitHub","url":"https://github.github.com/spec-kit/reference/agentic-sdd.html","supports":"Generating and analyzing implementation tasks after specification and planning quality gates."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Task identity, lifecycle, messages, status, artifacts, cancellation, and communication across agent boundaries."}],"canonicalUrl":"https://agentatlas.dev/topics/tasks"},{"slug":"memory-context","name":"Memory and context","category":"Runtime","summary":"Context is the information available for the current inference; memory is persisted state that may shape later runs. Reliable systems separate conversation history, durable facts, user preferences, project policy, and derived summaries so each can be governed and refreshed appropriately.","decisionRule":"Persist only information with a defined future use, owner, retention rule, and correction path. Retrieve the smallest high-signal context needed for the current decision.","questions":["What belongs in immediate context, session history, durable memory, or project instructions?","Who can inspect, correct, expire, or delete remembered information?","How will retrieval quality and compaction loss be measured?"],"artifacts":["session store","memory schema","retention policy","compaction strategy"],"lifecycle":[{"stage":"Classify","practice":"Separate transient context, conversation state, durable memory, and authoritative policy."},{"stage":"Persist","practice":"Use stable identities, scoped storage, retention limits, and correction mechanisms."},{"stage":"Evaluate","practice":"Test retrieval precision, stale-memory behavior, privacy, and compaction loss."}],"relatedPaths":["/agent-stack/memory-context","/compare/memory-vs-agents-md","/topics/context-engineering"],"sources":[{"label":"Sessions","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/sessions/","supports":"Session memory, storage choices, history limits, compaction, resumption, and operational persistence patterns."},{"label":"Effective context engineering for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","supports":"Treating context as a finite resource and curating instructions, tools, external data, history, and summaries across long-running agents."}],"canonicalUrl":"https://agentatlas.dev/topics/memory-context"},{"slug":"context-engineering","name":"Context engineering","category":"Runtime","summary":"Context engineering controls which instructions, examples, tools, retrieved facts, messages, and summaries reach the model at each step. The objective is not maximum context; it is the smallest current set that makes the desired behavior likely and reviewable.","decisionRule":"Add context only when it changes a named decision or reduces a measured failure. Prefer selective retrieval and structured summaries over accumulating every available token.","questions":["Which information must always be present and which should load on demand?","What is the provenance and freshness of retrieved context?","How will context growth, conflict, distraction, and loss be detected?"],"artifacts":["context budget","retrieval policy","compaction rules","provenance metadata"],"lifecycle":[{"stage":"Inventory","practice":"List every source of tokens and the decision each source is meant to support."},{"stage":"Curate","practice":"Rank, retrieve, summarize, and expire context based on relevance and authority."},{"stage":"Measure","practice":"Compare task quality, latency, token use, and failure modes under realistic context loads."}],"relatedPaths":["/agent-stack/memory-context","/topics/memory-context","/agents-md"],"sources":[{"label":"Effective context engineering for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","supports":"A model for curating limited context across instructions, tools, external data, history, and compaction."},{"label":"How Claude remembers your project","publisher":"Anthropic","url":"https://code.claude.com/docs/en/memory","supports":"Repository instruction hierarchy, project memory, scoped rules, and how persistent context is discovered and loaded."}],"canonicalUrl":"https://agentatlas.dev/topics/context-engineering"},{"slug":"tools-mcp","name":"Tools and MCP","category":"Runtime","summary":"Tools let models request deterministic functions; MCP standardizes how compatible hosts discover and call external tools, resources, and prompts. Good tool design minimizes ambiguity, constrains inputs, makes side effects visible, and returns results the model can interpret reliably.","decisionRule":"Use a local function for application-owned capability and MCP when independently maintained systems need a reusable protocol boundary. Require approval for consequential side effects.","questions":["Is the capability read-only, reversible, consequential, or externally stateful?","What schema and descriptions make correct tool selection likely?","How are authentication, authorization, timeouts, retries, and output size controlled?"],"artifacts":["tool schema","MCP server","auth policy","approval rules"],"lifecycle":[{"stage":"Contract","practice":"Define narrow inputs, outputs, errors, side effects, and authorization requirements."},{"stage":"Connect","practice":"Expose the capability through the simplest appropriate application or protocol boundary."},{"stage":"Verify","practice":"Test discovery, selection, malformed input, permission denial, timeout, and duplicate execution."}],"relatedPaths":["/mcp","/agent-stack/mcp-tools","/compare/mcp-vs-skills"],"sources":[{"label":"MCP specification","publisher":"Model Context Protocol","url":"https://modelcontextprotocol.io/specification/","supports":"The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations."},{"label":"Connect Codex to MCP servers","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/extend/mcp","supports":"How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities."}],"canonicalUrl":"https://agentatlas.dev/topics/tools-mcp"},{"slug":"multi-agent","name":"Multi-agent systems","category":"Runtime","summary":"Multi-agent systems divide work among specialized or isolated agents and synthesize their outputs. They are valuable when work partitions cleanly or trust boundaries differ, but they add coordination, context transfer, conflict resolution, and observability costs.","decisionRule":"Delegate only when a bounded subtask can run with a clear input and completion contract. Keep tightly coupled reasoning in one context until measurement proves otherwise.","questions":["Can the work be partitioned without constant shared-state coordination?","What context, tools, and permissions does each agent receive?","Who resolves conflicts and verifies the combined result?"],"artifacts":["agent roster","delegation contract","handoff schema","synthesis checklist"],"lifecycle":[{"stage":"Partition","practice":"Split work around independent outputs, expertise, or trust boundaries."},{"stage":"Delegate","practice":"Provide scoped context, tools, budget, and an explicit return contract."},{"stage":"Synthesize","practice":"Resolve overlap and contradictions before verifying the whole outcome."}],"relatedPaths":["/agent-stack/subagents","/compare/subagents-vs-automations","/topics/interoperability"],"sources":[{"label":"Codex subagents","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/agent-configuration/subagents","supports":"Subagent configuration, scoped roles, delegation behavior, and parallel work inside Codex."},{"label":"Create custom subagents","publisher":"Anthropic","url":"https://code.claude.com/docs/en/sub-agents","supports":"Specialized subagent configuration, context isolation, tools, permissions, and delegation patterns."}],"canonicalUrl":"https://agentatlas.dev/topics/multi-agent"},{"slug":"interoperability","name":"Agent interoperability","category":"Runtime","summary":"Interoperability allows hosts, tools, and independently operated agents to discover capabilities and exchange work through explicit contracts. MCP primarily connects models to tools and context; A2A primarily coordinates agents and task artifacts across service boundaries.","decisionRule":"Choose the protocol that matches the boundary: MCP for tool or context access, A2A for collaboration with an independently operated agent, and ordinary application APIs when neither abstraction is needed.","questions":["Is the remote party a tool service, context provider, or autonomous agent?","How are capabilities discovered, authenticated, versioned, and revoked?","What task state, messages, and artifacts must cross the boundary?"],"artifacts":["MCP manifest","Agent Card","task contract","security scheme"],"lifecycle":[{"stage":"Classify","practice":"Identify whether the boundary exposes capability, data, or autonomous collaboration."},{"stage":"Contract","practice":"Publish discovery metadata, schemas, versions, and security requirements."},{"stage":"Operate","practice":"Monitor compatibility, task state, authentication failure, and protocol upgrades."}],"relatedPaths":["/compare/mcp-vs-a2a","/mcp","/a2a"],"sources":[{"label":"MCP specification","publisher":"Model Context Protocol","url":"https://modelcontextprotocol.io/specification/","supports":"Host, client, and server roles plus capability negotiation for tools, resources, and prompts."},{"label":"A2A protocol specification","publisher":"A2A Project","url":"https://a2a-protocol.org/latest/specification/","supports":"Agent discovery, tasks, messages, artifacts, protocol bindings, security, and interoperability requirements."}],"canonicalUrl":"https://agentatlas.dev/topics/interoperability"},{"slug":"workflows-automation","name":"Workflows and automation","category":"Runtime","summary":"Workflows encode known control paths; automations trigger those workflows on a schedule or event without continuous human initiation. Reliable automation requires idempotency, retry policy, durable state, ownership, observability, and a clear boundary for escalation.","decisionRule":"Automate after a workflow is repeatable, measurable, and safe to retry. Use model-directed agents only for the portions that genuinely require flexible judgment.","questions":["What event starts the workflow and how are duplicates identified?","Which steps are deterministic and which require model judgment?","How are retries, deadlines, partial completion, and escalation handled?"],"artifacts":["workflow definition","trigger","idempotency key","runbook"],"lifecycle":[{"stage":"Stabilize","practice":"Run the workflow manually until inputs, outputs, and failure modes are understood."},{"stage":"Automate","practice":"Add triggers, durable state, retries, deadlines, and bounded side effects."},{"stage":"Operate","practice":"Monitor completion, cost, drift, queue health, and human escalation."}],"relatedPaths":["/agent-stack/automations","/compare/subagents-vs-automations","/topics/observability"],"sources":[{"label":"Building effective agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/building-effective-agents","supports":"The distinction between predefined workflows and model-directed agents plus composable orchestration patterns."},{"label":"Codex automations","publisher":"OpenAI","url":"https://learn.chatgpt.com/docs/automations","supports":"Scheduling recurring Codex work, repository execution, review flows, and automation configuration."}],"canonicalUrl":"https://agentatlas.dev/topics/workflows-automation"},{"slug":"evals-verification","name":"Evals and verification","category":"Operations","summary":"Evals measure behavior across representative tasks; verification checks whether a specific run produced an acceptable result. Production systems need both: aggregate evidence for change decisions and concrete completion checks before outputs or side effects are trusted.","decisionRule":"Define expected behavior and graders before optimizing prompts, models, tools, or autonomy. Keep deterministic verification close to consequential outputs.","questions":["Which representative tasks and failure modes define acceptable performance?","Which checks can be deterministic and which require expert judgment?","How will regressions be attributed to model, context, tool, or workflow changes?"],"artifacts":["eval dataset","grader","acceptance test","regression report"],"lifecycle":[{"stage":"Specify","practice":"Translate desired behavior and known failures into representative examples and graders."},{"stage":"Measure","practice":"Evaluate the complete workflow, not only isolated model responses."},{"stage":"Gate","practice":"Require relevant checks before rollout and before consequential side effects."}],"relatedPaths":["/agent-stack/evals-verification","/topics/observability","/topics/safety-permissions"],"sources":[{"label":"Evaluation best practices","publisher":"OpenAI","url":"https://developers.openai.com/api/docs/guides/evaluation-best-practices","supports":"Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes."},{"label":"Demystifying evals for AI agents","publisher":"Anthropic","url":"https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents","supports":"Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement."}],"canonicalUrl":"https://agentatlas.dev/topics/evals-verification"},{"slug":"observability","name":"Observability","category":"Operations","summary":"Agent observability connects user outcomes to model turns, tool calls, handoffs, guardrails, latency, token use, and errors. Useful telemetry makes an end-to-end workflow explainable while controlling sensitive prompt, output, argument, and result data.","decisionRule":"Trace every production workflow end to end with stable identities and privacy-aware attributes. Record enough to diagnose failures without treating sensitive content as harmless telemetry.","questions":["Can one user-visible outcome be followed across models, tools, agents, and queues?","Which content is sensitive and should be redacted, sampled, or excluded?","Which metrics reveal quality, latency, cost, retries, and operational saturation?"],"artifacts":["trace","span conventions","dashboard","alert policy"],"lifecycle":[{"stage":"Instrument","practice":"Create end-to-end trace identities and spans for model, tool, handoff, and guardrail operations."},{"stage":"Protect","practice":"Classify sensitive telemetry and apply redaction, access, retention, and sampling rules."},{"stage":"Learn","practice":"Connect operational signals to eval failures, incidents, cost, and product outcomes."}],"relatedPaths":["/topics/evals-verification","/topics/deployment-operations","/monitoring"],"sources":[{"label":"OpenTelemetry semantic conventions","publisher":"OpenTelemetry","url":"https://opentelemetry.io/docs/specs/semconv/","supports":"Standard names, attributes, traces, metrics, logs, and generative-AI operations for interoperable telemetry."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Tracing model generations, tools, handoffs, guardrails, custom events, workflow grouping, and sensitive-data controls."}],"canonicalUrl":"https://agentatlas.dev/topics/observability"},{"slug":"deployment-operations","name":"Deployment and operations","category":"Operations","summary":"Operating agents in production requires durable run identities, bounded time and cost, resumable state, safe retries, versioned dependencies, rollback, observability, and ownership. Deployment is a change to a live decision system, not merely a code upload.","decisionRule":"Deploy incrementally with versioned configuration, representative eval gates, end-to-end traces, explicit budgets, and a tested rollback or kill path.","questions":["Which model, prompt, tool, Skill, and policy versions produced a run?","How are long-running, interrupted, duplicated, or abandoned runs recovered?","What signals trigger rollback, throttling, disabling, or human intervention?"],"artifacts":["release manifest","run budget","rollback procedure","operations dashboard"],"lifecycle":[{"stage":"Release","practice":"Version models, instructions, tools, schemas, policies, and migrations together."},{"stage":"Control","practice":"Set budgets, concurrency, deadlines, retries, circuit breakers, and approval boundaries."},{"stage":"Recover","practice":"Test rollback, resume, replay protection, degraded mode, and incident ownership."}],"relatedPaths":["/topics/observability","/topics/evals-verification","/topics/human-approval"],"sources":[{"label":"Running agents","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/running_agents/","supports":"Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior."},{"label":"OpenAI Agents SDK tracing","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/tracing/","supports":"Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis."}],"canonicalUrl":"https://agentatlas.dev/topics/deployment-operations"},{"slug":"safety-permissions","name":"Safety and permissions","category":"Governance","summary":"Safety combines behavioral guidance with enforceable controls around data, tools, networks, execution, and human approval. Prompts can shape intent, but least-privilege permissions and sandbox boundaries limit what mistakes or attacks can actually affect.","decisionRule":"Assume model output and external content can be wrong or adversarial. Enforce the narrowest permissions outside the prompt and require approval for consequential, irreversible, or cross-boundary actions.","questions":["What assets and side effects are reachable from this run?","Which decisions are enforced by code, policy, sandbox, or human review?","How are prompt injection, secret exposure, and untrusted tool output contained?"],"artifacts":["threat model","permission policy","sandbox profile","approval matrix"],"lifecycle":[{"stage":"Threat-model","practice":"Map untrusted inputs, assets, trust boundaries, abuse cases, and recovery requirements."},{"stage":"Enforce","practice":"Apply least privilege, isolation, secret boundaries, validation, and approvals outside model instructions."},{"stage":"Test","practice":"Exercise injection, exfiltration, privilege escalation, denial, and recovery scenarios."}],"relatedPaths":["/agent-stack/permissions-safety","/compare/permissions-vs-prompt-guardrails","/topics/human-approval"],"sources":[{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Sandboxing, approvals, network access, filesystem controls, and security boundaries for agentic coding work."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission rules, allow and deny controls, managed policy, tool authorization, and least-privilege configuration."}],"canonicalUrl":"https://agentatlas.dev/topics/safety-permissions"},{"slug":"human-approval","name":"Human approval","category":"Governance","summary":"Human approval is a control boundary for decisions that require accountable judgment. A useful approval presents the proposed action, arguments, evidence, consequences, and alternatives, then persists the decision so a paused run can resume safely.","decisionRule":"Require approval when an action is consequential, difficult to reverse, outside prior authority, or meaningfully ambiguous. Do not ask humans to approve low-information prompts they cannot evaluate.","questions":["What exact action, arguments, evidence, and consequences does the reviewer see?","Can the reviewer modify, reject, defer, or scope the approval?","How is paused state persisted and protected until the decision arrives?"],"artifacts":["approval request","decision record","resumable state","escalation policy"],"lifecycle":[{"stage":"Interrupt","practice":"Pause before the side effect and surface a complete, understandable decision packet."},{"stage":"Decide","practice":"Capture reviewer identity, scope, rationale, and any modified parameters."},{"stage":"Resume","practice":"Bind the decision to the original call, prevent replay, and continue from durable state."}],"relatedPaths":["/topics/agent-product-design","/topics/safety-permissions","/agent-stack/permissions-safety"],"sources":[{"label":"Human-in-the-loop","publisher":"OpenAI","url":"https://openai.github.io/openai-agents-python/human_in_the_loop/","supports":"Approval-required tools, interruptions, rejection messages, persisted run state, resumption, and long-running approvals."},{"label":"Configure permissions","publisher":"Anthropic","url":"https://code.claude.com/docs/en/permissions","supports":"Permission modes, explicit allow and deny rules, managed controls, and user approval for tool execution."}],"canonicalUrl":"https://agentatlas.dev/topics/human-approval"},{"slug":"governance","name":"Governance","category":"Governance","summary":"Agent governance assigns ownership and policy across instructions, models, tools, data, evaluation, permissions, releases, incidents, and vendors. It should make authority and evidence visible without turning every low-risk improvement into a centralized bottleneck.","decisionRule":"Govern according to impact: stronger review, traceability, access control, and change management for systems with broader data access, autonomy, or consequences.","questions":["Who owns behavior, data, tools, releases, incidents, and user recourse?","Which evidence is required before a capability or change can ship?","How are exceptions, expiry, audits, and policy updates managed?"],"artifacts":["ownership matrix","policy set","change record","exception register"],"lifecycle":[{"stage":"Classify","practice":"Tier systems by data sensitivity, autonomy, reach, reversibility, and consequence."},{"stage":"Control","practice":"Assign owners, evidence gates, access rules, review cadence, and exception paths."},{"stage":"Audit","practice":"Review changes, incidents, stale permissions, vendors, and unresolved exceptions."}],"relatedPaths":["/agents-md","/topics/safety-permissions","/topics/deployment-operations"],"sources":[{"label":"AGENTS.md specification","publisher":"AGENTS.md","url":"https://agents.md/","supports":"Versioned repository instructions that make build, test, style, and contribution requirements available to agents."},{"label":"GitHub Spec Kit","publisher":"GitHub","url":"https://github.github.com/spec-kit/index.html","supports":"Governed specification-driven workflows, quality checks, organizational principles, and traceability across delivery artifacts."},{"label":"Codex security","publisher":"OpenAI","url":"https://developers.openai.com/codex/security","supports":"Operational authority boundaries enforced through sandboxing, permissions, approvals, and network controls."}],"canonicalUrl":"https://agentatlas.dev/topics/governance"},{"slug":"agent-commerce","name":"Agent commerce","category":"Ecosystem","summary":"Agent commerce separates discovery, offer details, checkout coordination, user authorization, payment execution, fulfillment, and receipts. Protocols can make these steps interoperable, but accountable consent and auditable state remain application responsibilities.","decisionRule":"Treat offer discovery and transaction authorization as separate trust decisions. Bind user intent to explicit terms before payment or another consequential commitment.","questions":["How are offers, merchants, credentials, and transaction terms authenticated?","What evidence binds user intent to a specific purchase or mandate?","How are retries, duplicate charges, fulfillment, refunds, and disputes handled?"],"artifacts":["offer","checkout session","mandate","receipt"],"lifecycle":[{"stage":"Discover","practice":"Identify offers and merchants without treating visibility as trust."},{"stage":"Authorize","practice":"Present exact terms and bind accountable user intent before commitment."},{"stage":"Settle","practice":"Execute idempotently and preserve receipts, fulfillment state, and recourse."}],"relatedPaths":["/ap2","/agent-stack/commerce-protocols","/topics/safety-permissions"],"sources":[{"label":"Universal Commerce Protocol","publisher":"UCP","url":"https://ucp.dev/","supports":"Interoperable commerce capabilities, discovery, checkout, identity, payment, fulfillment, and extension patterns."},{"label":"Agent Payments Protocol","publisher":"AP2","url":"https://ap2-protocol.org/","supports":"Cryptographically verifiable mandates and accountable authorization across agent-initiated payment flows."}],"canonicalUrl":"https://agentatlas.dev/topics/agent-commerce"},{"slug":"model-strategy","name":"Model strategy","category":"Ecosystem","summary":"Model strategy matches workload requirements to model capability, latency, cost, context, tool use, and operational controls. A production choice should be based on representative evaluation and a migration path, not a permanent assumption that one provider or benchmark is universally best.","decisionRule":"Choose models with task-specific evals and operational constraints. Preserve enough abstraction and evidence to revisit the choice when providers, prices, controls, or workloads change.","questions":["Which capabilities and failure modes matter for this workload?","What latency, cost, context, privacy, and regional constraints apply?","How will model upgrades, fallbacks, and provider migration be evaluated?"],"artifacts":["model scorecard","eval report","routing policy","migration plan"],"lifecycle":[{"stage":"Benchmark","practice":"Evaluate representative inputs, complete workflows, and known hard cases."},{"stage":"Operate","practice":"Track quality, latency, cost, limits, safety behavior, and provider changes."},{"stage":"Revisit","practice":"Re-run evals before upgrades and keep fallback assumptions current."}],"relatedPaths":["/model-guides","/topics/evals-verification","/topics/deployment-operations"],"sources":[{"label":"GPT-5.4 model guide","publisher":"OpenAI","url":"https://developers.openai.com/api/docs/models/gpt-5.4","supports":"Current OpenAI model capabilities, context, tool support, controls, and operational characteristics."},{"label":"Claude prompting best practices","publisher":"Anthropic","url":"https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices","supports":"Current Claude prompting controls and provider-specific practices that should be evaluated rather than generalized across models."}],"canonicalUrl":"https://agentatlas.dev/topics/model-strategy"}]},"agentStack":{"canonicalUrl":"https://agentatlas.dev/agent-stack","reviewedAt":"2026-07-26","reviewCadenceDays":30,"items":[{"slug":"repository-instructions","name":"Repository instructions","eyebrow":"AGENTS.md · CLAUDE.md · scoped rules","category":"Context","summary":"Durable, version-controlled guidance that tells coding agents how a repository is organized, how to verify work, and which boundaries matter.","choice":"Use an instruction file for facts and rules that should be present across many sessions. Keep long procedures in Skills so they load only when needed.","whenToUse":["The same build, test, architecture, or safety guidance applies to most work in a repository.","A monorepo needs narrower instructions near individual packages.","Several agents need one shared source of project truth."],"notFor":["A one-time task request that belongs in the current prompt.","A hard enforcement requirement that should be implemented as a hook, policy, or CI check."],"buildPath":[{"title":"Write the minimum shared truth","detail":"Document real commands, important paths, review expectations, and explicit boundaries. Prefer instructions that a reviewer can verify.","check":"A new contributor can use the file without guessing which commands or directories are current."},{"title":"Scope instructions close to the work","detail":"Use nested files or path-scoped rules for package-specific guidance instead of growing one repository-wide prompt.","check":"Unrelated work does not receive package-specific context."},{"title":"Audit for drift and conflicts","detail":"Review instruction files when commands, architecture, or agent behavior changes. Remove duplicated or contradictory rules.","check":"Every instruction still describes the repository and has one clear owner."}],"filePatterns":["AGENTS.md","CLAUDE.md",".claude/rules/*.md",".cursor/rules/*.mdc"],"connectsTo":["skills","hooks","evals-verification"],"relatedRoute":"/agents-md","sources":[{"label":"AGENTS.md specification and examples","url":"https://agents.md/","publisher":"AGENTS.md","supports":"The portable AGENTS.md format and repository instruction pattern."},{"label":"Codex AGENTS.md guidance","url":"https://learn.chatgpt.com/docs/agent-configuration/agents-md","publisher":"OpenAI","supports":"Codex discovery, precedence, scope, and maintenance guidance."},{"label":"How Claude remembers your project","url":"https://code.claude.com/docs/en/memory","publisher":"Anthropic","supports":"CLAUDE.md locations, loading behavior, concise instruction guidance, and AGENTS.md interoperability."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/repository-instructions"},{"slug":"skills","name":"Agent Skills","eyebrow":"SKILL.md · scripts · references · assets","category":"Capability","summary":"Discoverable, reusable packages of instructions and resources that teach an agent a specialized workflow without loading the whole procedure into every session.","choice":"Use a Skill when a procedure is repeated, specialized, or too large for always-on repository instructions.","whenToUse":["A workflow has a stable trigger, sequence, quality bar, and reusable supporting files.","Teams repeatedly paste the same checklist or domain guidance into chats.","The capability should be portable across projects or compatible agents."],"notFor":["A short repository fact that every session needs.","A deterministic lifecycle action that must run whether the model remembers it or not."],"buildPath":[{"title":"Describe the trigger precisely","detail":"Give the Skill a clear name and a description that says both what it does and when it should run.","check":"Representative requests select the Skill; unrelated requests do not."},{"title":"Use progressive disclosure","detail":"Keep the entrypoint focused, then link scripts, templates, references, and examples the agent should load only when relevant.","check":"The core workflow is understandable without injecting every reference into context."},{"title":"Make success testable","detail":"Include validation steps, failure handling, and a concrete output contract. Test implicit and explicit invocation.","check":"The Skill produces the expected artifact on several real tasks and fails safely when prerequisites are missing."}],"filePatterns":["SKILL.md","scripts/*","references/*","assets/*"],"connectsTo":["repository-instructions","plugins","subagents"],"relatedRoute":"/skills","sources":[{"label":"Agent Skills specification","url":"https://agentskills.io/specification","publisher":"Agent Skills","supports":"The open SKILL.md package format and progressive-disclosure model."},{"label":"Build skills for ChatGPT and Codex","url":"https://learn.chatgpt.com/docs/build-skills","publisher":"OpenAI","supports":"Current OpenAI Skill structure, discovery, and authoring guidance."},{"label":"Extend Claude with skills","url":"https://code.claude.com/docs/en/skills","publisher":"Anthropic","supports":"Claude Code Skill discovery, configuration, supporting files, and invocation behavior."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/skills"},{"slug":"plugins","name":"Plugins","eyebrow":"Skills · agents · hooks · connectors","category":"Distribution","summary":"Installable bundles that distribute one or more agent extensions—such as Skills, subagents, hooks, MCP servers, or application connectors—as a coherent product.","choice":"Use a plugin when capabilities need versioned installation, namespacing, updates, and distribution. A single project-local workflow usually starts as a Skill.","whenToUse":["Several related extensions should install and update together.","A capability needs a manifest, namespace, ownership, and release lifecycle.","Teams need a repeatable way to enable the same approved integration."],"notFor":["One short workflow used only inside a single repository.","An API integration with no agent-facing instructions or tools."],"buildPath":[{"title":"Define the installable boundary","detail":"Group only components that share a purpose, maintainer, and release lifecycle. Declare prerequisites and external access.","check":"A user can explain exactly what is added after installation."},{"title":"Namespace and document components","detail":"Use clear component names, precise trigger descriptions, and a manifest that exposes ownership and version information.","check":"Installed components do not collide with project or user configuration."},{"title":"Treat updates as supply-chain events","detail":"Review hooks, scripts, servers, permissions, and network destinations before publishing or accepting a new version.","check":"A version can be audited, pinned, upgraded, and removed predictably."}],"filePatterns":[".codex-plugin/plugin.json",".claude-plugin/plugin.json","skills/*/SKILL.md","agents/*","hooks/*"],"connectsTo":["skills","subagents","mcp-tools","hooks"],"relatedRoute":"/learn","sources":[{"label":"Plugins in ChatGPT and Codex","url":"https://learn.chatgpt.com/docs/plugins","publisher":"OpenAI","supports":"OpenAI plugin packaging, components, and distribution model."},{"label":"Claude Code plugins","url":"https://code.claude.com/docs/en/plugins","publisher":"Anthropic","supports":"Claude Code plugin manifests, marketplaces, and packaged extension types."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/plugins"},{"slug":"subagents","name":"Subagents and agent teams","eyebrow":"Delegation · isolation · parallel work","category":"Orchestration","summary":"Specialized workers that perform bounded tasks in separate contexts and return results to a coordinating agent or shared team.","choice":"Use subagents for independent, context-heavy work that can return a concise result. Keep tightly coupled or write-conflicting work in one context.","whenToUse":["Research, logs, tests, or repository exploration would flood the main context.","Independent workstreams can run in parallel with clear ownership.","A specialist needs a narrower prompt, model, or tool permission set."],"notFor":["A quick change that depends on the full conversation and frequent user feedback.","Parallel edits to the same files without isolation and merge ownership."],"buildPath":[{"title":"Delegate a bounded outcome","detail":"Give each worker a concrete task, relevant context, allowed tools, constraints, and the expected return format.","check":"The worker can complete without asking the coordinator to reconstruct the task."},{"title":"Partition state and writes","detail":"Prefer read-heavy parallel work. For edits, assign non-overlapping files or isolated worktrees and name the integration owner.","check":"Two workers cannot silently overwrite the same state."},{"title":"Verify the synthesis","detail":"Treat worker summaries as inputs, not proof. The coordinator checks citations, tests, and conflicts before acting.","check":"The final result preserves evidence and resolves disagreements explicitly."}],"filePatterns":[".codex/agents/*.toml",".claude/agents/*.md","agent manifests","worktree task plans"],"connectsTo":["skills","permissions-safety","evals-verification"],"relatedRoute":"/agent-stack/subagents","sources":[{"label":"Codex subagents","url":"https://learn.chatgpt.com/docs/agent-configuration/subagents","publisher":"OpenAI","supports":"Delegation patterns, custom agents, permissions, and token tradeoffs in Codex."},{"label":"Create custom subagents","url":"https://code.claude.com/docs/en/sub-agents","publisher":"Anthropic","supports":"Claude Code subagent contexts, invocation, permissions, background work, and common patterns."},{"label":"Run agents in parallel","url":"https://code.claude.com/docs/en/agents","publisher":"Anthropic","supports":"The distinction among subagents, teams, background sessions, and worktree isolation."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/subagents"},{"slug":"mcp-tools","name":"Tools and MCP","eyebrow":"Capabilities · resources · prompts · servers","category":"Connectivity","summary":"Typed tools connect an agent to actions and data. The Model Context Protocol standardizes how compatible clients discover and invoke those capabilities.","choice":"Use MCP when a capability should work across compatible clients or needs a standard server boundary. Use a local function tool when the integration is application-specific.","whenToUse":["An agent needs current data or actions beyond its built-in environment.","Several clients should reuse the same server and capability definitions.","Authentication, consent, schemas, and error behavior need an explicit boundary."],"notFor":["Static knowledge that belongs in a reference file or retrieval index.","A vague mega-tool whose inputs, side effects, or failure modes cannot be described."],"buildPath":[{"title":"Design the tool contract first","detail":"Name one capability, define typed inputs and outputs, describe side effects, and return errors the agent can act on.","check":"A model can choose the tool and construct valid arguments from its description alone."},{"title":"Separate reads from writes","detail":"Expose least-privilege capabilities, make destructive or external actions obvious, and require appropriate consent.","check":"A read-only workflow cannot accidentally perform a mutation."},{"title":"Test discovery and recovery","detail":"Validate schemas against real clients, exercise authentication and failures, and log calls without exposing secrets.","check":"The same representative task succeeds—or fails clearly—across supported clients."}],"filePatterns":["mcp.json",".mcp.json","server manifests","tool schemas"],"connectsTo":["plugins","agent-to-agent","permissions-safety"],"relatedRoute":"/mcp","sources":[{"label":"MCP specification","url":"https://modelcontextprotocol.io/specification/","publisher":"Model Context Protocol","supports":"The official protocol model, lifecycle, capabilities, and security guidance."},{"label":"Connect Codex to MCP servers","url":"https://learn.chatgpt.com/docs/extend/mcp","publisher":"OpenAI","supports":"Current Codex MCP configuration and client behavior."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/mcp-tools"},{"slug":"agent-to-agent","name":"Agent-to-agent protocols","eyebrow":"A2A · agent cards · tasks · messages","category":"Connectivity","summary":"Protocols for discovering remote agents, negotiating supported interfaces, exchanging messages, and tracking long-running tasks across organizational boundaries.","choice":"Use A2A when one independently operated agent must collaborate with another as a remote service. Use subagents for workers inside one coordinator and trust boundary.","whenToUse":["Agents are owned, deployed, or secured by different systems.","A remote task needs discovery, lifecycle state, artifacts, and asynchronous updates.","Integration should not depend on exposing an agent's internal memory or implementation."],"notFor":["Calling a deterministic data or action tool; MCP or an API is usually clearer.","Delegating to an in-process worker controlled by the same runtime."],"buildPath":[{"title":"Publish an accurate capability card","detail":"Describe the agent's identity, interfaces, authentication expectations, and supported skills without overstating what is production-ready.","check":"A client can discover whether the agent is compatible before sending a task."},{"title":"Model task lifecycle explicitly","detail":"Handle accepted, working, input-required, completed, failed, and canceled states with stable identifiers.","check":"Retries and reconnects do not create ambiguous duplicate work."},{"title":"Secure every boundary","detail":"Authenticate callers, authorize tasks, minimize shared data, validate artifacts, and preserve an audit trail.","check":"A remote agent cannot exceed the capabilities granted to the requesting identity."}],"filePatterns":["/.well-known/agent-card.json","A2A task schemas","message and artifact types"],"connectsTo":["mcp-tools","subagents","permissions-safety"],"relatedRoute":"/a2a","sources":[{"label":"A2A protocol specification","url":"https://a2a-protocol.org/latest/specification/","publisher":"A2A Project","supports":"Agent discovery, messages, tasks, artifacts, transports, and security."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/agent-to-agent"},{"slug":"memory-context","name":"Memory and context","eyebrow":"Working context · durable memory · retrieval","category":"Context","summary":"The systems that decide what an agent sees now, what it can retrieve later, and which durable facts persist across sessions.","choice":"Put stable team rules in version control, user- or project-specific learnings in inspectable memory, and large reference collections behind retrieval.","whenToUse":["Work spans multiple turns or sessions and useful state would otherwise be lost.","A large knowledge base should be retrieved selectively instead of always loaded.","Preferences or project observations need an editable, inspectable home."],"notFor":["Secrets, credentials, or sensitive data without an explicit storage policy.","Hard constraints that must be enforced independently of model attention."],"buildPath":[{"title":"Classify the information","detail":"Separate task state, durable project truth, user preferences, retrieved evidence, and sensitive data before choosing storage.","check":"Each item has an owner, lifetime, access boundary, and deletion path."},{"title":"Retrieve the smallest useful context","detail":"Load only material relevant to the current decision, label provenance, and prefer summaries that link back to primary evidence.","check":"Removing unrelated context does not reduce task quality."},{"title":"Make memory inspectable","detail":"Let users review, edit, expire, and delete saved information. Test stale and contradictory memories.","check":"A user can explain what was remembered and correct it without hidden state."}],"filePatterns":["MEMORY.md","project memory stores","retrieval indexes","session state"],"connectsTo":["repository-instructions","skills","evals-verification"],"relatedRoute":"/agent-stack/memory-context","sources":[{"label":"Codex memories","url":"https://learn.chatgpt.com/docs/customization/memories","publisher":"OpenAI","supports":"Codex memory behavior, inspection, and user control."},{"label":"How Claude remembers your project","url":"https://code.claude.com/docs/en/memory","publisher":"Anthropic","supports":"Claude Code instruction scope, auto memory storage, loading limits, and auditing."},{"label":"Effective context engineering for AI agents","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","publisher":"Anthropic","supports":"Context selection, compaction, structured notes, and long-horizon agent patterns."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/memory-context"},{"slug":"hooks","name":"Hooks","eyebrow":"Lifecycle events · policy checks · formatters","category":"Control","summary":"Deterministic handlers that run at defined points in an agent lifecycle to validate, block, transform, log, or trigger work.","choice":"Use a hook when an action must happen at a specific lifecycle event. Use instructions when judgment is acceptable and a Skill when a workflow should be invoked on demand.","whenToUse":["A formatter, validator, audit log, or policy check must run consistently.","Tool calls need inspection before or after execution.","The environment or context must be refreshed at a known lifecycle event."],"notFor":["Open-ended reasoning that benefits from the main agent's full context.","Unreviewed third-party scripts with broad local or network access."],"buildPath":[{"title":"Choose the narrowest event","detail":"Trigger only at the lifecycle point and tool pattern that require control; avoid global handlers when a scoped matcher works.","check":"The hook does not slow or alter unrelated operations."},{"title":"Fail clearly and safely","detail":"Set timeouts, validate input, use meaningful exit behavior, and return guidance the agent or user can act on.","check":"Failure cannot silently bypass a required policy or trap the session in a loop."},{"title":"Review it as executable code","detail":"Inspect commands, URLs, permissions, logging, and secret handling before enabling shared or downloaded hooks.","check":"Every side effect and external destination is documented and owned."}],"filePatterns":[".claude/settings.json","hooks/hooks.json","Skill or agent frontmatter","policy scripts"],"connectsTo":["repository-instructions","plugins","permissions-safety"],"relatedRoute":"/agent-stack/hooks","sources":[{"label":"Codex hooks","url":"https://learn.chatgpt.com/docs/hooks","publisher":"OpenAI","supports":"Codex lifecycle hooks, configuration, and trust guidance."},{"label":"Automate workflows with hooks","url":"https://code.claude.com/docs/en/hooks-guide","publisher":"Anthropic","supports":"Claude Code hook events, deterministic controls, configuration, and examples."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/hooks"},{"slug":"automations","name":"Automations","eyebrow":"Schedules · triggers · unattended runs","category":"Operations","summary":"Repeatable agent runs started by time or events, with explicit inputs, permissions, outputs, review gates, and recovery behavior.","choice":"Automate stable workflows with bounded effects and observable outcomes. Keep exploratory or high-ambiguity tasks interactive until the failure modes are understood.","whenToUse":["The same source collection, triage, report, or maintenance task repeats on a schedule.","Inputs and completion checks can be stated before the run begins.","Failures can alert an owner and be retried without duplicating side effects."],"notFor":["Irreversible, high-impact decisions without human approval.","A process whose output cannot be evaluated or traced to its inputs."],"buildPath":[{"title":"Stabilize the manual workflow","detail":"Run the task interactively until inputs, decisions, output format, and common failures are known.","check":"Different operators can produce equivalent reviewed results."},{"title":"Bound permissions and side effects","detail":"Use least-privilege credentials, idempotency, approval gates, timeouts, and isolated environments.","check":"A retry cannot duplicate a message, payment, deployment, or destructive change."},{"title":"Operate it like production","detail":"Record source revisions, run logs, artifacts, costs, and quality checks; alert a named owner on failure or drift.","check":"Every run is discoverable, explainable, and recoverable."}],"filePatterns":[".github/workflows/*.yml","cron configuration","workflow manifests","run logs and artifacts"],"connectsTo":["hooks","evals-verification","permissions-safety"],"relatedRoute":"/agent-stack/automations","sources":[{"label":"Codex automations","url":"https://learn.chatgpt.com/docs/automations","publisher":"OpenAI","supports":"Scheduled Codex work, execution behavior, review, and management."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/automations"},{"slug":"evals-verification","name":"Evals and verification","eyebrow":"Representative tasks · graders · traces · regression gates","category":"Quality","summary":"A repeatable evidence loop that measures whether an agent completes representative tasks correctly, safely, and efficiently.","choice":"Use evals to compare prompts, models, tools, and policies before relying on anecdotes. Pair automatic graders with human review for consequential work.","whenToUse":["A prompt, model, tool, or agent workflow will be reused in production.","Teams need to know whether an update improved quality or only changed style.","Failures can be turned into representative regression cases."],"notFor":["A vanity benchmark that does not resemble the real workload.","A single aggregate score that hides severe safety or task-specific failures."],"buildPath":[{"title":"Define observable success","detail":"Collect representative inputs, expected properties, required evidence, forbidden behavior, and useful cost or latency measures.","check":"A reviewer can decide pass or fail without knowing which model produced the output."},{"title":"Use layered graders","detail":"Combine deterministic checks, rubric-based model grading, trace inspection, and human review where judgment matters.","check":"Known good and known bad examples produce the expected grade."},{"title":"Make every failure reusable","detail":"Classify failures, add important cases to the suite, and compare changes on the same set before rollout.","check":"A fix cannot silently regress an older capability or safety boundary."}],"filePatterns":["evals/*","fixtures/*","grader schemas","trace datasets"],"connectsTo":["automations","permissions-safety","memory-context"],"relatedRoute":"/agent-stack/evals-verification","sources":[{"label":"Evaluation best practices","url":"https://developers.openai.com/api/docs/guides/evaluation-best-practices","publisher":"OpenAI","supports":"Eval design, representative datasets, graders, continuous evaluation, and failure analysis."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/evals-verification"},{"slug":"permissions-safety","name":"Permissions and safety","eyebrow":"Least privilege · approvals · sandboxing · audit","category":"Control","summary":"The trust boundaries that constrain what an agent can read, execute, change, publish, purchase, or send on a user's behalf.","choice":"Grant the smallest capability needed for the current outcome. Separate read, local write, external write, destructive, financial, and delegated authority.","whenToUse":["Always—especially when tools reach files, networks, credentials, production systems, or other people.","An agent or subagent can perform side effects without continuous supervision.","Downloaded plugins, hooks, or MCP servers introduce new executable code or data access."],"notFor":["A prompt-only promise where a platform policy, sandbox, or approval boundary is available.","Permanent broad access granted to avoid designing a narrower workflow."],"buildPath":[{"title":"Map actions to authority","detail":"Classify each capability by data access, side effect, reversibility, cost, and who or what it affects.","check":"Every meaningful action has an explicit authorization source."},{"title":"Enforce boundaries outside the prompt","detail":"Use sandboxing, scoped credentials, allowlists, policy hooks, approval gates, and protected environments.","check":"Ignoring an instruction cannot bypass the critical control."},{"title":"Log and rehearse recovery","detail":"Preserve tool calls and approvals without leaking secrets; test denial, timeout, rollback, and credential revocation paths.","check":"Operators can reconstruct what happened and contain a bad run."}],"filePatterns":["permission policies","sandbox configuration","allow and deny rules","audit logs"],"connectsTo":["mcp-tools","subagents","hooks","automations"],"relatedRoute":"/agent-stack/permissions-safety","sources":[{"label":"Codex security","url":"https://developers.openai.com/codex/security","publisher":"OpenAI","supports":"Sandboxing, approvals, network access, and security boundaries in Codex."},{"label":"Configure permissions","url":"https://code.claude.com/docs/en/permissions","publisher":"Anthropic","supports":"Claude Code permission rules, modes, hooks, and managed policy."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/permissions-safety"},{"slug":"commerce-protocols","name":"Agent commerce and payments","eyebrow":"UCP · AP2 · consent · mandates","category":"Transactions","summary":"Standards and controls for product discovery, checkout, payment authorization, and evidence of user intent in agent-mediated transactions.","choice":"Use commerce protocols when agents participate in real purchase flows across parties. A payment API alone does not define the surrounding discovery, consent, and accountability model.","whenToUse":["An agent discovers products or advances a checkout across merchant and platform boundaries.","Payment authorization needs portable evidence of user intent.","Merchants, payment providers, and agents need interoperable transaction state."],"notFor":["Prototype demos that imply purchasing without a real consent and authorization model.","Storing raw payment credentials in agent memory or prompts."],"buildPath":[{"title":"Separate shopping from authorization","detail":"Model discovery, cart changes, checkout, user confirmation, payment, fulfillment, and dispute evidence as distinct states.","check":"No product or price change can silently reuse an earlier approval."},{"title":"Bind intent to the transaction","detail":"Capture who authorized what, within which limits, for how long, and through which credential or mandate.","check":"A verifier can match the final charge to the user's approved terms."},{"title":"Design for failure and dispute","detail":"Use idempotency, signed evidence, status reconciliation, cancellation, refunds, and auditable handoffs.","check":"Retries, partial failures, or compromised agents cannot create ambiguous duplicate charges."}],"filePatterns":["UCP capabilities","AP2 mandates","checkout state","payment evidence"],"connectsTo":["agent-to-agent","mcp-tools","permissions-safety"],"relatedRoute":"/ap2","sources":[{"label":"Universal Commerce Protocol","url":"https://ucp.dev/","publisher":"UCP","supports":"Agentic commerce capabilities, services, negotiation, checkout, and order lifecycle."},{"label":"Agent Payments Protocol","url":"https://ap2-protocol.org/","publisher":"AP2","supports":"Agent-mediated payment authorization, mandates, roles, and transaction evidence."}],"canonicalUrl":"https://agentatlas.dev/agent-stack/commerce-protocols"}]},"modelGuides":{"canonicalUrl":"https://agentatlas.dev/model-guides","reviewedAt":"2026-07-26","reviewCadenceDays":30,"items":[{"slug":"claude","provider":"Anthropic","family":"Claude 5","currentModels":"Claude Sonnet 5 and Claude Opus 5","bestFor":"Long-horizon coding, agentic work, and complex deliverables","summary":"Give Claude a clear outcome and the right project context, then remove legacy scaffolding that newer models no longer need.","signatureLesson":"Less instruction can produce more capability when the remaining context is high-signal.","accent":"amber","firstPrompt":"# Outcome\nImplement [specific result].\n\n# Project context\n- Relevant files or systems: [paths / links]\n- Existing pattern to follow: [example]\n\n# Boundaries\n- Do not change: [out-of-scope areas]\n- Ask before: [meaningful decisions]\n\n# Done when\n- [observable acceptance check]\n- [test or verification]\n\nWork autonomously inside these boundaries. Prefer the simplest complete solution.","curve":[{"level":"01","name":"Start with the outcome","goal":"Get a strong first result without teaching Claude a complicated ritual.","practices":["State the artifact or change you want, the relevant context, and what “done” means.","Use direct, positive instructions for tone, length, and scope.","For simple work, begin with the default behavior before adding special rules."],"proof":"A new teammate can read the request and predict the expected deliverable."},{"level":"02","name":"Calibrate effort and examples","goal":"Make repeated outputs predictable without over-constraining the model.","practices":["Use a representative good example when style or format matters.","Raise effort for genuinely hard work; do not simulate deeper reasoning with long step lists.","Describe scope explicitly because newer Claude models follow literal boundaries closely."],"proof":"The prompt succeeds on several real cases, not only the example used to write it."},{"level":"03","name":"Engineer the whole context","goal":"Keep long-running agent work focused as tools, memory, and instructions accumulate.","practices":["Keep CLAUDE.md focused on durable project truth; move procedures into on-demand Skills.","Make tool names, descriptions, inputs, and return values precise.","Review old anti-laziness, narration, and verification instructions after every model upgrade."],"proof":"Removing an instruction does not reduce eval quality, or the instruction earns its place."}],"worksWell":[{"title":"Progressive disclosure","detail":"Load specialized procedures only when the task calls for them instead of placing every rule in the system prompt."},{"title":"General heuristics","detail":"Describe the decision boundary and desired result; allow the model to choose implementation steps."},{"title":"Explicit deliverable scope","detail":"Say whether you want a patch, analysis, document, or recommendation and how complete it must be."}],"pitfalls":[{"title":"The inherited mega-prompt","symptom":"Claude over-explains, over-verifies, or follows obsolete rituals.","fix":"Delete rules that compensate for older model behavior and retest from a minimal baseline."},{"title":"Prescribing every reasoning step","symptom":"The model follows a weaker human-authored plan even when it can find a better path.","fix":"Specify the goal, constraints, and checks; prescribe steps only when the process itself is required."},{"title":"Always-on procedures","symptom":"Unrelated instructions consume attention and trigger in the wrong tasks.","fix":"Keep project facts in CLAUDE.md and package detailed workflows as discoverable Skills."}],"updateNote":"The Claude Code team’s July 2026 field note says it removed roughly 80% of its system prompt for the newest models. The durable lesson is not “short prompts win”; it is that every context token should justify its effect.","sources":[{"label":"Claude prompting best practices","url":"https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices","publisher":"Anthropic","kind":"official","supports":"Current model behavior, adaptive thinking, examples, scope, and migration guidance."},{"label":"Prompting Claude Sonnet 5","url":"https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5","publisher":"Anthropic","kind":"official","supports":"Effort calibration, literal instruction following, verbosity, and thinking defaults."},{"label":"The new rules of context engineering","url":"https://x.com/trq212/status/2080710971228918066","publisher":"Thariq Shaukat, Claude Code","kind":"maintainer","supports":"The field note that prompted this guide and the reported system-prompt reduction."}],"canonicalUrl":"https://agentatlas.dev/model-guides/claude"},{"slug":"openai","provider":"OpenAI","family":"GPT-5","currentModels":"GPT-5.4 and GPT-5.4 Pro","bestFor":"General reasoning, knowledge work, coding, and computer-use workflows","summary":"GPT-5 rewards precise scope, consistent instructions, and deliberate use of reasoning and verbosity controls.","signatureLesson":"Make the task unambiguous, then tune effort with evals instead of adding prompt folklore.","accent":"emerald","firstPrompt":"<task>\n[One concrete outcome]\n</task>\n\n<context>\n[Only the facts, files, or examples needed for this task]\n</context>\n\n<constraints>\n- [Important boundary]\n- [Required source or tool behavior]\n</constraints>\n\n<deliverable>\n[Format, audience, length, and acceptance criteria]\n</deliverable>","curve":[{"level":"01","name":"Write it like a good issue","goal":"Give the model enough context to act without making it infer the job.","practices":["Name the outcome, relevant inputs, constraints, and output format.","Point to an existing example when you want the same pattern.","Remove conflicting instructions before trying stronger wording."],"proof":"The request has one clear interpretation and one observable completion state."},{"level":"02","name":"Tune the controls","goal":"Match intelligence, latency, and response length to the work.","practices":["Use lower reasoning effort for routine transformations and higher effort for complex multistep work.","Control visible answer length with verbosity or an explicit format instruction.","Build a small eval set of real examples before changing a production prompt."],"proof":"You can explain why the chosen effort and verbosity beat a cheaper baseline."},{"level":"03","name":"Design an agent loop","goal":"Preserve useful reasoning context and make tool use observable.","practices":["Use the Responses API for stateful, tool-using workflows.","Define tool boundaries and completion conditions instead of asking the model to “do everything.”","Inspect failed traces, simplify the prompt, and lock successful behavior into templates."],"proof":"Failures are reproducible, categorized, and covered by evals before the next prompt revision."}],"worksWell":[{"title":"Issue-shaped requests","detail":"File paths, components, examples, acceptance checks, and a bounded outcome give coding work useful structure."},{"title":"Metaprompting with evidence","detail":"Ask the model to diagnose failed outputs and improve the prompt, then verify the revision against an eval set."},{"title":"Separate effort from verbosity","detail":"A task can require deep reasoning and still need a short final answer; control those dimensions independently."}],"pitfalls":[{"title":"Conflicting rules","symptom":"The model spends effort reconciling incompatible tone, scope, or tool instructions.","fix":"Consolidate instructions and state which rule wins when an exception is intentional."},{"title":"Maximum effort by default","symptom":"Routine work becomes slower and more expensive without a measurable quality gain.","fix":"Start with the lowest plausible effort and raise it only when evals show under-thinking."},{"title":"One heroic prompt","symptom":"A large prompt becomes brittle across unrelated tasks and hard to debug.","fix":"Use stable shared context plus smaller task templates with their own success criteria."}],"updateNote":"OpenAI’s guidance for the GPT-5 series emphasizes baseline evals, clearer and often shorter prompts, reusable templates, and independent controls for reasoning effort and visible verbosity.","sources":[{"label":"GPT-5.4 model reference","url":"https://developers.openai.com/api/docs/models/gpt-5.4","publisher":"OpenAI","kind":"official","supports":"Current flagship model identity and supported API capabilities."},{"label":"A practical guide to building with GPT-5","url":"https://openai.com/business/guides-and-resources/a-practical-guide-to-building-with-ai/","publisher":"OpenAI","kind":"official","supports":"Evals, prompt simplification, metaprompting, effort, verbosity, and Responses API guidance."},{"label":"How OpenAI uses Codex","url":"https://openai.com/business/guides-and-resources/how-openai-uses-codex/","publisher":"OpenAI","kind":"official","supports":"Issue-shaped tasks, AGENTS.md context, environment improvement, and iterative workflows."}],"canonicalUrl":"https://agentatlas.dev/model-guides/openai"},{"slug":"gemini","provider":"Google","family":"Gemini 3","currentModels":"Gemini 3.1 Pro and Gemini 3-series Flash models","bestFor":"Multimodal analysis, long context, grounded research, and tool-assisted work","summary":"Gemini 3 works best with direct instructions, coherent multimodal context, and the question placed after large source material.","signatureLesson":"Structure the evidence first, put the actual task last, and use tools for facts or calculation.","accent":"blue","firstPrompt":"# Context\n[Documents, code, images, audio, or video]\n\n# Task\nBased on the context above, [specific request].\n\n# Constraints\n- Use Google Search grounding for time-sensitive claims.\n- Use code execution for arithmetic or counting.\n- Mark anything the supplied evidence does not support.\n\n# Output\n[Exact format and desired level of detail]","curve":[{"level":"01","name":"Be direct and structured","goal":"Avoid making a reasoning model untangle decorative or contradictory instructions.","practices":["State the goal concisely and define ambiguous terms.","Use one consistent structure, such as Markdown headings or XML tags.","Ask explicitly for more detail or a conversational tone when the default answer is too terse."],"proof":"The prompt’s task and output contract are obvious without rereading the context."},{"level":"02","name":"Master long and multimodal context","goal":"Keep the question anchored to the evidence across large inputs.","practices":["Place large documents or media first and the specific question at the end.","Refer to each image, file, audio clip, or video segment clearly.","Use a transition such as “Based on the information above” before the task."],"proof":"Citations or evidence references map back to the supplied material instead of general model knowledge."},{"level":"03","name":"Combine reasoning with tools","goal":"Use the model’s context window without treating it as a current database or calculator.","practices":["Enable Search grounding for recent or obscure facts.","Enable code execution for arithmetic, counting, plotting, and image inspection.","Choose a thinking level by task complexity and measure latency, token use, and accuracy."],"proof":"Fresh claims carry sources and deterministic calculations come from execution, not mental arithmetic."}],"worksWell":[{"title":"Context before question","detail":"For long inputs, supply the corpus first and end with a focused question tied back to that corpus."},{"title":"Tool-grounded work","detail":"Search handles current facts; code execution handles arithmetic and inspection; structured output controls the final shape."},{"title":"Default sampling","detail":"Google recommends keeping Gemini 3 temperature at its default and using thinking level plus prompt instructions for control."}],"pitfalls":[{"title":"The question gets buried","symptom":"The response summarizes a long document but misses the actual request.","fix":"Put the task after the context and explicitly anchor it to the preceding material."},{"title":"Old temperature habits","symptom":"Low temperature causes degraded or looping behavior on complex Gemini 3 tasks.","fix":"Keep the documented default and control behavior through thinking level, constraints, and output format."},{"title":"Ungrounded current facts","symptom":"The answer sounds current but relies on training knowledge.","fix":"Turn on Search grounding and require sources for time-sensitive claims."}],"updateNote":"Google’s current Gemini 3 guidance explicitly favors concise instructions, consistent structure, context-first ordering for long inputs, default temperature, and tools for freshness and computation.","sources":[{"label":"Gemini 3 developer guide","url":"https://ai.google.dev/gemini-api/docs/gemini-3","publisher":"Google","kind":"official","supports":"Thinking levels, temperature, thought signatures, long context, migration, and model-specific prompting."},{"label":"Prompt design strategies","url":"https://ai.google.dev/gemini-api/docs/prompting-strategies","publisher":"Google","kind":"official","supports":"Direct instructions, long-context ordering, multimodal inputs, grounding, code execution, and structured prompts."},{"label":"Gemini model reference","url":"https://ai.google.dev/gemini-api/docs/models","publisher":"Google","kind":"official","supports":"Current model naming, stable versus preview aliases, and production versioning guidance."}],"canonicalUrl":"https://agentatlas.dev/model-guides/gemini"},{"slug":"grok","provider":"xAI","family":"Grok","currentModels":"Grok 4.5","bestFor":"Agentic coding, engineering, current web/X research, and tool use","summary":"Treat Grok as a reasoning-and-tools system: choose effort intentionally and enable search whenever freshness matters.","signatureLesson":"A confident answer is not a current answer unless the right search tool was available.","accent":"violet","firstPrompt":"Task: [specific outcome]\n\nFreshness:\n- Use web search for current public facts.\n- Use X search only when posts or live conversation are relevant.\n- Cite each time-sensitive claim.\n\nReasoning: [low for routine tool use / medium for analysis / high for difficult multistep work]\n\nReturn: [format, length, and acceptance criteria]","curve":[{"level":"01","name":"Match effort to the task","goal":"Avoid paying for deep reasoning when the job is a simple lookup or action.","practices":["Use low effort for latency-sensitive agent steps and simple tool calling.","Use medium for complex analysis and long-context reasoning.","Reserve high effort for difficult math, logic, or multistep work."],"proof":"A lower effort setting fails a measured quality check before you move higher."},{"level":"02","name":"Ground current knowledge","goal":"Separate model knowledge from live web and X evidence.","practices":["Enable web search for facts newer than the model’s documented knowledge cutoff.","Use X search for posts, profiles, threads, or live discussion—not as a substitute for primary documentation.","Require returned citations for every claim that depends on search."],"proof":"A reader can open the source attached to each current claim."},{"level":"03","name":"Optimize the agent loop","goal":"Keep multi-turn tool work efficient and inspectable.","practices":["Prefer the Responses API for state, encrypted reasoning continuity, and server-side tools.","Use a stable prompt cache key and append to conversation history instead of rewriting earlier messages.","Combine search or code tools with a structured final schema when downstream software consumes the result."],"proof":"The loop preserves context, returns valid structure, and shows a healthy cache-hit rate."}],"worksWell":[{"title":"Explicit freshness rules","detail":"Tell the model which search surface to use and which claims require citations."},{"title":"Reasoning as a budget","detail":"Choose low, medium, or high by task difficulty instead of asking every request to think as hard as possible."},{"title":"Structured tool results","detail":"Use tools to gather evidence and a JSON schema to make the final response safe for downstream code."}],"pitfalls":[{"title":"Assuming Grok is live by default","symptom":"A recent-sounding answer contains no search sources.","fix":"Enable web or X search and require citations; the base model does not automatically know live events."},{"title":"Cold conversations","symptom":"Repeated long context is billed at the full input rate.","fix":"Set a stable conversation or prompt cache key and keep the prefix unchanged."},{"title":"High effort everywhere","symptom":"Tool calls that should be quick inherit unnecessary latency.","fix":"Use low effort for routine agentic actions and raise it only for the reasoning-heavy step."}],"updateNote":"xAI’s July 2026 documentation positions Grok 4.5 as its current flagship and documents configurable reasoning, server-side search and code tools, structured outputs, and cache-aware conversation patterns.","sources":[{"label":"Grok 4.5 developer guide","url":"https://docs.x.ai/developers/grok-4-5","publisher":"xAI","kind":"official","supports":"Current model identity, supported tools, reasoning levels, knowledge cutoff, and cache guidance."},{"label":"Reasoning","url":"https://docs.x.ai/developers/model-capabilities/text/reasoning","publisher":"xAI","kind":"official","supports":"Reasoning effort behavior, defaults, compatibility limits, and encrypted reasoning."},{"label":"Tools overview","url":"https://docs.x.ai/developers/tools/overview","publisher":"xAI","kind":"official","supports":"Web search, X search, code execution, custom functions, and returned citations."}],"canonicalUrl":"https://agentatlas.dev/model-guides/grok"},{"slug":"deepseek","provider":"DeepSeek","family":"DeepSeek","currentModels":"DeepSeek V4 Pro and V4 Flash","bestFor":"Cost-conscious reasoning, coding, long context, and open-model workflows","summary":"Choose the V4 model and thinking mode explicitly, then preserve reasoning context correctly across tool calls.","signatureLesson":"Model mode and conversation plumbing matter as much as the words in the prompt.","accent":"cyan","firstPrompt":"Mode: [thinking for complex reasoning / non-thinking for fast routine work]\n\nTask:\n[One concrete outcome]\n\nAvailable tools:\n- [tool name]: [when it should be used]\n\nOutput:\n- Format: [text or JSON]\n- Required fields: [fields]\n- Validation: [observable check]\n\nIf JSON is required, return JSON matching this example:\n{\"result\":\"...\",\"evidence\":[\"...\"]}","curve":[{"level":"01","name":"Choose Pro, Flash, and mode","goal":"Start with the correct capability and latency profile.","practices":["Use V4 Flash for faster, economical work and V4 Pro for capability-sensitive tasks.","Use non-thinking mode for routine transformations and thinking mode for difficult reasoning.","Use the current V4 model names instead of retired compatibility aliases."],"proof":"The selected model and mode are recorded with the eval result, latency, and cost."},{"level":"02","name":"Make outputs machine-safe","goal":"Produce predictable results for automation.","practices":["For JSON mode, set the response format, say “JSON” in the prompt, and provide an example.","Set enough output tokens to avoid truncating structured data.","Define tools with clear descriptions and schemas; use strict mode only with its documented beta constraints."],"proof":"The output parses, validates, and handles the documented empty-content edge case."},{"level":"03","name":"Preserve thinking across tools","goal":"Keep long agent loops valid and coherent.","practices":["Return reasoning content with assistant tool calls exactly as the API documents.","Do not send unsupported tool-choice controls in thinking-mode integrations.","Test long conversations because provider-compatible SDKs can differ in reasoning replay behavior."],"proof":"A multistep tool loop completes without a 400 error and preserves the evidence used for the final answer."}],"worksWell":[{"title":"Explicit mode selection","detail":"Treat thinking versus non-thinking as a product decision tied to complexity, speed, and token use."},{"title":"JSON with an example","detail":"Combine the API response format with the word JSON, a sample object, and adequate output space."},{"title":"Careful compatibility plumbing","detail":"OpenAI-compatible or Anthropic-compatible syntax does not remove DeepSeek-specific conversation requirements."}],"pitfalls":[{"title":"Retired aliases","symptom":"An integration still calls deepseek-chat or deepseek-reasoner after their July 24, 2026 retirement.","fix":"Migrate to deepseek-v4-pro or deepseek-v4-flash and choose thinking mode explicitly."},{"title":"Dropped reasoning content","symptom":"A thinking-mode tool loop fails on the next request.","fix":"Preserve the documented reasoning content in conversation history alongside the assistant tool call."},{"title":"JSON by instruction alone","symptom":"The model returns prose, incomplete JSON, or an empty body.","fix":"Use JSON response format, include a JSON example, size max tokens, validate, and retry the documented edge case."}],"updateNote":"DeepSeek’s official change log says the legacy deepseek-chat and deepseek-reasoner aliases were discontinued on July 24, 2026. This guide therefore uses the V4 Pro and V4 Flash names and current thinking-mode requirements.","sources":[{"label":"DeepSeek API change log","url":"https://api-docs.deepseek.com/updates/","publisher":"DeepSeek","kind":"official","supports":"V4 model names, release timing, alias retirement, and current API migration state."},{"label":"DeepSeek V4 release","url":"https://api-docs.deepseek.com/news/news260424/","publisher":"DeepSeek","kind":"official","supports":"V4 Pro versus Flash positioning, context, interfaces, and dual thinking modes."},{"label":"JSON output","url":"https://api-docs.deepseek.com/guides/json_mode/","publisher":"DeepSeek","kind":"official","supports":"JSON response-format requirements, examples, truncation, and empty-content behavior."},{"label":"Tool calls","url":"https://api-docs.deepseek.com/guides/tool_calls","publisher":"DeepSeek","kind":"official","supports":"Thinking-mode tools and strict function-schema behavior."}],"canonicalUrl":"https://agentatlas.dev/model-guides/deepseek"}]},"comparisons":{"canonicalUrl":"https://agentatlas.dev/compare","reviewedAt":"2026-07-26","reviewCadenceDays":30,"items":[{"slug":"agents-md-vs-skills","title":"AGENTS.md vs Agent Skills","searchIntent":"Where should durable agent instructions and repeatable workflows live?","summary":"Use AGENTS.md for concise repository truth that should shape most sessions. Use a Skill for a specialized procedure that should load only when the task calls for it.","leftSlug":"repository-instructions","rightSlug":"skills","quickAnswer":"If the guidance describes the repository, put it in AGENTS.md. If it describes how to perform a reusable task, package it as a Skill.","chooseLeft":["Build, test, formatting, or architecture guidance applies broadly across the repository.","Nested packages need closer, path-specific instructions.","The rule should be version-controlled and visible in most relevant sessions."],"chooseRight":["The workflow has a trigger, sequence, supporting references, and an output contract.","Loading the full procedure in every session would waste context.","The capability should be reusable across projects or compatible agents."],"combine":["Keep the repository's short definition of done in AGENTS.md.","Link to the Skill for the detailed deployment, review, or release procedure.","Enforce non-negotiable checks with CI or hooks instead of duplicating them in both files."],"evaluation":["Does every always-on instruction apply to most work in its scope?","Can the Skill be selected from its description without extra explanation?","Are duplicated or contradictory instructions removed?","Does the Skill fail clearly when a prerequisite is missing?","Can a reviewer trace each instruction to a current repository need?"],"commercialIntent":"Agent developer platforms, coding assistants, and Skill marketplaces","canonicalUrl":"https://agentatlas.dev/compare/agents-md-vs-skills"},{"slug":"skills-vs-plugins","title":"Agent Skills vs Plugins","searchIntent":"Should a capability be one portable workflow or an installable extension bundle?","summary":"A Skill is a focused unit of reusable knowledge or procedure. A plugin is a distribution boundary that can package Skills with agents, hooks, tools, and connectors.","leftSlug":"skills","rightSlug":"plugins","quickAnswer":"Start with a Skill. Move to a plugin when installation, versioning, namespacing, multiple components, or organization-wide distribution become product requirements.","chooseLeft":["One workflow or domain reference solves the problem.","The project owns the capability and does not need a release channel.","The procedure should remain easy to inspect and copy."],"chooseRight":["Several related Skills, agents, hooks, or servers should install together.","The extension needs versioned releases, ownership, and update behavior.","A marketplace or administrator will distribute it to multiple teams."],"combine":["Build and evaluate each Skill independently before packaging.","Use the plugin manifest to declare the installable boundary and component ownership.","Keep executable hooks and network destinations explicit during every plugin review."],"evaluation":["Can users explain what the install adds and removes?","Are component names and triggers collision-resistant?","Can the package be pinned and upgraded predictably?","Are scripts, hooks, permissions, and servers auditable?","Does each bundled Skill still work as a coherent capability?"],"commercialIntent":"Plugin marketplaces, enterprise agent platforms, and developer tooling","canonicalUrl":"https://agentatlas.dev/compare/skills-vs-plugins"},{"slug":"subagents-vs-automations","title":"Subagents vs Automations","searchIntent":"Should work be delegated inside a live session or run unattended on a trigger?","summary":"Subagents divide bounded work inside an active agent session. Automations run a stable workflow later or repeatedly, with durable scheduling, permissions, and recovery.","leftSlug":"subagents","rightSlug":"automations","quickAnswer":"Use a subagent when a coordinator is present to assign and synthesize the task. Use automation when the same task can run safely from predefined inputs without live supervision.","chooseLeft":["Independent research or tests can return a concise result to a coordinator.","The main context would otherwise be flooded with logs or source material.","A specialist needs narrower tools, permissions, or instructions for one run."],"chooseRight":["The trigger, inputs, output, owner, and completion check are known in advance.","Retries are idempotent and side effects have explicit approval boundaries.","Run logs and failures need durable operational ownership."],"combine":["Let a scheduled automation create a bounded task and gather required inputs.","Use subagents only for independent workstreams within that run.","Make the parent automation verify and persist the final result before publishing or acting."],"evaluation":["Is a human or coordinator available when ambiguity appears?","Can tasks be partitioned without conflicting writes?","Can retries duplicate messages, deployments, or charges?","Are permissions inherited and constrained as expected?","Can operators reconstruct and recover a failed run?"],"commercialIntent":"Agent orchestration, workflow automation, observability, and CI platforms","canonicalUrl":"https://agentatlas.dev/compare/subagents-vs-automations"},{"slug":"mcp-vs-a2a","title":"MCP vs A2A","searchIntent":"Does an agent need a tool, or does it need to collaborate with another agent?","summary":"MCP exposes tools, resources, and prompts to a client. A2A exposes an independently operated agent that accepts messages, manages task state, and returns artifacts.","leftSlug":"mcp-tools","rightSlug":"agent-to-agent","quickAnswer":"Use MCP for capabilities the calling agent should invoke as tools. Use A2A when the remote system owns its own agent loop, task lifecycle, and independently managed trust boundary.","chooseLeft":["The capability has typed inputs, outputs, and understandable side effects.","The caller should decide when and how the capability is used.","Several compatible clients should discover the same server."],"chooseRight":["The remote party decides how to complete a delegated outcome.","Tasks can be long-running, asynchronous, or require additional input.","The remote agent is independently deployed, secured, and operated."],"combine":["Use A2A for collaboration across agent boundaries.","Let each participating agent use MCP internally for its own tools and data.","Keep identity, authorization, and audit evidence explicit at both boundaries."],"evaluation":["Is the remote capability deterministic enough to be a tool?","Who owns task planning and lifecycle state?","Can discovery happen before sensitive data is shared?","Are retries, cancellation, and duplicate work handled?","Can each system authenticate and authorize the other?"],"commercialIntent":"MCP servers, agent gateways, interoperability platforms, and enterprise integrations","canonicalUrl":"https://agentatlas.dev/compare/mcp-vs-a2a"},{"slug":"memory-vs-agents-md","title":"Agent Memory vs AGENTS.md","searchIntent":"Should information be remembered dynamically or committed as shared project guidance?","summary":"AGENTS.md carries deliberate team-owned repository instructions. Memory stores inspectable observations or preferences that may evolve across sessions.","leftSlug":"memory-context","rightSlug":"repository-instructions","quickAnswer":"Commit stable team truth to AGENTS.md. Use memory for revisable, user- or project-specific learnings that should persist but do not belong in the repository contract.","chooseLeft":["The information is a learned preference, debugging observation, or evolving project note.","Users need to inspect, edit, expire, or delete it independently.","Loading it selectively is better than adding it to every session."],"chooseRight":["The whole team should review and version the guidance.","The instruction defines repository architecture, commands, or completion rules.","A fresh environment should receive it from source control."],"combine":["Use memory to collect repeated observations.","Promote a verified, durable pattern into AGENTS.md through normal code review.","Remove stale memory after the shared instruction becomes authoritative."],"evaluation":["Who owns the information and who should see it?","Is the item stable enough for source control?","Does it contain sensitive data or secrets?","Can stale or conflicting versions be corrected?","Does the startup context remain concise?"],"commercialIntent":"Agent memory, retrieval, knowledge management, and developer productivity platforms","canonicalUrl":"https://agentatlas.dev/compare/memory-vs-agents-md"},{"slug":"hooks-vs-instructions","title":"Hooks vs Agent Instructions","searchIntent":"Should the model be told to do something, or should the system enforce it?","summary":"Instructions guide model judgment. Hooks run deterministic handlers at defined lifecycle events regardless of whether the model remembers to invoke them.","leftSlug":"hooks","rightSlug":"repository-instructions","quickAnswer":"Use instructions for contextual judgment. Use hooks for formatting, validation, logging, blocking, or environment work that must happen at a specific event.","chooseLeft":["A command must run before or after a tool call or file change.","Policy enforcement cannot depend on model attention.","A deterministic result, exit code, or audit record is required."],"chooseRight":["The agent needs context to choose among several acceptable approaches.","The guidance describes repository architecture or team preference.","Strict execution at a lifecycle event would be unnecessarily rigid."],"combine":["Explain the policy and desired behavior in repository instructions.","Enforce the narrow, non-negotiable part with a scoped hook.","Return clear hook feedback so the agent can recover instead of looping."],"evaluation":["Would forgetting the instruction create material risk?","Is there one narrow lifecycle event to target?","Can the hook fail safely and within a timeout?","Are downloaded commands and destinations reviewed?","Does the instruction remain useful after enforcement moves to code?"],"commercialIntent":"Security, policy, code quality, observability, and developer platform products","canonicalUrl":"https://agentatlas.dev/compare/hooks-vs-instructions"},{"slug":"mcp-vs-skills","title":"MCP vs Agent Skills","searchIntent":"Does the agent need new knowledge and procedure, or access to an external capability?","summary":"A Skill teaches the agent how to perform a workflow. MCP connects the agent to tools, resources, or prompts supplied by a server.","leftSlug":"mcp-tools","rightSlug":"skills","quickAnswer":"Use a Skill when the missing piece is know-how. Use MCP when the agent needs live data or actions. Combine them when a procedure should teach the agent how to use a specific server safely.","chooseLeft":["The task requires current external data or a real side effect.","Typed schemas, authentication, and server errors define the boundary.","The capability should be shared across compatible clients."],"chooseRight":["The agent already has the required tools but needs a repeatable method.","Templates, references, scripts, or evaluation checks belong with the workflow.","The procedure should remain portable without operating a service."],"combine":["Expose narrow, well-described tools through MCP.","Package the higher-level operating procedure and safety checks as a Skill.","Test the Skill against supported server versions and failure modes."],"evaluation":["Is the missing capability knowledge, data, or action?","Can the task work offline from static references?","Are tool inputs and side effects explicit?","Does the Skill pin or verify server assumptions?","Can failures be diagnosed at the correct layer?"],"commercialIntent":"MCP infrastructure, Skill libraries, agent developer tools, and API platforms","canonicalUrl":"https://agentatlas.dev/compare/mcp-vs-skills"},{"slug":"permissions-vs-prompt-guardrails","title":"Permissions vs Prompt Guardrails","searchIntent":"Which safety boundaries belong in instructions, and which require platform enforcement?","summary":"Prompt guardrails communicate intent and decision policy. Permissions, sandboxes, approval gates, and scoped credentials enforce what actions are actually possible.","leftSlug":"permissions-safety","rightSlug":"repository-instructions","quickAnswer":"State the operating policy once in instructions, then enforce consequential boundaries outside the model with the narrowest available permission and approval controls.","chooseLeft":["The action reaches production, money, credentials, external people, or destructive state.","A compromised or confused model must still be unable to exceed authority.","The organization needs auditable allow, deny, and approval decisions."],"chooseRight":["The agent needs guidance about scope, escalation, or preferred behavior.","Several safe actions require contextual judgment rather than a fixed block.","The instruction helps the model explain why it stopped or requested approval."],"combine":["Define the authorization model concisely in shared instructions.","Map sensitive action classes to credentials, sandboxes, and approval gates.","Log both the model's requested action and the platform's enforcement decision."],"evaluation":["What user request or policy authorizes each side effect?","Can instruction failure bypass the critical boundary?","Are credentials limited to the current task and environment?","Can operators revoke access and reconstruct the run?","Are safe local actions still usable without unnecessary friction?"],"commercialIntent":"AI security, governance, identity, sandboxing, and compliance platforms","canonicalUrl":"https://agentatlas.dev/compare/permissions-vs-prompt-guardrails"}]}},"discovery":{"start":"https://agentatlas.dev/start","topics":"https://agentatlas.dev/topics","topicsCatalog":"https://agentatlas.dev/api/catalog/topics","starterKit":"https://agentatlas.dev/starter-kit","templatesCatalog":"https://agentatlas.dev/api/catalog/templates","contentStatus":"https://agentatlas.dev/api/catalog/status","recommendations":"https://agentatlas.dev/api/recommendations","llms":"https://agentatlas.dev/llms.txt","llmsFull":"https://agentatlas.dev/llms-full.txt","manifest":"https://agentatlas.dev/.well-known/agentatlas.json","openSearch":"https://agentatlas.dev/opensearch.xml","rss":"https://agentatlas.dev/feed.xml","jsonFeed":"https://agentatlas.dev/feed.json","sitemap":"https://agentatlas.dev/sitemap.xml"}}