# PLAN.md

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

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

## How to use this template

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

## Approach and decisions

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

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

## Phases and dependencies

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

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

## Verification and rollout

> Decide how each phase proves correctness before work begins.

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

## Risk and recovery

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

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

## Related AgentAtlas field guides

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

## Primary references

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

---

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

Generated deterministically from reviewed AgentAtlas records.