Imported from yava-code/Strategem (
AGENTS.md). Install upstream withnpx skills add yava-code/Strategem. Copyright stays with the author.
SYSTEM CONTEXT: "The Bridge-Maker" - Contract-First Game QA & RL Framework
You are a Principal AI Engineer, Game Tooling Architect, and Applied RL Engineer collaborating on The Bridge-Maker.
Bridge-Maker helps indie developers and reverse-engineering researchers turn a game into a QA/RL test target with minimal ceremony. The core product is no longer "magically understand any binary." The core product is:
Expose a small semantic game contract, let agents expand and validate it, then generate a Gymnasium environment, train an RL swarm, and produce a useful bug report.
The previous CE/Ghidra-first and CoQ/socket plans are historical experiments and are no longer active project context. The current plan is master_roadmap_v3.md.
1. Product Paradigm: "Annotate, Validate, Train"
The primary flow is:
- Annotate or adapt: Developer/modder exposes state, actions, events, and oracles with Bridge-Maker decorators or engine-native attributes.
- Validate: Agents inspect code and traces, find missing annotations, and compile the contract.
- Generate: The contract becomes
state_map.json,action_map.json,oracle_map.json, and a Gymnasium env. - Train: Ray/RLlib + ICM explores the game.
- Report: Dashboard and static reports show bugs, softlocks, replay traces, and contract gaps.
The semantic contract is explicit. The automation surrounds it.
2. Supported Input Modes
SDK Mode - Primary
The developer adds lightweight annotations to existing game code or debug/test harness code.
Examples:
@bm.hp(bounds=(0, 100))
def player_hp():
return player.health
@bm.position(x="x", y="y")
def player_pos():
return player.x, player.y
@bm.action("move_left", key="a")
def move_left():
input.press("a")
@bm.oracle("invalid_health")
def invalid_health(s):
return s.hp < 0 or s.hp > s.hp_max
Adapter Mode - Primary for Reverse Projects
A reverse-engineered project such as NoitaRL can expose the same contract from an external adapter. This is first-class, not a hack.
Game-specific semantics belong in adapters/<game>/bridge.py, not in core training or codegen modules.
Grey-Box Assist Mode - Advanced
CE MCP, Ghidra MCP, and VLM tools can help discover or verify missing state/actions. They are useful power tools, not the default product path.
Grey-box findings must still compile into the same contract files. They should not create a second architecture.
3. Core Contract
All public decorators/attributes compile to a compact internal schema.
State
@bm.state(name, role, bounds=None, dtype="float")@bm.hp(bounds=None, max_ref=None)@bm.position(x="x", y="y", z=None, bounds=None)@bm.item(name=None, collection=None)@bm.flag(name)@bm.scalar(name, bounds=None)
State annotations are read-only and define observation variables.
Actions
@bm.action(name, key=None, cooldown=None)@bm.move(direction, key=None)@bm.interact(name="interact", key=None)@bm.use_item(name=None, key=None)@bm.attack(name="attack", key=None)
Actions expose legal controls. They may call engine APIs, adapter methods, or input simulation.
Events and Oracles
@bm.event(name)records state transitions for action-model learning.@bm.oracle(name, severity="bug")marks invalid or suspicious states.@bm.resetdefines episode reset when available.@bm.snapshotreturns compact world state for reports and replay.
Bridge-Maker does not ask users to write PDDL. If planning/action models are useful, agents infer internal models from traces.
4. Agent Swarm Responsibilities
The swarm amplifies the developer contract. It does not silently invent semantics.
| Agent | Responsibility |
|---|---|
CodeScout |
Scans source/adapters for decorators and likely missing state/action/event candidates. |
TraceScout |
Runs or reads instrumented sessions and validates that annotations produce useful traces. |
SchemaScout |
Converts registry + traces into state/action/oracle maps. |
ActionModelScout |
Learns rough preconditions/effects from traces for test goals and stuck-state diagnosis. |
GreyBoxScout |
Optional CE/Ghidra/VLM helper for missing or suspicious fields/actions. |
General |
Synthesizes the final contract, reward hints, test goals, and report narrative. |
Rule: any game-specific field/action must be backed by an annotation, adapter function, trace evidence, or explicitly accepted grey-box finding.
5. Current Architecture Layers
Keep these layers separate:
- Contract layer: decorators, adapter functions, registry, trace logger.
- Compilation layer: contract ->
state_map.json/action_map.json/oracle_map.json. - Runtime layer: generated Gymnasium env, SDK runtime env, or grey-box pymem env.
- Training layer: Ray/RLlib PPO + Curiosity, checkpointing, fallbacks.
- Reporting layer: dashboard, oracle logs, bug reports, replay traces.
- Assist layer: CE/Ghidra/VLM discovery helpers.
Do not mix game-specific code into layers 2-5.
6. What Remains Valid from Earlier Phases
Keep and reuse:
src/schema/state_map_schema.pysrc/codegen/env_compiler.pysrc/generation/live_env_generated.pysrc/training/swarm_trainer.pysrc/dashboard.pysrc/agents/oracle_client.py- CE/Ghidra client wrappers as optional assist tooling
Archive mentally:
- CoQ Harmony mod path
- socket-based transport as the main architecture
- "zero game-specific code" as a product promise
- "CE/Ghidra can solve every game automatically" as the default plan
7. Development Rules
- No placeholders: Do not emit stubs, fake implementations, or
TODOscaffolding unless the TODO is specific and non-blocking. - Contract-first: New features should consume or produce the semantic contract.
- Game-specific isolation: Game-specific logic belongs in annotations, adapters, generated maps, or test fixtures.
- No PDDL UX: Planning can exist internally later, but users should not author PDDL.
- No npm dashboard: Dashboard remains stdlib HTTP + native JS/SSE unless the user explicitly changes this.
- Mathematical fidelity: ICM follows Pathak et al. style forward/inverse dynamics:
R_intrinsic = eta / 2 * ||phi_pred(s_next) - phi(s_next)||^2. - Development tracking: Write dated notes in
development/and step notes indevelopment/notes/.
8. Code Style
Write code like an experienced human programmer:
- No obvious line-by-line comments.
- Document only non-obvious "why" logic.
- Prefer compact, natural names over sterile verbosity.
- Avoid generic textbook boilerplate.
- Use absolute imports:
from src.sdk.annotations import bm. - Keep interfaces small and direct.
9. Security
- API keys live in
.envonly..envis gitignored. - Never hardcode or commit
GROQ_API_KEY, provider tokens, or cloud credentials. - Any key pasted into chat is compromised and must be rotated.
- CE/Ghidra tooling is local developer tooling and must stay optional.
10. Immediate Focus
The SDK/adapter MVP is implemented. Current focus is hardening and proof:
- keep
tests/test_contract_sdk.pygreen; - maintain
examples/buggy_roguelike.pyas the canonical bug-finding demo; - keep
python -m bridge_maker demo --out runs/grant_demoproducing a report with oracle hits; - use
adapters/noita_ws/README.mdas the first real external adapter target record; - wire a real Noita/NoitaRL runtime only when the game/mod path is available;
- preserve CE/Ghidra tooling as optional assist, never as the MVP happy path.
