Empire Phoenix
2e4eb283b5
- 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.
63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# 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.
|