Files
PX4-Autopilot/docs/scripts/get_mode_requirements/AGENTS.md
T
Jacob Dahl eff5e1b350 chore(agents): move Claude instructions and skills to AGENTS.md and .agents (#28803)
* 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>
2026-09-22 14:26:39 -06:00

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 the requirement_defns dict (flag name → text / sensor / detail).
  • test_data/vehicle_modes_golden.json — expected output of parse_requirements() applied to the checked-in mode_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.