chore(agents): add Codex instructions and skills

Expose PX4 guidance and workflows to Codex while keeping root instructions concise and reusing tracked Claude workflows where possible.

Assisted-by: Copilot:gpt-6-astra
Signed-off-by: Ramon Roche <mrpollo@gmail.com>

.agents/README.md

@@ -0,0 +1,53 @@
+# GPT-based coding agents
+
+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.
+
+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:
+
+```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 |
+| --- | --- |
+| `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` |
+
+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).

.agents/skills/build-px4/SKILL.md

@@ -0,0 +1,95 @@
+---
+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.
+---
+
+# Build PX4 Firmware
+
+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.
+
+## Inputs
+
+- A board target, for example `px4_fmu-v6xrt_default` or
+  `cubepilot_cubeorange_default`. Ask for the target if it is missing.
+- Optional git refs or existing worktree paths. Without them, build the current
+  working tree as-is. Do not silently substitute a clean checkout.
+
+For a POSIX SITL target, use an appropriate SITL workflow instead; do not promise
+a flashable `.px4` artifact.
+
+## Prepare
+
+1. Read the build and code-review guidance referenced by `AGENTS.md`.
+2. Inspect `git status --short` and `git worktree list`. Validate the target
+   against `boards/` and the repository's build configuration.
+3. Confirm Docker is available and running. Inspect the image with
+   `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`.
+   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
+   user files.
+
+## Build
+
+Read `Tools/docker_run.sh` in the checkout being built. Use it if it handles
+the git common-directory mount, a writable HOME for the non-root user, and
+container git ownership. Otherwise run the equivalent container explicitly.
+The checked-in wrapper may not yet provide these worktree requirements.
+
+From the selected worktree root, after assigning `TARGET` to the validated board
+target, the explicit form is:
+
+```bash
+SRC_DIR="$(pwd -P)"
+CCACHE_DIR="${HOME}/.ccache"
+GIT_COMMON_DIR="$(git rev-parse --path-format=absolute --git-common-dir)"
+mkdir -p "$CCACHE_DIR"
+
+docker run --rm \
+  --workdir="$SRC_DIR" \
+  --user="$(id -u):$(id -g)" \
+  --env=HOME=/tmp \
+  --env=CCACHE_DIR="$CCACHE_DIR" \
+  --env=GIT_CONFIG_COUNT=1 \
+  --env=GIT_CONFIG_KEY_0=safe.directory \
+  --env=GIT_CONFIG_VALUE_0='*' \
+  --volume="$SRC_DIR:$SRC_DIR:rw" \
+  --volume="$GIT_COMMON_DIR:$GIT_COMMON_DIR:rw" \
+  --volume="$CCACHE_DIR:$CCACHE_DIR:rw" \
+  px4io/px4-dev:v1.17.0 \
+  make "$TARGET"
+```
+
+Run this with Bash and stop if path resolution or preparation fails. Mounting
+the worktree and git common directory at their original absolute paths preserves
+git's worktree references. The ownership exception is scoped to this container;
+do not change the user's global git configuration.
+
+Preserve the build's exit status. If capturing output through `tee` or `tail`,
+enable `set -o pipefail` in that shell. Report failures; do not treat an old
+artifact as evidence of success.
+
+## Stage and report
+
+After a successful build, require `build/<target>/<target>.px4` to exist.
+Copy it to `/tmp/px4-firmware/` with a distinct name such as
+`<target>_<ref-label>_<short-sha>_<timestamp>.px4`. Do not overwrite an existing
+artifact. Label dirty-tree builds explicitly: their source is not represented
+by the commit alone.
+
+Report the source ref, commit, dirty state, target, absolute artifact path, and
+size. Staging is not flashing; never invoke an uploader without a separate user
+request. Artifacts under `/tmp` are temporary and may disappear on reboot.
+Remove only clean temporary worktrees created for this invocation, using
+`git worktree remove`, or report retained worktrees if cleanup is unsafe.

.agents/skills/commit/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: commit
+description: Create a PX4 conventional commit from reviewed changes with a topic-based scope and assistant disclosure.
+---
+
+# PX4 Conventional Commit
+
+Read `.claude/skills/commit/SKILL.md` from the repository root and follow its
+workflow with these substitutions:
+
+- 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.

.agents/skills/pr/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pr
+description: Create a PX4 pull request with a conventional title and concise Summary, Problem, and Solution sections.
+---
+
+# PX4 Pull Request
+
+Read `.claude/skills/pr/SKILL.md` from the repository root and follow its
+workflow with these substitutions:
+
+- 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.

.agents/skills/rebase-onto-main/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: rebase-onto-main
+description: Rebase a PX4 branch onto main, handling squash-merged parent branches without replaying inherited commits.
+---
+
+# Rebase Branch onto Main
+
+Read `.claude/skills/rebase-onto-main/SKILL.md` from the repository root and
+follow its workflow with these adaptations:
+
+- 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.

.agents/skills/review-pr/SKILL.md

@@ -0,0 +1,21 @@
+---
+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.
+---
+
+# PX4 Pull Request Review
+
+Read `.claude/skills/review-pr/SKILL.md` from the repository root and follow
+its workflow with these substitutions:
+
+- 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.

.gitignore

@@ -118,3 +118,6 @@ _emscripten_sdk/
 
 # Claude Code local settings
 .claude/settings.local.json
+
+# Agent-created build worktrees
+/.agents/worktrees/

AGENTS.md

@@ -0,0 +1,15 @@
+# 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.
+- **Attribution:** use the actual assistant identity, never Claude's when
+  running another client. 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
+  `.github/instructions/*.instructions.md` files whose `applyTo` patterns
+  match the affected paths, plus any nested `AGENTS.md` along those paths.

docs/scripts/get_mode_requirements/AGENTS.md

@@ -0,0 +1,11 @@
+# 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.
+
+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.