PlantCtrl/AGENTS.md

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.