RFC: Add tasklists & documentation for AI Agents#130
Open
nsaulnier-ti wants to merge 15 commits intomainfrom
Open
RFC: Add tasklists & documentation for AI Agents#130nsaulnier-ti wants to merge 15 commits intomainfrom
nsaulnier-ti wants to merge 15 commits intomainfrom
Conversation
Review Summary by QodoAdd AI agent task guides, expand documentation, and standardize project configurations
WalkthroughsDescription• **Comprehensive AI agent task guides**: Added three new task guides (task_create_project.md, task_port_project.md, task_add_features.md) to support AI agents in common OpenPRU development workflows with decision trees, detailed checklists, and verification steps • **Expanded project creation documentation**: Significantly enhanced open_pru_create_new_project.md with prerequisites, decision trees, detailed makefile customization guidance, and build checkpoints • **New MCU+ integration guide**: Added open_pru_create_new_mcuplus_project.md for comprehensive guidance on adding MCU+ code to OpenPRU projects • **Build system fixes**: Fixed pru_rules.mak linker flags and makefile variable references ($^ to $<, added order-only prerequisites for directory creation) • **Standardized project configurations**: Updated 100+ project specification files across academy labs and examples to use OpenPRU paths, remove MCU+ SDK dependencies, add optimization flags, and improve consistency • **Dependency simplification**: Replaced SDK-specific includes with standard C headers in cslr_soc_baseaddress.h for improved portability • **Consistent naming conventions**: Standardized project names and output binaries across all getting started labs and examples (e.g., pru_add_assembly, pru_add_c_and_assembly, pru_add_c_and_inline_assembly) Diagramflowchart LR
A["AI Agent Task Guides<br/>task_create_project<br/>task_port_project<br/>task_add_features"] --> B["Enhanced Documentation<br/>open_pru_create_new_project<br/>open_pru_create_new_mcuplus_project"]
C["Build System Fixes<br/>pru_rules.mak<br/>Linker flags & variables"] --> D["Standardized Projects<br/>100+ projectspec files<br/>Consistent naming & paths"]
E["Dependency Updates<br/>Remove MCU+ SDK<br/>Use OpenPRU paths"] --> D
F["Code Simplification<br/>Replace SDK includes<br/>with standard C headers"] --> E
B --> D
File Changes1. source/include/am62x/cslr_soc_baseaddress.h
|
Code Review by Qodo
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| ## Verification steps | ||
|
|
||
| - [ ] V1. Build the project after each significant change: | ||
| `cd <project> && make -s clean && make` |
There was a problem hiding this comment.
1. Inline cd && make command 📘 Rule violation ⚙ Maintainability
docs_ai/task_add_features.md presents a user-entered shell command inline (backticks) instead of a fenced code block, which can wrap and break copy/paste. This violates the documentation requirement to fence shell commands.
Agent Prompt
## Issue description
Shell commands in `docs_ai/task_add_features.md` are written inline (single-line backticks) instead of fenced code blocks, which can break copy/paste due to wrapping.
## Issue Context
Compliance requires user-entered shell commands in documentation to be presented in fenced code blocks.
## Fix Focus Areas
- docs_ai/task_add_features.md[130-137]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
1
to
2
| export OPEN_PRU_PATH?=$(abspath ../../../../..) | ||
| include $(OPEN_PRU_PATH)/imports.mak |
There was a problem hiding this comment.
2. Wrong open_pru_path depth 🐞 Bug ≡ Correctness
Several makefile_projectspec files set OPEN_PRU_PATH with too few .. levels, so `include $(OPEN_PRU_PATH)/imports.mak` points at a non-root directory and the project-spec build/export targets fail unless OPEN_PRU_PATH is manually overridden. This also contradicts the documented requirement that makefile_projectspec must follow the same folder-depth rule as the sibling makefile.
Agent Prompt
### Issue description
Multiple `makefile_projectspec` files set `OPEN_PRU_PATH` with an incorrect relative depth (too few `..` components). Because these files immediately do `include $(OPEN_PRU_PATH)/imports.mak`, the wrong depth makes Make try to include `imports.mak` from the wrong directory, breaking the documented `makefile_projectspec` command-line workflow (build/export CCS projects).
### Issue Context
The repo docs explicitly state that `OPEN_PRU_PATH` in `makefile_projectspec` must follow the same folder-depth rule as the sibling `makefile`. In the affected directories, `makefile` and `makefile_projectspec` disagree on the number of `..` levels.
### Fix Focus Areas
Update each affected `makefile_projectspec` so `OPEN_PRU_PATH` matches the sibling `makefile` in the same directory (same number of `..` levels).
- examples/empty/mcuplus/am263x-lp/r5fss0-0_freertos/ti-arm-clang/makefile_projectspec[1-2]
- examples/fir/firmware/am243x-lp/icss_g0_pru0_fw/ti-pru-cgt/makefile_projectspec[1-2]
- examples/custom_frequency_generator/firmware/am243x-lp/icss_g0_pru0_fw/ti-pru-cgt/makefile_projectspec[1-2]
- examples/logic_scope/firmware/am243x-lp/icss_g0_pru0_fw/ti-pru-cgt/makefile_projectspec[1-2]
- academy/getting_started_labs/c_code/solution/mcuplus/am263x-lp/r5fss0-0_freertos/ti-arm-clang/makefile_projectspec[1-2]
(Recommended) Add a quick consistency check script or CI lint that asserts `OPEN_PRU_PATH` lines match between `makefile` and `makefile_projectspec` in the same folder.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Resolves this issue around imports.mak comments & settings: #94 I am unable to replicate Thomas's observations for setting PROFILE to either debug or release for AM243x on Linux. Next, test on Windows. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
These scripts got out of date and are not currently maintained. Remove for now, since we do not want customers using them at this point in time. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
The PRU Academy v2026.01.00 made significant updates to the academy training that this page is based on. Update the OpenPRU version of the docs. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Update this file to more explicitly cover steps in a non-MCU+ usecase. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Create a new OpenPRU document based on the PRU Academy v2026.01.00 page **Getting Started Labs > Lab 1: How to Create a PRU Project > Creating a CCS PRU Project with MCU+ Code** Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Update the docs/contributing.md file for v2026.01.00. Include updates to better enable AI agents to interact with the OpenPRU repo. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
In v2026.01.00, make docs/open_pru_organization the single source of truth about organization in OpenPRU repo (i.e., other documents should refer to this document instead of replicating the information). AI agents using docs/open_pru_organization.md needed the document to include more information about where key files were located. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Update pr_compliance_checklist to align with updates to other files in the docs/ folder for v2026.01.00. Update the pr_compliance_checklist so that any changes to the OpenPRU repository which may require updates to future AI documentation are flagged, so that the AI documentation can be reviewed and updated as needed. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Update the readme based on the latest documentation and code. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Create separate best practices sections for C code for MCU+ cores, and C code for PRU cores. Do not duplicate information in docs/open_pru_organization, simply refer to that file. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
We observed that AI agents needed a set of guidelines to consistently execute certain tasks in the OpenPRU repository. Create the docs_ai folder to house this AI-specific documentation. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Add docs_ai/task_port_project.md, which provides guidance to AI agents which are porting an OpenPRU project from one processor to another processor. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Add docs_ai/task_create_project.md, which provides guidance to AI agents which are creating a new OpenPRU project. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Add docs_ai/task_add_features.md, which provides guidance to AI agents which are programming code for an OpenPRU project. This tasklist may need to be significantly modified or replaced in the future, depending on test results. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Add a default CLAUDE.md file which points AI agents to the correct resources. This file may or may not stay in this location, or we may copy a version of this into docs_ai and explicitly tell customers to copy and modify the file, similar to imports.mak. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
nsaulnier-ti
force-pushed
the
a0226750_ai_documentation
branch
from
06f1c94 to
a506a7a
Compare
Review Summary by QodoAdd comprehensive AI-agent documentation and enhance contribution guidelines
WalkthroughsDescription• Comprehensive documentation updates for project creation and contribution workflows • New AI-agent task runbooks for porting, creating, and extending projects • Enhanced contributing guidelines with detailed build verification and documentation requirements • Improved project organization documentation with clearer directory structure explanations Diagramflowchart LR
A["Contributing Guidelines"] -->|enhanced| B["docs/contributing.md"]
C["Project Creation"] -->|new runbook| D["docs_ai/task_create_project.md"]
E["Project Porting"] -->|new runbook| F["docs_ai/task_port_project.md"]
G["Feature Addition"] -->|new runbook| H["docs_ai/task_add_features.md"]
I["AI Documentation Index"] -->|new| J["docs_ai/README.md"]
K["Claude Integration"] -->|new| L["CLAUDE.md"]
B -->|references| D
B -->|references| F
B -->|references| H
M["Compliance Checklist"] -->|expanded| N["pr_compliance_checklist.yaml"]
O["Project Organization"] -->|clarified| P["docs/open_pru_organization.md"]
Q["Best Practices"] -->|expanded| R["best_practices.md"]
S["Main README"] -->|updated| T["README.md"]
File Changes1. docs/open_pru_create_new_project.md
|
|
Persistent review updated to latest commit a506a7a |
| ### Set up the repo | ||
|
|
||
| Before creating a new OpenPRU project, set up the OpenPRU repo by following the | ||
| steps at [Getting Started with OpenPRU](docs/getting_started.md). |
There was a problem hiding this comment.
1. Broken docs/... relative links 📘 Rule violation ⚙ Maintainability
Several new documentation links use repo-root style paths (e.g., docs/...) inside files already located under docs/, producing broken docs/docs/... relative URLs. This violates the portability/validity requirement for doc links on case-sensitive and non-Windows environments.
Agent Prompt
## Issue description
Several markdown links were added with incorrect relative paths (e.g., `docs/...` inside files under `docs/`, and `../docs/...` inside repo-root files), which breaks navigation.
## Issue Context
These documents live under `docs/` or the repo root, so links should be relative to the current file location (or use correct repo-root-relative links where supported by the renderer).
## Fix Focus Areas
- docs/open_pru_create_new_project.md[27-27]
- docs/open_pru_create_new_mcuplus_project.md[13-13]
- best_practices.md[499-500]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| - Build the PRU project using the CCS project menu. Refer to | ||
| **the MCU+ SDK documentation > Using SDK with CCS Projects**: | ||
| - For more information about using MCU+ SDK projects with CCS, refer to the | ||
| MCU+ SDK documentation: **Developer Guides > Using SDK with CCS Projects** |
There was a problem hiding this comment.
2. Trailing whitespace in readme 📘 Rule violation ⚙ Maintainability
The updated README contains a line with trailing whitespace, which can cause markdown render instability and formatting noise in diffs. This violates the documentation formatting requirements.
Agent Prompt
## Issue description
A modified README line contains trailing whitespace, which violates the documentation formatting rule.
## Issue Context
Trailing whitespace is discouraged because it can create inconsistent rendering and noisy diffs.
## Fix Focus Areas
- README.md[122-122]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+499
to
+500
| See [docs/open_pru_organization.md](../docs/open_pru_organization.md) for the | ||
| authoritative project and repository layout. |
There was a problem hiding this comment.
3. Broken best_practices link 🐞 Bug ≡ Correctness
best_practices.md links to ../docs/open_pru_organization.md, which points outside the repo root and breaks the reference to the organization doc. Readers won’t be able to reach the authoritative layout documentation from best_practices.md.
Agent Prompt
### Issue description
`best_practices.md` contains a broken relative link to the OpenPRU organization document.
### Issue Context
`best_practices.md` is at the repo root, so linking to `../docs/...` escapes the repo and breaks on GitHub.
### Fix Focus Areas
- best_practices.md[499-500]
### What to change
- Update:
- `See [docs/open_pru_organization.md](../docs/open_pru_organization.md)`
- To one of:
- `See [docs/open_pru_organization.md](./docs/open_pru_organization.md)`
- `See [docs/open_pru_organization.md](docs/open_pru_organization.md)`
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
manojKoppolu
approved these changes
Apr 13, 2026
manojKoppolu
approved these changes
Apr 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is dependent upon this other PR, which must be merged first: #133