d10_cs_generator/AGENTS.md

55 lines
2.9 KiB
Markdown

# D10 Roll20 sheet agent guide
## Scope and sources
Build the base fantasy D10 and cyberpunk Roll20 sheets only. The former base
sheet in Git history is the compatibility reference; `origin/cyberpunk-latest`
supplies the cyberpunk skill catalogue. Check `origin/cyberpunk` when a latest
branch detail is ambiguous. `agent_models/` (including the Ravenous model) is
an untracked reference area provided by the user: borrow its build discipline,
not its game mechanics. Do not edit, commit, or import that directory as part
of this project. It is ignored by Git so it remains local. Roll20 Mod scripts
live in `scripts/`, are installed separately, and are not embedded in the
generated sheet. `d10_character_io.js` is current; `change.js` and `crit.js`
are unvalidated legacy scripts.
## Source of truth
Keep skills in YAML and sheet structure in explicit model data. HTML/CSS/JSON
under build/ are generated and must not be hand edited. Preserve existing
Roll20 attribute names and repeating section identifiers when feasible;
record any deliberate incompatibility. Keep theme changes visual, with no
change to rolls or stored attributes. Escape data inserted into HTML and
validate YAML and model references before writing output.
`FEATURES.md` is the behavioral and portability contract. `ARCHITECTURE.md` is
the component, data-flow, and reconstruction contract. Update the applicable
feature dossier for every behavior change, including its persistent/runtime
interfaces and acceptance checks. Update the architecture document whenever a
source-of-truth boundary, generated artifact, runtime component, or build flow
changes. README remains the operator guide and must agree with both contracts.
Keep character JSON exchange versioned and generic over Roll20 attributes so
both variants and repeating rows round-trip. Validate a complete payload before
mutation, retain player/GM permission boundaries, and test Mod behavior in the
local API mock. A sheet button is not proof that its separately installed Mod
command works.
## Workflow
Work through TASKS.md in order and update it as each task finishes. Make a
focused commit after each completed stage. Each commit must leave the generator
and its applicable tests passing. Document commands, output files, variant
behavior, and migration caveats in README.md. Consult old source in Git history
only when necessary for compatibility.
For each behavior change, test the generated artifact, including attribute
references and roll expressions. Check both variants and every theme. Use a
local worker or calculation test when behavior can be simulated; structural
string checks alone do not establish Roll20 correctness. Record any interaction
that still requires the Roll20 Custom Sheet Sandbox. Do not claim a live
Roll20 test unless it was actually done.
Before completing a change, verify that `.gitignore` still excludes
`agent_models/` and that no file from that reference tree is staged.