RFC: Add tasklists & documentation for AI Agents#130
Open
nsaulnier-ti wants to merge 5 commits into
Open
Conversation
Review Summary by Qodo(Agentic_describe updated until commit 7dba58f)Add AI agent documentation and task runbooks for OpenPRU
WalkthroughsDescription• Create docs_ai/ folder with AI-agent task runbooks • Add four task-specific documentation files for common OpenPRU operations • Establish strict factuality rules and guidelines for AI tool interactions • Provide structured checklists and decision trees for AI-assisted development Diagramflowchart LR
A["CLAUDE.md<br/>AI Instructions"] --> B["docs_ai/<br/>AI Documentation"]
B --> C["README.md<br/>Task Index"]
C --> D["task_port_project.md<br/>Device Porting"]
C --> E["task_create_project.md<br/>New Projects"]
C --> F["task_add_features.md<br/>Feature Addition"]
File Changes1. CLAUDE.md
|
Code Review by Qodo
1. e.g. used in docs
|
![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
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
previously approved these changes
Apr 13, 2026
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
a506a7a to
7dba58f
Compare
|
Persistent review updated to latest commit 7dba58f |
Comment on lines
+119
to
+121
| `mcuplus/<new_board>/<core>/ti-arm-clang/` (e.g., `examples/empty`); | ||
| others use `<new_board>/<core>/ti-arm-clang/` directly at the project root | ||
| (e.g., `academy/intc/intc_mcu`). Match the convention used by the project |
There was a problem hiding this comment.
1. e.g. used in docs 📘 Rule violation ⚙ Maintainability
New documentation uses e.g., which is disallowed terminology per documentation/comment standards. This reduces consistency and violates the required phrasing rules.
Agent Prompt
## Issue description
The documentation uses `e.g.`, but the repo standard requires "for example".
## Issue Context
This rule applies to repository text (documentation and comments).
## Fix Focus Areas
- docs_ai/task_port_project.md[119-121]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
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.
Add tasklists & documentation.
TODO: How to do stuff like pinmuxing?