Stateful features with one owner, pure decisions, and explicit effects.
Write your first feature · Decide whether it pays off · Agent skills · Core specification · Russian documentation
Pokeball is an architecture specification for stateful applications. A feature owns its state, makes decisions in a pure function, and performs external actions only after accepting the decision. It can start as one source file with ordinary types and functions.
Start with the human quickstart. It shows a complete local feature, its tests, and a business-rule change before introducing asynchronous work. You do not need to master the full reference before making an ordinary change inside an established project binding.
Consider a search that starts A, then B, but receives A's result last; or a payment that times out after the provider may have charged the customer. Layers and dependency direction alone do not select how your application handles these situations.
Pokeball gives a team explicit contracts for recurring questions:
- State ownership: one authority and one logical writer for each mutable fact.
- Decisions and consequences: decide from State and explicit current input/context; accept State and all present outputs together; dispatch afterward.
- Asynchronous work: associate results with accepted causes, reject or handle stale results by policy, and distinguish a timeout from a known failure.
- Bounded operation: resolve finite limits for present variable dimensions and name the evidence behind stronger guarantees.
These contracts can make reviews and failure handling more consistent. They also cost design, code, tests, and learning. The value comparison and pilot explains how to measure both.
Good Clean Architecture can use the same mechanisms. Pure functions, isolated tests, and replaceable adapters are shared benefits; Pokeball's additional value is a common, explicit contract for stateful behavior. If your project already has equivalent rules and checks, adopting another vocabulary may add little.
| Everyday code | Pokeball term | Responsibility |
|---|---|---|
| A state-owning feature module | Ball | Own the fact, its invariant, and lifecycle. |
| Input adapter | Interaction | Validate/adapt the present input channel; keep business choices in the decision. |
| Pure decision and read functions | Nucleus | Compute the proposed change or read result from explicit values. |
| Adapter for an external action | Resources | Execute only accepted requested work through the required boundary. |
The binding connects these roles and enforces the writer, acceptance, and applicable execution rules. A small project can implement it directly; an established project can reuse it. It is real integration work, not something this specification supplies.
For a local state-only feature, the Resource role is empty. Three logical roles do not require three classes, folders, interfaces, or a message bus. Source types, calls, verification sites, and the single accepted-write site can carry the role map; a separate document is unnecessary when those facts are already inspectable.
There is one Core. Always-applicable invariants remain in force; optional machinery appears when a real path, risk, or claim activates it.
| Situation | Start with |
|---|---|
| Local state and synchronous calls | Owned State, closed typed input, pure decision, serial atomic publication, relevant tests. |
| Detached external work | Accepted outputs, verified result correlation, bounded execution, and the required operation-status contract. |
| Accepted work must survive process loss | A concrete durable binding, crash/recovery tests, and explicit external-outcome handling. |
| Multiple authorities need an independent workflow | A Flow owner for the actual coordination and terminal outcome. |
No standalone manifest, empty protocol category, unused adapter, runtime DI container, or per-feature copy of an unchanged shared policy is required. A present obligation still needs a real mechanism. Learn the details when the task activates them through adoption, composition, and Core's everyday workflow.
Production readiness belongs to an implemented system and its exact binding, workload, and guarantees. This repository provides the specification, teaching examples, and verification routes; it contains no runtime, library, reference implementation, comparative benchmark, or evidence for your deployment. Version and compatibility status are owned by the Core header.
Use one real slice to check failure behavior, implementation cost, and a human's first change. Include shared setup and maintenance cost. Continue when the benefit is demonstrated within your budget; reshape or stop when the existing approach satisfies the same requirements more simply. Use ordinary utilities or adapters for stateless mechanics and passive paths that need no state-owning decision module. Pokeball does not promise an advantage on every project.
Follow the project evaluation and production evidence guide. Documentation consistency and agent walkthroughs do not establish human usability or production reliability.
Give your coding agent practical Pokeball instructions with the official skills. Start with pokeball for everyday feature changes; add pokeball-async, pokeball-composition, pokeball-binding, or pokeball-review for those tasks. Each independently installable skill contains concise work instructions and task-specific checks in one SKILL.md. Agents can apply them directly to project code and tests; the canonical Core remains authoritative.
Download and install from GitHub, copying only the complete skill directories you want. Installed skills work without a local Pokeball checkout or network access. The same page explains separate updates from GitHub. Skills provide coding workflows; the Agent Pack provides the broader contract, runbooks and review gates. Neither supplies an application runtime or a conformance verdict. Contributors should follow the skill authoring guide when changing a skill or a source it uses.
| Start here when you want to… | Document |
|---|---|
| Write and change a small feature | Human quickstart |
| Compare benefits, cost, and production fit | Project evaluation |
| Select profiles and adopt incrementally | Adoption guide |
| Understand decisions and logical roles | Architecture guide |
| Choose boundaries, dependencies, and Flow ownership | Composition guide |
| Resolve an exact rule or audit the architecture | Core specification |
| Give an agent focused coding workflows | Skills, installation and updates |
| Apply the full agent contract in another repository | Agent Pack and installation |
| Read the complete documentation in Russian | Russian documentation |
The Core entrypoint and its ordered manifest form the canonical specification. Each marked source clause owns its law; guides, examples, law indexes, and the Agent Pack are derived views. If a view conflicts with its source clause, Core controls. Ordinary work follows affected sources and tests; a full audit still covers every unique source.
Copyright © 2026 Vladislav Tomilov (4wl2d). 4wl2d is his public
pseudonym. The original specification, documentation,
diagrams, examples, and Agent Pack are licensed under
Creative Commons Attribution 4.0 International
(CC-BY-4.0). Anyone may share and adapt those materials for any purpose,
including commercial use, subject to CC BY 4.0: retain the supplied creator,
copyright, license, and warranty-disclaimer notices; include the license text
or URL; link the source to the extent reasonably practicable; and indicate
changes while retaining prior change notices. No ShareAlike condition applies.
This licenses the copyrightable expression of Pokeball Architecture; it does
not create exclusive copyright ownership in abstract ideas, methods, systems,
or functional concepts. CC BY 4.0 does not grant patent or trademark rights.
See NOTICE.md for the exact scope and recommended attribution,
and LICENSE for the complete legal code.