Architecture and decision records

Documents where game state lives and why consequential architecture choices were made. Records alternatives and trade-offs so future contributors understand both the implementation and its limits.

documentation-and-adrs

Agents using this skill

AgentCleo

See how it helps

When is it useful?

Use when developers need to know where behavior belongs or why an architectural decision was made.

What does it help you do?

Maps processes, modules and data flows to actual repository paths.
Documents state ownership and invariants such as tenant isolation and ordering.
Records alternatives, trade-offs and status for significant decisions.

Try asking this

Document why the cooperative game's inventory is owned by the server rather than each client. Trace item creation, transfer and save loading to actual modules. Record the rejected alternative, disconnect behavior and test evidence, and clearly mark whether the decision is accepted or still proposed.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Architecture & Decision Records

Explain the system's structure, data flow and invariants so a developer knows where new behavior belongs, which boundaries must hold, and why significant technical decisions were made.

1. Architecture overviews that trace real boundaries

System map: name the runtime processes, packages or services (server, ui, workers, database, external providers) and state the single responsibility of each.
Data and control flow: walk through the main end-to-end flows (such as an incoming HTTP request, a background job lifecycle or a real-time event stream) from entry point to storage and back.
State and ownership: state where each kind of state lives (database tables, in-memory caches, URL/client state, filesystem artifacts) and which module is allowed to mutate it.
Invariants and constraints: highlight the rules that must never be violated (security invariants, transaction boundaries, tenant isolation, idempotency, ordering guarantees).
Ground every diagram or module list in actual directory paths and entry files; never draw boxes for layers that do not exist in the repository.

2. Architecture Decision Records (ADRs)

Record an ADR whenever a choice has lasting consequences across modules, data models, dependencies, security or operations. Each ADR must state:

Title and status: Proposed, Accepted, Superseded by ADR-NNN or Deprecated, with the date or change context.
Context and problem: the technical, product and operational forces at play, stated neutrally without pre-judging the answer.
Alternatives considered: the realistic options evaluated (including doing nothing or extending an existing pattern) and their trade-offs.
Decision: the chosen approach and the concrete reason it won over the alternatives.
Consequences: what becomes easier, what becomes harder, what risks or limits remain, and how the decision is enforced or verified.

3. Keep architecture docs alive

When a new ADR supersedes an earlier decision, keep the old ADR for historical context, mark its status as Superseded by ..., and update the active architecture overview to reflect current reality.
Never present an unaccepted proposal or future target architecture as the system that runs today.

Before you finish

Every module, package and boundary named in the overview points to real paths in the repo.
End-to-end data flow and state ownership are clear.
Each ADR records status, context, alternatives considered, decision and consequences.
Accepted decisions, open proposals and superseded historical records are clearly distinguished.

Included files 2

LICENSE.txt
SKILL.md