agent: add basic workflows for agents

lrgirdwo · lgirdwood · commit 07f53cbad849 · 2026-03-11T15:55:12.000Z
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 &lt;liam.r.girdwood@linux.intel.com&gt;
diff --git a/.agent/rules/commit_style.md b/.agent/rules/commit_style.md
@@ -0,0 +1,28 @@
+---
+trigger: always_on
+---
+
+# Agent Commit Rules
+
+The user requires 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/subsystem>: <one line description>
+
+<body>
+```
+
+* **`<feature/subsystem>`**: A short name or tag representing the feature or component being modified.
+* **`<one line description>`**: A succinct one-line description of the change.
+* **`<body>`**: A detailed description of the changes made in the commit. The body must be at least one sentence describing the changes.
+
+## Sign-off
+
+Every commit message must end with a `Signed-off-by:` line using the patch author's name and email (from the local git config):
+
+```
+Signed-off-by: <author name> <author email>
+```
diff --git a/.agent/rules/documentation.md 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
@@ -0,0 +1,22 @@
+---
+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. The user requires the build must be error and warning free and the ztests must all pass.
+
+// turbo-all
+1. Build the new C code feature using the `xtensa-build-zephyr.py` script.
+    ```bash
+    source ../.venv/bin/activate
+    ./scripts/xtensa-build-zephyr.py qemu_xtensa
+    ```
+
+2. Validate the feature with a ztest run using the `sof-qemu-run.sh` script.
+    ```bash
+    source ../.venv/bin/activate
+    ./scripts/sof-qemu-run.sh build-qemu_xtensa
+    ```
+
+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
@@ -0,0 +1,22 @@
+---
+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.
+
+// turbo-all
+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 --name <module_name> --version <version>
+    ```
+
+2. Develop the module logic within the generated skeleton.
+
+3. Validate the module by executing the module within 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 -l <path_to_module_library>
+    ```
+
+4. Document the new module using Doxygen comments. Validate that the Doxygen build completes without errors or warnings. Add a README.md for the module.
diff --git 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 <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>")
         sys.exit(1)
 
     # Configuration --- paths are with respect to script dir
