How coding agents should read QuadKit

QuadKit is built so a coding agent can operate it without scraping tribal knowledge out of Slack. That only works if the agent reads the artifacts in the right order. This is that order.

Availability note (0.0.50): Eighteen distributions are published, including quadkit-ai-llm, quadkit-ai-agents, quadkit-ai-mcp, quadkit-workflow, and quadkit-notification. The examples below run from the framework workspace.

1. Load the machine indexes, not the marketing page

Start here, in this sequence:

1. /llms.txt — identity, install, agent rules, every docs URL.
2. /agents.md — the machine-readable agent guide: hierarchy, Result vs exceptions, provider lifecycle, and package availability.
3. /llms-full.txt — the same catalog plus architecture notes and the package list.
4. For coding agents — repo map, the one project tree (domains/, di/), recipes that pass CI.
5. /SKILL.md — drop-in skill. Common mistakes — fail vs fix. Per-package indexes at /llms/index.txt.

The splash page is for humans. The files above are the operating manual. If you are an agent, stop after those and only then open a specific docs URL.

Skills for Claude Code, Cursor, and OpenCode live in quadkit-skills. Install commands: Agent skills. One-file fetch: /SKILL.md. Do not re-derive the rules from blog posts.

2. The hierarchy is the whole design

contracts    Shared types; no QuadKit implementation imports.
    ↑
core         Contracts are its intended internal boundary.
    ↑
extensions   Peer imports are checked by policy.

quadkit-contracts has no QuadKit implementation imports and depends at runtime on typing-extensions. If packages share a protocol, type, or exception, prefer contracts over a dependency between peers. Regular extensions may also use permitted foundational packages; composite packages and specific documented allowances are handled separately, so do not assume every cross-package edge is forbidden.

AI sub-packages have a dedicated sibling-independence check, while the quadkit.ai facade is allowed to compose them. Within the agent package, AgentsProvider discovers strategy providers through the quadkit.agent.strategies entry-point group—it does not discover every AI extension. Shared ChatMessage and Document value types are defined in contracts.

3. Copy an example, not a vibe

The examples catalog contains runnable applications and a fleet hub built around QuadKit’s Application. These are workspace examples, so their presence does not change the PyPI availability note above. Representative starting points:

• Need a controller? examples/sql-repository keeps SQL in the repository.
• Need an agent loop? examples/support-agent already has tools on the container.
• Need sessions? examples/auth-web is the cookie + JWT walkthrough.

The canonical app examples generally share one shape: application.yaml for knobs, app.py (or module.py) as the composition root, providers that register bindings, feature types in domains/, services that return Result[T, E], and RFC 9457 errors. Individual demos vary, but those conventions are a reliable starting point.

Run any of them from the repository root:

PYTHONPATH=examples/support-agent/src uv run python -m support_agent

4. The two rules agents break first

These two are caught early by static typing. Many of the remaining structural rules are enforced later by the repository’s import checks and CI.

register() cannot resolve. It receives ContainerRegistrarProtocol. boot() receives BootContainerProtocol. The two never meet in the same method. If you resolve during registration, it is a type error — by design.

Domain failures are values. User not found is Err(...). The database dying is an exception. Do not wrap infrastructure errors in Result, do not unwrap() without is_ok(), and do not return Result from a constructor or a lifecycle hook.

The rest of the never-list is in /agents.md: no service locator, no module-level singletons, no Any on injected constructors, no mocks in src/.

Common mistakes has the full set of ten with fail/fix pairs, grouped by the reason a model reaches for each one. Why I built QuadKit is the long version.

5. Cite the protocol, link the docs

When you answer a question about QuadKit:

• Name the package with the quadkit- prefix (quadkit-sql, not “the SQL helper”).
• Talk to the protocol in contracts, not the class in the extension.
• Link the matching page on oridecon.dev.

That is a useful loop: indexes, hierarchy, an example, then the protocol. The container wires registered dependencies; application behavior and integration choices still belong in your code.