Skip to content

CLAUDE.md

Latest commit

 

History

History
88 lines (64 loc) · 8.25 KB

CLAUDE.md

File metadata and controls

88 lines (64 loc) · 8.25 KB
Raw

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:

Status Means Where
Binding a change that violates it is wrong all of docs/engineering/ and docs/patterns/, the 16 files above
Design of record live rulings; amend it rather than contradicting it docs/design/ including protocols/, and docs/delivery/, whose plans are cited by ruling number from tests and source
Reference true, not law docs/brand/README.md
History a state the project has left. Usually it is deleted instead: git is the archive, and #734 deleted the eight that nothing read nothing, currently

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.