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>
This commit is contained in:
Jacob Dahl authored and GitHub committed 2026-09-22 14:26:39 -06:00
1 parent cc49b8be30
commit eff5e1b350
22 files changed
+523 -595

No files matched your search

+11 -48
View File
@@ -1,53 +1,16 @@
# GPT-based coding agents
# Agent instructions
This repository supports OpenAI Codex alongside the existing Claude Code setup.
Instruction discovery belongs to the client, not the model: choosing a GPT
model in another client does not make that client read Codex configuration.
`AGENTS.md` files hold repository and directory guidance; `.agents/skills/` holds the shared skills. Keep skills client-agnostic: no argument variables or client-specific attribution.
Codex reads the root `AGENTS.md` and discovers skills under `.agents/skills/`.
No global configuration changes, plugins, or copied personal permissions are
required. Start Codex from this checkout and use `/skills` to browse, or invoke
a skill directly:
Claude Code reads neither location directly. Each `CLAUDE.md` is a one-line `@AGENTS.md` import, and each `.claude/skills/<name>` is a symlink to `.agents/skills/<name>`; add both when adding a nested `AGENTS.md` or a skill.
```text
$commit describe the staged changes
$pr target main
$review-pr <PR number or URL>
$rebase-onto-main <branch>
$build-px4 px4_fmu-v6xrt_default
```
Skills can also be selected from a matching natural-language request. GitHub
workflows require an authenticated `gh` CLI; container builds require Docker.
No model is pinned, so the instructions work with the GPT model selected in
your client. Restart Codex if newly added skills do not appear.
## Shared guidance
| Entry point | Source of workflow guidance |
| Skill | Use |
| --- | --- |
| `AGENTS.md` | Repository conventions and references to `.github/instructions/` |
| `skills/commit/SKILL.md` | `.claude/skills/commit/SKILL.md` |
| `skills/pr/SKILL.md` | `.claude/skills/pr/SKILL.md` |
| `skills/review-pr/SKILL.md` | `.claude/skills/review-pr/SKILL.md` |
| `skills/rebase-onto-main/SKILL.md` | `.claude/skills/rebase-onto-main/SKILL.md` |
| `skills/build-px4/SKILL.md` | Self-contained container build workflow |
| `../docs/scripts/get_mode_requirements/AGENTS.md` | The generator's existing local `CLAUDE.md` |
| `commit` | Conventional commit with `Assisted-by:` trailer |
| `pr` | Pull request with Summary/Problem/Solution body |
| `review-pr` | PR review debrief and draft comment |
| `rebase-onto-main` | Rebase, including onto a squash-merged parent |
| `build-px4-linux` | Board or SITL build on a Linux host |
| `build-px4-macos` | Board build on macOS, in the `px4-dev` container |
The four adapters load the existing tracked workflow instead of maintaining
duplicate copies. Keep workflow changes in those shared source files; keep
Codex-specific invocation, tool, and attribution adjustments in the adapters.
References to `.claude/` are ordinary repository file reads, not a dependency
on having Claude Code installed.
The build skill is self-contained because the existing local Claude build
skill is not tracked. It does not depend on local Claude settings, plans,
worktrees, or permissions. Agent-created build worktrees go under the ignored
`.agents/worktrees/` directory.
Nested `AGENTS.md` files bridge existing directory-specific guidance without
duplicating it. The Claude entry points remain unchanged.
See the official Codex documentation for
[AGENTS.md discovery](https://developers.openai.com/codex/guides/agents-md) and
[skills](https://developers.openai.com/codex/skills).
Create worktrees outside the repository, e.g. `../PX4-Autopilot-worktrees/`.
+46
View File
@@ -0,0 +1,46 @@
---
name: build-px4-linux
description: Build PX4 firmware or SITL natively on a Linux host, in the current checkout, without flashing hardware.
---
# Build PX4 on Linux
## Inputs
- A make target, for example `px4_fmu-v6x_default` or `px4_sitl`. Ask for it
if missing; validate it against `boards/`.
Build the current checkout as-is, worktree or not. Do not create a worktree
or switch branches to build.
## Prepare
1. `arm-none-eabi-gcc --version` must succeed for NuttX targets. If it does
not, the host needs `Tools/setup/ubuntu.sh` (Ubuntu) — tell the user rather
than installing it, or build in the container:
`docker run --rm -w "$PWD" --user "$(id -u):$(id -g)" -v "$PWD:$PWD" px4io/px4-dev:v1.17.0 make <target>`.
`Tools/docker_run.sh` passes `-it` and fails without a TTY.
2. The build initializes submodules itself; do not overwrite locally modified
ones.
## Build
```bash
set -o pipefail
make <target> 2>&1 | tail -n 40
```
Report failures with the output; never treat an existing artifact as
evidence of success. After changing a defconfig or Kconfig option, or
switching toolchains, `rm -rf build/<target>` first: a stale build dir
recompiles nothing and links mixed objects.
Do not run a NuttX build concurrently with `make tests` or SITL in the same
tree.
## Report
The artifact is `build/<target>/<target>.px4` (NuttX) or
`build/px4_sitl_default/bin/px4` (SITL). Report the ref, commit, dirty state,
target, and artifact path. Building is not flashing; never upload without a
separate request.
@@ -1,15 +1,14 @@
---
name: build-px4
description: Build PX4 board firmware in the px4-dev Docker container, including git worktrees, and stage commit-labeled artifacts without flashing hardware.
name: build-px4-macos
description: Build PX4 board firmware on macOS in the px4-dev Docker container, including git worktrees, and stage commit-labeled artifacts without flashing hardware.
---
# Build PX4 Firmware
# Build PX4 Firmware on macOS
Use this workflow for flashable board firmware, especially when a macOS host
lacks the NuttX toolchain. Use `px4io/px4-dev` container with the latest available
this container is a native cross-arch container.
It does not supply Gazebo or ROS 2. For Gazebo, use the repository's documented
host setup or a suitable simulator image instead.
Builds run in the multi-arch `px4io/px4-dev` container, so the host needs no
NuttX toolchain. If `Tools/setup/macos.sh` has been run (`arm-none-eabi-gcc`
on PATH), `make <target>` also works natively. The container has no Gazebo or
ROS 2; for simulation use the host setup in `docs/en/dev_setup/dev_env_mac.md`.
## Inputs
@@ -30,14 +29,15 @@ a flashable `.px4` artifact.
`docker image inspect px4io/px4-dev:v1.17.0`; pull it if missing.
4. Prefer an existing worktree for a requested ref. Otherwise resolve the ref
(fetch its remote if necessary) and create a new detached worktree under
`.agents/worktrees/build-<short-sha>/` using `git worktree add --detach`.
`../PX4-Autopilot-worktrees/build-<short-sha>/`, outside the repository,
using `git worktree add --detach`.
Reuse a path only after confirming its HEAD and working-tree state match the
request. Never switch the user's active branch.
5. Check submodule status. Initialize required missing submodules, but do not
overwrite locally modified submodules.
6. Inspect previous build artifacts if moving between macOS and Linux. Remove
only identified generated host binaries with an incompatible format or a
confirmed stale `build/<target>/` directory. Do not blindly clean source or
6. Inspect previous build artifacts if moving between native and container
builds. Remove only identified generated host binaries with an incompatible
format or a confirmed stale `build/<target>/` directory. Do not blindly clean source or
user files.
## Build
+39 -13
View File
@@ -1,20 +1,46 @@
---
name: commit
description: Create a PX4 conventional commit from reviewed changes with a topic-based scope and assistant disclosure.
description: Create a conventional commit for PX4 changes
argument-hint: "[optional: description of changes]"
allowed-tools: Bash Read Glob Grep
---
# PX4 Conventional Commit
Read `.claude/skills/commit/SKILL.md` from the repository root and follow its
workflow with these substitutions:
Create a git commit in conventional-commit format: `type(scope): description`.
- Input is the user's request accompanying this skill, not literal `$ARGUMENTS`.
- Use the current client's tools rather than Claude-specific tool names.
- Replace `Assisted-by: Claude:<model-id>` with
`Assisted-by: Codex:<model-id>` when running in Codex. Use the actual client
name in other clients. If the model ID is unavailable, omit the colon and
model ID rather than inventing one.
- Preserve the user's authorship and the source workflow's DCO review
requirement. Follow any higher-priority client requirements for trailers.
- Stage only changes the user has authorized; never include unrelated dirty
submodules or untracked files.
- **type:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`,
`build`, `ci`, `chore`, `revert`. Append `!` before `:` for breaking changes.
- **scope:** the module/driver/area affected — derive from the directory
path of the changed files (`src/modules/ekf2/` → `ekf2`,
`src/drivers/imu/invensense/icm42688p/` → `drivers/icm42688p`,
`.github/workflows/` → `ci`).
- **description:** imperative, concise, ≥5 chars.
**The user is the author. Never add `Co-Authored-By` naming an AI. End the
commit body with the disclosure trailer `Assisted-by: <tool>:<model-id>`
(e.g. `Assisted-by: Claude:claude-fable-5`). Omit `:<model-id>` rather than
invent one.**
## Steps
1. Check branch (`git branch --show-current`). If on `main`, create a feature
branch `<username>/<description>` where `<username>` comes from
`gh api user --jq .login`.
2. Run `git status` and `git diff --staged`. If nothing staged, ask what to stage.
3. Run `make format` (or `./Tools/astyle/fix_code_style.sh <file>`) on changed
C/C++ files.
4. Body (if needed): explain **why**, not what.
5. Commit with `git commit -s`. Do not pass `-S`: GPG signing is the user's
git config decision (`commit.gpgsign`), not the skill's. The `-s` sign-off
is the user's DCO certification of changes they have reviewed: never
commit with `-s` work the user has not seen.
6. Add new commits rather than amending pushed ones, and never force-push
unless the user asks or the branch is being rebased. PRs are squash-merged,
so the branch history costs nothing on `main` and shows reviewers the
decision chain.
7. If the branch has an upstream (`git rev-parse --abbrev-ref @{u}`), push.
8. If the branch has an open PR (`gh pr view --json state,body`), update its
description with `gh pr edit --body` when the commit changes what the
Summary, Problem, Solution or Testing sections say, following the `pr`
skill's format. Leave it alone otherwise.
+37 -11
View File
@@ -1,18 +1,44 @@
---
name: pr
description: Create a PX4 pull request with a conventional title and concise Summary, Problem, and Solution sections.
description: Create a pull request with conventional commit title and description
argument-hint: "[optional: target branch or description]"
allowed-tools: Bash Read Glob Grep
---
# PX4 Pull Request
Read `.claude/skills/pr/SKILL.md` from the repository root and follow its
workflow with these substitutions:
**The user is the author: no `Co-Authored-By`, no "Generated with <assistant>"
footers. Disclose AI assistance with `Assisted-by: <tool>:<model-id>` as the
last line of the PR body, as in the commit trailers.**
- Input is the user's request accompanying this skill, not literal `$ARGUMENTS`.
- Use the current client's tools rather than Claude-specific tool names.
- Apply the source's ban on Claude attribution to generated-by footers for
any assistant. Keep disclosure in commit trailers, not the PR body.
- If a firmware build is needed, read `.agents/skills/build-px4/SKILL.md`.
Choose a target affected by the change; do not build for documentation-only
changes or imply that a build proves flight safety.
- Use `gh` for GitHub operations and return the created PR URL.
## Steps
1. Check branch. If on `main`, create a feature branch `<username>/<description>`
where `<username>` comes from `gh api user --jq .login`.
2. Gather context: `git status`, `git log --oneline main..HEAD`,
`git diff main...HEAD --stat`, check for remote tracking branch.
3. Sanity-build **one** target the change can actually affect — a board for
firmware changes, `px4_sitl` for POSIX-only or simulation changes. Skip the
build entirely when the diff cannot reach any target (submodule pointer
bumps, docs, ROMFS). Build with the `build-px4-linux` or `build-px4-macos`
skill. Fix any build errors before opening the PR.
4. PR **title:** `type(scope): description` — under 72 chars, covers the
overall change across all commits. This becomes the squash-merge commit
message.
5. PR **body:** as short as it can be while still landing the point — a
reviewer should take it in at a glance, and a long description is one
nobody reads. Sections, in order: `## Summary`, `## Problem`,
`## Solution`, a sentence or two each. Do not restate the diff (no
file-changed lists, no code snippets), do not mention CI, and do not repeat
what the title already says. If the PR closes an issue, the first line of
`## Summary` is `fixes #<N>`, then a blank line, then the summary. No
boilerplate.
6. Optional `## Testing` section after `## Solution`, only for substantial
testing: SITL scenarios, synthetic or replayed data, hardware-in-the-loop,
bench or flight tests. Building and unit tests are not testing; never
mention them. State what was run and what it showed, as tersely as the
other sections. Never report testing that did not happen: ask the user
what they actually ran.
7. Push with `-u` if needed, then `gh pr create`. Default base is `main`
unless user says otherwise.
8. Return the PR URL.
+95 -19
View File
@@ -1,26 +1,102 @@
---
name: rebase-onto-main
description: Rebase a PX4 branch onto main, handling squash-merged parent branches without replaying inherited commits.
description: Rebase a branch onto main, handling squash-merged parent branches cleanly
argument-hint: "[optional: branch name, defaults to current branch]"
allowed-tools: Bash Read Glob Grep Agent
---
# Rebase Branch onto Main
Read `.claude/skills/rebase-onto-main/SKILL.md` from the repository root and
follow its workflow with these adaptations:
Rebase the current (or specified) branch onto `main`, correctly handling the case where the branch was built on top of another branch that has since been squash-merged into `main`.
- Input is the branch in the user's request, defaulting to the current branch.
Do not interpret `$ARGUMENTS` as a shell variable.
- Use available tools; ignore claims about Claude's Bash execution environment.
Explicitly check checkout and rebase failures regardless of shell behavior.
- Inspect the working tree and worktrees first. Preserve unrelated changes and
run in the worktree that owns the branch. Do not automatically stash user work.
- If `main` is checked out in another worktree, fetch `origin main` and use
`origin/main` as the new base rather than updating that checked-out branch.
- Record the old head and the unique-commit boundary before rewriting history.
For a squash-merged parent, compare only the branch's unique commits in
`git range-diff <first-unique-commit>^..<old-head> <new-base>..<new-head>`.
Inherited commits intentionally excluded from the replay are not lost work.
Investigate any changed, missing, or added unique patch before proceeding.
- Keep a backup ref until the result has been reviewed. Ask before force-pushing
and use only `--force-with-lease`. Do not rewrite or push dependent branches
without authorization.
## Background
When a parent branch is squash-merged, its individual commits become a single new commit on `main` with a different hash. A normal `git rebase main` will try to replay the parent's original commits, causing messy conflicts. The fix is to **cherry-pick only the commits unique to this branch** onto a fresh branch from `main`.
## Steps
1. **Identify the branch.** Use the branch the user named, otherwise the current branch.
Check `git worktree list` first. A branch checked out in another worktree cannot be checked out here — `git checkout` fails with `fatal: '<branch>' is already used by worktree at ...`. Rebase it in place instead: `git -C <worktree-path> rebase main`.
When rebasing several branches in a loop, test the checkout's exit status explicitly:
```
git checkout -q "$b" || { echo "SKIP $b (worktree?)"; continue; }
```
Without that guard the loop rebases whatever is *currently* checked out, once per failed iteration, and reports success — the rebase really did work, just on the wrong branch. `set -e` is not a substitute: it is ignored in an agent's Bash tool call (it only takes effect when bash runs a script file).
2. **Fetch and update main:**
```
git fetch origin main:main
```
3. **Find the merge base** between the branch and `main`:
```
git merge-base <branch> main
```
4. **List all commits** on the branch since the merge base:
```
git log --oneline <merge-base>..<branch>
```
5. **Identify which commits are unique to this branch** vs. inherited from a parent branch. Look for:
- Squash-merged commits on `main` that correspond to a group of commits at the bottom of the branch's history (check PR titles, commit message keywords).
- The boundary commit: the first commit that belongs to *this* branch's work, not the parent's.
- If ALL commits are unique (no parent branch), just do a normal `git rebase main` and skip the rest.
6. **Create a fresh branch from `main`:**
```
git checkout -b <branch>-rebase main
```
7. **Cherry-pick only the unique commits** (oldest first):
```
git cherry-pick <first-unique-commit>^..<branch>
```
The `A^..B` range means "from the parent of A through B inclusive."
8. **Handle conflicts** if any arise during cherry-pick. Resolve and `git cherry-pick --continue`.
9. **Replace the old branch:**
```
git branch -m <branch> <branch>-old
git branch -m <branch>-rebase <branch>
```
10. **Verify** the result:
```
git log --oneline main..<branch>
```
Confirm only the expected commits are present.
Then prove no content changed, because the next step overwrites the only copy of the old head:
```
git range-diff <old-merge-base>..<old-head> main..<branch>
```
Every line must be marked `=` (identical patch). `!` means a commit's diff changed, `<` means one was dropped, `>` means one appeared. Anything but `=` is a rebase that lost or altered work — stop and look before pushing. Scripted:
```
rd=$(git range-diff --no-color <old-merge-base>..<old-head> main..<branch>)
tot=$(echo "$rd" | grep -cE '^ *[0-9]+:')
eq=$(echo "$rd" | grep -cE '^ *[0-9]+: +[0-9a-f]+ = ')
[ "$tot" = "$eq" ] && echo CLEAN || echo REVIEW
```
11. **Ask the user** before force-pushing. When approved:
```
git push origin <branch> --force-with-lease
```
Use `--force-with-lease`, never a bare `--force`. Push to the remote that holds the branch's PR head.
If this branch is the base of a stacked PR, the branch above it still points at the pre-rebase commits. Rebase it onto the new head and force-push it too:
```
git rebase --onto <branch> <old-head-of-branch> <branch-above>
```
Skipping this makes the upper PR show every commit on `main`.
12. **Clean up** the old branch:
```
git branch -D <branch>-old
```
+50 -14
View File
@@ -1,21 +1,57 @@
---
name: review-pr
description: Review a PX4 pull request for engineering merit, first-principles correctness, and architecture fit; deliver a debrief and an unpublished draft.
description: Substance-focused review of a PX4 pull request — merit, first-principles correctness, architecture fit. Produces a debrief for the user and a draft review comment.
argument-hint: "<PR number or URL>"
allowed-tools: Bash Read Glob Grep Agent
---
# PX4 Pull Request Review
Read `.claude/skills/review-pr/SKILL.md` from the repository root and follow
its workflow with these substitutions:
Goal: brief the user on a PR before they spend their own time on it, and draft a review comment they can choose to post. The review is by the assistant and is presented as such — write from its own frame of reference, not the user's, unless the user explicitly requests a different voice.
- Input is the PR number or URL in the user's request, not literal `$ARGUMENTS`.
- Use the current client's tools. Delegate independent subsystem investigations
only when subagents are available and the scope warrants them; otherwise
investigate directly.
- Write from the actual assistant's perspective, not Claude's or the user's.
In Codex, the draft's first line is
`**Codex review on behalf of @<login>**`. Use the actual client name elsewhere;
obtain the login with `gh api user --jq .login` as in the source workflow.
- Read the applicable `.github/instructions/` guidance referenced by `AGENTS.md`.
- Deliver both the debrief and fenced draft. Do not post the draft unless
explicitly requested.
Focus on substance only. Do not review commit messages, do not recommend a merge strategy, do not audit formatting (CI enforces it). Be extremely thorough — the user wants a deep understanding of the problem, not just verdicts — but scale effort with impact: roughly proportional to lines/files changed and how flight-critical the touched code is. For diffs too large to hold at once, fan out subagents per subsystem when the client has them.
## Gather
In parallel:
- `gh pr view <PR> --json number,title,body,author,baseRefName,files,reviews`
- `gh pr diff <PR>` — on HTTP 406 (huge diff) do not retry; use `gh api repos/{owner}/{repo}/pulls/<PR>/files --paginate` and fetch key patches selectively
- `gh pr checks <PR>` (exit code 8 just means checks are pending)
- existing feedback: `gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate --jq '.[] | {user: .user.login, path, body}'` (inline) and `gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate --jq '.[] | {user: .user.login, body}'` (conversation)
Read any linked issue — the claimed problem is the baseline for judging merit. For full post-change file contents without touching the working tree: `git fetch origin pull/<PR>/head`, then `git show FETCH_HEAD:<path>`.
## History (optional)
When the PR changes existing behavior rather than adding something new, check whether the author has done their homework on the area:
- Open issues and PRs touching the same code or symptom: `gh issue list --search`, `gh pr list --search`. Is this already being worked on, or duplicated?
- `git log -L` / `git log --follow -p` and `git blame` on the changed lines, then the PRs and issues those commits reference. Was the current behavior intentional, and was the reasoning sound?
- Deferred work: TODOs, issue threads, or review comments where the change was considered and deliberately postponed or rejected.
Report only what bears on the PR: a reverted decision the author does not acknowledge, conflicting in-flight work, or an unaddressed reason the code is the way it is.
## Review
Never judge a hunk from the diff alone. Read the enclosing function and file, and grep for callers and consumers — a PR is always reviewed in the context of the surrounding code.
- **Merit and need.** Is this solving a real problem or papering over one? Trace the failure mechanism; check the fix addresses the root cause at the right layer. Ask whether a simpler change (different default, existing parameter, deleting code) would achieve the same.
- **Physics and math.** If the change involves physics, estimation, control, or nontrivial math, do a first-principles analysis: re-derive the result and check the implementation against your derivation, not against the PR description. Verify units, reference frames (FRD/NED, body/earth), signs, singularities and edge cases (division by zero, gimbal lock, low airspeed), timestep/discretization dependence, and numerical robustness in the given representation (NaN propagation, cancellation, float32 precision limits).
- **Architecture and maintainability.** Does the change follow the patterns of the code around it (uORB usage, scheduling, param handling, data ownership)? Does it reimplement something an existing library provides (AlphaFilter, SlewRate, mathlib)? Does the logic live in the module that owns the data? Watch for hidden coupling — a change that silently breaks an assumption in another module; if cross-module coupling is genuinely necessary, expect a unit test that codifies the new contract and fails if it is later broken. Embedded reality: flash is scarce, no dynamic allocation in flight code, mind CPU cost.
- **Alternatives.** Identify plausible alternative implementations and judge each: better, worse, or not worth mentioning. Raise only the ones the author should genuinely consider, and say why.
- **Correctness and reliability.** Edge cases, overflow, unsigned arithmetic, initialization, bounds, races, resource exhaustion, and failure-path handling. Flag real defects, not style.
- **Compatibility.** Changes to `msg/`, params, or MAVLink: impact on QGC, uLog tooling, and third-party integrations. uORB: `timestamp` vs `timestamp_sample`, `device_id`. Every new parameter is configuration burden on users — challenge it.
- **New board** (`boards/<mfr>/<board>/`): require a logs.px4.io flight log for the vehicle type, a docs page in `docs/en/flight_controller/`, the manufacturer's own USB VID/PID, a unique board_id in `boards.json`, CI build coverage, flash fit, and no copy-pasted template leftovers or board-local forks of common drivers.
Also, briefly: the PR title must be `type(scope): description` (it becomes the commit subject on squash); note CI status and read failure logs only when plausibly related to the change; do not repeat feedback other reviewers already gave — build on it or stay silent.
## Deliver
End with two things, then stop — do not post anything.
**1. Debrief for the user.** Lead with the findings — the user wants actionable information, not a play-by-play of the diff. Give only the framing they need to judge the change: whether the claimed problem is real, scope and risk (subsystems touched, flight-critical or not), and what CI and other reviewers already said. Restate what the change actually does and why only when the PR description is missing, ambiguous, or misleading. Order findings by severity (blocker / concern / nit) with `file:line`.
**2. Draft review comment**, shown verbatim in a fenced block. First line: `**<assistant> review on behalf of @<login>**` (e.g. `Claude`, `Codex`) (login via `gh api user --jq .login`). Then terse, actionable findings only — what is wrong, why it matters, what to do, with file:line references. Frame each as an objective engineering tradeoff, not a moral judgment. Never guess: if you cannot demonstrate a flaw via a concrete code path or a first-principles derivation, stay silent. No praise or "verified OK" notes unless they change what the author should do, no meta sections, no conversational filler, nothing already raised by others.
If the user asks to post it, post the draft verbatim with `gh pr comment <PR> --body "$(cat <<'EOF' ... EOF)"`.
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/build-px4-linux
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/build-px4-macos
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/commit
-38
View File
@@ -1,38 +0,0 @@
---
name: commit
description: Create a conventional commit for PX4 changes
argument-hint: "[optional: description of changes]"
allowed-tools: Bash, Read, Glob, Grep
---
# PX4 Conventional Commit
Create a git commit in conventional-commit format: `type(scope): description`.
- **type:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`,
`build`, `ci`, `chore`, `revert`. Append `!` before `:` for breaking changes.
- **scope:** the module/driver/area affected — derive from the directory
path of the changed files (`src/modules/ekf2/` → `ekf2`,
`src/drivers/imu/invensense/icm42688p/` → `drivers/icm42688p`,
`.github/workflows/` → `ci`).
- **description:** imperative, concise, ≥5 chars.
**The user is the author. Never add `Co-Authored-By` naming an AI. End the
commit body with the disclosure trailer `Assisted-by: Claude:<model-id>`
(e.g. `Assisted-by: Claude:claude-fable-5`).**
## Steps
1. Check branch (`git branch --show-current`). If on `main`, create a feature
branch `<username>/<description>` where `<username>` comes from
`gh api user --jq .login`.
2. Run `git status` and `git diff --staged`. If nothing staged, ask what to stage.
3. Run `make format` (or `./Tools/astyle/fix_code_style.sh <file>`) on changed
C/C++ files.
4. Body (if needed): explain **why**, not what.
5. Commit with `git commit -s`. Do not pass `-S`: GPG signing is the user's
git config decision (`commit.gpgsign`), not the skill's. The `-s` sign-off
is the user's DCO certification of changes they have reviewed: never
commit with `-s` work the user has not seen.
If the user provided arguments, use them as context: $ARGUMENTS
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/pr
-42
View File
@@ -1,42 +0,0 @@
---
name: pr
description: Create a pull request with conventional commit title and description
argument-hint: "[optional: target branch or description]"
allowed-tools: Bash, Read, Glob, Grep
---
# PX4 Pull Request
**The user is the author: no `Co-Authored-By`, no "Generated with Claude"
footers. AI disclosure lives in the commit trailers (`Assisted-by:`), not in
the PR body.**
## Steps
1. Check branch. If on `main`, create a feature branch `<username>/<description>`
where `<username>` comes from `gh api user --jq .login`.
2. Gather context: `git status`, `git log --oneline main..HEAD`,
`git diff main...HEAD --stat`, check for remote tracking branch.
3. Sanity-build **one** target the change can actually affect — a board for
firmware changes, `px4_sitl` for POSIX-only or simulation changes. Skip the
build entirely when the diff cannot reach any target (submodule pointer
bumps, docs, ROMFS). Fix any build errors before opening the PR.
4. PR **title:** `type(scope): description` — under 72 chars, covers the
overall change across all commits. This becomes the squash-merge commit
message.
5. PR **body:** as short as it can be while still landing the point — a
reviewer should take it in at a glance, and a long description is one
nobody reads. Exactly three sections, in order: `## Summary`, `## Problem`,
`## Solution`, a sentence or two each. Do not restate the diff (no
file-changed lists, no code snippets), do not mention CI, and do not repeat
what the title already says. If the PR closes an issue, the first line of
`## Summary` is `fixes #<N>`, then a blank line, then the summary. No
`## Test plan` section, no boilerplate, no Claude attribution. Never state
testing that did not happen: ask the user what they actually ran, report
exactly that, and say plainly when something is untested.
6. Push with `-u` if needed, then `gh pr create`. Default base is `main`
unless user says otherwise.
7. Return the PR URL.
If the user provided arguments, use them as context: $ARGUMENTS
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/rebase-onto-main
-102
View File
@@ -1,102 +0,0 @@
---
name: rebase-onto-main
description: Rebase a branch onto main, handling squash-merged parent branches cleanly
argument-hint: "[optional: branch name, defaults to current branch]"
allowed-tools: Bash, Read, Glob, Grep, Agent
---
# Rebase Branch onto Main
Rebase the current (or specified) branch onto `main`, correctly handling the case where the branch was built on top of another branch that has since been squash-merged into `main`.
## Background
When a parent branch is squash-merged, its individual commits become a single new commit on `main` with a different hash. A normal `git rebase main` will try to replay the parent's original commits, causing messy conflicts. The fix is to **cherry-pick only the commits unique to this branch** onto a fresh branch from `main`.
## Steps
1. **Identify the branch.** Use `$ARGUMENTS` if provided, otherwise use the current branch.
Check `git worktree list` first. A branch checked out in another worktree cannot be checked out here — `git checkout` fails with `fatal: '<branch>' is already used by worktree at ...`. Rebase it in place instead: `git -C <worktree-path> rebase main`.
When rebasing several branches in a loop, test the checkout's exit status explicitly:
```
git checkout -q "$b" || { echo "SKIP $b (worktree?)"; continue; }
```
Without that guard the loop rebases whatever is *currently* checked out, once per failed iteration, and reports success — the rebase really did work, just on the wrong branch. `set -e` is not a substitute: it is ignored in a Claude Code Bash tool call (it only takes effect when bash runs a script file).
2. **Fetch and update main:**
```
git fetch origin main:main
```
3. **Find the merge base** between the branch and `main`:
```
git merge-base <branch> main
```
4. **List all commits** on the branch since the merge base:
```
git log --oneline <merge-base>..<branch>
```
5. **Identify which commits are unique to this branch** vs. inherited from a parent branch. Look for:
- Squash-merged commits on `main` that correspond to a group of commits at the bottom of the branch's history (check PR titles, commit message keywords).
- The boundary commit: the first commit that belongs to *this* branch's work, not the parent's.
- If ALL commits are unique (no parent branch), just do a normal `git rebase main` and skip the rest.
6. **Create a fresh branch from `main`:**
```
git checkout -b <branch>-rebase main
```
7. **Cherry-pick only the unique commits** (oldest first):
```
git cherry-pick <first-unique-commit>^..<branch>
```
The `A^..B` range means "from the parent of A through B inclusive."
8. **Handle conflicts** if any arise during cherry-pick. Resolve and `git cherry-pick --continue`.
9. **Replace the old branch:**
```
git branch -m <branch> <branch>-old
git branch -m <branch>-rebase <branch>
```
10. **Verify** the result:
```
git log --oneline main..<branch>
```
Confirm only the expected commits are present.
Then prove no content changed, because the next step overwrites the only copy of the old head:
```
git range-diff <old-merge-base>..<old-head> main..<branch>
```
Every line must be marked `=` (identical patch). `!` means a commit's diff changed, `<` means one was dropped, `>` means one appeared. Anything but `=` is a rebase that lost or altered work — stop and look before pushing. Scripted:
```
rd=$(git range-diff --no-color <old-merge-base>..<old-head> main..<branch>)
tot=$(echo "$rd" | grep -cE '^ *[0-9]+:')
eq=$(echo "$rd" | grep -cE '^ *[0-9]+: +[0-9a-f]+ = ')
[ "$tot" = "$eq" ] && echo CLEAN || echo REVIEW
```
11. **Ask the user** before force-pushing. When approved:
```
git push origin <branch> --force-with-lease
```
Use `--force-with-lease`, never a bare `--force`. Push to the remote that holds the branch's PR head.
If this branch is the base of a stacked PR, the branch above it still points at the pre-rebase commits. Rebase it onto the new head and force-push it too:
```
git rebase --onto <branch> <old-head-of-branch> <branch-above>
```
Skipping this makes the upper PR show every commit on `main`.
12. **Clean up** the old branch:
```
git branch -D <branch>-old
```
+1
View File
@@ -0,0 +1 @@
../../.agents/skills/review-pr
-49
View File
@@ -1,49 +0,0 @@
---
name: review-pr
description: Substance-focused review of a PX4 pull request — merit, first-principles correctness, architecture fit. Produces a debrief for the user and a draft review comment.
argument-hint: "<PR number or URL>"
allowed-tools: Bash, Read, Glob, Grep, Agent
---
# PX4 Pull Request Review
Goal: brief the user on a PR before they spend their own time on it, and draft a review comment they can choose to post. The review is by Claude and is presented as such — write from Claude's frame of reference, not the user's, unless the user explicitly requests a different voice.
Focus on substance only. Do not review commit messages, do not recommend a merge strategy, do not audit formatting (CI enforces it). Be extremely thorough — the user wants a deep understanding of the problem, not just verdicts — but scale effort with impact: roughly proportional to lines/files changed and how flight-critical the touched code is. For diffs too large to hold at once, fan out Explore agents per subsystem.
## Gather
In parallel:
- `gh pr view <PR> --json number,title,body,author,baseRefName,files,reviews`
- `gh pr diff <PR>` — on HTTP 406 (huge diff) do not retry; use `gh api repos/{owner}/{repo}/pulls/<PR>/files --paginate` and fetch key patches selectively
- `gh pr checks <PR>` (exit code 8 just means checks are pending)
- existing feedback: `gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate --jq '.[] | {user: .user.login, path, body}'` (inline) and `gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate --jq '.[] | {user: .user.login, body}'` (conversation)
Read any linked issue — the claimed problem is the baseline for judging merit. For full post-change file contents without touching the working tree: `git fetch origin pull/<PR>/head`, then `git show FETCH_HEAD:<path>`.
## Review
Never judge a hunk from the diff alone. Read the enclosing function and file, and grep for callers and consumers — a PR is always reviewed in the context of the surrounding code.
- **Merit and need.** Is this solving a real problem or papering over one? Trace the failure mechanism; check the fix addresses the root cause at the right layer. Ask whether a simpler change (different default, existing parameter, deleting code) would achieve the same.
- **Physics and math.** If the change involves physics, estimation, control, or nontrivial math, do a first-principles analysis: re-derive the result and check the implementation against your derivation, not against the PR description. Verify units, reference frames (FRD/NED, body/earth), signs, singularities and edge cases (division by zero, gimbal lock, low airspeed), timestep/discretization dependence, and numerical robustness in the given representation (NaN propagation, cancellation, float32 precision limits).
- **Architecture and maintainability.** Does the change follow the patterns of the code around it (uORB usage, scheduling, param handling, data ownership)? Does it reimplement something an existing library provides (AlphaFilter, SlewRate, mathlib)? Does the logic live in the module that owns the data? Watch for hidden coupling — a change that silently breaks an assumption in another module; if cross-module coupling is genuinely necessary, expect a unit test that codifies the new contract and fails if it is later broken. Embedded reality: flash is scarce, no dynamic allocation in flight code, mind CPU cost.
- **Alternatives.** Identify plausible alternative implementations and judge each: better, worse, or not worth mentioning. Raise only the ones the author should genuinely consider, and say why.
- **Correctness and reliability.** Edge cases, overflow, unsigned arithmetic, initialization, bounds, races, resource exhaustion, and failure-path handling. Flag real defects, not style.
- **Compatibility.** Changes to `msg/`, params, or MAVLink: impact on QGC, uLog tooling, and third-party integrations. uORB: `timestamp` vs `timestamp_sample`, `device_id`. Every new parameter is configuration burden on users — challenge it.
- **New board** (`boards/<mfr>/<board>/`): require a logs.px4.io flight log for the vehicle type, a docs page in `docs/en/flight_controller/`, the manufacturer's own USB VID/PID, a unique board_id in `boards.json`, CI build coverage, flash fit, and no copy-pasted template leftovers or board-local forks of common drivers.
Also, briefly: the PR title must be `type(scope): description` (it becomes the commit subject on squash); note CI status and read failure logs only when plausibly related to the change; do not repeat feedback other reviewers already gave — build on it or stay silent.
## Deliver
End with two things, then stop — do not post anything.
**1. Debrief for the user.** Lead with the findings — the user wants actionable information, not a play-by-play of the diff. Give only the framing they need to judge the change: whether the claimed problem is real, scope and risk (subsystems touched, flight-critical or not), and what CI and other reviewers already said. Restate what the change actually does and why only when the PR description is missing, ambiguous, or misleading. Order findings by severity (blocker / concern / nit) with `file:line`, and end with a one-or-two-sentence overall take.
**2. Draft review comment**, shown verbatim in a fenced block. First line: `**Claude review on behalf of @<login>**` (login via `gh api user --jq .login`). Then terse, actionable findings only — what is wrong, why it matters, what to do, with file:line references. Frame each as an objective engineering tradeoff, not a moral judgment. Never guess: if you cannot demonstrate a flaw via a concrete code path or a first-principles derivation, stay silent. No praise or "verified OK" notes unless they change what the author should do, no meta sections, no conversational filler, nothing already raised by others.
If the user asks to post it, post the draft verbatim with `gh pr comment <PR> --body "$(cat <<'EOF' ... EOF)"`.
PR to review: $ARGUMENTS
+2 -4
View File
@@ -117,8 +117,6 @@ _emscripten_sdk/
# virtual Python environment
.venv
# Claude Code local settings
# Claude Code local settings and worktrees
.claude/settings.local.json
# Agent-created build worktrees
/.agents/worktrees/
/.claude/worktrees/
+7 -4
View File
@@ -3,11 +3,14 @@
Safety-critical C/C++ flight control firmware for autopilots, plus SITL
simulation and Python tooling.
- **Commits:** use the `$commit` skill. Conventional commit format with
- **Commits:** use the `commit` skill. Conventional commit format with
topic-based scope: `type(scope): description`.
- **Pull requests:** use the `$pr` skill.
- **Attribution:** use the actual assistant identity, never Claude's when
running another client. No generated-by footer in PR bodies.
- **Pull requests:** use the `pr` skill.
- **Builds:** use the `build-px4-linux` or `build-px4-macos` skill for the
host OS.
- **Attribution:** disclose AI assistance only in the `Assisted-by:` commit
trailer. No `Co-Authored-By` naming an AI, no generated-by footer in PR
bodies.
- **Style:** run `make format` on changed C/C++ before committing; CI
enforces `make check_format`.
- **Scoped guidance:** before editing or reviewing, read only the
+1 -12
View File
@@ -1,12 +1 @@
# PX4-Autopilot
Safety-critical C/C++ flight control firmware for autopilots, plus SITL
simulation and Python tooling.
- **Commits:** use the `/commit` skill. Conventional commit format with
topic-based scope: `type(scope): description`.
- **Pull requests:** use the `/pr` skill.
- **No Claude attribution** — no `Co-Authored-By: Claude`, no "Generated
with Claude Code" footer.
- **Style:** run `make format` on changed C/C++ before committing; CI
enforces `make check_format`.
@AGENTS.md
+216 -8
View File
@@ -1,11 +1,219 @@
# get_mode_requirements
Before changing files in this directory, read the sibling
[CLAUDE.md](CLAUDE.md) and follow its generator-specific instructions.
That file is the shared source of truth for parser behavior, generated-content
boundaries, metadata ordering, and golden-file tests; it applies regardless of
which assistant or model is being used.
## Purpose
In particular, do not hand-edit generated sentinel blocks in `docs/en/`.
Change the generator inputs instead, and follow the documented test and
golden-file update workflow for intentional behavior changes.
`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:
```sh
python3 docs/scripts/get_mode_requirements/get_mode_requirements.py
```
Or from the `docs/` directory:
```sh
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:
```markdown
<!-- 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/`):
```sh
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:
```sh
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.
+1 -219
View File
@@ -1,219 +1 @@
# 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:
```sh
python3 docs/scripts/get_mode_requirements/get_mode_requirements.py
```
Or from the `docs/` directory:
```sh
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:
```markdown
<!-- 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/`):
```sh
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:
```sh
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.
@AGENTS.md