From 64d54c20b34d4280479b58b662d01c4ce35edeac Mon Sep 17 00:00:00 2001 From: Chao Liu Date: Wed, 15 Jul 2026 10:03:26 +0800 Subject: [PATCH 1/4] skills: add Zephyr debug skill Helps agents reproduce and isolate Zephyr build, boot, board, and runtime failures. Signed-off-by: Chao Liu --- README.md | 6 + skills/zephyr/README.md | 53 +++++++ skills/zephyr/install.sh | 206 ++++++++++++++++++++++++++++ skills/zephyr/zephyr-debug/SKILL.md | 108 +++++++++++++++ 4 files changed, 373 insertions(+) create mode 100644 skills/zephyr/README.md create mode 100755 skills/zephyr/install.sh create mode 100644 skills/zephyr/zephyr-debug/SKILL.md diff --git a/README.md b/README.md index dbd102d..f95adbb 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,12 @@ cp -R agent-skills/ ~/.codex/skills/ Replace `` with a skill directory name. For other agents, copy it to that agent's Skills directory. +## Skills + +| Skill category | Description | +| --- | --- | +| [Zephyr agent skills](skills/zephyr/README.md) | Reusable skills for Zephyr development, debugging, exploration, patch review, and safety evidence. | + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=processmission/agent-skills&type=Date)](https://www.star-history.com/#processmission/agent-skills&Date) diff --git a/skills/zephyr/README.md b/skills/zephyr/README.md new file mode 100644 index 0000000..94cca98 --- /dev/null +++ b/skills/zephyr/README.md @@ -0,0 +1,53 @@ +# Zephyr Agent Skills + +Agent skills for [Zephyr Project](https://www.zephyrproject.org/) development, +debugging, exploration, patch review, and safety evidence work. + +Source repository: + +## Install + +From the root of the Zephyr repository, run: + +```sh +curl -fsSL https://raw.githubusercontent.com/processmission/agent-skills/main/skills/zephyr/install.sh | bash +``` + +By default, the installer adds every skill in the `skills/zephyr/` catalog to +the current project for Codex and Claude Code. It also adds `.agents/`, +`.claude/skills/`, `.zephyr-skills/`, and `skills-lock.json` to the +repository's local Git exclude file, so installation and agent task artifacts +do not dirty the worktree. It does not modify the repository's `.gitignore`. + +To install from a local checkout, or to select an individual skill: + +```sh +./skills/zephyr/install.sh --target /path/to/zephyr +./skills/zephyr/install.sh --target /path/to/zephyr --skill zephyr-debug +``` + +## Repository workflow + +Each Zephyr skill is self-contained, can be installed independently, and does +not require another Zephyr skill. Every skill includes the same compact audit +workflow. For non-trivial tasks that write to the workspace, agent plans, audit +records, command journals, decisive logs, and other temporary evidence go under +`.zephyr-skills//`. Put generated intermediate debugging documents, +debug scripts, and Bash or Python scaffolding and harness scripts in +`.zephyr-skills//scripts/`, never in a build directory. Put +non-Zephyr third-party source or libraries acquired solely for the agent's task, +and temporary binaries produced by agent-only probes or tools, in +`.zephyr-skills//output/`. Do not copy normal Zephyr build artifacts +there. Keep Zephyr-native build trees, binaries, and routine test outputs in a +path chosen by the user or the relevant Zephyr tool's default. In a Git +worktree, add `/.zephyr-skills/` to the repository-local exclude file returned +by `git rev-parse --git-path info/exclude` before writing audit artifacts, and +verify that `git status --short` contains no `.zephyr-skills/` paths. + +## Skills + +### `zephyr-debug` + +Reproduce and isolate Zephyr build, toolchain, QEMU, boot, board, or runtime +failures. Use targeted Zephyr logging, QEMU GDB stubs, or OpenOCD and J-Link +remote debugging according to the target and available tools. diff --git a/skills/zephyr/install.sh b/skills/zephyr/install.sh new file mode 100755 index 0000000..776698c --- /dev/null +++ b/skills/zephyr/install.sh @@ -0,0 +1,206 @@ +#!/usr/bin/env bash + +set -euo pipefail + +readonly DEFAULT_SKILL_SOURCE="https://github.com/processmission/agent-skills/tree/main/skills/zephyr" +readonly REQUIRED_EXCLUDES=( + ".agents/" + ".claude/skills/" + ".zephyr-skills/" + "skills-lock.json" +) + +usage() { + cat <<'EOF' +Install the Zephyr agent skills into a Git repository. + +Usage: + install.sh [install] [--target DIR] [skills options...] + +Options: + --target DIR Install into DIR instead of the current directory. + -s, --skill NAME Install one skill instead of every Zephyr skill. + -a, --agent NAME... Override the default agents (codex and claude-code). + -y, --yes Skip confirmation prompts. + -h, --help Show this help. + +Environment: + ZEPHYR_SKILLS_SOURCE Override the skills source passed to `npx skills add`. + +By default, the installer installs every skill in the Zephyr catalog for Codex +and Claude Code. It also adds .agents/, .claude/skills/, .zephyr-skills/, and +skills-lock.json to the repository's local Git exclude file. +EOF +} + +die() { + printf 'zephyr-skills: %s\n' "$*" >&2 + exit 1 +} + +require_command() { + command -v "$1" >/dev/null 2>&1 || + die "required command not found: $1" +} + +resolve_skill_source() { + if [[ -n "${ZEPHYR_SKILLS_SOURCE:-}" ]]; then + printf '%s\n' "$ZEPHYR_SKILLS_SOURCE" + return + fi + + local script_path="" + local script_dir="" + + if [[ -n "${BASH_SOURCE[0]:-}" && -f "${BASH_SOURCE[0]}" ]]; then + script_path="${BASH_SOURCE[0]}" + script_dir="$(cd "$(dirname "$script_path")" && pwd)" + fi + + if [[ -n "$script_dir" && + -f "$script_dir/README.md" && + -f "$script_dir/zephyr-debug/SKILL.md" ]]; then + printf '%s\n' "$script_dir" + return + fi + + printf '%s\n' "$DEFAULT_SKILL_SOURCE" +} + +resolve_target_root() { + local requested_target="$1" + local target_dir + local git_root + + target_dir="$(cd "$requested_target" 2>/dev/null && pwd -P)" || + die "target directory does not exist: $requested_target" + git_root="$(git -C "$target_dir" rev-parse --show-toplevel 2>/dev/null)" || + die "target directory is not inside a Git repository: $target_dir" + + [[ "$target_dir" == "$git_root" ]] || + die "run from the repository root or pass --target $git_root" + + printf '%s\n' "$git_root" +} + +add_local_exclude() { + local target_root="$1" + local entry="$2" + local exclude_file + local bare_entry + local escaped_entry + local probe_path + + exclude_file="$(git -C "$target_root" rev-parse --git-path info/exclude)" + if [[ "$exclude_file" != /* ]]; then + exclude_file="$target_root/$exclude_file" + fi + + mkdir -p "$(dirname "$exclude_file")" + touch "$exclude_file" + + bare_entry="${entry%/}" + escaped_entry="$(printf '%s' "$bare_entry" | sed 's/[][\.^$*+?{}|()]/\\&/g')" + + if ! grep -Eq "^/?${escaped_entry}/?$" "$exclude_file"; then + printf '/%s\n' "$entry" >>"$exclude_file" + fi + + if [[ "$entry" == */ ]]; then + probe_path="${entry}.zephyr-skills-install-probe" + else + probe_path="$entry" + fi + + git -C "$target_root" check-ignore --no-index -q "$probe_path" || + die "failed to configure local Git exclude for $entry" +} + +main() { + local target_dir="." + local skill_source + local target_root + local saw_skill=0 + local saw_agent=0 + local saw_yes=0 + local arg + local -a forwarded_args=() + + if [[ "${1:-}" == "install" ]]; then + shift + fi + + while [[ "$#" -gt 0 ]]; do + arg="$1" + case "$arg" in + --target) + [[ "$#" -ge 2 ]] || die "--target requires a directory" + target_dir="$2" + shift 2 + ;; + -s|--skill) + saw_skill=1 + forwarded_args+=("$arg") + shift + ;; + -a|--agent) + saw_agent=1 + forwarded_args+=("$arg") + shift + ;; + -y|--yes) + saw_yes=1 + forwarded_args+=("$arg") + shift + ;; + -h|--help) + usage + exit 0 + ;; + -g|--global) + die "global installation is not supported; run from a project root" + ;; + -l|--list|--all) + die "$arg is not an install option for this script" + ;; + *) + forwarded_args+=("$arg") + shift + ;; + esac + done + + require_command git + require_command grep + require_command npx + require_command sed + + skill_source="$(resolve_skill_source)" + target_root="$(resolve_target_root "$target_dir")" + + if [[ "$saw_skill" -eq 0 ]]; then + forwarded_args+=(--skill '*') + fi + if [[ "$saw_agent" -eq 0 ]]; then + forwarded_args+=(--agent codex claude-code) + fi + if [[ "$saw_yes" -eq 0 ]]; then + forwarded_args+=(-y) + fi + + printf 'Installing Zephyr agent skills into %s\n' "$target_root" + ( + cd "$target_root" + npx --yes skills add "$skill_source" "${forwarded_args[@]}" + ) + + for arg in "${REQUIRED_EXCLUDES[@]}"; do + add_local_exclude "$target_root" "$arg" + done + + printf 'Installed Zephyr agent skills.\n' + printf 'Configured repository-local Git excludes in %s.\n' \ + "$(git -C "$target_root" rev-parse --git-path info/exclude)" +} + +main "$@" diff --git a/skills/zephyr/zephyr-debug/SKILL.md b/skills/zephyr/zephyr-debug/SKILL.md new file mode 100644 index 0000000..3aeed17 --- /dev/null +++ b/skills/zephyr/zephyr-debug/SKILL.md @@ -0,0 +1,108 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission +# SPDX-License-Identifier: MIT +name: zephyr-debug +description: >- + Use when reproducing or isolating the root cause of a Zephyr build, + toolchain, QEMU, boot, board, or runtime failure. +--- + +# Zephyr Debug + +## Audit workflow + +For every non-trivial task that writes to the workspace, choose a stable task +slug and keep agent-only records under: + +```text +.zephyr-skills// +├── audit.md # Baseline, decisions, evidence, verification, and gaps +├── commands.md # Redacted commands, working directories, and results +├── scripts/ # Intermediate debug documents, scripts, and harnesses +├── output/ # Non-Zephyr dependencies and temporary binaries +└── logs/ # Decisive build, test, runtime, or diagnostic logs +``` + +Put every generated intermediate debugging document, debug script, and +scaffolding or harness script, including Bash and Python scripts, under +`scripts/`, never in a build directory. Put non-Zephyr third-party source or +libraries acquired solely for the agent's task, and temporary binaries produced +by agent-only probes or tools, under `output/`. Do not copy normal Zephyr build +artifacts there. Keep other agent plans and temporary evidence in the same task +directory. In a Git worktree, add +`/.zephyr-skills/` to the repository-local exclude file returned by +`git rev-parse --git-path info/exclude` before writing audit artifacts. Preserve +existing entries, avoid duplicates, and verify before handoff that +`git status --short` contains no `.zephyr-skills/` paths. Keep Zephyr-native +build trees, binaries, and test outputs separate: honor a user-specified path, +otherwise use defaults such as configured `build.dir-fmt`, `build/`, or +`twister-out/`. Record the effective paths, do not stage `.zephyr-skills/` +unless requested, and report the task directory and unresolved gaps at handoff. + +## Diagnose + +1. Capture expected and observed behavior, the narrowest reproducer, and the + first decisive log. +2. Exclude wrong revisions, boards, configuration, stale output, and generated + artifact or toolchain mismatches before changing source. +3. Locate the first broken invariant across Kconfig, CMake, devicetree, + generated files, runner commands, boot flow, and runtime state. +4. Test each hypothesis with the smallest reversible probe and distinguish + observations from inferences. +5. For diagnosis-only requests, stop at the supported cause and remaining + uncertainty. Implement a fix and regression gate only when requested. + +## Choose a debugging path + +- Use Zephyr logging and targeted instrumentation when the failure remains + observable without stopping the system. +- Use a QEMU GDB stub for reproducible emulated failures, early boot, exception + state, memory inspection, breakpoints, and instruction-level stepping. +- Use the board's configured debug runner with OpenOCD or J-Link for hardware + failures. Select the runner from the board, probe, and user environment; do + not assume that one backend is universally available. +- Combine logs with GDB when console history or timing explains state that a + stopped target cannot. + +## Run a remote GDB session + +1. Preserve the exact ELF and build configuration that reproduce the failure. + Use the matching toolchain GDB and keep symbols in the Zephyr build tree. +2. Start the remote endpoint with the configured Zephyr runner: a QEMU GDB + stub for emulation, or a debug server backed by OpenOCD or J-Link for + hardware. Prefer runner-generated arguments over guessed probe, transport, + reset, or device settings. +3. If installed, use Tmux for concurrent panes; otherwise use Zellij, then + separate terminals. Keep the debug server or QEMU in one pane, GDB in a + second, and optional console or log monitoring in a third. +4. Generate a task-specific GDB command file under + `.zephyr-skills//scripts/`, including the symbol file, remote + endpoint, breakpoints or watchpoints, thread inspection, and + evidence-producing commands. Avoid changing global GDB configuration. +5. Connect with `target remote` or `target extended-remote` as required by the + server. Capture the server command, GDB command file, decisive backtraces, + register or memory state, and target logs in the audit directory. +6. For a live hardware target, prefer attach semantics when flashing or reset + is not requested. Record any operation that changes target state. + +## Use Zephyr logging and instrumentation + +- Enable the Zephyr logging subsystem and the narrowest useful module or + subsystem log level through task-specific configuration or overlays. +- Add `LOG_DBG`, `LOG_INF`, `LOG_WRN`, `LOG_ERR`, or hexdump probes at state + transitions, error paths, ownership changes, and relevant interrupt or + scheduling boundaries. +- Include stable identifiers and state in messages, but never log secrets or + unbounded data. Keep probes minimal and easy to remove or gate. +- Account for timing changes from added logging, synchronous output, transport + buffering, and log overflow. Recheck the failure with reduced instrumentation + before treating the result as causal. +- Save decisive console output under `.zephyr-skills//logs/` and + state which logging configuration and probes produced it. + +## Guardrails + +- Do not hide a failure by weakening assertions or tests. +- Stop only QEMU processes started for the task; never kill broad process + groups. +- Stop only debug servers and multiplexer sessions started for the task. From 4da5dd792b8e451256237ac1606cff00b625ea2e Mon Sep 17 00:00:00 2001 From: Chao Liu Date: Wed, 15 Jul 2026 10:03:46 +0800 Subject: [PATCH 2/4] skills: add Zephyr exploration skill Helps agents investigate Zephyr source, history, and constraints before making changes. Signed-off-by: Chao Liu --- skills/zephyr/README.md | 6 +++ skills/zephyr/zephyr-explore/SKILL.md | 61 +++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 skills/zephyr/zephyr-explore/SKILL.md diff --git a/skills/zephyr/README.md b/skills/zephyr/README.md index 94cca98..070dfae 100644 --- a/skills/zephyr/README.md +++ b/skills/zephyr/README.md @@ -51,3 +51,9 @@ verify that `git status --short` contains no `.zephyr-skills/` paths. Reproduce and isolate Zephyr build, toolchain, QEMU, boot, board, or runtime failures. Use targeted Zephyr logging, QEMU GDB stubs, or OpenOCD and J-Link remote debugging according to the target and available tools. + +### `zephyr-explore` + +Investigate Zephyr source, branch history, external precedent, and design +constraints before making changes. Use it to clarify current behavior, +maintainer boundaries, and compatibility requirements. diff --git a/skills/zephyr/zephyr-explore/SKILL.md b/skills/zephyr/zephyr-explore/SKILL.md new file mode 100644 index 0000000..ed91b29 --- /dev/null +++ b/skills/zephyr/zephyr-explore/SKILL.md @@ -0,0 +1,61 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission +# SPDX-License-Identifier: MIT +name: zephyr-explore +description: >- + Use when Zephyr source, branch history, external precedent, or design + constraints must be investigated before a decision can be made. +--- + +# Zephyr Explore + +## Audit workflow + +For every non-trivial task that writes to the workspace, choose a stable task +slug and keep agent-only records under: + +```text +.zephyr-skills// +├── audit.md # Baseline, decisions, evidence, verification, and gaps +├── commands.md # Redacted commands, working directories, and results +├── scripts/ # Intermediate debug documents, scripts, and harnesses +├── output/ # Non-Zephyr dependencies and temporary binaries +└── logs/ # Decisive build, test, runtime, or diagnostic logs +``` + +Put every generated intermediate debugging document, debug script, and +scaffolding or harness script, including Bash and Python scripts, under +`scripts/`, never in a build directory. Put non-Zephyr third-party source or +libraries acquired solely for the agent's task, and temporary binaries produced +by agent-only probes or tools, under `output/`. Do not copy normal Zephyr build +artifacts there. Keep other agent plans and temporary evidence in the same task +directory. In a Git worktree, add +`/.zephyr-skills/` to the repository-local exclude file returned by +`git rev-parse --git-path info/exclude` before writing audit artifacts. Preserve +existing entries, avoid duplicates, and verify before handoff that +`git status --short` contains no `.zephyr-skills/` paths. Keep Zephyr-native +build trees, binaries, and test outputs separate: honor a user-specified path, +otherwise use defaults such as configured `build.dir-fmt`, `build/`, or +`twister-out/`. Record the effective paths, do not stage `.zephyr-skills/` +unless requested, and report the task directory and unresolved gaps at handoff. + +## Investigate + +1. Bound the question to paths, symbols, configuration, and behavior. +2. Search current source, tests, documentation, and `MAINTAINERS.yml` before + using history or external material. +3. For branch comparisons, use the user-specified target. Otherwise resolve the + configured upstream and use `git merge-base HEAD `; report a + missing target or upstream instead of guessing. +4. Use local history when current source does not explain intent or a + compatibility constraint. +5. Consult primary external sources only when local evidence is insufficient. +6. Stop when the evidence supports the next design, review, or verification + decision. + +## Report + +- Separate implemented, verified, documented, inferred, and unknown behavior. +- Cite decisive paths, symbols, commits, or external revisions. +- Treat external code as precedent unless import is explicitly in scope and + license-compatible. From 26f28b3ac6ca9c52766cdddb1a9809a8609ef3c9 Mon Sep 17 00:00:00 2001 From: Chao Liu Date: Wed, 15 Jul 2026 10:03:54 +0800 Subject: [PATCH 3/4] skills: add Zephyr patch review skill Guides agents in reviewing Zephyr patches for correctness, coverage, ownership, and merge readiness. Signed-off-by: Chao Liu --- skills/zephyr/README.md | 6 ++ skills/zephyr/zephyr-patch-review/SKILL.md | 71 ++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 skills/zephyr/zephyr-patch-review/SKILL.md diff --git a/skills/zephyr/README.md b/skills/zephyr/README.md index 070dfae..1d13656 100644 --- a/skills/zephyr/README.md +++ b/skills/zephyr/README.md @@ -57,3 +57,9 @@ remote debugging according to the target and available tools. Investigate Zephyr source, branch history, external precedent, and design constraints before making changes. Use it to clarify current behavior, maintainer boundaries, and compatibility requirements. + +### `zephyr-patch-review` + +Review Zephyr diffs or patch stacks for correctness, integration impact, test +coverage, reviewer boundaries, and merge readiness. Report only actionable, +source-backed findings. diff --git a/skills/zephyr/zephyr-patch-review/SKILL.md b/skills/zephyr/zephyr-patch-review/SKILL.md new file mode 100644 index 0000000..38c9a6e --- /dev/null +++ b/skills/zephyr/zephyr-patch-review/SKILL.md @@ -0,0 +1,71 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission +# SPDX-License-Identifier: MIT +name: zephyr-patch-review +description: >- + Use when reviewing Zephyr diffs or patch stacks for correctness, + integration, coverage, reviewer boundaries, or merge readiness. +--- + +# Zephyr Patch Review + +## Audit workflow + +For every non-trivial task that writes to the workspace, choose a stable task +slug and keep agent-only records under: + +```text +.zephyr-skills// +├── audit.md # Baseline, decisions, evidence, verification, and gaps +├── commands.md # Redacted commands, working directories, and results +├── scripts/ # Intermediate debug documents, scripts, and harnesses +├── output/ # Non-Zephyr dependencies and temporary binaries +└── logs/ # Decisive build, test, runtime, or diagnostic logs +``` + +Put every generated intermediate debugging document, debug script, and +scaffolding or harness script, including Bash and Python scripts, under +`scripts/`, never in a build directory. Put non-Zephyr third-party source or +libraries acquired solely for the agent's task, and temporary binaries produced +by agent-only probes or tools, under `output/`. Do not copy normal Zephyr build +artifacts there. Keep other agent plans and temporary evidence in the same task +directory. In a Git worktree, add +`/.zephyr-skills/` to the repository-local exclude file returned by +`git rev-parse --git-path info/exclude` before writing audit artifacts. Preserve +existing entries, avoid duplicates, and verify before handoff that +`git status --short` contains no `.zephyr-skills/` paths. Keep Zephyr-native +build trees, binaries, and test outputs separate: honor a user-specified path, +otherwise use defaults such as configured `build.dir-fmt`, `build/`, or +`twister-out/`. Record the effective paths, do not stage `.zephyr-skills/` +unless requested, and report the task directory and unresolved gaps at handoff. + +## Review + +1. Bound the review to an explicit base and intended behavior; separate + unrelated changes before judging the patch. +2. Inspect correctness and semantic integration, including ownership, lifetime, + locking, error paths, generated artifacts, and 32/64-bit assumptions. +3. Check the affected Kconfig, CMake, devicetree, architecture, board, SoC, + toolchain, documentation, and API-lifecycle boundaries. +4. Verify that targeted tests and logs support each behavior claim and state the + remaining coverage gaps. +5. Check patch order, reviewer-sized separation, bisectability, and applicable + SPDX and license conventions for new files. + +## Ownership and precedent + +- Use `MAINTAINERS.yml` for affected areas, reviewers, labels, and tests; + `CODEOWNERS` is not authoritative in this tree. +- Consult local history for unfamiliar APIs, regressions, or subsystem boundary + changes. Prefer `git log --follow`, `git log -S`, `git blame`, and `git show`. +- Query the current Gerrit change and patch-set state, or an upstream pull + request when explicitly in scope, only for merge readiness. Read current + submit, approval, and blocker policy instead of hard-coding it. +- Treat unavailable history as a gap, not evidence of a defect. + +## Findings + +- Report only actionable, source-backed findings, with file and line references + when available. +- Explain the failure mode, impact, and any missing or inadequate verification. +- If there are no findings, say so and list residual verification gaps. From 823d597a022bce09a6c43a8338273694c919d17b Mon Sep 17 00:00:00 2001 From: Chao Liu Date: Wed, 15 Jul 2026 10:04:05 +0800 Subject: [PATCH 4/4] skills: add Zephyr safety evidence skill Guides agents in planning and reviewing Zephyr safety evidence, traceability, and certification gaps. Signed-off-by: Chao Liu --- skills/zephyr/README.md | 7 ++ skills/zephyr/zephyr-safety-evidence/SKILL.md | 62 ++++++++++++++++++ .../references/safety-guardrails.md | 64 +++++++++++++++++++ 3 files changed, 133 insertions(+) create mode 100644 skills/zephyr/zephyr-safety-evidence/SKILL.md create mode 100644 skills/zephyr/zephyr-safety-evidence/references/safety-guardrails.md diff --git a/skills/zephyr/README.md b/skills/zephyr/README.md index 1d13656..3e7c89b 100644 --- a/skills/zephyr/README.md +++ b/skills/zephyr/README.md @@ -63,3 +63,10 @@ maintainer boundaries, and compatibility requirements. Review Zephyr diffs or patch stacks for correctness, integration impact, test coverage, reviewer boundaries, and merge readiness. Report only actionable, source-backed findings. + +### `zephyr-safety-evidence` + +Plan or review Zephyr safety evidence, requirements traceability, and +certification gaps for ASIL, ISO 26262, IEC 61508, SIL, MC/DC, HARA, +FMEA/FMEDA, and tool qualification work. It never presents draft or partial +evidence as completed certification. diff --git a/skills/zephyr/zephyr-safety-evidence/SKILL.md b/skills/zephyr/zephyr-safety-evidence/SKILL.md new file mode 100644 index 0000000..f100978 --- /dev/null +++ b/skills/zephyr/zephyr-safety-evidence/SKILL.md @@ -0,0 +1,62 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission +# SPDX-License-Identifier: MIT +name: zephyr-safety-evidence +description: >- + Use when planning or reviewing Zephyr safety evidence, safety requirements + traceability, certification gaps, or claims involving ASIL, ISO 26262, + IEC 61508, SIL, MC/DC, HARA, FMEA/FMEDA, tool qualification, or safety + cases. +--- + +# Zephyr Safety Evidence + +## Audit workflow + +For every non-trivial task that writes to the workspace, choose a stable task +slug and keep agent-only records under: + +```text +.zephyr-skills// +├── audit.md # Baseline, decisions, evidence, verification, and gaps +├── commands.md # Redacted commands, working directories, and results +├── scripts/ # Intermediate debug documents, scripts, and harnesses +├── output/ # Non-Zephyr dependencies and temporary binaries +└── logs/ # Decisive build, test, runtime, or diagnostic logs +``` + +Put every generated intermediate debugging document, debug script, and +scaffolding or harness script, including Bash and Python scripts, under +`scripts/`, never in a build directory. Put non-Zephyr third-party source or +libraries acquired solely for the agent's task, and temporary binaries produced +by agent-only probes or tools, under `output/`. Do not copy normal Zephyr build +artifacts there. Keep other agent plans and temporary evidence in the same task +directory. In a Git worktree, add +`/.zephyr-skills/` to the repository-local exclude file returned by +`git rev-parse --git-path info/exclude` before writing audit artifacts. Preserve +existing entries, avoid duplicates, and verify before handoff that +`git status --short` contains no `.zephyr-skills/` paths. Keep Zephyr-native +build trees, binaries, and test outputs separate: honor a user-specified path, +otherwise use defaults such as configured `build.dir-fmt`, `build/`, or +`twister-out/`. Record the effective paths, do not stage `.zephyr-skills/` +unless requested, and report the task directory and unresolved gaps at handoff. + +## Evidence workflow + +1. Read the [safety guardrails](references/safety-guardrails.md) in full before + producing safety-facing output. +2. Bound the claim to a safety scope layer, owner, source baseline, and evidence + boundary. +3. Create only the artifacts the task needs: traceability, evidence, scope, or + assumptions. +4. For implementation claims, link requirements to code or configuration and + verification evidence. For product, process, or assessment claims, link the + applicable requirement, process, or assessment evidence and mark code or + test fields as not applicable or as gaps. +5. Separate facts, assumptions, human judgments, and gaps, and state what the + evidence does not prove. +6. Leave certification, risk acceptance, and scope-closure decisions to the + responsible humans and assessors. + +Never treat draft or partial evidence as proof of product ASIL compliance, +IEC 61508 SIL/SC compliance, or completed certification. diff --git a/skills/zephyr/zephyr-safety-evidence/references/safety-guardrails.md b/skills/zephyr/zephyr-safety-evidence/references/safety-guardrails.md new file mode 100644 index 0000000..e930e81 --- /dev/null +++ b/skills/zephyr/zephyr-safety-evidence/references/safety-guardrails.md @@ -0,0 +1,64 @@ + + +# Zephyr Safety Guardrails + +Use this reference only when requirements or traceability are explicitly in a +safety, certification, ASIL, SIL, or safety-case context. + +## Claim boundary + +- Describe only what cited artifacts demonstrate for the stated baseline. +- Zephyr's public safety overview targets IEC 61508 SIL 3 / SC 3 for a limited + source scope that remains to be defined. Treat source areas as candidate + evidence until an approved scope, revision, and owner are cited. +- Project evidence is not product certification evidence. Platform, hardware, + toolchain, integration, application, and assessor evidence remain with the + responsible integrator and organizations. +- Tie IEC 61508 SIL statements to the applicable safety function and scope; do + not assign SIL to arbitrary code from component evidence alone. +- Never infer certification, a safety integrity level, or readiness from draft, + partial, or public-only evidence. + +## Evidence layers + +Keep these boundaries explicit: + +1. Zephyr project evidence for an approved source scope and baseline. +2. Platform evidence for the BSP, drivers, middleware, hardware, and toolchain. +3. Product or vehicle evidence for the item, hazards, safety concepts, + integration, validation, and safety case. + +Do not use evidence from one layer to close a claim owned by another. + +## Lifecycle routing + +Select the applicable standard and route before defining gates. Do not apply a +single lifecycle to every safety task. + +- For Zephyr's IEC 61508 effort, confirm the approved limited source scope and + whether route 3s or 1s applies. Follow the current Safety Committee process + and source baseline rather than assuming a fixed certification boundary. +- For ISO 26262 product work, establish the item definition, HARA, safety goals, + and ASIL before the functional safety concept. Refine that into the technical + safety concept and derived requirements before implementation, integration, + verification, and assessment evidence is claimed complete. +- For another standard or route, record the lifecycle mapping, responsible + owner, required outputs, and unresolved differences. + +These activities may iterate, but later evidence cannot substitute for a +missing concept, scope, or ownership decision. + +## Evidence record + +For each safety-facing claim, record: + +- claim and status; +- standard and edition, lifecycle route, scope layer, source baseline, and + owner; +- requirement, process, or assessment source; +- code or configuration path and verification evidence for implementation + claims, otherwise `not applicable` or an explicit gap; +- assumptions, contrary evidence, unresolved gaps, and next human decision.