From 2e4eb283b5f66773b3e88b875966db0a14dd769b Mon Sep 17 00:00:00 2001 From: Empire Phoenix Date: Sun, 26 Apr 2026 19:47:07 +0200 Subject: [PATCH] Add `AGENTS.md` to document repository structure and development guidelines - Introduced `AGENTS.md` to provide an overview of the repository layout and working conventions. - Included guidance for firmware, hardware, and website contributions. - Added validation, file hygiene, and handoff expectations for consistent development practices. --- AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bd7e527 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md + +## Scope +These instructions apply to the entire repository unless a deeper `AGENTS.md` overrides them. + +## Repository Overview +`PlantCtrl` is a mixed-discipline repository with embedded firmware, shared Rust crates, hardware design files, and a Hugo-based website. + +Top-level layout: +- `Software/MainBoard/rust`: main embedded Rust firmware for the controller board (`plant-ctrl2`). +- `Software/CAN_Sensor`: embedded Rust firmware for the CAN sensor / BMS board. +- `Software/Shared/canapi`: shared Rust crate used by firmware projects. +- `Hardware`: PCB, case, and related hardware design assets. +- `DataSheets`: reference material; treat as source data, not generated output. +- `website`: Hugo site based on the Blowfish theme. +- `bin`: helper scripts and local tooling, if present. + +## Working Rules +- Keep changes tightly scoped to the user request; this repo spans hardware, firmware, and website code. +- Prefer fixing the underlying cause instead of applying cosmetic workarounds. +- Preserve existing file structure and naming unless the user explicitly asks for restructuring. +- Avoid mass formatting or opportunistic cleanup in KiCad files, lockfiles, generated assets, or vendored dependencies. +- Do not edit dependency directories such as `website/themes` or `Software/MainBoard/rust/src_webpack/node_modules` unless the user explicitly asks for vendor changes. +- When touching firmware code, keep resource usage and target constraints in mind; avoid unnecessary allocations or feature creep. + +## Firmware Guidance +- Shared protocol or serialization changes must be checked for impact across both `Software/MainBoard/rust` and `Software/CAN_Sensor`. +- Prefer small, explicit changes in embedded code paths; do not introduce heavyweight abstractions without a clear payoff. +- Keep `no_std`/embedded assumptions intact unless the code clearly opts into something else. +- Be careful with feature flags, target-specific dependencies, and boot/runtime configuration in Cargo manifests. + +## Hardware Guidance +- Treat hardware directories as design artifacts, not generic text files. +- Do not reorder, normalize, or bulk-edit PCB / CAD files unless the user specifically requests those changes. +- If a software change depends on hardware assumptions, call that out clearly in the final handoff. + +## Website Guidance +- The site in `website` uses Hugo with the Blowfish theme. +- Prefer editing site content, config, or custom assets over modifying vendored theme internals. +- Keep frontend changes consistent with the existing site structure unless the user asks for a redesign. + +## Validation +Use the narrowest relevant check first. + +Useful commands: +- `cargo check --manifest-path Software/Shared/canapi/Cargo.toml` +- `cargo check --manifest-path Software/CAN_Sensor/Cargo.toml` +- `cargo check --manifest-path Software/MainBoard/rust/Cargo.toml` +- `npm run dev` from `website` for local Hugo development if the environment has the required tools installed. + +Validation notes: +- Embedded firmware may require target-specific toolchains or hardware-adjacent tooling that is not always available. +- If you cannot run a meaningful validation step, say so explicitly and describe the likely prerequisite. + +## File Hygiene +- Read large files in chunks. +- Prefer targeted searches (`rg`, or `find` if unavailable) over broad scans. +- Do not commit build outputs, generated binaries, or local IDE metadata unless the user explicitly requests it. + +## Handoff Expectations +- Summarize what changed, where it changed, and any validation performed. +- Call out follow-up work when a change likely affects both firmware targets, hardware assumptions, or the website.