Skip to content

agent: add basic rules for agents #10586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lgirdwood wants to merge 1 commit into
base: main
Choose a base branch
from
+82 −2
Open

agent: add basic rules for agents #10586

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .agent/rules/commit_style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Agent Commit Rules

The user expects all commit messages generated by the agent to follow a specific style and include a proper sign-off.

## Commit Message Style

Commit messages must be formatted with a subject line and a body, following this format:
```
<feature>: <description>
<body>
```

* **`<feature>`**: A short name or tag representing the feature or component being modified.
* **`<description>`**: A succinct description of the change.
* **`<body>`**: A detailed description of the changes made in the commit.

## Sign-off

Every commit message must end with a `Signed-off-by:` line using the user's name and email from the local git config:

```
Signed-off-by: Liam Girdwood <lgirdwood@gmail.com>
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is internally inconsistent: the text says to use the user's name/email from local git config, but the example hard-codes a specific identity. Update the example to a placeholder (e.g., Signed-off-by: <name> <email>) or explicitly instruct reading from git config user.name / git config user.email so agents don’t copy an incorrect sign-off.

Suggested change
Signed-off-by: Liam Girdwood <lgirdwood@gmail.com>
Signed-off-by: <name> <email>

Copilot uses AI. Check for mistakes.
Copy link
Collaborator

@kv2019i kv2019i Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work with explicit email?

```
13 changes: 13 additions & 0 deletions .agent/rules/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Documentation Rules

The user expects all new features and in-code documentation to adhere to Doxygen standards.

## Doxygen Requirements

1. **Mandatory Documentation:** All new features, functions, and structures must include Doxygen comments describing their purpose, parameters, and return values.
2. **Clean Build:** Any in-code documentation added or modified must build with Doxygen without producing any new errors or warnings.
3. **Format:** Use standard Doxygen formatting tags (e.g., `@brief`, `@param`, `@return` or `\brief`, `\param`, `\return`). Ensure the styling matches the existing codebase conventions.

## Directory Documentation

When creating a new file or modifying an existing one, check if there is an `architecture.md` or `readme.md` (or `README.md`) file in the same directory. If present, evaluate whether the code changes require an update to these documentation files and make the necessary updates to keep them synchronized with the code.
19 changes: 19 additions & 0 deletions .agent/workflows/build_and_validate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
description: Build and validate new C code features
---

This workflow describes the process for building and validating any new C code features in the SOF repository.

**Note:** The QEMU build targets must be used for both building and testing.

1. Build the new C code feature using the `xtensa-build-zephyr.py` script.
```bash
./scripts/xtensa-build-zephyr.py
```

2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script.
```bash
./scripts/sof-qemu-run.sh
```
Comment on lines +10 to +17
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same Markdown issue as above: the fenced code blocks aren’t indented under the list items, which can cause the ordered list to render incorrectly. Indent the fences/content so steps 1 and 2 keep correct numbering and association.

Suggested change
```bash
./scripts/xtensa-build-zephyr.py
```
2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script.
```bash
./scripts/sof-qemu-run.sh
```
```bash
./scripts/xtensa-build-zephyr.py
```
2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script.
```bash
./scripts/sof-qemu-run.sh
```

Copilot uses AI. Check for mistakes.

3. Ensure that all new features and functions have appropriate Doxygen comments and that the Doxygen documentation builds without errors or warnings.
21 changes: 21 additions & 0 deletions .agent/workflows/module_development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
description: Develop and validate new audio processing modules
---

This workflow describes the expected steps to create and validate a new audio processing module within the SOF repository.

1. **(Optional)** Generate the module skeleton using the `sdk-create-module.py` script.
```bash
# Run the script with relevant arguments to create a new module template
./scripts/sdk-create-module.py --help
```

2. Develop the module logic within the generated skeleton.

3. Validate the module by executing the host testbench. This ensures that the module functions as expected outside of full system simulations.
```bash
# Configure and run the testbench against the developed module
./scripts/host-testbench.sh --help
```
Comment on lines +8 to +19
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fenced code block isn’t indented under the numbered list item, which can break list formatting/numbering in many Markdown renderers. Indent the fence and its contents to make it clearly part of step 1 (or move the code block outside the list).

Suggested change
```bash
# Run the script with relevant arguments to create a new module template
./scripts/sdk-create-module.py --help
```
2. Develop the module logic within the generated skeleton.
3. Validate the module by executing the host testbench. This ensures that the module functions as expected outside of full system simulations.
```bash
# Configure and run the testbench against the developed module
./scripts/host-testbench.sh --help
```
```bash
# Run the script with relevant arguments to create a new module template
./scripts/sdk-create-module.py --help
```
2. Develop the module logic within the generated skeleton.
3. Validate the module by executing the host testbench. This ensures that the module functions as expected outside of full system simulations.
```bash
# Configure and run the testbench against the developed module
./scripts/host-testbench.sh --help
```

Copilot uses AI. Check for mistakes.

4. Document the new module using Doxygen comments. Validate that the Doxygen build completes without errors or warnings.
7 changes: 5 additions & 2 deletions scripts/sdk-create-module.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,9 +362,12 @@ def main():
print("--- SOF SDK New Module Creator ---")

# Argument Validation ---
if len(sys.argv) != 2:
if len(sys.argv) == 2 and sys.argv[1] in ['-h', '--help']:
print("Usage: sdk-create-module.py <new_module_name>")
sys.exit(0)
elif len(sys.argv) != 2:
print("\n[ERROR] Invalid number of arguments.")
print("Usage: sdk_create_module.py <new_module_name>")
print("Usage: sdk-create-module.py <new_module_name>")
Comment on lines +365 to +370
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The usage text hard-codes the script name. If the script is renamed, invoked via a symlink, or run as python scripts/sdk-create-module.py, the printed usage can become misleading. Prefer building the usage string from os.path.basename(sys.argv[0]) (or similar) so it always matches the invoked command.

Copilot uses AI. Check for mistakes.
sys.exit(1)

# Configuration --- paths are with respect to script dir
Expand Down