Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity
main
Blacksite/AGENTS.md
Rbanh f29712d158
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Initial project import
2026-06-05 21:44:45 -04:00

2.1 KiB
Raw Permalink Blame History

Agent Instructions

Documentation Maintenance

When changing behavior, architecture, or user-facing workflows, update documentation in the same task. Do not defer documentation updates for implemented work.

Use docs/README.md as the documentation map and keep each fact in one home:

Change type Update
Architecture, crate boundaries, or sim/network split New or updated ADR in docs/adr/
Editor framework intent, principles, or non-goals docs/mission.md
Editor feature design or phase status docs/editor/
User controls, run commands, or troubleshooting Root README.md
Shipped feature completion Root README.md implementation checklist
Bevy upgrade policy ADR 0002 and migration notes in docs/adr/
Milestone scope before implementation .cursor/plans/ plan file

Create an ADR in docs/adr/NNNN-short-title.md when a decision is hard to reverse or affects multiple crates, such as rendering path, scene format, PIE semantics, settings schema, or netcode choice. Use this format: Status, Context, Decision, Consequences. Number ADRs sequentially and link new ADRs from docs/README.md and the root README when relevant.

Coherence rules:

  • One home per fact. Link across docs; do not copy paragraphs between README, mission, and ADRs.
  • Intent vs implementation: mission/ADRs explain why, README explains how to use, crate module docs explain local API.
  • Plans vs permanent docs: .cursor/plans/ holds working roadmaps; promote stable decisions into docs/ when implemented.
  • Stale docs are bugs. If code contradicts docs, fix both or fix docs in the same PR/task.
  • New subsystems get a short entry in docs/README.md and, if editor-facing, docs/editor/README.md.

End-of-task checklist for relevant implementation work:

  1. Did behavior or UX change? Update README controls or checklist.
  2. Did architecture or policy change? Update or create an ADR or mission note.
  3. Did an editor workflow change? Update docs/editor/.
  4. Added a new doc file? Index it in docs/README.md.
  5. Left a deliberate gap? Record it as future work in README or an ADR Consequences section.