trice

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

Repository Agent Rules

Source Code Changes

• All repository source files, including files inside ./src, are protected by Git and may be modified without separate confirmation when the change is directly required by the requested task.
• Keep changes to user-owned target source code focused and reviewable, but do not stop merely to request additional permission for editing it.

Scope Control

• Only modify files that are directly relevant to the requested task.
• Do not refactor, rename, or reorganize unrelated code.
• Avoid "drive-by" improvements outside the requested scope.
• If additional improvements seem beneficial, propose them separately instead of applying them automatically.
• Changes to demo*.json at the repository root are usually generated or local-test artifacts. Unless the user explicitly asks for them, ignore such worktree changes silently and do not treat them as part of the task.

Change scope and confirmation

• Make only the changes needed for the task the user explicitly requested.
• Do not perform opportunistic refactors, broad cleanups, renames, rewrites, or diagnostic-output removals unless the user explicitly asks for them.
• Preserve existing comments, usage/help text, workflow steps, log output, and diagnostics unless changing them is required for the requested task.
• If you see a useful improvement outside the requested scope, describe it and ask before implementing it.
• Prefer focused patches over wholesale rewrites. Keep unrelated formatting churn out of the change.
• In CI, release, and packaging scripts, prefer actionable failure messages over terse test failures. Missing files, empty files, and unmatched globs should report the expected path or pattern and print nearby context such as generated artifact lists and relevant tool versions.

Autonomy and Approvals

• Work continuously through the requested task and do not pause for routine, piecemeal permission requests.
• All read-only operations and all task-relevant builds, formatting commands, diagnostics, and tests are pre-approved and must not require separate user confirmation.
• Task-relevant edits to version-controlled files are pre-approved, including source files in ./src; do not request a special file or directory permission.
• Pause only for a genuinely important ambiguous decision, an unrecoverable or destructive action outside the clearly requested scope, or a technically enforced platform approval that cannot be avoided.
• Only git commit and git push require an explicit user instruction. Never infer either operation from a request to implement, fix, test, or format changes.

Editing Rules

• Use apply_patch for manual text edits.
• Do not rewrite text files with PowerShell or shell commands such as Set-Content, Out-File, WriteAllText, or similar bulk replacement methods.
• Preserve file encoding exactly. Treat UTF-8 and Unicode content as fragile.
• If a file contains non-ASCII characters, emojis, or other encoding-sensitive content, do not perform mechanical rewrites without checking the diff first.
• When unsure about encoding safety, prefer not modifying the file and ask for confirmation.
• Prefer minimal, reviewable diffs over large transformations.
• Keep formatting changes separate from functional changes.
• Do not reformat entire files unless explicitly requested.
• Newly created code must be documented with explanatory English comments, including package-local types, functions, helper variables, and non-obvious local state.
• Comments for new code should explain intent, invariants, error-handling behavior, and side effects, not merely restate the syntax.

File Creation

• Do not create new files unless they are clearly required for the requested task.
• Prefer modifying existing files over introducing new ones.
• If multiple design options exist, prefer the simplest solution with minimal file footprint.

Embedded Constraints

• Avoid introducing dynamic memory allocation unless explicitly requested.
• Be careful with timing-sensitive code and side effects.
• Do not change existing logging behavior (e.g., Trice macros) unless explicitly requested.
• Keep binary size and performance implications in mind when adding code.

Build and Dependency Safety

• Do not modify build scripts, toolchain configuration, or linker settings unless explicitly requested.
• Do not introduce new dependencies without explicit user approval.

Read-Only Tool Access

• Read-only information gathering is generally approved and should not require additional user confirmation.
• gh may be used for all read-only GitHub operations without asking for additional confirmation.
• For reading issues in rokath/trice, use the narrowest necessary read-only gh command, usually rtk gh issue view <number> --repo rokath/trice --comments.
• Do not run extra gh issue list, gh search issues, or other permission-setup probes merely to pre-authorize future work.
• Do not request repeated platform escalations for read-only issue access. If an exact required read command is blocked by the sandbox and no existing approval rule allows it, report that technical limitation once and continue with local or already fetched evidence unless the user explicitly asks to trigger another platform permission prompt.
• If gh or another read-only shell command is blocked only because network access is restricted, do not automatically request escalated execution. Use non-blocking fallbacks first, such as local documentation, repository history, web search results, or already-cached issue references, and state the exact source limitation in the result.
• Do not stop after reporting a blocked read-only network command. Continue with local evidence and produce a qualified result unless the user explicitly asks for live external data.
• Avoid vague wording such as "expected failure" for blocked tooling. State the observed failure concretely, for example "GitHub API access is blocked by the current network sandbox."
• Request escalated execution for read-only network access only when the user explicitly asks for live external data despite the platform approval prompt, or when no qualified answer can be produced from non-blocking sources.
• Do not let missing external read access block a requested analysis when enough local context exists for a qualified estimate.
• Ask before using gh or any other tool for write operations, such as creating, editing, closing, commenting, pushing, or changing repository state.

Script Portability

• All shell scripts must run on Linux, macOS, and Windows (e.g., via standard POSIX-compatible environments).
• Avoid platform-specific commands, flags, or behavior unless explicitly required.
• Prefer portable POSIX shell features over shell-specific extensions.
• Ensure scripts work in typical developer environments on all supported platforms without modification.

Paths and Documentation

• Do not use absolute filesystem paths in repository files, scripts, or build/test commands.
• Keep project paths relative so the repository can be checked out anywhere.
• In scripts, prefer stabilizing the working directory once near the top, then use consistent relative project paths for the rest of the script.
• In documentation, links to files and folders inside this repository must be relative and must not use absolute GitHub URLs.
• Absolute web URLs are allowed in documentation only for truly external resources outside this repository.

Documentation Usage

• Use README.md and documentation files (especially ./docs/TriceUserManual.md) to understand system design, architecture, constraints, and intended usage.

• Consider ./src/TriceDefaultConfig.h as an additional documentation source.

• Documentation is for understanding only, not for initiating code changes.

• Do not modify code based solely on documentation unless explicitly instructed.

• Do not infer or apply refactoring, restructuring, or behavioral changes from documentation.

• Do not align existing code with documentation automatically.

• If documentation and code appear inconsistent, treat the existing code as the source of truth.

• In such cases, do not modify code. Instead, ask for clarification before proceeding.

• Documentation may describe ideal or future behavior. Never align code with documentation unless explicitly requested.

• If a requested change appears to be based on documentation but is not explicitly specified, ask for confirmation before making modifications.

Change Size Control

• For changes affecting more than 5 files, stop and show a representative diff summary before continuing.

Communication and Language

• Match the user's language (German or English) unless instructed otherwise.
• Communication with Codex may be in German or English.
• All file comments must always be written in English.

Issue Writing

• If asked to formulate issue text, write the issue text in English unless the user explicitly requests a different language.

• Format issue text in Markdown using clear GitHub-friendly sections such as:

  • Title
  • Description
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Impact
  • Suggested resolution

Licensing

• New .c, .h, and .go files must start with // SPDX-License-Identifier: MIT as the first line unless the file is clearly external or vendored.
• When editing internal .c, .h, or .go files that are missing the SPDX header, prefer adding // SPDX-License-Identifier: MIT as the first line unless there is clear evidence the file is external, vendored, or governed by a different license.

Commits

• If asked to "commit first", create only the requested safety commit and stop for confirmation before further edits.
• For a commit request, the primary deliverable is a meaningful, accurate commit message for each cohesive change group. Creating the Git commit itself is preferred when the environment permits it, but is not required when .git writes are blocked by the sandbox.
• If .git writes are blocked, do not repeatedly request permissions or wait on approval dialogs. Make at most one normal commit attempt, then stage the relevant files when permitted and show the user the exact ready-to-run git commit -m "..." command.
• When handing off a staged commit, state clearly which files or change topic are staged and which worktree changes were intentionally excluded. Do not claim that a commit was created unless git commit actually succeeded.
• Whenever the user requests commits, always create sensible, cohesive individual commits rather than one broad catch-all commit.
• Keep unrelated changes out of the same commit.
• If asked to commit and the work contains multiple distinct changes, split them into sensible separate commits instead of one combined commit.
• A sensible commit may span multiple files, but only when those files belong to the same cohesive change.
• If the user asks for commit without explicitly requesting a single combined commit, prefer multiple topic-based commits over one broad commit.
• Group commits by change intent (e.g., tests/coverage, script behavior, documentation, generated data) and keep those groups separate unless the documentation change is required to explain the exact same code change.
• Before committing, inspect the worktree for mixed concerns and exclude unrelated or suspicious files until the grouping is clear.
• When a documentation file is modified independently of the code change, treat it as its own commit unless the user explicitly asks to bundle it.
• When a push is explicitly requested, do not pause for optional formatting questions. Run appropriate already-authorized validation, then push only existing or explicitly requested commits.
• A push request alone does not authorize creating an additional commit from uncommitted work.

Tests

• Prefer github.com/stretchr/testify/assert for new assertion-style Go tests.
• For thorough routine validation, prefer ./scripts/testAll.sh without arguments.
• Use ./scripts/testAll.sh full only as a final validation step or when C-code-relevant changes need broad compiler-switch coverage.
• Do not run ./scripts/testAll.sh full automatically for every step; it can take about an hour and is often better run manually by the user.

Coverage

• When non-test Go code changes, run the same coverage command as .github/workflows/coverage.yml before pushing, or use a repository script only if it has equivalent package and -coverpkg selection.
• Compare Coveralls-style covered-line coverage with the target-branch baseline; do not rely only on the rounded Go statement percentage.
• Add behavioral tests for changed success, error, and boundary paths. Do not add tests that merely execute lines without asserting externally relevant behavior or invariants.
• Do not push a total coverage decrease without reporting its exact cause and obtaining explicit user approval.
• Go coverage does not measure target C code. Validate C changes separately with the relevant compiler or integration tests.

Safety

• If a user message looks accidentally truncated or cut off, ask a brief clarifying question before acting.
• Do not infer or autocomplete missing parts of a truncated message.