# DESIGN.md

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

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

## How to use this template

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

## Users, jobs, and outcomes

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

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

## Interaction and system state

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

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

## Control and trust

> Place human judgment where authority or consequence changes.

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

## Edge states and accessibility

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

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

## Related AgentAtlas field guides

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

## Primary references

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

---

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

Generated deterministically from reviewed AgentAtlas records.