# DECISIONS.md

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

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

## How to use this template

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

## Decision index

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

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

## Decision record

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

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

## Alternatives and evidence

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

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

## Review and supersession

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

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

## Related AgentAtlas field guides

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

## Primary references

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

---

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

Generated deterministically from reviewed AgentAtlas records.