Repository Agent Rules

Source Code Protection

• Files inside ./src are considered user-owned target source code.
• Do not modify files in ./src unless the user explicitly requests changes to specific files or explicitly allows modifications in that directory.
• If a task would normally require changes in ./src, stop and ask for confirmation before proceeding.

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.

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.

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.

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.
• 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.
• If the user asks for a push, stop first and ask whether ./scripts/format_repo.sh should be run before pushing.
• If ./scripts/format_repo.sh is run for that purpose, ask whether the resulting formatting changes should be committed before the push.
• Treat this formatting-and-commit step as an optional append-on to the requested push workflow, not as an automatic action.

Tests

• Prefer github.com/stretchr/testify/assert for new assertion-style Go 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.