* chore(agents): move Claude instructions and skills to AGENTS.md and .agents Claude Code now reads AGENTS.md and .agents/skills, so one client-agnostic copy serves every assistant and the Codex adapters that pointed back into .claude go away. The build skill splits by host: Linux builds natively, macOS needs the container. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com> * chore(agents): expose .agents to Claude Code via imports and symlinks Claude Code reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists and never reads .agents/, so the skills and instructions were invisible to it. Worktrees move outside the repository, where no tool's recursive search reaches them. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com> * chore(agents): refine build, commit, pr and review-pr skills Linux builds run in whatever checkout the agent is in. PR bodies now carry the Assisted-by disclosure and an optional Testing section for testing worth reporting. Commits preserve history for reviewers since PRs are squash-merged. Reviews can check the area's history for intentional or in-flight work. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com> * feat(agents): push and refresh the PR description from the commit skill A commit on a pushed branch otherwise leaves the PR stale until someone remembers to push and re-edit it. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com> * fix(agents): drop trailing blank line in .gitignore Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com> --------- Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com>
11 KiB
get_mode_requirements
Purpose
get_mode_requirements.py parses the PX4 flight mode requirements defined in
src/modules/commander/ModeUtil/mode_requirements.cpp and generates Markdown documentation.
It produces two kinds of output under docs/en/:
flight_modes/mode_requirements.md— a consolidated overview table for all vehicle types.- Per-mode requirement text injected directly into individual flight-mode pages using include markers.
Running
From the repo root:
python3 docs/scripts/get_mode_requirements/get_mode_requirements.py
Or from the docs/ directory:
python3 scripts/get_mode_requirements/get_mode_requirements.py
Inline Injection
The script locates each parent flight-mode doc (e.g. flight_modes_fw/manual.md) by scanning
docs/en/flight_modes/, docs/en/flight_modes_fw/, docs/en/flight_modes_mc/, and
docs/en/advanced_features/ for a VitePress <!--@include:--> directive (or an existing
AUTO-GENERATED sentinel block) that references the corresponding snippet name
(build_snippet_to_parent_map()). This directory scan is what actually determines where a
mode's requirements get injected — it is independent of the doc field in
mode_nav_state_defns.json, which only controls headings/links in mode_requirements.md. A
mode can have a doc pointing at a page that isn't scanned (or has no injection marker on it
yet) and still trigger a "not mapped to a doc" warning; fix this by adding an
<!-- AUTO-GENERATED: snippet_stem --><!-- END AUTO-GENERATED: snippet_stem --> marker pair
(content between them can be empty — the script fills it in) to the actual doc page, and if
that page lives outside the four scanned directories, add its directory to search_dirs in
build_snippet_to_parent_map().
A single doc page can contain multiple injection points for different nav-states (e.g.
flight_modes/offboard.md has one per vehicle type; flight_modes_mc/manual_stabilized.md
has one for NAVIGATION_STATE_STAB and one for NAVIGATION_STATE_MANUAL, since those are
distinct nav-states with different requirements that happen to share one doc page). Each
generated block always starts its own ### Mode Requirements heading, so when adding a second
block to the same page, add distinguishing surrounding text/labels manually to avoid duplicate
headings, then hand-write the marker pair; the script replaces the content and heading between
the markers.
It replaces that directive with the rendered content, wrapped in sentinel HTML comments:
<!-- AUTO-GENERATED: mode_requirements_fixed_wing_manual -->
### Mode Requirements
The following requirements must be met to arm in this mode, or to switch to this mode when it is armed.
- [`mode_req_manual_control`](xxx) - Requires stick input
<!-- END AUTO-GENERATED: mode_requirements_fixed_wing_manual -->
On subsequent runs the sentinels are detected and the content between them is updated in-place,
so the script is safe to re-run whenever mode_requirements.cpp changes.
Do not edit the text between the sentinel comments manually — it will be overwritten on the
next run. Make changes in requirement_defns.json or in mode_requirements.cpp.
Path Calculation
The script resolves the repository root at runtime using Path(__file__).resolve() and
navigating three parent directories up:
docs/scripts/get_mode_requirements/get_mode_requirements.py
-> docs/scripts/get_mode_requirements/ (parent)
-> docs/scripts/ (parent.parent)
-> docs/ (parent.parent.parent)
-> PX4-Autopilot/ (parent.parent.parent.parent) ← repo root
If this script is ever moved, update the repo_root line accordingly.
Adding or Changing Requirement Definitions
requirement_defns.json (in the same directory as the script) maps each mode_req_* flag
name to a human-readable text, an example sensor, and an extended detail string. Add
new entries here when new requirement flags are introduced in mode_requirements.cpp.
If the script encounters a flag in mode_requirements.cpp that has no entry in
requirement_defns.json, it prints a WARNING: line to stderr and continues with empty
text, sensor, and detail strings. If the JSON file is missing or malformed the script
exits immediately with a clear ERROR: message.
Nav-State / Vehicle-Type Metadata
mode_nav_state_defns.json (in the same directory as the script) maps every
(VEHICLE_TYPE_*, NAVIGATION_STATE_*) pair to display metadata used when generating
mode_requirements.md section headings and controlling per-mode warning behaviour.
Each entry may contain:
| Key | Type | Default | Meaning |
|---|---|---|---|
label |
string | — | Human-readable mode name (e.g. "Mission Mode") |
doc |
string | — | Relative doc path used as a heading hyperlink (e.g. "../flight_modes_fw/mission.md") |
warn |
bool | true |
Set to false to suppress warnings for this mode |
status |
string | — | Short implementation-status note, used only when doc is absent (see below) |
Heading generation (in mode_requirements.md):
A mode is only given a full heading + requirement list in the main per-vehicle-type list if it
has a doc. Modes with no doc are not given a bare heading in the main list — instead
they are collected into a trailing ### Modes Without a Dedicated Page summary for that
vehicle type, rendered as - **NAV_STATE** — {status}. Use status to explain why there's
no dedicated page — e.g. the mode isn't implemented for this vehicle type, or it behaves
identically to another mode already documented, or it's an internal/failsafe state that isn't
user-selectable. If a no-doc mode has no status text, the script prints a WARNING: to
stderr and falls back to "Not currently documented."
Skipping snippet injection: if an entry has "warn": false and no "doc" key, the script
skips snippet processing for that mode without printing a warning. Use this for modes that
are not real operational modes (e.g. TERMINATION) or that deliberately have no doc page.
(This is orthogonal to status: warn/doc control snippet-injection behaviour, while
status controls what's shown in the mode_requirements.md summary.)
If the script encounters a (vehicle_type, nav_state) pair that has no entry at all in
mode_nav_state_defns.json, it prints a WARNING: line to stderr. Add a new entry whenever
a new navigation state is introduced in mode_requirements.cpp.
Ordering: the key order of NAVIGATION_STATE_* entries within each vehicle-type block in
mode_nav_state_defns.json — not the order setRequirement() calls appear in
mode_requirements.cpp — determines the order modes are rendered in mode_requirements.md,
for both the headed list and the trailing "Modes Without a Dedicated Page" summary. The
intended order is low-to-high autonomy (e.g. MANUAL → STAB → ACRO → ... → OFFBOARD).
VEHICLE_TYPE_FIXED_WING and VEHICLE_TYPE_ROTARY_WING are separate JSON objects, so keep
their key order in sync manually when adding or reordering a mode. Any nav_state the parser
finds that has no entry at all in mode_nav_state_defns.json is appended after all
JSON-ordered modes (in addition to the existing "no entry" warning).
The same principle applies one level up: the top-level key order of
mode_nav_state_defns.json (currently VEHICLE_TYPE_FIXED_WING before
VEHICLE_TYPE_ROTARY_WING) determines the order the ## Fixed-wing / ## Multicopter
sections are rendered in mode_requirements.md. This is deliberate — vehicle types are
discovered from mode_requirements.cpp into a Python set, whose iteration order is
randomized per-process, so the render loops must never iterate that set/dict directly or the
section order will vary between runs for no code reason. Any vehicle type found in the C++ but
absent from the JSON is appended afterwards in sorted order.
Parser design
parse_requirements() uses a single-pass token scanner. A single compiled regex (_TOKEN)
identifies all meaningful tokens in the getModeRequirements() body in left-to-right order:
single-line comments (skipped), if (vehicle_type == X) { (push condition), } else { (flip
condition), } (pop), { (push None for non-conditional blocks), and setRequirement(…)
calls. A condition stack tracks the innermost active vehicle-type condition; requirements are
assigned to the appropriate vehicle-type set based on whether we are inside an if-branch, an
else-branch, or unconditional code.
This replaces an earlier two-pass regex approach that was fragile: its non-greedy [\s\S]*?
pattern would span across unrelated blocks when a standalone if appeared before an if-else,
producing silently wrong output for several modes.
Tests
The test suite lives in tests/ and is a pytest regression suite that guards against
unintended changes to the parser output. It compares the live output of the parser against
golden JSON snapshots:
tests/
__init__.py
test_get_mode_requirements.py ← the test module
test_data/
requirement_defns_golden.json ← expected requirement_defns contents
vehicle_modes_golden.json ← expected parse_requirements() output
test_data/requirement_defns_golden.json— expected contents of therequirement_defnsdict (flag name → text / sensor / detail).test_data/vehicle_modes_golden.json— expected output ofparse_requirements()applied to the checked-inmode_requirements.cpp: a per-vehicle-type, per-mode mapping of sorted requirement flag names.
conftest.py at the package root adds this directory to sys.path so pytest can import
get_mode_requirements without any install step.
The suite contains three tests:
| Test | What it checks |
|---|---|
test_requirement_defns_matches_golden |
requirement_defns exactly matches the golden snapshot |
test_vehicle_modes_matches_golden |
parse_requirements() output matches the golden snapshot; prints a per-mode diff on failure |
test_all_requirement_flags_are_defined |
Every flag found in mode_requirements.cpp has an entry in requirement_defns |
Running the tests
From this directory (get_mode_requirements/):
pytest tests/ -v
When to run and update
Run the tests whenever you change:
- the parser logic in
get_mode_requirements.py, or src/modules/commander/ModeUtil/mode_requirements.cpp.
Update the golden files after any intentional change to either of the above so that the snapshots stay in sync with the new expected output:
python tests/test_get_mode_requirements.py --update-golden
Then re-run the tests to confirm they pass, and commit the updated golden files alongside the parser or C++ changes.