d10_cs_generator/AGENTS.md

2.9 KiB

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.