Imported from usbharu/HomeCockpit (AGENTS.md). Install upstream with npx skills add usbharu/HomeCockpit. Copyright stays with the author.

HomeCockpit Agent Guide

このファイルはリポジトリ全体の案内です。詳細をここへ複製せず、原則として実装・設定・専用ドキュメントを正とします。サブディレクトリに AGENTS.md がある場合は、そちらも併せて参照してください。

最初に確認するもの

作業内容が上記スキルの対象なら、該当する SKILL.md を先に読んでください。デバッグや原因調査では、まず docs/debugging-scope.md で必要な component と最初の観測点を決めてください。

対象	正本・入口
IMCP core / adapter	`imcp/Cargo.toml`、`imcp/src/`、`imcp/tests/`
Firmware全体	`firmware/AGENTS.md`
HCP application protocol	`firmware/hcp/README.md`、`firmware/hcp/src/lib.rs`
firmware 共通処理	`firmware/homecockpit_firmware_base/README.md`
Upper Panel DDI firmware	`firmware/upper_panel_ddi/README.md`、`firmware/upper_panel_ddi/.cargo/config.toml`
Pico 2 bring-up	`firmware/pico2_blinky/README.md`
DCS-BIOS library	`dcs-bios-rs/src/lib.rs`、`dcs-bios-rs/src/import.rs`
IMCP CLI	`utils/imcp-cli/src/main.rs`
Manager	`manager/AGENTS.md`
KiCad hardware	現行 Upper Panel DDI 基板 `upper_panel_ddi/pcb/button_panel/`、機械部品 `upper_panel_ddi/mechanical/`、共有ライブラリ `HomeCockpit.kicad_sym` / `Library.pretty/`

ルートは Cargo workspace ではありません。各 Cargo project/workspace のディレクトリでコマンドを実行してください。対象と CI コマンドの対応は CI workflow が正です。
firmware/lib/embassy と firmware/lib/trouble は git submodule です。明示的な依頼なしに中身や gitlink を更新しないでください。
IMCP は framing/address/ACK・再送を、HCP は IMCP payload 上の application message を担当します。HCP は 1 packet が IMCP の最大 payload 128 bytes に収まる前提です。
manager/src-tauri は dcs-bios-rs、imcp、firmware/hcp を path dependency として利用します。公開型やプロトコルの変更時は Manager への影響も確認してください。
target/、manager/.next/、manager/out/、KiCad の production/ やバックアップは生成物です。実装として編集・コミットしないでください。
firmware/lib/cyw43-firmware/*.bin はライセンス付きの upstream firmware です。通常の生成物として変更しないでください。
ハードウェアを使っていない場合、ビルド成功を実機検証済みとして報告しないでください。実機確認時は board、probe、transport、観測結果を記録してください。

既存の Rust lint は各 Cargo.toml を正とし、rustfmt と Clippy に従ってください。特に protocol/shared firmware の通常経路では unwrap() / panic! を避けます。
wire value、永続化 JSON、Tauri command/event、device/control ID の変更は互換性変更として扱い、producer と consumer と regression test を同時に更新してください。
dependency 変更以外で lockfile を更新しないでください。lockfile は手編集しません。
protocol、セットアップ、hardware procedure を変えた場合は、コードだけでなく上記の正本も更新してください。
secrets、token、device credential、署名情報、個人環境の絶対パスや固定 probe ID をコミットしないでください。
完了前に変更対象に対応する CI の format / test / Clippy / build を実行してください。環境や実機の都合で実行できない検証は、未実施理由を明記してください。

ユーザーが指定した言語で本文を書く。日本語指定時は、概要・変更内容・検証結果を日本語で記載する。
gh pr createやgh pr editの--body "...\n..."は使用しない。ダブルクォート内の\nは改行にならず、文字どおり保存される。
本文は実際の改行を含むUTF-8ファイルを作成して--body-fileで渡す。インライン指定が必要な場合は、実改行を含む引数またはシェルのANSI-Cクォート（$'...\n...'）を使用する。
作成・更新後はgh pr view <番号> --json body --jq .bodyで本文を取得して確認する。--json bodyだけではJSON表現として改行が\nにエスケープされるため、--jq .bodyを使って実際の改行、見出し、空行を検証する。
本文に\nが表示された場合はGitHubの表示不具合と判断せず、gh pr edit <番号> --body-file <本文ファイル>で実改行を含む本文に置き換え、再確認する。
既存履歴に合わせて Conventional Commits と適切な scope（例: fix(imcp):、feat(manager):、chore(ci):）を使います。
PR には変更理由、互換性・hardware への影響、実行した検証を記載します。UI は screenshot、基板は ERC/DRC、firmware は可能なら実機結果を添えてください。