From dc841599010e1a6e30bc17b94650fef3999ec942 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 2 Mar 2026 16:08:28 +0000 Subject: [PATCH 1/4] agent: add basic rules for agents Add some initial and basic rules for agents to use when performing work on the codebase. These can be expanded and improved as agents improve. This includes a --help needed in sdk-config for agent use. Signed-off-by: Liam Girdwood --- .agent/rules/commit_style.md | 24 ++++++++++++++++++++++++ .agent/rules/documentation.md | 13 +++++++++++++ .agent/workflows/build_and_validate.md | 19 +++++++++++++++++++ .agent/workflows/module_development.md | 21 +++++++++++++++++++++ scripts/sdk-create-module.py | 7 +++++-- 5 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 .agent/rules/commit_style.md create mode 100644 .agent/rules/documentation.md create mode 100644 .agent/workflows/build_and_validate.md create mode 100644 .agent/workflows/module_development.md diff --git a/.agent/rules/commit_style.md b/.agent/rules/commit_style.md new file mode 100644 index 000000000000..c1d7a49b324a --- /dev/null +++ b/.agent/rules/commit_style.md @@ -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: +``` +: + + +``` + +* **``**: A short name or tag representing the feature or component being modified. +* **``**: A succinct description of the change. +* **``**: 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 +``` diff --git a/.agent/rules/documentation.md b/.agent/rules/documentation.md new file mode 100644 index 000000000000..5d88e6aa3dd4 --- /dev/null +++ b/.agent/rules/documentation.md @@ -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. diff --git a/.agent/workflows/build_and_validate.md b/.agent/workflows/build_and_validate.md new file mode 100644 index 000000000000..c4caa6b0b440 --- /dev/null +++ b/.agent/workflows/build_and_validate.md @@ -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 +``` + +3. Ensure that all new features and functions have appropriate Doxygen comments and that the Doxygen documentation builds without errors or warnings. diff --git a/.agent/workflows/module_development.md b/.agent/workflows/module_development.md new file mode 100644 index 000000000000..a6364e699605 --- /dev/null +++ b/.agent/workflows/module_development.md @@ -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 +``` + +4. Document the new module using Doxygen comments. Validate that the Doxygen build completes without errors or warnings. diff --git a/scripts/sdk-create-module.py b/scripts/sdk-create-module.py index b9193a57f942..bc80db16dfe9 100755 --- a/scripts/sdk-create-module.py +++ b/scripts/sdk-create-module.py @@ -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 ") + sys.exit(0) + elif len(sys.argv) != 2: print("\n[ERROR] Invalid number of arguments.") - print("Usage: sdk_create_module.py ") + print("Usage: sdk-create-module.py ") sys.exit(1) # Configuration --- paths are with respect to script dir From aec67d156681f70459ae75014fe9f7b261e54123 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 3 Mar 2026 12:21:54 +0000 Subject: [PATCH 2/4] Update .agent/rules/commit_style.md Make email generic Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Liam Girdwood --- .agent/rules/commit_style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agent/rules/commit_style.md b/.agent/rules/commit_style.md index c1d7a49b324a..c3b8734d302e 100644 --- a/.agent/rules/commit_style.md +++ b/.agent/rules/commit_style.md @@ -20,5 +20,5 @@ Commit messages must be formatted with a subject line and a body, following this 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 +Signed-off-by: ``` From 1b3887e85f56a8543564043ba47b89d7fc24dba3 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 3 Mar 2026 12:24:20 +0000 Subject: [PATCH 3/4] Update .agent/workflows/module_development.md Indent fenced code block. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Liam Girdwood --- .agent/workflows/module_development.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.agent/workflows/module_development.md b/.agent/workflows/module_development.md index a6364e699605..0ce68df2d300 100644 --- a/.agent/workflows/module_development.md +++ b/.agent/workflows/module_development.md @@ -5,17 +5,17 @@ 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 -``` + ```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 + # Configure and run the testbench against the developed module + ./scripts/host-testbench.sh --help + ``` 4. Document the new module using Doxygen comments. Validate that the Doxygen build completes without errors or warnings. From 7c902ec80aae06559906d3e63d4ce176dc001c99 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Tue, 3 Mar 2026 12:24:43 +0000 Subject: [PATCH 4/4] Update .agent/workflows/build_and_validate.md indent fenced code block Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Liam Girdwood --- .agent/workflows/build_and_validate.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.agent/workflows/build_and_validate.md b/.agent/workflows/build_and_validate.md index c4caa6b0b440..4947b3fa8451 100644 --- a/.agent/workflows/build_and_validate.md +++ b/.agent/workflows/build_and_validate.md @@ -7,13 +7,13 @@ This workflow describes the process for building and validating any new C code f **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 -``` + ```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/sof-qemu-run.sh + ``` 3. Ensure that all new features and functions have appropriate Doxygen comments and that the Doxygen documentation builds without errors or warnings.