Add agentic-docs plugin: platform (enhancements repo) and component documentation#437
Open
Prashanth684 wants to merge 3 commits into
Open
Add agentic-docs plugin: platform (enhancements repo) and component documentation#437Prashanth684 wants to merge 3 commits into
Prashanth684 wants to merge 3 commits into
Conversation
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Prashanth684 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
Bot
added
the
approved
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds a new Claude plugin "agentic-docs" (v1.0.0) and accompanying skills, templates, and shell scripts to scaffold, discover, populate, gap-detect, and validate AI-optimized OpenShift documentation for platform (openshift/enhancements) and component repositories. ChangesPlugin registration & registry
Top-level README & Skill specs
Platform skill — Implementation, tooling, templates, validation
Component skill — Implementation, tooling, templates, validation
Update-platform skill — Delegations & template references
Estimated code review effort🎯 4 (Complex) | ⏱️ ~40 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 10✅ Passed checks (10 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Prashanth684
force-pushed
the
agentic-docs-ep
branch
from
dd62988 to
a7f325b
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
plugins/agentic-docs/skills/platform/scripts/populate-templates.sh (1)
28-29:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
🔧 Proposed fix
echo "Next: LLM creates remaining documentation files following template patterns" +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/populate-templates.sh` around lines 28 - 29, The file ends without a trailing newline after the final echo statement ("Next: LLM creates remaining documentation files following template patterns"); update the script to ensure it terminates with a single newline character by adding a newline at EOF so POSIX tools and editors treat the file as newline-terminated.plugins/agentic-docs/skills/platform/scripts/validate.sh (1)
152-153:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
🔧 Proposed fix
exit 1 fi +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/validate.sh` around lines 152 - 153, The file ends with the shell block terminator "fi" but lacks a trailing newline which can cause POSIX tools or linters to complain; update plugins/agentic-docs/skills/platform/scripts/validate.sh by adding a single newline character after the final "fi" (ensure the file ends with a newline).plugins/agentic-docs/skills/platform/scripts/discover.sh (1)
46-47:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
🔧 Proposed fix
echo "✅ Discovery complete" +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/discover.sh` around lines 46 - 47, The file ends with the line echo "✅ Discovery complete" but is missing a trailing newline; update plugins/agentic-docs/skills/platform/scripts/discover.sh (the final echo line) to ensure the file terminates with a newline character by adding an empty newline after that line so POSIX tools and editors handle it correctly.plugins/agentic-docs/skills/component/scripts/validate.sh (1)
89-90:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
The file should end with a newline character for POSIX compliance.
🔧 Proposed fix
echo "===================================" echo "✅ Validation complete" +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/scripts/validate.sh` around lines 89 - 90, The script ends with the line echo "✅ Validation complete" but is missing a trailing newline; open plugins/agentic-docs/skills/component/scripts/validate.sh and ensure the file ends with a final newline character (add a newline after the echo "✅ Validation complete" line) to make the file POSIX-compliant.plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md (1)
188-189:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
🔧 Proposed fix
- [Component Documentation Guide](https://github.com/openshift/ai-helpers/tree/master/plugins/agentic-docs) +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md` around lines 188 - 189, Add a missing trailing newline at end-of-file for the README: ensure the last line containing the Markdown link "[Component Documentation Guide](https://github.com/openshift/ai-helpers/tree/master/plugins/agentic-docs)" in exec-plans-README.md ends with a newline character (EOF newline) so the file terminates with a proper trailing newline.plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh (1)
96-97:⚠️ Potential issue | 🟡 MinorMissing trailing newline.
🔧 Proposed fix
exit $GAPS_FOUND +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh` around lines 96 - 97, The script ends with "exit $GAPS_FOUND" but is missing a trailing newline at EOF; add a single newline character after the final line (after the exit $GAPS_FOUND statement) so the file ends with a proper newline, ensuring POSIX-compliant shell behavior and tools that expect a newline at EOF.
🟡 Minor comments (19)
plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md-14-17 (1)
14-17:⚠️ Potential issue | 🟡 MinorAdd a language to the directory-layout fenced block (markdownlint MD040).
Line 14 should include a fence language for lint compliance.
Suggested fix
-``` +```text exec-plans/ └── active/ # Create feature-specific exec-plans here</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md
around lines 14 - 17, The fenced code block in exec-plans-README-template.md
that contains the directory layout (the block starting with "exec-plans/" and
the comment "Create feature-specific exec-plans here") is missing a fence
language marker; update the opening triple backticks to include a language
(e.g., ```text) so the block complies with markdownlint MD040.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/templates/AGENTS.md-29-39 (1)</summary><blockquote> `29-39`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the fenced code block (markdownlint MD040).** Line 29 should specify a fence language for lint compliance. <details> <summary>Suggested fix</summary> ```diff -``` +```text [Repo Agentic Docs]|root:./ai-docs|XX files, XXXX lines | |CRITICAL_READS:{KNOWLEDGE_GRAPH.md,DESIGN_PHILOSOPHY.md} | |platform/operator-patterns:{controller-runtime.md,status-conditions.md,...} |practices/testing:{pyramid.md,e2e-framework.md,...} |domain/kubernetes:{pod.md,node.md,...} |domain/openshift:{clusteroperator.md,machine.md,...} |decisions:{adr-0001-*.md,...} ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/platform/templates/AGENTS.mdaround lines 29 -
39, The fenced code block in AGENTS.md (the block starting with "[Repo Agentic
Docs]|root:./ai-docs|...") lacks a language specifier and triggers markdownlint
MD040; update the opening fence fromto include a language (e.g.,text)
so the block is annotated (modify the fenced code block in AGENTS.md that wraps
the repo summary content).</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/scripts/create-structure.sh-16-16 (1)</summary><blockquote> `16-16`: _⚠️ Potential issue_ | _🟡 Minor_ **Line 16 creates a directory that downstream discovery/gap checks don’t process.** `platform/openshift-specifics` is created here, but current discovery and gap-detection scripts only target `platform/operator-patterns` for platform patterns. This can leave docs in that folder invisible to automation. <details> <summary>One simple fix (remove untracked directory for now)</summary> ```diff -mkdir -p "$REPO_PATH/ai-docs/platform/openshift-specifics" ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/create-structure.sh` at line 16, The script currently creates the directory named by the mkdir call "$REPO_PATH/ai-docs/platform/openshift-specifics" which is not picked up by downstream discovery/gap checks; remove that mkdir invocation (or replace it to create "$REPO_PATH/ai-docs/platform/operator-patterns" instead) so created directories match the discovery target used by the gap-detection tools; update the mkdir usage in create-structure.sh (the line containing mkdir -p "$REPO_PATH/ai-docs/platform/openshift-specifics") accordingly. ``` </details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/templates/adr-template.md-67-67 (1)</summary><blockquote> `67-67`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix placeholder link text/target mismatch in References.** Line 67 uses `[related-doc.md](./related.md)`, which is inconsistent and can produce confusing generated docs. <details> <summary>Suggested fix</summary> ```diff -- **Related**: [related-doc.md](./related.md) +- **Related**: [related.md](./related.md) ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/templates/adr-template.md` at line 67, The References entry contains a mismatched link text and target ("[related-doc.md](./related.md)"); update the markdown so the visible text and href match (e.g., change to "[related.md](./related.md)" or change the target to "./related-doc.md") to ensure the link label and destination are consistent. ``` </details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/component/templates/AGENTS-template.md-23-31 (1)</summary><blockquote> `23-31`: _⚠️ Potential issue_ | _🟡 Minor_ **Label the fenced blocks to satisfy markdownlint.** Lines [23] and [39] use unlabeled code fences and trigger MD040. <details> <summary>Suggested fix</summary> ```diff -``` +```text ai-docs/ ├── domain/ # Component-specific CRDs ├── architecture/ # Component internals ├── decisions/ # Component-specific ADRs ├── exec-plans/ # Feature planning └── references/ └── ecosystem.md # Links to Tier 1 ``` @@ -``` +```text [AGENTS.md] ← Start here │ ┌───────────────┼───────────────┐ │ │ │ [domain/] [architecture/] [decisions/] CRD concepts Component design ADR history │ │ │ └───────────────┼───────────────┘ │ [references/ecosystem] Links to Tier 1 ``` ``` </details> Also applies to: 39-51 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/component/templates/AGENTS-template.mdaround
lines 23 - 31, Update the two unlabeled fenced code blocks in AGENTS-template.md
(the directory tree block and the ASCII diagram block) to include a language
label (use "text") so markdownlint MD040 is satisfied; locate the
triple-backtick fences around the ai-docs tree and the ASCII diagram and change
them fromtotext in both places.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md-32-66 (1)</summary><blockquote> `32-66`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language tags to all fenced blocks.** These fences are currently unlabeled and trigger MD040. <details> <summary>Suggested fix</summary> ```diff -``` +```text ┌─────────────────────────────────────────────────────────────┐ ... -``` +``` @@ -``` +```text DESIGN_PHILOSOPHY.md ... -``` +``` @@ -``` +```text DESIGN_PHILOSOPHY.md ... -``` +``` @@ -``` +```text practices/testing/index.md (→ links to dev-guide/test-conventions.md) ... -``` +``` ``` </details> Also applies to: 73-83, 86-94, 97-103 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.mdaround
lines 32 - 66, The fenced ASCII diagram blocks in KNOWLEDGE_GRAPH.md are
unlabeled and trigger MD040; add a language tag (e.g.,text) to every fenced block shown (the big diagram block containing DESIGN_PHILOSOPHY.md and the smaller blocks listing DESIGN_PHILOSOPHY.md, PLATFORM/, practices/testing/index.md, references, etc.) so each opening triple-backtick becomestext (or another appropriate literal language) and leave the closing
backticks unchanged; update all occurrences referenced in the diff and the other
blocks at the same sections (around the ASCII diagram and the blocks at lines
~73-83, 86-94, 97-103) to silence the MD040 lint.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md-27-31 (1)</summary><blockquote> `27-31`: _⚠️ Potential issue_ | _🟡 Minor_ **Specify a language for the reconciliation example block.** Line [27] should include a fence language to avoid MD040 warnings. <details> <summary>Suggested fix</summary> ```diff -``` +```text User declares: "I want 3 replicas" (Desired State) Kubernetes sees: "I have 1 replica" (Current State) Controller: "I'll create 2 more" (Reconciliation) ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.mdaround
lines 27 - 31, The fenced code block showing the reconciliation example is
missing a fence language; update the opening triple-backtick for the block that
contains the three lines starting with 'User declares: "I want 3 replicas"' to
include a language tag (e.g., changetotext) so the block is explicitly
marked and MD040 warnings are resolved.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/templates/domain-concept-template.md-47-49 (1)</summary><blockquote> `47-49`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language tag to the workflow fence.** Line [47] uses an unlabeled fenced block, which triggers MD040 in markdownlint. <details> <summary>Suggested fix</summary> ```diff -``` +```text Step 1 → Step 2 → Step 3 → Step 4 ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/templates/domain-concept-template.md` around lines 47 - 49, The unlabeled fenced code block containing "Step 1 → Step 2 → Step 3 → Step 4" in domain-concept-template.md triggers MD040; update that fence to include a language tag (e.g., use "text") so the block becomes a labeled code fence and the markdownlint rule passes—locate the fenced block with the exact content "Step 1 → Step 2 → Step 3 → Step 4" and prepend the fence with the language tag. ``` </details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/component/templates/TESTING-template.md-11-17 (1)</summary><blockquote> `11-17`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language specifier to fenced code block.** Static analysis flagged this block as missing a language. Use `text` or `plaintext` for ASCII diagrams. <details> <summary>🔧 Proposed fix</summary> ````diff -``` +```text E2E Tests (10%, slow, comprehensive) ▲ Integration Tests (30%, medium) ▲ Unit Tests (60%, fast, focused) ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md` around lines 11 - 17, The fenced ASCII diagram block in TESTING-template.md is missing a language specifier; update the opening triple-backtick for the diagram (the block starting with the ASCII pyramid "E2E Tests... Integration Tests... Unit Tests...") to include a language token such as text or plaintext (e.g., change ``` to ```text) and keep the closing triple-backticks as-is so the block is treated as plain text by static analysis and syntax highlighters.plugins/agentic-docs/skills/platform/scripts/validate.sh-25-27 (1)
25-27:⚠️ Potential issue | 🟡 MinorRange check doesn't match warning message.
The condition checks
< 80 || > 220but the warning says "100-200 lines". Either the range or the message is incorrect.🔧 Proposed fix (assuming 100-200 is the intended range)
- if [ "$LINE_COUNT" -lt 80 ] || [ "$LINE_COUNT" -gt 220 ]; then + if [ "$LINE_COUNT" -lt 100 ] || [ "$LINE_COUNT" -gt 200 ]; then echo " ⚠️ WARNING: Should be 100-200 lines (current: $LINE_COUNT)" fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/validate.sh` around lines 25 - 27, The range check in the validate.sh if statement that uses LINE_COUNT is mismatched with the warning text; update the conditional to match the intended 100-200 line range (replace "[ \"$LINE_COUNT\" -lt 80 ] || [ \"$LINE_COUNT\" -gt 220 ]" with a check for "< 100 || > 200") so the logic and the echo warning ("Should be 100-200 lines (current: $LINE_COUNT)") are consistent; alternatively, if 80-220 is actually intended, change the warning message to reflect "80-220" — adjust the if condition or the echo string around the LINE_COUNT check accordingly.plugins/agentic-docs/skills/component/templates/TESTING-template.md-167-174 (1)
167-174:⚠️ Potential issue | 🟡 MinorAdd language specifier to fenced code block.
Use
textfor directory tree representations.🔧 Proposed fix
-``` +```text test/e2e/ ├── [feature-1]_test.go # Feature 1 E2E tests ├── [feature-2]_test.go # Feature 2 E2E tests └── framework/ # E2E test utilities ├── client.go # K8s client helpers └── helpers.go # Test helpers ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md` around lines 167 - 174, The fenced code block that shows the directory tree (the block starting with "test/e2e/") in TESTING-template.md lacks a language specifier; update the opening fence from ``` to ```text so the directory tree is marked as plain text (i.e., replace the existing ``` before the tree with ```text and keep the closing ``` as-is).plugins/agentic-docs/skills/component/SKILL.md-454-488 (1)
454-488:⚠️ Potential issue | 🟡 MinorAdd language specifier to fenced code block.
🔧 Proposed fix
-``` +```text ✅ Component Documentation Created🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/SKILL.md` around lines 454 - 488, The fenced code block starting with ``` that contains the "✅ Component Documentation Created" summary in SKILL.md lacks a language specifier; update that opening fence (the triple backticks surrounding the block) to include a language token such as text or markdown (e.g., change ``` to ```text) so the block is explicitly typed and renders correctly in markdown viewers; locate the block by the visible content "✅ Component Documentation Created" and adjust the fence accordingly.plugins/agentic-docs/skills/component/SKILL.md-28-45 (1)
28-45:⚠️ Potential issue | 🟡 MinorAdd language specifier to fenced code block.
Static analysis flagged this as MD040. Use
textfor directory trees.🔧 Proposed fix
-``` +```text component-repo/ ├── AGENTS.md # Master entry point (80-100 lines) └── ai-docs/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/SKILL.md` around lines 28 - 45, The fenced code block in SKILL.md containing the directory tree (the block starting with "component-repo/") lacks a language specifier and triggers MD040; update that fenced block to use a language tag of "text" (i.e., replace the opening ``` with ```text) so the directory tree is treated as plain text and the linter warning is resolved.plugins/agentic-docs/skills/component/SKILL.md-225-229 (1)
225-229:⚠️ Potential issue | 🟡 MinorAdd language specifier to fenced code block.
🔧 Proposed fix
-``` +```text ai-docs/exec-plans/ ├── active/ # Component-specific exec-plans go here └── README.md # Pointer to Tier 1 guidance🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/SKILL.md` around lines 225 - 229, The fenced code block showing the directory tree starting with "ai-docs/exec-plans/" lacks a language specifier; edit SKILL.md and change the opening fence for that snippet (the triple backticks immediately before "ai-docs/exec-plans/") to include a language token such as ```text so the block is language-marked (e.g., replace ``` with ```text) and save the file.plugins/agentic-docs/skills/platform/scripts/discover.sh-29-34 (1)
29-34:⚠️ Potential issue | 🟡 MinorDirectory list is missing entries created by
create-structure.sh.
create-structure.shcreatesplatform/openshift-specificsandworkflows/exec-plans, but this discovery script doesn't iterate over them. This inconsistency may cause confusion when the discovery output doesn't reflect the full structure.🔧 Proposed fix to align with create-structure.sh
- for dir in platform/operator-patterns practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows references; do + for dir in platform/operator-patterns platform/openshift-specifics practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows workflows/exec-plans references; do🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/discover.sh` around lines 29 - 34, The for-loop that enumerates directories in discover.sh omits the directories created by create-structure.sh; update the Dir list in the loop that currently iterates over "platform/operator-patterns practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows references" to also include "platform/openshift-specifics" and "workflows/exec-plans" (the loop uses the REPO_PATH/ai-docs/$dir variable and COUNT with find, so simply add those two paths to the same list so they are discovered and counted).plugins/agentic-docs/skills/component/scripts/validate.sh-17-21 (1)
17-21:⚠️ Potential issue | 🟡 MinorLine count validation doesn't warn when below target range.
The target is 80-100 lines per SKILL.md, but the script only warns when
LINE_COUNT > 100. Files under 80 lines should also trigger a warning.🔧 Proposed fix
-if [ "$LINE_COUNT" -gt 100 ]; then - echo " ⚠️ AGENTS.md is $LINE_COUNT lines (target: 80-100)" +if [ "$LINE_COUNT" -lt 80 ] || [ "$LINE_COUNT" -gt 100 ]; then + echo " ⚠️ AGENTS.md is $LINE_COUNT lines (target: 80-100)" else echo " $LINE_COUNT lines (target: 80-100) ✅" fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/scripts/validate.sh` around lines 17 - 21, The current check in validate.sh only warns when LINE_COUNT is greater than 100, but we need to warn when LINE_COUNT is outside the target range 80-100; update the condition that references LINE_COUNT in the AGENTS.md/SKILL.md validation to test if LINE_COUNT < 80 OR LINE_COUNT > 100 and print a warning in that case, otherwise print the success message; keep the variables and messages (LINE_COUNT, target: 80-100) but change the logical check to an out-of-range check so files below 80 lines also trigger the warning.plugins/agentic-docs/skills/component/SKILL.md-158-169 (1)
158-169:⚠️ Potential issue | 🟡 MinorAdd language specifier to fenced code block.
🔧 Proposed fix
-``` +```text ai-docs/ ├── domain/ # CRDs: MachineConfig, MachineConfigPool🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/SKILL.md` around lines 158 - 169, The fenced code block in SKILL.md showing the ai-docs directory tree lacks a language specifier; update the opening fence (the ``` above the directory tree) to include a language like text (e.g., change ``` to ```text) so syntax highlighters render it correctly; locate the fenced block in plugins/agentic-docs/skills/component/SKILL.md where the ai-docs tree is defined and replace the fence accordingly.plugins/agentic-docs/skills/update-platform-docs/SKILL.md-364-365 (1)
364-365:⚠️ Potential issue | 🟡 MinorFix “See Also” relative paths; they appear to point to the wrong locations.
From
skills/update-platform-docs/SKILL.md,../SKILL.mdand../scripts/validate.shlikely resolve incorrectly.Proposed fix
-- [Platform SKILL.md](../SKILL.md) - Full platform docs creation guide -- [Validation Script](../scripts/validate.sh) - Structure validation +- [Platform SKILL.md](../platform/SKILL.md) - Full platform docs creation guide +- [Validation Script](./scripts/validate.sh) - Structure validation🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/update-platform-docs/SKILL.md` around lines 364 - 365, The "See Also" relative links in skills/update-platform-docs/SKILL.md are incorrect: update the link targets in the "See Also" section so they point to the repository-root SKILL.md and to the scripts/validate.sh under the platform docs context instead of using "../SKILL.md" and "../scripts/validate.sh"; locate the "See Also" block in SKILL.md and replace the two links (../SKILL.md and ../scripts/validate.sh) with correct relative paths that resolve from skills/update-platform-docs/SKILL.md to the actual files (e.g., ../../SKILL.md or ../../scripts/validate.sh or the appropriate repo-root-relative path) so the links open the intended documents.plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md-197-197 (1)
197-197:⚠️ Potential issue | 🟡 MinorFix broken relative link in “See Also”.
[Testing Guide](./ [COMPONENT]_TESTING.md)contains a space after./, so the generated link is invalid.Proposed fix
-- [Testing Guide](./ [COMPONENT]_TESTING.md) +- [Testing Guide](./[COMPONENT]_TESTING.md)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md` at line 197, The "See Also" relative link is broken due to a stray space in the link target; locate the Markdown line containing the link text "[Testing Guide](./ [COMPONENT]_TESTING.md)" and remove the space after "./" so the target reads "./[COMPONENT]_TESTING.md" to produce a valid relative link.
🧹 Nitpick comments (5)
plugins/agentic-docs/skills/platform/scripts/discover.sh (1)
21-24: Usefindinstead oflsfor safer filename handling.Shellcheck SC2012:
lscan misbehave with non-alphanumeric filenames. Usingfindis more robust.🔧 Proposed fix
- ADR_SAMPLE=$(ls "$REPO_PATH/ai-docs/decisions/"adr-*.md 2>/dev/null | head -1) + ADR_SAMPLE=$(find "$REPO_PATH/ai-docs/decisions" -maxdepth 1 -name "adr-*.md" -type f 2>/dev/null | head -1) if [ -n "$ADR_SAMPLE" ]; then echo " ✅ Convention: $(basename "$ADR_SAMPLE" | grep -oE '^adr-[0-9]+-')" fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/scripts/discover.sh` around lines 21 - 24, Replace the fragile ls pipeline used to set ADR_SAMPLE with a safer find-based search: use find on "$REPO_PATH/ai-docs/decisions" to locate the first regular file matching the glob pattern adr-*.md (e.g., find ... -maxdepth 1 -type f -name 'adr-*.md' -print -quit), assign that result to ADR_SAMPLE, keep the existing check if [ -n "$ADR_SAMPLE" ] and the echo that extracts the convention via basename and grep -oE '^adr-[0-9]+-' so the script handles filenames with special characters robustly.plugins/agentic-docs/skills/component/templates/TESTING-template.md (1)
180-208: Consider movingdeferbefore assertions for proper cleanup.The
defer client.Delete(...)on line 206 is placed afterrequire.NoErrorcalls. If assertions fail, cleanup won't execute. In templates, it's good to show best practices.♻️ Suggested pattern
func TestFeatureE2E(t *testing.T) { // Setup client := framework.NewClient(t) // Create resource resource := &v1.MyResource{ Spec: v1.MyResourceSpec{...}, } err := client.Create(ctx, resource) require.NoError(t, err) + + // Cleanup - place defer immediately after successful creation + defer client.Delete(ctx, resource) // Wait for expected state err = wait.PollImmediate(5*time.Second, 5*time.Minute, func() (bool, error) { // ... }) require.NoError(t, err) // Verify side effects verify.SideEffects(t, client, resource) - - // Cleanup - defer client.Delete(ctx, resource) }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md` around lines 180 - 208, Move the cleanup defer so it always runs even if assertions fail: immediately after creating the client/resource (in TestFeatureE2E), call defer client.Delete(ctx, resource) rather than placing it after require.NoError checks; ensure the defer appears right after client := framework.NewClient(t) or immediately after successful client.Create(...) so cleanup is guaranteed, and keep the require.NoError checks in place for Create and the wait.PollImmediate block.plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md (1)
33-52: Add a language tag to the fenced repository-structure block.This will satisfy markdownlint MD040 and improve rendering consistency.
Proposed fix
-``` +```text cmd/ # Binary entrypoints ├── [component-1]/ # Component 1 └── [component-2]/ # Component 2 @@ test/ ├── e2e/ # End-to-end tests └── integration/ # Integration tests</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md
around lines 33 - 52, The fenced repository-structure code block currently uses
plain backticks () without a language tag; update the opening fence to include a language tag (e.g., change the openingto ```text) so the block
becomes a language-tagged fenced code block, ensuring markdownlint MD040 is
satisfied and rendering is consistent for the repository-structure section shown
in the template.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/update-platform-docs/SKILL.md (1)</summary><blockquote> `314-337`: **Add a language tag to the success-output code fence.** Non-blocking, but this will satisfy markdownlint MD040. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/update-platform-docs/SKILL.mdaround lines 314 -
337, The success-output fenced code block in SKILL.md (the block that starts
with "✅ Platform Documentation Updated" and shows the
repository/Changes/Validation/Next Steps) lacks a language tag; update that
opening fence fromto a tagged fence such astext (or ```md) so
markdownlint rule MD040 is satisfied, leaving the block contents unchanged and
only modifying the opening backticks.</details> </blockquote></details> <details> <summary>plugins/agentic-docs/skills/platform/SKILL.md (1)</summary><blockquote> `127-143`: **Add language tags to unlabeled fenced code blocks.** This is a lint-only cleanup (MD040), but worth fixing for consistency. Also applies to: 462-499, 582-623 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/agentic-docs/skills/platform/SKILL.mdaround lines 127 - 143, The
fenced code blocks in SKILL.md that show the repository tree (starting with the
line "AGENTS.md" and the ai-docs/ tree block) are missing language tags, causing
MD040 lint warnings; update those triple-backtick fences to include a language
(e.g.,text orbash) for each unlabeled block (including the blocks around
the directory tree and the other occurrences called out in the review) so all
fenced code blocks have explicit language tags while preserving the exact block
content.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@docs/data.json:
- Around line 1731-1745: CI reports docs/data.json is stale because the new
plugin entry "agentic-docs" (version "1.0.0", skill id "platform") was added
manually; run the repository metadata regeneration and commit the results:
execute make update to regenerate docs/data.json (ensuring the plugin registry
and skill metadata are synchronized), verify the updated file contains the
"agentic-docs" entry and its "platform" skill, then commit the regenerated
docs/data.json.In
@plugins/agentic-docs/README.md:
- Around line 10-12: The README's Tier 2 section references the wrong output
path (agentic/) — update the text under "Tier 2: Component Repos" and the
other occurrence (around the second mention) to useai-docs/so it aligns with
the plugin's component templates and structure; search for the literal string
agentic/in README.md and replace it withai-docs/ensuring both occurrences
are updated.- Around line 25-33: The README references the command
/update-docsbut the
plugin and skill in this PR are named/update-platform-docs; update the
documentation to use the correct command name/update-platform-docs(or
vice‑versa if you rename the skill) so examples, usage text and the bash snippet
consistently refer to/update-platform-docs; ensure any mentions of "use
/platform-docs" are reconciled with the same name and that the documented
behavior (scanning ai-docs/, incremental updates, index/nav updates) remains
unchanged.In
@plugins/agentic-docs/skills/component/SKILL.md:
- Around line 461-468: Update the success output block in SKILL.md to align with
Phase 6 constraints by removing any mention of templates and the completed/
exec-plans directory (specifically remove "template, README, active/,
completed/" and any reference to "completed/"); also delete the entry
"ai-docs/exec-plans/template.md" from the example files list so no template file
is suggested; adjust the success output to only list allowed exec-plans (e.g.,
active/ and README if permitted by Phase 6) and ensure the Phase 6 rules and the
Success output are consistent.In
@plugins/agentic-docs/skills/platform/scripts/gap-detection.sh:
- Line 139: The remediation hint in gap-detection.sh currently echoes "Run
/update-docs to add missing content." which is the wrong command; update the
echo message in the script (the echo statement in
plugins/agentic-docs/skills/platform/scripts/gap-detection.sh) to use the
documented update skill name, e.g. "Run /update-platform-docs to add missing
content." (or the namespaced form used elsewhere) so users are routed to the
correct command.In
@plugins/agentic-docs/skills/platform/SKILL.md:
- Around line 475-478: The documentation references an incorrect filename
"OPENSHIFT_AGENTS.md" which conflicts with the rest of the spec; update the
execution flow and all occurrences in this section (the "Phase 2: Create
OPENSHIFT_AGENTS.md" heading and any mentions nearby) to use the consistent
filename "AGENTS.md", ensure the template reference still points to the correct
template, and adjust the validation step text ("Validate 150-170 lines") if
needed to match the AGENTS.md template length so the creation and validation
steps remain aligned.- Around line 417-421: The current line-count validation uses LINE_COUNT and an
if condition that checks for 80-220, which contradicts the documented target of
100-200; update the conditional around LINE_COUNT (the if block that references
AGENTS.md and theif [ $LINE_COUNT -gt 220 ] || [ $LINE_COUNT -lt 80 ]; then
check) to enforce the correct bounds (less than 100 or greater than 200) and
adjust the echo message to report the target range 100-200 so failures reflect
the documented policy.- Around line 353-355: The doc contains a contradiction: earlier text requires
workflows/exec-plans/* while the "Component work tracking" bullet forbids
exec-plans; reconcile by updating the SKILL.md content so both statements
align—either remove exec-plans from the forbidden list under "Component work
tracking" or change the earlier required reference to a different path. Edit the
"Component work tracking" section (the bullet starting with "❌ Component work
tracking") and the earlier mention of workflows/exec-plans/* so they
consistently allow or disallow exec-plans, and ensure the example (exec-plans)
matches the final policy language.- Around line 514-516: Resolve the conflict between "Mistake 3" and Phase 7 by
making a single canonical rule: update the SKILL.md text that currently reads
"Wrong: Creating fullworkflows/enhancement-process.mdduplicating
guidelines/enhancement_template.md" so it instead mandates creating
workflows/enhancement-process.mdas the canonical Phase 7 workflow (or
explicitly state thatworkflows/enhancement-process.mdmust exist and may
include a link toguidelines/enhancement_template.mdrather than a full
duplicate); ensure references to "Mistake 3", "Phase 7",
"workflows/enhancement-process.md", and "guidelines/enhancement_template.md" are
consistent and unambiguous.In
@plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md:
- Line 26: The navigation map in KNOWLEDGE_GRAPH.md contains inconsistent paths:
replace the malformed "agentic/ docs" entry with the correct "ai-docs/" path and
change any instances of "rbac-patterns.md" to "rbac.md" so they match the rest
of the plugin; update the row that currently reads "| Find a component |
references/repo-index.md | Component's AGENTS.md | Component's agentic/ docs |"
to use "Component's ai-docs/" and scan the file for any other occurrences of
"rbac-patterns.md" and "agentic/ docs" to rename them to "rbac.md" and
"ai-docs/" respectively.In
@plugins/agentic-docs/skills/update-platform-docs/SKILL.md:
- Line 77: The AGENTS.md line-count validation currently enforces only an upper
bound (≤200); change the validation so it enforces a range of 100-200 lines
(inclusive). Locate the check(s) that reference "Verify line count stays ≤200
lines" (and the equivalent checks at the other occurrences noted) and modify the
logic to fail when lines < 100 or > 200, update any error/warning messages to
state "AGENTS.md must be 100-200 lines", and adjust any tests or documentation
strings that expect only the upper bound.- Around line 116-117: The instructions currently create files named "README.md"
where your naming rules require "index.md"; update each occurrence of
workflows/exec-plans/README.md (and any other README.md mentions at the same
blocks such as the ones paired with template.md) to create
workflows/exec-plans/index.md instead, and adjust the related template
references (e.g., workflows/exec-plans/template.md) or wording so they
consistently refer to index.md; search for the exact string "README.md" in this
skill doc (including the listed occurrences around the template entries) and
replace with "index.md" to ensure compliance.
Outside diff comments:
In@plugins/agentic-docs/skills/component/scripts/validate.sh:
- Around line 89-90: The script ends with the line echo "✅ Validation complete"
but is missing a trailing newline; open
plugins/agentic-docs/skills/component/scripts/validate.sh and ensure the file
ends with a final newline character (add a newline after the echo "✅ Validation
complete" line) to make the file POSIX-compliant.In
@plugins/agentic-docs/skills/platform/scripts/discover.sh:
- Around line 46-47: The file ends with the line echo "✅ Discovery complete" but
is missing a trailing newline; update
plugins/agentic-docs/skills/platform/scripts/discover.sh (the final echo line)
to ensure the file terminates with a newline character by adding an empty
newline after that line so POSIX tools and editors handle it correctly.In
@plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh:
- Around line 96-97: The script ends with "exit $GAPS_FOUND" but is missing a
trailing newline at EOF; add a single newline character after the final line
(after the exit $GAPS_FOUND statement) so the file ends with a proper newline,
ensuring POSIX-compliant shell behavior and tools that expect a newline at EOF.In
@plugins/agentic-docs/skills/platform/scripts/populate-templates.sh:
- Around line 28-29: The file ends without a trailing newline after the final
echo statement ("Next: LLM creates remaining documentation files following
template patterns"); update the script to ensure it terminates with a single
newline character by adding a newline at EOF so POSIX tools and editors treat
the file as newline-terminated.In
@plugins/agentic-docs/skills/platform/scripts/validate.sh:
- Around line 152-153: The file ends with the shell block terminator "fi" but
lacks a trailing newline which can cause POSIX tools or linters to complain;
update plugins/agentic-docs/skills/platform/scripts/validate.sh by adding a
single newline character after the final "fi" (ensure the file ends with a
newline).In
@plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md:
- Around line 188-189: Add a missing trailing newline at end-of-file for the
README: ensure the last line containing the Markdown link "Component
Documentation
Guide"
in exec-plans-README.md ends with a newline character (EOF newline) so the file
terminates with a proper trailing newline.
Minor comments:
In@plugins/agentic-docs/skills/component/scripts/validate.sh:
- Around line 17-21: The current check in validate.sh only warns when LINE_COUNT
is greater than 100, but we need to warn when LINE_COUNT is outside the target
range 80-100; update the condition that references LINE_COUNT in the
AGENTS.md/SKILL.md validation to test if LINE_COUNT < 80 OR LINE_COUNT > 100 and
print a warning in that case, otherwise print the success message; keep the
variables and messages (LINE_COUNT, target: 80-100) but change the logical check
to an out-of-range check so files below 80 lines also trigger the warning.In
@plugins/agentic-docs/skills/component/SKILL.md:
- Around line 454-488: The fenced code block starting with
that contains the "✅ Component Documentation Created" summary in SKILL.md lacks a language specifier; update that opening fence (the triple backticks surrounding the block) to include a language token such as text or markdown (e.g., changetoviewers; locate the block by the visible content "✅ Component Documentation Created" and adjust the fence accordingly. - Around line 28-45: The fenced code block in SKILL.md containing the directory tree (the block starting with "component-repo/") lacks a language specifier and triggers MD040; update that fenced block to use a language tag of "text" (i.e., replace the opening ``` with ```text) so the directory tree is treated as plain text and the linter warning is resolved. - Around line 225-229: The fenced code block showing the directory tree starting with "ai-docs/exec-plans/" lacks a language specifier; edit SKILL.md and change the opening fence for that snippet (the triple backticks immediately before "ai-docs/exec-plans/") to include a language token such as ```text so the block is language-marked (e.g., replace ``` with ```text) and save the file. - Around line 158-169: The fenced code block in SKILL.md showing the ai-docs directory tree lacks a language specifier; update the opening fence (the ``` above the directory tree) to include a language like text (e.g., change ``` to ```text) so syntax highlighters render it correctly; locate the fenced block in plugins/agentic-docs/skills/component/SKILL.md where the ai-docs tree is defined and replace the fence accordingly. In `@plugins/agentic-docs/skills/component/templates/AGENTS-template.md`: - Around line 23-31: Update the two unlabeled fenced code blocks in AGENTS-template.md (the directory tree block and the ASCII diagram block) to include a language label (use "text") so markdownlint MD040 is satisfied; locate the triple-backtick fences around the ai-docs tree and the ASCII diagram and change them from ``` to ```text in both places. In `@plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md`: - Line 197: The "See Also" relative link is broken due to a stray space in the link target; locate the Markdown line containing the link text "[Testing Guide](./ [COMPONENT]_TESTING.md)" and remove the space after "./" so the target reads "./[COMPONENT]_TESTING.md" to produce a valid relative link. In `@plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md`: - Around line 14-17: The fenced code block in exec-plans-README-template.md that contains the directory layout (the block starting with "exec-plans/" and the comment "Create feature-specific exec-plans here") is missing a fence language marker; update the opening triple backticks to include a language (e.g., ```text) so the block complies with markdownlint MD040. In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md`: - Around line 11-17: The fenced ASCII diagram block in TESTING-template.md is missing a language specifier; update the opening triple-backtick for the diagram (the block starting with the ASCII pyramid "E2E Tests... Integration Tests... Unit Tests...") to include a language token such as text or plaintext (e.g., change ``` to ```text) and keep the closing triple-backticks as-is so the block is treated as plain text by static analysis and syntax highlighters. - Around line 167-174: The fenced code block that shows the directory tree (the block starting with "test/e2e/") in TESTING-template.md lacks a language specifier; update the opening fence from ``` to ```text so the directory tree is marked as plain text (i.e., replace the existing ``` before the tree with ```text and keep the closing ``` as-is). In `@plugins/agentic-docs/skills/platform/scripts/create-structure.sh`: - Line 16: The script currently creates the directory named by the mkdir call "$REPO_PATH/ai-docs/platform/openshift-specifics" which is not picked up by downstream discovery/gap checks; remove that mkdir invocation (or replace it to create "$REPO_PATH/ai-docs/platform/operator-patterns" instead) so created directories match the discovery target used by the gap-detection tools; update the mkdir usage in create-structure.sh (the line containing mkdir -p "$REPO_PATH/ai-docs/platform/openshift-specifics") accordingly. In `@plugins/agentic-docs/skills/platform/scripts/discover.sh`: - Around line 29-34: The for-loop that enumerates directories in discover.sh omits the directories created by create-structure.sh; update the Dir list in the loop that currently iterates over "platform/operator-patterns practices/testing practices/security practices/reliability practices/development domain/kubernetes domain/openshift decisions workflows references" to also include "platform/openshift-specifics" and "workflows/exec-plans" (the loop uses the REPO_PATH/ai-docs/$dir variable and COUNT with find, so simply add those two paths to the same list so they are discovered and counted). In `@plugins/agentic-docs/skills/platform/scripts/validate.sh`: - Around line 25-27: The range check in the validate.sh if statement that uses LINE_COUNT is mismatched with the warning text; update the conditional to match the intended 100-200 line range (replace "[ \"$LINE_COUNT\" -lt 80 ] || [ \"$LINE_COUNT\" -gt 220 ]" with a check for "< 100 || > 200") so the logic and the echo warning ("Should be 100-200 lines (current: $LINE_COUNT)") are consistent; alternatively, if 80-220 is actually intended, change the warning message to reflect "80-220" — adjust the if condition or the echo string around the LINE_COUNT check accordingly. In `@plugins/agentic-docs/skills/platform/templates/adr-template.md`: - Line 67: The References entry contains a mismatched link text and target ("[related-doc.md](./related.md)"); update the markdown so the visible text and href match (e.g., change to "[related.md](./related.md)" or change the target to "./related-doc.md") to ensure the link label and destination are consistent. In `@plugins/agentic-docs/skills/platform/templates/AGENTS.md`: - Around line 29-39: The fenced code block in AGENTS.md (the block starting with "[Repo Agentic Docs]|root:./ai-docs|...") lacks a language specifier and triggers markdownlint MD040; update the opening fence from ``` to include a language (e.g., ```text) so the block is annotated (modify the fenced code block in AGENTS.md that wraps the repo summary content). In `@plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md`: - Around line 27-31: The fenced code block showing the reconciliation example is missing a fence language; update the opening triple-backtick for the block that contains the three lines starting with 'User declares: "I want 3 replicas"' to include a language tag (e.g., change ``` to ```text) so the block is explicitly marked and MD040 warnings are resolved. In `@plugins/agentic-docs/skills/platform/templates/domain-concept-template.md`: - Around line 47-49: The unlabeled fenced code block containing "Step 1 → Step 2 → Step 3 → Step 4" in domain-concept-template.md triggers MD040; update that fence to include a language tag (e.g., use "text") so the block becomes a labeled code fence and the markdownlint rule passes—locate the fenced block with the exact content "Step 1 → Step 2 → Step 3 → Step 4" and prepend the fence with the language tag. In `@plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md`: - Around line 32-66: The fenced ASCII diagram blocks in KNOWLEDGE_GRAPH.md are unlabeled and trigger MD040; add a language tag (e.g., ```text) to every fenced block shown (the big diagram block containing DESIGN_PHILOSOPHY.md and the smaller blocks listing DESIGN_PHILOSOPHY.md, PLATFORM/, practices/testing/index.md, references, etc.) so each opening triple-backtick becomes ```text (or another appropriate literal language) and leave the closing backticks unchanged; update all occurrences referenced in the diff and the other blocks at the same sections (around the ASCII diagram and the blocks at lines ~73-83, 86-94, 97-103) to silence the MD040 lint. In `@plugins/agentic-docs/skills/update-platform-docs/SKILL.md`: - Around line 364-365: The "See Also" relative links in skills/update-platform-docs/SKILL.md are incorrect: update the link targets in the "See Also" section so they point to the repository-root SKILL.md and to the scripts/validate.sh under the platform docs context instead of using "../SKILL.md" and "../scripts/validate.sh"; locate the "See Also" block in SKILL.md and replace the two links (../SKILL.md and ../scripts/validate.sh) with correct relative paths that resolve from skills/update-platform-docs/SKILL.md to the actual files (e.g., ../../SKILL.md or ../../scripts/validate.sh or the appropriate repo-root-relative path) so the links open the intended documents. --- Nitpick comments: In `@plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md`: - Around line 33-52: The fenced repository-structure code block currently uses plain backticks (```) without a language tag; update the opening fence to include a language tag (e.g., change the opening ``` to ```text) so the block becomes a language-tagged fenced code block, ensuring markdownlint MD040 is satisfied and rendering is consistent for the repository-structure section shown in the template. In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md`: - Around line 180-208: Move the cleanup defer so it always runs even if assertions fail: immediately after creating the client/resource (in TestFeatureE2E), call defer client.Delete(ctx, resource) rather than placing it after require.NoError checks; ensure the defer appears right after client := framework.NewClient(t) or immediately after successful client.Create(...) so cleanup is guaranteed, and keep the require.NoError checks in place for Create and the wait.PollImmediate block. In `@plugins/agentic-docs/skills/platform/scripts/discover.sh`: - Around line 21-24: Replace the fragile ls pipeline used to set ADR_SAMPLE with a safer find-based search: use find on "$REPO_PATH/ai-docs/decisions" to locate the first regular file matching the glob pattern adr-*.md (e.g., find ... -maxdepth 1 -type f -name 'adr-*.md' -print -quit), assign that result to ADR_SAMPLE, keep the existing check if [ -n "$ADR_SAMPLE" ] and the echo that extracts the convention via basename and grep -oE '^adr-[0-9]+-' so the script handles filenames with special characters robustly. In `@plugins/agentic-docs/skills/platform/SKILL.md`: - Around line 127-143: The fenced code blocks in SKILL.md that show the repository tree (starting with the line "AGENTS.md" and the ai-docs/ tree block) are missing language tags, causing MD040 lint warnings; update those triple-backtick fences to include a language (e.g., ```text or ```bash) for each unlabeled block (including the blocks around the directory tree and the other occurrences called out in the review) so all fenced code blocks have explicit language tags while preserving the exact block content. In `@plugins/agentic-docs/skills/update-platform-docs/SKILL.md`: - Around line 314-337: The success-output fenced code block in SKILL.md (the block that starts with "✅ Platform Documentation Updated" and shows the repository/Changes/Validation/Next Steps) lacks a language tag; update that opening fence from ``` to a tagged fence such as ```text (or ```md) so markdownlint rule MD040 is satisfied, leaving the block contents unchanged and only modifying the opening backticks.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID:
d6266153-bc6d-4a08-8dab-b7f3fe8b1dd5📒 Files selected for processing (35)
.claude-plugin/marketplace.jsondocs/data.jsonplugins/agentic-docs/.claude-plugin/plugin.jsonplugins/agentic-docs/README.mdplugins/agentic-docs/skills/component/SKILL.mdplugins/agentic-docs/skills/component/scripts/create-structure.shplugins/agentic-docs/skills/component/scripts/validate.shplugins/agentic-docs/skills/component/templates/AGENTS-template.mdplugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.mdplugins/agentic-docs/skills/component/templates/TESTING-template.mdplugins/agentic-docs/skills/component/templates/adr-template.mdplugins/agentic-docs/skills/component/templates/domain-concept-template.mdplugins/agentic-docs/skills/component/templates/ecosystem-template.mdplugins/agentic-docs/skills/component/templates/exec-plans-README-template.mdplugins/agentic-docs/skills/platform/SKILL.mdplugins/agentic-docs/skills/platform/scripts/create-structure.shplugins/agentic-docs/skills/platform/scripts/discover.shplugins/agentic-docs/skills/platform/scripts/fill-gaps.shplugins/agentic-docs/skills/platform/scripts/gap-detection.shplugins/agentic-docs/skills/platform/scripts/populate-templates.shplugins/agentic-docs/skills/platform/scripts/validate.shplugins/agentic-docs/skills/platform/templates/AGENTS.mdplugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.mdplugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.mdplugins/agentic-docs/skills/platform/templates/adr-template.mdplugins/agentic-docs/skills/platform/templates/domain-concept-template.mdplugins/agentic-docs/skills/platform/templates/operator-pattern-template.mdplugins/agentic-docs/skills/platform/templates/practice-template.mdplugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.mdplugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.mdplugins/agentic-docs/skills/update-platform-docs/SKILL.mdplugins/agentic-docs/skills/update-platform-docs/scripts/discover.shplugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.shplugins/agentic-docs/skills/update-platform-docs/scripts/validate.shplugins/agentic-docs/skills/update-platform-docs/templates
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/agentic-docs/skills/component/SKILL.md`:
- Line 28: Add explicit language tags to the Markdown fenced code blocks that
currently have no language identifier to satisfy MD040 lint rules: update each
triple-backtick block in the SKILL.md content to use appropriate tags such as
```text, ```markdown, or ```bash depending on the block content (plain text,
Markdown snippets, or shell commands). Ensure each fenced block around examples
or commands (the instances noted in the review) is updated consistently so the
linter no longer reports MD040 warnings.
In `@plugins/agentic-docs/skills/component/templates/AGENTS-template.md`:
- Line 23: The two fenced code blocks (the directory tree block and the ASCII
graph block) are missing a language tag which fails markdownlint; update each
opening fence from ``` to include a language (e.g., ```text) so both fenced
blocks specify a language and satisfy the linter requirements.
- Around line 23-31: The ai-docs directory listing in AGENTS-template.md omits
the generated development and testing guides, causing missing navigation for
[COMPONENT]_DEVELOPMENT.md and [COMPONENT]_TESTING.md; update the template's
ai-docs tree to include entries for [COMPONENT]_DEVELOPMENT.md and
[COMPONENT]_TESTING.md (in the same root level as references/ecosystem.md) so
the generated output includes links to those generated guides and maintains
consistent navigation across the template.
In `@plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md`:
- Line 33: The code fence in the DEVELOPMENT-template.md "repository-structure"
example is missing a language identifier; update the triple-backtick fence (the
repository-structure code block) to use "text" (i.e., change ``` to ```text) so
markdownlint MD040 is satisfied and the block is explicitly marked as plain
text.
- Line 197: The Testing Guide markdown link contains an extra space after "./"
which breaks the relative link; update the link text "- [Testing Guide](./
[COMPONENT]_TESTING.md)" by removing the space so the target reads
"(./[COMPONENT]_TESTING.md)" (i.e., change the href to
"./[COMPONENT]_TESTING.md") to restore the correct relative path.
In
`@plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md`:
- Around line 14-17: The fenced code block showing the directory tree (the lines
containing "exec-plans/" and "└── active/") is missing a language tag and
triggers markdownlint MD040; update that fenced block in the
exec-plans-README-template.md to use the text language tag (i.e., change the
opening ``` to ```text) so the tree block is typed and linter-compliant.
In `@plugins/agentic-docs/skills/component/templates/TESTING-template.md`:
- Around line 11-17: Add the missing language specifier "text" to the
triple-backtick code fences that contain the diagram/tree (the block showing
"E2E Tests (10%, slow, comprehensive) ▲ Integration Tests (30%, medium) ▲ Unit
Tests (60%, fast, focused)") and the similar diagram at lines 167-174; locate
the code fences around those diagram strings and change the opening ``` to
```text so the markdown linter (MD040) recognizes them as plain text blocks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 8872fdc9-946a-47bb-a618-ab54fb94c924
📒 Files selected for processing (11)
docs/data.jsonplugins/agentic-docs/skills/component/SKILL.mdplugins/agentic-docs/skills/component/scripts/create-structure.shplugins/agentic-docs/skills/component/scripts/validate.shplugins/agentic-docs/skills/component/templates/AGENTS-template.mdplugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.mdplugins/agentic-docs/skills/component/templates/TESTING-template.mdplugins/agentic-docs/skills/component/templates/adr-template.mdplugins/agentic-docs/skills/component/templates/domain-concept-template.mdplugins/agentic-docs/skills/component/templates/ecosystem-template.mdplugins/agentic-docs/skills/component/templates/exec-plans-README-template.md
✅ Files skipped from review due to trivial changes (4)
- plugins/agentic-docs/skills/component/scripts/create-structure.sh
- plugins/agentic-docs/skills/component/templates/ecosystem-template.md
- plugins/agentic-docs/skills/component/templates/domain-concept-template.md
- plugins/agentic-docs/skills/component/templates/adr-template.md
🚧 Files skipped from review as they are similar to previous changes (2)
- plugins/agentic-docs/skills/component/scripts/validate.sh
- docs/data.json
Prashanth684
force-pushed
the
agentic-docs-ep
branch
from
a7f325b to
cde07cd
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/agentic-docs/skills/component/templates/AGENTS-template.md`:
- Line 35: The template currently points to a potentially missing file
(`exec-plans/README.md`) in the string "**Exec-Plans**: Use `active/` for new
features. See `exec-plans/README.md`."; update the template in
AGENTS-template.md to avoid a broken link by either replacing the file-specific
reference with a generic directory reference (e.g., "See `exec-plans/`") or by
adding a README file to the scaffold; ensure the edit touches the exact text
containing "Exec-Plans" / "`exec-plans/README.md`" so generated docs reference a
valid target.
In `@plugins/agentic-docs/skills/platform/scripts/gap-detection.sh`:
- Around line 124-128: The script only checks AGENTS_LINES > 200 and misses the
documented lower bound (100); update the conditional around AGENTS_LINES to also
detect when AGENTS.md is undersized (AGENTS_LINES < 100) and emit a warning
(e.g., "⚠️ AGENTS.md exists but is too short: X lines (target: ≥100)"), keep the
existing too-long warning for AGENTS_LINES > 200, and leave the middle range
(100–200) to print the success message; locate the block that references
AGENTS_LINES and the echo calls for AGENTS.md to implement this three-way
branch.
In `@plugins/agentic-docs/skills/platform/SKILL.md`:
- Around line 96-97: The checklist has conflicting requirements for exec-plans
using README.md vs index.md; pick one canonical filename (e.g., use index.md)
and make all entries consistent: replace references to
workflows/exec-plans/README.md with workflows/exec-plans/index.md, update the
template references (templates/workflows/exec-plans-README.md →
templates/workflows/exec-plans-index.md or remove if unused), and ensure the
other checklist items that mention exec-plans (the instances that currently
reference templates/workflows/exec-plan-template.md and the block that mandates
index.md) all match the chosen convention so the SKILL.md file is unambiguous.
- Line 127: Three fenced code blocks in SKILL.md currently use bare triple
backticks (```); update each opening fence to include an explicit language
identifier (e.g., ```bash, ```text, or ```json as appropriate) to satisfy
markdownlint MD040. Locate the three occurrences of ``` in the file and replace
them with the correct fenced-language markers that match the snippet content.
- Line 104: Replace the incorrect exec-plan path string
"agentic/exec-plans/active/" in the SKILL.md line reading "Actual exec-plans
live in Tier 2 component repos" with the ai-docs convention path
"agentic/ai-docs/exec-plans/active/"; update that literal and any other
occurrences in the same document to keep the `ai-docs/` convention consistent.
In `@plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md`:
- Line 32: The markdown file KNOWLEDGE_GRAPH.md contains four fenced code blocks
opened without a language identifier (causing MD040); update each unnamed
triple-backtick fence (the blocks at the four places flagged in the review) to
include a language token such as "text" (i.e., replace ``` with ```text for each
of those fenced blocks) so markdownlint passes and the blocks are properly
identified.
In `@plugins/agentic-docs/skills/update-platform-docs/SKILL.md`:
- Line 314: The fenced code block starting with ``` at Line 314 in SKILL.md is
missing a language identifier; update that opening fence to include the
appropriate language tag (e.g., ```json, ```yaml, ```bash, etc.) matching the
block contents so the markdown linter (MD040) is satisfied and the file stays
lint-clean.
- Line 120: The SKILL.md step that tells the agent to "Update structure in
platform/scripts/create-structure.sh" instructs edits to implementation scripts
(plugin code) during a docs-only update; remove or replace those directives so
the agent only updates documentation. Locate the two occurrences of the step
text "Update structure in platform/scripts/create-structure.sh" in SKILL.md and
change them to either (a) instruct the user to run the create-structure.sh
script locally (no agent edits), or (b) restrict the agent to modifying only
docs files (e.g., files under docs/ or the platform docs folder), thereby
preventing any automated edits to plugin implementation files.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 4e22c8dc-2e54-48c5-b916-e7ef1392af2d
📒 Files selected for processing (16)
docs/data.jsonplugins/agentic-docs/README.mdplugins/agentic-docs/skills/component/SKILL.mdplugins/agentic-docs/skills/component/scripts/create-structure.shplugins/agentic-docs/skills/component/scripts/validate.shplugins/agentic-docs/skills/component/templates/AGENTS-template.mdplugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.mdplugins/agentic-docs/skills/component/templates/TESTING-template.mdplugins/agentic-docs/skills/component/templates/adr-template.mdplugins/agentic-docs/skills/component/templates/domain-concept-template.mdplugins/agentic-docs/skills/component/templates/ecosystem-template.mdplugins/agentic-docs/skills/component/templates/exec-plans-README-template.mdplugins/agentic-docs/skills/platform/SKILL.mdplugins/agentic-docs/skills/platform/scripts/gap-detection.shplugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.mdplugins/agentic-docs/skills/update-platform-docs/SKILL.md
✅ Files skipped from review due to trivial changes (9)
- plugins/agentic-docs/skills/component/templates/domain-concept-template.md
- plugins/agentic-docs/skills/component/templates/ecosystem-template.md
- plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md
- plugins/agentic-docs/skills/component/templates/adr-template.md
- plugins/agentic-docs/skills/component/templates/TESTING-template.md
- plugins/agentic-docs/skills/component/scripts/create-structure.sh
- plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md
- plugins/agentic-docs/skills/component/SKILL.md
- plugins/agentic-docs/README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- plugins/agentic-docs/skills/component/scripts/validate.sh
- docs/data.json
Comment on lines
+124
to
+128
| if [ "$AGENTS_LINES" -gt 200 ]; then | ||
| echo "⚠️ AGENTS.md exists but is too long: $AGENTS_LINES lines (target: ≤200)" | ||
| else | ||
| echo "✅ AGENTS.md exists ($AGENTS_LINES lines)" | ||
| fi |
Contributor
There was a problem hiding this comment.
Also warn when AGENTS.md is below the minimum length.
Line [124] only checks >200. This misses the documented lower bound (100), so undersized navigation docs pass as complete.
Suggested fix
- if [ "$AGENTS_LINES" -gt 200 ]; then
- echo "⚠️ AGENTS.md exists but is too long: $AGENTS_LINES lines (target: ≤200)"
+ if [ "$AGENTS_LINES" -gt 200 ] || [ "$AGENTS_LINES" -lt 100 ]; then
+ echo "⚠️ AGENTS.md exists but length is out of range: $AGENTS_LINES lines (target: 100-200)"
else
echo "✅ AGENTS.md exists ($AGENTS_LINES lines)"
fi📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| if [ "$AGENTS_LINES" -gt 200 ]; then | |
| echo "⚠️ AGENTS.md exists but is too long: $AGENTS_LINES lines (target: ≤200)" | |
| else | |
| echo "✅ AGENTS.md exists ($AGENTS_LINES lines)" | |
| fi | |
| if [ "$AGENTS_LINES" -gt 200 ] || [ "$AGENTS_LINES" -lt 100 ]; then | |
| echo "⚠️ AGENTS.md exists but length is out of range: $AGENTS_LINES lines (target: 100-200)" | |
| else | |
| echo "✅ AGENTS.md exists ($AGENTS_LINES lines)" | |
| fi |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/agentic-docs/skills/platform/scripts/gap-detection.sh` around lines
124 - 128, The script only checks AGENTS_LINES > 200 and misses the documented
lower bound (100); update the conditional around AGENTS_LINES to also detect
when AGENTS.md is undersized (AGENTS_LINES < 100) and emit a warning (e.g., "⚠️
AGENTS.md exists but is too short: X lines (target: ≥100)"), keep the existing
too-long warning for AGENTS_LINES > 200, and leave the middle range (100–200) to
print the success message; locate the block that references AGENTS_LINES and the
echo calls for AGENTS.md to implement this three-way branch.
cde07cd to
cb4852b
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
plugins/agentic-docs/skills/platform/SKILL.md (1)
477-480:⚠️ Potential issue | 🟠 Major | ⚡ Quick winKeep the AGENTS.md target aligned with the rest of the file.
The execution flow still says
150-170lines, but the surrounding requirements all use100-200. That leaves two conflicting acceptance targets for the same file.Suggested fix
- → Validate 150-170 lines + → Validate 100-200 lines🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/agentic-docs/skills/platform/SKILL.md` around lines 477 - 480, The target line-count in the "Phase 2: Create AGENTS.md" execution flow is inconsistent (it currently says "150-170 lines") with the surrounding requirements that use "100-200"; update the AGENTS.md target text in SKILL.md (the "Phase 2: Create AGENTS.md" block) to "100-200 lines" so the acceptance criteria match the rest of the file.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/agentic-docs/skills/component/SKILL.md`:
- Around line 117-121: Phase 9's AGENTS.md validation currently only enforces an
upper bound (≤100) and misses the lower bound; update the validation in
SKILL_DIR/scripts/validate.sh (the AGENTS.md check) to enforce both 80 ≤ lines ≤
100 (i.e., count the lines of AGENTS.md and fail if less than 80 or greater than
100) so the script returns non-zero and logs a helpful error when the file is
too short or too long.
---
Duplicate comments:
In `@plugins/agentic-docs/skills/platform/SKILL.md`:
- Around line 477-480: The target line-count in the "Phase 2: Create AGENTS.md"
execution flow is inconsistent (it currently says "150-170 lines") with the
surrounding requirements that use "100-200"; update the AGENTS.md target text in
SKILL.md (the "Phase 2: Create AGENTS.md" block) to "100-200 lines" so the
acceptance criteria match the rest of the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 8ea4a25e-4e77-4bba-bb74-fe4c4e459206
📒 Files selected for processing (17)
docs/data.jsonplugins/agentic-docs/README.mdplugins/agentic-docs/skills/component/SKILL.mdplugins/agentic-docs/skills/component/scripts/create-structure.shplugins/agentic-docs/skills/component/scripts/validate.shplugins/agentic-docs/skills/component/templates/AGENTS-template.mdplugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.mdplugins/agentic-docs/skills/component/templates/TESTING-template.mdplugins/agentic-docs/skills/component/templates/adr-template.mdplugins/agentic-docs/skills/component/templates/domain-concept-template.mdplugins/agentic-docs/skills/component/templates/ecosystem-template.mdplugins/agentic-docs/skills/component/templates/exec-plans-README-template.mdplugins/agentic-docs/skills/platform/SKILL.mdplugins/agentic-docs/skills/platform/scripts/gap-detection.shplugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.mdplugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.mdplugins/agentic-docs/skills/update-platform-docs/SKILL.md
✅ Files skipped from review due to trivial changes (10)
- plugins/agentic-docs/skills/component/templates/adr-template.md
- plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md
- plugins/agentic-docs/skills/component/scripts/create-structure.sh
- plugins/agentic-docs/skills/component/templates/domain-concept-template.md
- plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md
- plugins/agentic-docs/skills/component/templates/ecosystem-template.md
- plugins/agentic-docs/skills/component/templates/TESTING-template.md
- plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md
- plugins/agentic-docs/skills/update-platform-docs/SKILL.md
- plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md
🚧 Files skipped from review as they are similar to previous changes (3)
- plugins/agentic-docs/skills/platform/scripts/gap-detection.sh
- plugins/agentic-docs/skills/component/scripts/validate.sh
- plugins/agentic-docs/README.md
Contributor
Author
|
/cc @stbenjam |
openshift-ci
Bot
added
the
needs-rebase
kenjpais
added a commit
to kenjpais/ai-helpers
that referenced
this pull request
May 8, 2026
Created templates for agentic documentation generation following the structure from openshift-eng#437: Templates added: - AGENTS.md.template (80-150 lines) - Navigation index with compressed docs tree - ARCHITECTURE.md.template (~200 lines) - Repository structure and code organization - DESIGN.md.template (~350 lines) - Design philosophy and principles - DEVELOPMENT.md.template (~280 lines) - Development setup and workflow - TESTING.md.template (~320 lines) - Test pyramid and execution guide Key features from PR openshift-eng#437: - Concise, scannable format with ASCII diagrams - Task-oriented quick maps ("Task → Docs" tables) - Retrieval-first emphasis (read docs, don't guess) - Progressive disclosure (link to details, don't duplicate) - AI-optimized structure Template placeholders: - Repository metadata: {REPOSITORY_NAME}, {PROJECT_NAME}, {LAST_UPDATED} - Metrics: {TOTAL_FILES}, {TOTAL_LINES}, {CURRENT_COVERAGE} - Content: {BUILD_COMMAND}, {TEST_COMMAND}, {REPO_TREE}, etc. Usage: File-specific generation skills will read templates, extract data from repository, replace placeholders, and write output. Reference: Adapted from PR openshift-eng#437 for generic repositories (not OpenShift-specific). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
kenjpais
added a commit
to kenjpais/ai-helpers
that referenced
this pull request
May 8, 2026
…lates
Modified generate-development-md/SKILL.md to use the template-based approach:
Changes:
- Added "Load Template" step to read DEVELOPMENT.md.template
- Added "Extract Repository Data" step with specific data sources
- Added "Replace Template Placeholders" with complete mapping table
- Documents 19 placeholders and their data sources
Template placeholders include:
- Project metadata: {PROJECT_NAME}, {REPOSITORY_NAME}
- Commands: {BUILD_COMMAND}, {TEST_COMMAND}, {LINT_COMMAND}, etc.
- Paths: {BUILD_OUTPUT_PATH}, {REPO_TREE}
- Descriptions: {CODE_ORGANIZATION_DETAILS}, {CI_BUILD_DESCRIPTION}
This follows the PR openshift-eng#437 pattern of:
1. Load template with placeholder syntax
2. Extract data from repository files (Makefile, README, package files)
3. Replace placeholders with actual values
4. Write final output
Next: Update remaining generation skills to follow this pattern.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
|
I've been using this in our SDLC pilot and it has been generating helpful context. |
Member
|
I used this to generate docs for sippy which it identified as a component. The docs seem reasonable to me overall. openshift/sippy#3506 However, the distinction isn't clear to me between "tier 1" and "tier 2" docs -- do you think it would be possible to have a single skill for agentic docs, and use progressive discovery to decide what kinds of docs are needed for what kind of repo? There could be ocp-specific things for operators, crd's etc, but also work in a generic repo to help guide the agent. WDYT? I've not been able to see if the docs are more useful than without, but this is a good case to try evals. e.g. compare fixing a bug with and without it. |
Contributor
Author
I've been debating removing the "Tier1" docs which are meant to be the overarching documentation which is generic to openshift - it is very specific to the enhancements repo and with this PR up: openshift/enhancements#1992, i doubt this skill will be very useful going forward as the docs are generated already. Once the enhancement PR merges, i'm going to remove it.
We are in the process of writing evals to check the usage of these docs, but this scenario is hard to evaluate - models like claude opus have great training data to be able to develop features/fix bugs on their own with little to no documentation as it is. |
Introduces tier-1 platform documentation skills for creating and maintaining AI-optimized documentation in openshift/enhancements. Skills: /agentic-docs:platform (/platform-docs): Creates tier-1 platform documentation with: - AGENTS.md navigation index - DESIGN_PHILOSOPHY.md and KNOWLEDGE_GRAPH.md - platform/, domain/, practices/, decisions/, workflows/, references/ - Automated discovery, structure creation, template population, and validation /agentic-docs:update-platform-docs (/update-platform-docs): Incrementally updates tier-1 documentation with: - Automatic gap detection (scans existing ai-docs/ for missing files) - Targeted additions without full regeneration - Smart navigation updates (auto-updates indexes and AGENTS.md) - Validation of naming conventions, line counts, and link integrity
Prashanth684
force-pushed
the
agentic-docs-ep
branch
from
cb4852b to
b0868c9
Compare
openshift-ci
Bot
removed
the
needs-rebase
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (2)
plugins/agentic-docs/skills/platform/SKILL.md (2)
104-104:⚠️ Potential issue | 🟠 Major | ⚡ Quick winCorrect exec-plan location path at Line [104].
This path conflicts with the rest of the document (
workflows/exec-plans/...) and can send generated content to the wrong location.Proposed fix
-- Actual exec-plans live in Tier 2 component repos (`ai-docs/exec-plans/active/`) +- Actual exec-plans live in Tier 2 component repos (`ai-docs/workflows/exec-plans/active/`)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plugins/agentic-docs/skills/platform/SKILL.md` at line 104, Replace the incorrect path string "ai-docs/exec-plans/active/" in the SKILL.md sentence that currently reads "Actual exec-plans live in Tier 2 component repos (`ai-docs/exec-plans/active/`)" with the consistent path used elsewhere: "workflows/exec-plans/active/"; update the `Actual exec-plans live in Tier 2 component repos (...)` line so it references `workflows/exec-plans/active/` instead of `ai-docs/exec-plans/active/`.
477-480:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFix AGENTS.md line-count inconsistency in execution flow.
Line [479] says 150–170, but the skill policy elsewhere requires 100–200. Keep one canonical range.
Proposed fix
Phase 2: Create AGENTS.md → Use template reference - → Validate 150-170 lines + → Validate 100-200 lines🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plugins/agentic-docs/skills/platform/SKILL.md` around lines 477 - 480, Update the inconsistent line-count range in the Phase 2 AGENTS.md creation text: replace the "150–170" range (noted at line [479] in SKILL.md under "Phase 2: Create AGENTS.md") with the canonical "100–200" used by the skill policy; ensure any template reference or validation text in the same block that mentions the line-count uses the unified "100–200" range so AGENTS.md and the skill policy match.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plugins/agentic-docs/skills/platform/scripts/fill-gaps.sh`:
- Line 41: The file counting line using grep -v index.md undercounts files like
api-index.md; update the count calculation that sets the variable count to have
find exclude only the exact file name index.md (e.g., add a -not -name
'index.md' to the find invocation that builds count) instead of piping through
grep -v, keeping the same variables AI_DOCS, dir and pattern and preserving the
2>/dev/null error suppression and wc -l tailing.
In `@plugins/agentic-docs/skills/platform/scripts/validate.sh`:
- Around line 25-27: Update the bounds in the validate.sh check so they match
the documented 100–200 line policy: change the conditional that uses LINE_COUNT
(the if [ "$LINE_COUNT" -lt 80 ] || [ "$LINE_COUNT" -gt 220 ] check) to use 100
and 200 as the lower and upper limits and update the echo message to state
"Should be 100-200 lines (current: $LINE_COUNT)"; ensure you only modify the
conditional and the warning string that reference LINE_COUNT.
In `@plugins/agentic-docs/skills/platform/templates/AGENTS.md`:
- Around line 29-39: The fenced code block in AGENTS.md (the repository index
snippet starting with "[Repo Agentic Docs]|root:./ai-docs|XX files, XXXX lines")
is missing a language tag and triggers MD040; update that block to use the
"text" language tag by changing the opening fence from ``` to ```text so the
snippet is typed correctly.
In `@plugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.md`:
- Around line 27-31: The fenced code block containing the reconciliation example
is missing a language tag; update the block in DESIGN_PHILOSOPHY.md (the
three-line example starting with "User declares: 'I want 3 replicas'") to use a
text fence by adding ```text at the opening fence so the block becomes fenced as
text and avoids the MD040 warning.
In `@plugins/agentic-docs/skills/platform/templates/domain-concept-template.md`:
- Around line 47-49: The fenced code block showing the lifecycle "Step 1 → Step
2 → Step 3 → Step 4" lacks a language tag; update that fenced block in
domain-concept-template.md (the lifecycle snippet at Line 47) to use the "text"
fence language so markdownlint passes and formatting remains consistent (i.e.,
change ``` to ```text for that snippet).
---
Duplicate comments:
In `@plugins/agentic-docs/skills/platform/SKILL.md`:
- Line 104: Replace the incorrect path string "ai-docs/exec-plans/active/" in
the SKILL.md sentence that currently reads "Actual exec-plans live in Tier 2
component repos (`ai-docs/exec-plans/active/`)" with the consistent path used
elsewhere: "workflows/exec-plans/active/"; update the `Actual exec-plans live in
Tier 2 component repos (...)` line so it references
`workflows/exec-plans/active/` instead of `ai-docs/exec-plans/active/`.
- Around line 477-480: Update the inconsistent line-count range in the Phase 2
AGENTS.md creation text: replace the "150–170" range (noted at line [479] in
SKILL.md under "Phase 2: Create AGENTS.md") with the canonical "100–200" used by
the skill policy; ensure any template reference or validation text in the same
block that mentions the line-count uses the unified "100–200" range so AGENTS.md
and the skill policy match.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 3d586e2f-6a94-45bb-8b73-6da8316d8b74
📒 Files selected for processing (35)
.claude-plugin/marketplace.jsondocs/data.jsonplugins/agentic-docs/.claude-plugin/plugin.jsonplugins/agentic-docs/README.mdplugins/agentic-docs/skills/component/SKILL.mdplugins/agentic-docs/skills/component/scripts/create-structure.shplugins/agentic-docs/skills/component/scripts/validate.shplugins/agentic-docs/skills/component/templates/AGENTS-template.mdplugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.mdplugins/agentic-docs/skills/component/templates/TESTING-template.mdplugins/agentic-docs/skills/component/templates/adr-template.mdplugins/agentic-docs/skills/component/templates/domain-concept-template.mdplugins/agentic-docs/skills/component/templates/ecosystem-template.mdplugins/agentic-docs/skills/component/templates/exec-plans-README-template.mdplugins/agentic-docs/skills/platform/SKILL.mdplugins/agentic-docs/skills/platform/scripts/create-structure.shplugins/agentic-docs/skills/platform/scripts/discover.shplugins/agentic-docs/skills/platform/scripts/fill-gaps.shplugins/agentic-docs/skills/platform/scripts/gap-detection.shplugins/agentic-docs/skills/platform/scripts/populate-templates.shplugins/agentic-docs/skills/platform/scripts/validate.shplugins/agentic-docs/skills/platform/templates/AGENTS.mdplugins/agentic-docs/skills/platform/templates/DESIGN_PHILOSOPHY.mdplugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.mdplugins/agentic-docs/skills/platform/templates/adr-template.mdplugins/agentic-docs/skills/platform/templates/domain-concept-template.mdplugins/agentic-docs/skills/platform/templates/operator-pattern-template.mdplugins/agentic-docs/skills/platform/templates/practice-template.mdplugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.mdplugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.mdplugins/agentic-docs/skills/update-platform-docs/SKILL.mdplugins/agentic-docs/skills/update-platform-docs/scripts/discover.shplugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.shplugins/agentic-docs/skills/update-platform-docs/scripts/validate.shplugins/agentic-docs/skills/update-platform-docs/templates
✅ Files skipped from review due to trivial changes (16)
- plugins/agentic-docs/.claude-plugin/plugin.json
- plugins/agentic-docs/skills/update-platform-docs/scripts/validate.sh
- plugins/agentic-docs/skills/platform/templates/practice-template.md
- plugins/agentic-docs/README.md
- plugins/agentic-docs/skills/update-platform-docs/templates
- plugins/agentic-docs/skills/component/templates/adr-template.md
- plugins/agentic-docs/skills/platform/templates/operator-pattern-template.md
- plugins/agentic-docs/skills/platform/templates/adr-template.md
- plugins/agentic-docs/skills/update-platform-docs/scripts/discover.sh
- plugins/agentic-docs/skills/platform/templates/workflows/exec-plans-README.md
- plugins/agentic-docs/skills/component/templates/ecosystem-template.md
- plugins/agentic-docs/skills/platform/templates/KNOWLEDGE_GRAPH.md
- plugins/agentic-docs/skills/component/templates/exec-plans-README-template.md
- plugins/agentic-docs/skills/component/templates/TESTING-template.md
- plugins/agentic-docs/skills/component/templates/AGENTS-template.md
- plugins/agentic-docs/skills/component/templates/DEVELOPMENT-template.md
🚧 Files skipped from review as they are similar to previous changes (12)
- plugins/agentic-docs/skills/platform/templates/workflows/exec-plan-template.md
- plugins/agentic-docs/skills/update-platform-docs/scripts/gap-detection.sh
- plugins/agentic-docs/skills/component/scripts/validate.sh
- plugins/agentic-docs/skills/component/scripts/create-structure.sh
- plugins/agentic-docs/skills/component/templates/domain-concept-template.md
- plugins/agentic-docs/skills/platform/scripts/gap-detection.sh
- plugins/agentic-docs/skills/component/SKILL.md
- plugins/agentic-docs/skills/update-platform-docs/SKILL.md
- plugins/agentic-docs/skills/platform/scripts/create-structure.sh
- plugins/agentic-docs/skills/platform/scripts/populate-templates.sh
- docs/data.json
- .claude-plugin/marketplace.json
Prashanth684
force-pushed
the
agentic-docs-ep
branch
2 times, most recently
from
439a492 to
3cad8e8
Compare
Introduces tier-2 lean component documentation skill for creating structured component-level documentation in OpenShift repositories. Skills: /agentic-docs:component (/component-docs): Creates tier-2 lean component documentation with: - Component-specific CRDs and architecture only - Pointers to tier-1 for generic patterns - Component ADRs and exec-plan tracking - AGENTS.md entry point - DEVELOPMENT.md and TESTING.md guides - Domain concepts and ecosystem maps
Prashanth684
force-pushed
the
agentic-docs-ep
branch
from
3cad8e8 to
198f3c2
Compare
Contributor
Author
kenjpais
added a commit
to kenjpais/ai-helpers
that referenced
this pull request
May 13, 2026
Created templates for agentic documentation generation following the structure from openshift-eng#437: Templates added: - AGENTS.md.template (80-150 lines) - Navigation index with compressed docs tree - ARCHITECTURE.md.template (~200 lines) - Repository structure and code organization - DESIGN.md.template (~350 lines) - Design philosophy and principles - DEVELOPMENT.md.template (~280 lines) - Development setup and workflow - TESTING.md.template (~320 lines) - Test pyramid and execution guide Key features from PR openshift-eng#437: - Concise, scannable format with ASCII diagrams - Task-oriented quick maps ("Task → Docs" tables) - Retrieval-first emphasis (read docs, don't guess) - Progressive disclosure (link to details, don't duplicate) - AI-optimized structure Template placeholders: - Repository metadata: {REPOSITORY_NAME}, {PROJECT_NAME}, {LAST_UPDATED} - Metrics: {TOTAL_FILES}, {TOTAL_LINES}, {CURRENT_COVERAGE} - Content: {BUILD_COMMAND}, {TEST_COMMAND}, {REPO_TREE}, etc. Usage: File-specific generation skills will read templates, extract data from repository, replace placeholders, and write output. Reference: Adapted from PR openshift-eng#437 for generic repositories (not OpenShift-specific). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
kenjpais
added a commit
to kenjpais/ai-helpers
that referenced
this pull request
May 13, 2026
…lates
Modified generate-development-md/SKILL.md to use the template-based approach:
Changes:
- Added "Load Template" step to read DEVELOPMENT.md.template
- Added "Extract Repository Data" step with specific data sources
- Added "Replace Template Placeholders" with complete mapping table
- Documents 19 placeholders and their data sources
Template placeholders include:
- Project metadata: {PROJECT_NAME}, {REPOSITORY_NAME}
- Commands: {BUILD_COMMAND}, {TEST_COMMAND}, {LINT_COMMAND}, etc.
- Paths: {BUILD_OUTPUT_PATH}, {REPO_TREE}
- Descriptions: {CODE_ORGANIZATION_DETAILS}, {CI_BUILD_DESCRIPTION}
This follows the PR openshift-eng#437 pattern of:
1. Load template with placeholder syntax
2. Extract data from repository files (Makefile, README, package files)
3. Replace placeholders with actual values
4. Write final output
Next: Update remaining generation skills to follow this pattern.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Prashanth684
changed the title
Prashanth684
force-pushed
the
agentic-docs-ep
branch
2 times, most recently
from
962f124 to
417521d
Compare
openshift-ci
Bot
added
the
do-not-merge/invalid-owners-file
Platform documentation in openshift/enhancements/ai-docs/ already exists and was created using this skill. Remove the /platform-docs skill that was designed to create it from scratch - it's no longer needed. Changes: - Remove entire skills/platform/ directory - Keep /update-platform-docs for incremental updates to existing platform docs - Keep /component-docs for creating component-level documentation - Update README to clarify platform docs "already exist" - Simplify tier architecture description (tier-1/tier-2 → platform/component) - Update component skill templates to reference "platform docs" consistently - Update validation scripts to remove platform-specific checks - Remove platform-docs from marketplace registration This simplifies the plugin to focus on its two active use cases: 1. Creating new component documentation (/component-docs) 2. Updating existing platform documentation (/update-platform-docs)
Prashanth684
force-pushed
the
agentic-docs-ep
branch
from
417521d to
bbb32c3
Compare
|
The OWNERS file contains untrusted users, which makes it INVALID. The following users are mentioned in OWNERS file(s) but are untrusted for the following reasons. One way to make the user trusted is to add them as members of the openshift-eng org. You can then trigger verification by writing
|
openshift-ci
Bot
added
the
needs-rebase
|
PR needs rebase. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
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
3 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 agentic-docs plugin: platform and component level documentation
Introduces platform (enhancements repo) and component documentation skills for creating and maintaining
AI-optimized documentation in openshift/enhancements.
Platform docs have already been generated n enhancements repo: openshift/enhancements#1992
Skills:
/agentic-docs:update-platform-docs (/update-platform-docs):
Incrementally updates enhancements repo documentation with:
- Automatic gap detection (scans existing ai-docs/ for missing files)
- Targeted additions without full regeneration
- Smart navigation updates (auto-updates indexes and AGENTS.md)
- Validation of naming conventions, line counts, and link integrity
/agentic-docs:component (/component-docs):
Creates component documentation with:
- Component-specific CRDs and architecture only
- Pointers to platforma agentic docs for generic patterns
- Component ADRs and exec-plan tracking
- AGENTS.md entry point
- DEVELOPMENT.md and TESTING.md guides
- Domain concepts and ecosystem maps
Summary by CodeRabbit
New Features
Documentation