Architecture & Agent Framework

Knowledge vs Maker

Plain English: the spec is the rulebook. The engine is the referee (NFR-1, NFR-10). The Maker is the table you play on. This knowledge site is the companion booklet. Agent skills and why they were chosen live in SKILL_MATRIX. See 0002-typescript-monorepo-2d-to-3d.

flowchart TB
  spec["GAME_SPEC.md — formal rules"]
  engine["packages/engine — simulation NFR-1 / NFR-10"]
  maker["apps/web — Maker on zorg.artof.link"]
  knowledge["apps/knowledge — this site"]
  docs["docs/ — guide, ledger, ADRs, journal"]
  spec --> engine
  spec --> knowledge
  docs --> knowledge
  engine --> maker

Agent instructions

This file is the single source of truth for any AI collaborator on this

repo — Claude, Codex, or anything else. Tool-specific files (CLAUDE.md,

etc.) exist only so that tool finds its entry point; they must never

diverge from this one. If you're an agent and a tool-specific file

contradicts this file, this file wins.

The rules below are this repo's adaptation of the **Adaptive Experience

Architecture (AEA)** framework (architecture.artof.link) to a solo/small-team

game project. Citations point at the pages the rule is drawn from.

1. Knowledge First

"Read committed shared memory before doing new work. Shared memory is

[the repo's default branch]. Chat is not shared memory."

— architecture.artof.link/comparison.html

Before changing anything, read in this order: this file, GAME_SPEC.md

(the rules + FR/NFR), docs/adr/ (why things are the way they are),

docs/STATUS_LEDGER.md (what's actually proven vs. claimed). A prior chat

session's context does not exist for the next agent or the next person —

if it mattered, it's in one of these files, or it didn't happen.

2. Honesty

"A status word is a claim. Probe it, or write Unknown."

— architecture.artof.link/glossary.html ("Probe")

Never mark an FR/NFR, a PR description, or a commit message as "done",

"implemented", "working", or similar without evidence a reviewer (human or

CI) can check. Use docs/STATUS_LEDGER.md's five-word vocabulary

(Unknown, Planned, Simulated, Probed (date), Live & Probed) — see

that file for the exact rules. Closing an issue is not proof.

Archify 3.x ignores meta.views, so status wording must live in a diagram's

components or cards, never only in its chapter notes. The governance check

runs scripts/check-archify-honesty.mjs (word list:

scripts/archify-honesty.config.json) to enforce that.

Keep Learning and Apply

When the build teaches something, write it into the harness (skill,

sensor, guide, matrix row, or ADR) before the next loop — so the next

agent inherits it instead of rediscovering the failure.

— AEA Keep Learning and Apply

(GitLab work item #434; sponsor reports

!513

merged and #434 closed — Documented on AEA main. Pages still

Unknown until probed. GitLab sign-in from this agent is not a

content probe.)

This complements Honesty (§2) and Knowledge First (§1). It is

not Antifragility (§3). Antifragility is the second-miss → sensor

gate. This principle is the first-loop write: if the build taught

something, commit a skill, guide, SKILL_MATRIX row, or ADR before

the next agent starts — a chat note is not apply.

AEA cites (same GitLab project):

Status in zorg-dungeon: Documented; zorg knowledge Pages Probed

(2026-09-13 HTTP 200:

skills,

aea,

findings).

GitLab #434

is the stable formal principle. Café App cites #434 and filed

#214

(keep-learning-and-apply). Café Knowledge cites #434 on

#213

/ the matrix PR. Also zorg

#53, logify

#24

(closed; PR #25 merged

on logify main, cites #434 — Documented). Café MRC

is COMMENT-only. The apply map is SKILL_MATRIX: historical pain →

skill / matrix row / finding sensor. AEA Knowledge Pages for this

principle remain Unknown until AEA probes them. Not Live & Probed

for game FRs; not a STATUS_LEDGER promotion. GitLab sign-in from

this agent is not a merge probe.

The skill map is SKILL_MATRIX (columns: Skill | Scope | Why? | What).

Shared Grok skills (sand-workflow slugs pr-train-rebase,

honesty-ledger-gate, companion-plain-docs,

persona-journey-validation, corpus-quarantine-honesty) are

adopted here — tracked by

#50.

Quarantine evidence: #52.

Kid learn page stays Planned: #51.

Cross-project ack: Café MRC is COMMENT-only (skills on the Café

train; no self-merge on one-issue PRs). New Bot squash-merges

Café skill PRs when MRC is CLEAN. Café App is **Documented

until probed** (cites #434; Grok skill

#214

(keep-learning-and-apply); shared four via

#206;

created #207–#212;

matrix #205

→ knowledge/skills-matrix.md / skills-matrix.html). Café Knowledge

is Documented until probed (cites #434 on

#213

/ the matrix PR + knowledge-pages-ratchet

#203

/ #204).

AEA is Documented on AEA main (skill matrix !512

/ #433;

principle sponsor-reports !513

merged / #434

closed; Pages Unknown; shared four referenced, no dup). logify Keep

Learning is Documented on logify main

(#24 closed,

PR #25 merged, cites

#434). logify skills stay Documented / Simulated

(#22

pr-train-parallel-merge,

#23

tagged-release-cut); companion / personas N/A. ctos is N/A (docker

smoke is a repo script). 3DX Lab is Documented until probed

(#7 honesty,

#8 infra-apply,

#9 lab-vs-factory,

#10 Keep Learning

gap; skills 3dx-lab-honesty, 3dx-lab-infra-apply,

3dx-lab-lab-vs-factory; draft

PR #11 awaiting

sponsor merge). This agent got 404 on that repo — URLs are

sponsor-reported, not probed here. Shared PR-train / companion /

personas are N/A there. Other-lane skills are Documented / Simulated

until probed. Not Live. Not a ledger promotion.

3. Antifragility

"The same miss twice is a missing sensor or gate, not a missing

paragraph." — architecture.artof.link/schema.html

Log every discrepancy you find or cause as a CF-NNN entry in

docs/FINDINGS.md. If something breaks the same way twice, the fix is not

allowed to be "be more careful" — it has to change .github/workflows/**

or add a test. See that file for the enforced rule.

4. Traceability (the "graph")

Every functional/non-functional requirement in GAME_SPEC.md has a stable

ID (FR-xx / NFR-xx, never renumbered — "ID Freeze",

architecture.artof.link/glossary.html). Code and tests that implement one

should say so in a comment (see packages/engine/src/geometry.ts for the

pattern). scripts/check-requirements-trace.mjs fails CI on orphaned IDs

(referenced in code but not defined) and on ledger entries claiming proof

with no matching test. Docs cross-reference each other with wikilinks

(checked by scripts/check-docs-graph.mjs) — this repo's docs are its

second brain; keep them linked, not siloed.

5. Collaboration ground rules (agent-neutral & multi-agent)

This repository is designed for concurrent, asynchronous collaboration across

diverse AI assistants and human contributors, including:

All tool-specific entrypoints are minimal pointers that redirect to this file.

To ensure clean collaboration between different agents:

committed files — no tool-specific formatting, no instructions only one

tool would understand.

prior chat sessions. The committed default branch and files (GAME_SPEC.md,

docs/STATUS_LEDGER.md, docs/FINDINGS.md, docs/journal/, docs/adr/)

are the sole shared memory. If it matters, write it to docs or code;

otherwise, it does not exist for the next agent.

off main using the pattern agent/<agent-family>/<task-slug> (e.g.

agent/claude/phase-0-loader, agent/copilot/fr-10-geometry). Never rebase

over another agent's active in-flight branch.

and governance checks plus a peer review (human or peer agent) before

merging — see CONTRIBUTING.md.

docs/FINDINGS.md, touch only the rows related to your task to minimize

rebase friction with peer branches.

shipped changes, active investigations, and pending decisions for the next

agent.

.gitattributes across Windows, macOS, and Linux/container environments.

See docs/adr/0003-multi-agent-collaboration.md for the full rationale.

6. Repo shape

UI framework. This is what NFR-1 (determinism) and NFR-10 (AI

testability) are actually about — keep it that way.

playback view. Currently a 2D canvas app; see docs/adr/0002-*.md for

the planned path to 3D and to Android/tablet via Capacitor.

day by day (the "second brain"). docs/STATUS_LEDGER.md and

docs/FINDINGS.md — the honesty/antifragility ledgers above.

docs/PLAYER_GUIDE.md — plain-English + diagram companion to

GAME_SPEC.md (published as guide.html). Formal IDs stay in the spec;

if they disagree, the spec wins. docs/LEARN.md — kid-facing rules

(published as learn.html). docs/PLAYER_JOURNEYS.md — persona UX

validation cases (published as journeys.html). Not a rules rewrite.

docs/SKILL_MATRIX.md — which agent skills apply, who must load them,

why they were chosen after the 2026-09 build, and how each row

Keep Learning and Apply

(#434 /

!513;

AEA matrix !512)

(published as skills.html). See SKILL_MATRIX. Compose with

persona-journey / kid-rules pages; do not rewrite that copy here.

(pnpm governance) exactly as CI runs them.

7. Local commands

pnpm install
pnpm build            # all workspaces
pnpm test             # all workspaces
pnpm governance       # requirements trace + honesty ledger + findings + docs graph