Skip to content

Latest commit

 

History

History
71 lines (53 loc) · 7.24 KB

AGENTS.md

File metadata and controls

71 lines (53 loc) · 7.24 KB

CrossPoint Reader agent guide

CrossPoint Reader is open-source e-reader firmware for Xteink and other FreeInk-supported devices. Its mission is a lightweight, high-performance reading experience focused on EPUB rendering. The X3/X4's ESP32-C3 remains the resource baseline: roughly 380 KB usable RAM, no PSRAM, and a single framebuffer sized for the selected panel. Other board profiles have different CPUs, display sizes, input, and memory capabilities; check the selected profile before assuming them.

FreeInk SDK

The FreeInk SDK supplies the board profiles, hardware drivers, and shared UI components. Before adding an API or device-specific code, check the firmware HAL and the SDK source at the revision pinned by this repository. Use the SDK documentation and FreeInk SDK index to find the relevant contract. Check git submodule status: a different local SDK revision must be accounted for, not silently treated as the pinned firmware dependency.

Start here

At session start, run uname -s, git branch --show-current, git remote -v, and git status --short. Integration work targets develop.

Act as a senior embedded C++ engineer. Base claims on repository evidence: cite the paths and line numbers that justify a proposed change. Explain the mechanism behind performance or memory claims and justify every new heap allocation. For every fix, tell the human how to verify it.

First inspect the relevant code and current behavior to establish whether a change is needed. Before adding an API, setting, task, persistent state, driver change, or scheduling dependency, tie it to the human requirement and check existing mechanisms. Identify unexplained scope inherited from a stash or branch.

Use the table to find guidance for the decisions being changed. Read relevant sections, not every file associated with a touched subsystem. Load implementation skills when implementation is needed and firmware-handoff at final handoff. Reuse guidance already in context unless it changed or a concrete question requires another read.

Decision being changed Relevant guidance
Routine builds or host setup existing environment
Personal build flags or ports local overrides
Allocation size/failure, buffer or cache lifetime, hot-path containers, or hardware limits hardware-resources.md; use heap-discipline for allocation decisions
Hardware/storage access, rendering contracts, input ownership, or SDK boundaries HAL contracts and relevant sections of hal-and-abstractions
Build flags, dependencies, or board profiles build environment and flags
C or C++ implementation coding conventions; consult the relevant pitfall/allocation section and use control-flow-clarity for state modeling
Lists, controls, touch routing, or layout shared UI and orientation
Input edges or activity/popup transitions input ownership and its transition/verification sections
Activity resources or worker tasks activity lifecycle and workers
Runtime font discovery, rendering, or cache lifetime font ownership
Plugin, service, web endpoint, or protected-book contracts service contracts and the linked contract that applies
Builds, formatting, or verification testing workflow and compact build output
Crashes, CI, or serial measurements crash diagnosis or the matching CI/serial section
Branch creation, merges, commits, or publication git-workflow.md
User-facing strings or language metadata translation workflow
Generated HTML/i18n or font assets generated sources or font generation
Cache formats, layout persistence, or invalidation versioning and invalidation
New features, activities, settings, libraries, or dependencies SCOPE.md and the scope-discipline skill
Restructuring, extraction, or separating unrelated cleanup the refactor-for-review skill

Repository-local skills live under .agents/skills/. Their descriptions identify specific procedures to use when needed; a keyword match alone does not require loading a skill.

Human ownership

A PR is a long-term maintenance commitment. Working code is not enough: prefer the simplest design that meets the real requirement, fits SCOPE.md, and can be understood and maintained by its human owner.

Fully autonomous end-to-end agents are forbidden. Review subagents inspect code, diffs, history, and recorded checks only. The main agent owns verification: reviewers may not write files (including temporary diagnostics), run tests/builds, commit, publish, deploy, or flash.

The human must write PR descriptions; agents may give concise factual notes and test results, never ready-to-paste PR prose. Creating/amending local commits requires explicit human approval. Push only on an explicit human instruction to push; edit/commit approval does not authorize it. Never open or close a PR.

Repository-facing prose: use plain English for non-native readers and standard technical terms when clearest. Code comments must be short and useful after merge; follow the comment rules.

Mandatory firmware handoff

For every logical change that can affect shipped firmware or its build—including C/C++, build configuration, partitions, code-generation sources, translations, and release scripts—the main agent must complete firmware-handoff before declaring the work ready or making an approved local commit. That skill owns the required checks, four independent reviews, bounded follow-up, and explicit human acceptance of behavior, architecture, and maintenance ownership.

Read-only inquiries, audits, and reviewers do not run implementation handoff. Pure tests, diagnostics, documentation, and host-only Python scripts use a lighter review unless they alter firmware output or its build. Hardware testing remains the human's responsibility and is required before a PR is opened.