AgentDeck

AgentDeck is a declarative runtime harness for multi-agent systems and workflows (OpenAI Agents SDK, plus AgentDeck-native @tool/@workflow).

Core standards: docs/engineering/: the linked suite of binding engineering law:

1. docs/engineering/principles.md: Product philosophy, and the standard a feature is held to (Q1-Q7).
2. docs/engineering/coding-standards.md: Binding front door for every code change.
3. docs/engineering/coding-agents.md: Mandatory rules for coding agents.
4. docs/engineering/documentation.md: Binding for every page under docs-site/content/.
5. Specialized standards: architecture.md, runtime-contracts.md, testing.md, dependencies.md, repository-policy.md, import-boundaries.md.
6. docs/patterns/: the project's taste as real good/bad pairs. Read the file for your concern before writing; match the good side.

Every file under docs/ declares its status on line 3, from four words, so law is distinguishable from archaeology without opening it:

A version in a History title is that document's own subject, not a stale claim about this repository.

1. Product Philosophy & North Star

You build the software. AgentDeck handles the agentic machinery. Simple on the outside, elegant on the inside.

Suspending a run on a human and resuming it days later on another machine is hard. So is cancelling a live run from another process, one conversation that spans turns and surfaces and restarts, and one run readable over HTTP, stdio and AG-UI at once. Our position is that we write those once, carefully, instead of every team writing them again under deadline. These subsystems are sophisticated inside and must not make application code sophisticated. When a design makes the inside simpler by making the outside harder, we have failed, and that is not a trade we are allowed to make quietly.

• User owns intent, AgentDeck owns machinery: Users define agents, tools, workflows, skills, and context. AgentDeck manages run identity, execution lifecycle, persistence, event streams, cancellation, and concurrency.
• Complexity grows slower than capability: Needing concurrency, a human, another agent or a protocol costs one call, not a redesign. An application is never restructured because its requirements got more serious.
• Abstractions must delete complexity: An abstraction is successful only when the caller needs to know less. Never leak internal plumbing (stores, resolvers, internal contexts, log keys) into public user APIs.
• One obvious path first: One clean, standard path for common tasks (await deck.run(...)). Advanced knobs remain escape hatches, never obstacles.
• We are not exempt: Finding that AgentDeck's own API has transferred complexity to the user is a defect, not a preference.

The standard. Every major feature answers Q1-Q7 in docs/engineering/principles.md, and a review cites them by key. Q2, can a developer who does not need it ignore it completely, kills most proposals. Q4, are we absorbing complexity or transferring it to the user, is the one we most often fail. A bugfix answers neither.

2. Architecture & Layout

Deck is the single composition root: Deck(...) or Deck.from_project() (discovering ./.agentdeck/).

• agentdeck/core/: Pure domain model, event schema, content blocks, ports, error taxonomy. Imports stdlib + pydantic only (enforced by import-linter).
• agentdeck/runtime/: Execution orchestration, lifecycle state machine, event dispatch. Imports core/ only.
• agentdeck/adapters/: Pluggable integrations (executors: openai_agents, native; stores: sqlite, postgres, redis; mcp; telemetry). Each adapter imports core/ plus exactly one external technology. Adapters never import other adapters.
• agentdeck/authoring/: Declarations (Agent, @tool, @workflow, Skill) compiled to specs.
• agentdeck/bindings/: The binding SPI: Binding, Gateway, exposure, and the native / agui / terminal entry points. Reaches Deck through its public surface only.
• agentdeck/skills/: Skills, the capability object a Deck composes for skill disclosure.

3. Engineering & Coding Standards

• Correctness before convenience: Strict internal invariants, forgiving external APIs. Make invalid states impossible to express.
• Errors are part of the API: Every error must state what happened, why it happened, and the exact code/action to resolve it.
  • Good (real, runtime/registry.py): "No {self.label} named {name!r}. Available: {sorted(plugins)}." - a lookup failure names the alternatives.
  • Bad: "invalid workflow state".
• Typing: Python ≥3.12. Strict annotations everywhere. Pydantic v2 models at system boundaries; @dataclass(frozen=True, slots=True) for internal immutable value objects. No unprincipled Any.
• Zero unnecessary abstractions: YAGNI. Delete dead code aggressively. Do not add configuration for things that never change.
  • Good (real, deck.py): cancellation is Run.cancel(), a method on the existing handle.
  • Bad: a new CancellationManager class for that same responsibility. Run uv run scripts/repomap.py before adding any public abstraction.
• Comments: Extremely rare, max 1–2 lines explaining non-obvious why, never restating what the code does.
  • Good (real, core/control.py): # Before the raise, because the raise is what records the effect: an intent left pending behind an honored one would be honored a second time on the next resume.
  • Bad: # Increment the retry count above retry_count += 1. A PostToolUse hook (scripts/slopcheck.py) flags this per edit.
• Conciseness is mandatory: No fluff, no sprawling prose. If one sentence suffices, write one sentence. Code, comments, docs, PR descriptions, and issue specs must be terse, precise, and dense with signal.
• No em dashes: Never use the - character in any documentation, code, comments, or agent output. Use a regular hyphen -, colon :, or separate into distinct sentences.

4. Verification Gate & Conventions

• Gate: make check (runs ruff, ty typecheck, import-linter, and pytest). Must be 100% green.
• Settings & Env: Layered pydantic-settings; all environment variables use the AGENTDECK_* prefix exclusively (except third-party SDK vars like OPENAI_*).
• Goldens & Snapshots: tests/golden/ and tests/core/snapshots/ update only via intentional make golden with PR justification.
• CHANGELOG: Add concise, user-facing entries under ## [Unreleased] for any user-visible change.

5. Agent Instructions & Git Discipline

• Communication conciseness: Keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless more detail is required.
• Branches: dev is default; PRs target dev. main is release-only.
• No attribution trailers: Never include an AI Co-Authored-By, 🤖 Generated with, or AI vendor signatures in commits, PRs, or issues. A trailer naming a person is collaboration, not attribution: GitHub writes one itself when a contributor accepts a maintainer's suggestion.
• Draft PR workflow: Open a draft PR on your first commit (gh pr create --draft) and push continuously as you work. Mark ready with gh pr ready only when make check is clean.