OPCT-419: Add AI agentic assets for SDLC and Review modes#216
Open
mtulio wants to merge 1 commit into
Open
Conversation
Add comprehensive AI/LLM development instructions and tools for OPCT project: **CLAUDE.md enhancements:** - Go version bump procedure with all file locations - Dependency management (SBOM optimization, k8s/OpenShift client updates) - Retry logic implementation pattern for validations - Release process (CLI and plugins) with branch strategy - Web UI report development guide - AI attribution requirements for SDLC traceability **Agents (.claude/agents/):** - ci-triage: Automated CI failure analysis and Jira bug filing - opct-developer: General OPCT development assistant - pr-reviewer: Code review and PR feedback - webui-developer: Web UI and Vue.js development **Skills (.claude/skills/):** - ci-triage: Triage OPCT periodic job failures with Jira integration - e2e-quick-test: Rapid live cluster validation workflow - go-validate: Standard validation checklist (tidy, build, test, vet) - jira-ops: Common Jira operations for OPCT project - opct-runtime: Plugin runtime architecture and debugging - webui-chat-debug: Chat backend troubleshooting - webui-report-test: Report generation and browser testing **Key features:** - Comprehensive development procedures with exact commands - Common pitfalls and troubleshooting guides - Validation checklists for all changes - AI SDLC traceability (required bot signatures) - Project-specific patterns and conventions Total additions: 1340 lines across 12 files Relates to: OPCT-419 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
📝 WalkthroughWalkthroughThis pull request adds comprehensive AI agent and skill documentation for the OPCT project, establishing standardized workflows for CI failure triage, developer operations, PR review, web UI development, and runtime diagnostics. It includes agent instruction documents, step-by-step skill guides with tool configurations, and updates central project documentation with revised AI attribution requirements and new development guidance. ChangesClaude Agent Instructions and Operational Skills
🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Collaborator
Author
|
cc @rvanderp3 @bshaw7 getting started with claude instructions to ag-sdlc on opct project. (please help me reviewing it if you get a chance :) thanks ) |
Collaborator
Author
|
Waiting for whole human review. /hold |
openshift-ci
Bot
added
the
do-not-merge/hold
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
.claude/agents/pr-reviewer.md (1)
45-45: ⚡ Quick winAlign validation command with the shared Go validation workflow.
Step 4 should include
go mod tidybefore build/test/vet to match.claude/skills/go-validate/SKILL.mdand catch dependency drift consistently.Suggested update
-4. Run `make build && make test && make vet` to verify +4. Run `go mod tidy && make build && make test && make vet` to verify🤖 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 @.claude/agents/pr-reviewer.md at line 45, Step 4 currently runs "make build && make test && make vet" but omits running dependency hygiene; update the step text to run "go mod tidy" before the build/test/vet sequence so it aligns with the shared Go validation workflow (per .claude/skills/go-validate/SKILL.md) — modify the Step 4 line to include "go mod tidy &&" preceding the existing "make build && make test && make vet" command.
🤖 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 @.claude/agents/ci-triage.md:
- Line 96: Clarify and reconcile the conflicting bug-filing policy by making the
behavior consistent: update the phrase "For NEW_FAILURE items, prepare a bug
draft using these fields. **Do NOT file automatically — present the draft and
ask the user for approval.**" to align with the MCP wording, or alternatively
change the MCP-related lines that currently refer to "auto-filing" so they state
that MCP is required only when auto-filing is enabled and that by default agents
must present a draft for user approval; ensure both the "NEW_FAILURE"
instruction and the MCP section use the same approval-gated language (mentioning
"present the draft and ask the user for approval") and remove any language
implying mandatory auto-creation to eliminate ambiguity.
In @.claude/agents/opct-developer.md:
- Line 74: Replace the naked rm -rf instruction with a scoped REPORT_DIR
variable and a safety check: set REPORT_DIR to an explicit concrete path (e.g.
"${PWD}/build/report"), assert it is non-empty and not "/" (or other dangerous
roots) before deleting, and only then run rm -rf "${REPORT_DIR}". Update the doc
text that currently mentions `rm -rf the report dir` to reference the REPORT_DIR
variable and the safety checks so copy/paste usage is guarded.
In @.claude/agents/pr-reviewer.md:
- Line 17: The branch-name checklist item "- [ ] Branch naming follows
convention (`feature/`, `fix/`, `dev/`)" is too restrictive; update the rule to
reference the canonical branch strategy in CLAUDE.md (or accept a broader regex)
instead of hardcoding only those prefixes. Replace the hardcoded prefixes with a
reference note like "see CLAUDE.md for branch naming" or expand the allowed
pattern to include ticket-style prefixes (e.g., /^[A-Z]+-\d+-/ or configurable
list) so branches like OPCT-419-agentic-assets pass; ensure the checklist text
and any validation comment reflect this change.
In @.claude/agents/webui-developer.md:
- Around line 73-85: Update the CDN dependency table to pin exact versions and
make it match actual template usage: replace ambiguous entries "Vue.js 2.x",
"Bootstrap latest", "BootstrapVue latest", and "axios latest" with concrete
version numbers used by the templates (or choose locked versions and note the
upgrade policy), and either add Chart.js, chartjs-adapter-date-fns, Hammer.js,
chartjs-plugin-zoom, and marked.js to the table if you will load them in
data/templates/report/report.html and data/templates/report/filter.html or
remove them from the table if those templates do not include them; ensure the
doc references the exact script tags/versions used in report.html and
filter.html (e.g., mention bootstrap-vue@X.Y.Z, vue@X.Y.Z, axios@A.B.C) so the
documentation and templates remain consistent.
In @.claude/skills/ci-triage/SKILL.md:
- Around line 72-75: The document mixes two Jira target projects—jira:ocpbugs
(OCPBUGS) and OPCT—causing conflicting routing; pick the correct canonical
project and update every reference to it (search for literal strings
"jira:ocpbugs", "OCPBUGS", and "OPCT" in the "Bug Draft (pending approval)"
section and elsewhere) so all templates and examples consistently use the chosen
project; ensure the Jira project value used in the bug template metadata and any
example ticket titles/comments are replaced accordingly and run a quick grep to
confirm no remaining contradictory references.
In @.claude/skills/go-validate/SKILL.md:
- Around line 48-51: Update the remediation for the "no required module provides
package" entry so it does not recommend `@latest`; instead instruct to add the
dependency with an explicit, reproducible version (for example `go get
<package>`@vX.Y.Z`` or a project-aligned major/minor like `@vX.Y`) and then run
`go mod tidy`; modify the line that currently suggests `go get <package>`@latest``
in the `no required module provides package` row to recommend specifying a
fixed/versioned reference to keep builds reproducible.
In @.claude/skills/jira-ops/SKILL.md:
- Line 36: The doc currently instructs asking users for a Jira credentials file
path; remove that prompt and instead require pre-configured auth via environment
variables or approved secret manager. Update SKILL.md text (the sentence that
reads "If credentials are not exported, ask the user where their Jira
credentials file is located.") to reject ad-hoc file prompts and add a clear
instruction to set JIRA_USERNAME and JIRA_API_TOKEN (or follow the org
secret-manager flow) before running fallback commands; also add guidance to
abort with a descriptive error message when those env vars are missing rather
than prompting for file input.
In @.claude/skills/webui-chat-debug/SKILL.md:
- Around line 29-33: The doc currently shows shell commands that print sensitive
environment variable values (e.g., using echo on GOOGLE_CLOUD_LOCATION,
ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION, GOOGLE_CLOUD_PROJECT, and
ANTHROPIC_API_KEY); update the guidance to use non-revealing presence checks
instead (describe using conditional tests or tools that check existence/exit
status without echoing values), and replace the explicit echo examples with
statements that only verify presence/absence of each variable for Vertex AI and
Anthropic API credential checks.
- Around line 37-46: Update the example curl invocation to use unbuffered mode
so SSE events are emitted immediately: add the -N (or --no-buffer) flag to the
curl command in the chat example (the line starting with curl -s -X POST ... -d
'{"message": "hello", "history": []}'). Keep the rest of the pipeline (2>&1 |
head -20) intact and ensure the README/SKILL.md example text still shows the
expected SSE output lines like "event: text" and "data: Hello...".
---
Nitpick comments:
In @.claude/agents/pr-reviewer.md:
- Line 45: Step 4 currently runs "make build && make test && make vet" but omits
running dependency hygiene; update the step text to run "go mod tidy" before the
build/test/vet sequence so it aligns with the shared Go validation workflow (per
.claude/skills/go-validate/SKILL.md) — modify the Step 4 line to include "go mod
tidy &&" preceding the existing "make build && make test && make vet" command.
🪄 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: Organization UI
Review profile: CHILL
Plan: Enterprise
Run ID: 8d0c6328-fa21-4f74-9197-bef58e50b702
📒 Files selected for processing (12)
.claude/agents/ci-triage.md.claude/agents/opct-developer.md.claude/agents/pr-reviewer.md.claude/agents/webui-developer.md.claude/skills/ci-triage/SKILL.md.claude/skills/e2e-quick-test/SKILL.md.claude/skills/go-validate/SKILL.md.claude/skills/jira-ops/SKILL.md.claude/skills/opct-runtime/SKILL.md.claude/skills/webui-chat-debug/SKILL.md.claude/skills/webui-report-test/SKILL.mdCLAUDE.md
|
|
||
| ### Step 8: Draft Jira bug | ||
|
|
||
| For NEW_FAILURE items, prepare a bug draft using these fields. **Do NOT file automatically — present the draft and ask the user for approval.** |
There was a problem hiding this comment.
Resolve conflicting bug-filing policy (approval-gated vs auto-filing).
Line 96 requires explicit user approval before filing, but Line 176-179 frames MCP as required for auto-filing. This ambiguity can lead to unintended issue creation behavior by agents.
Suggested doc fix
-### Jira MCP Server (required for auto-filing bugs)
+### Jira MCP Server (required for filing after user approval)
...
-The Jira MCP server must be configured for the agent to file bugs automatically. Set it up with:
+The Jira MCP server must be configured so the agent can file bugs *after explicit user approval*. Set it up with:Also applies to: 176-179
🤖 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 @.claude/agents/ci-triage.md at line 96, Clarify and reconcile the
conflicting bug-filing policy by making the behavior consistent: update the
phrase "For NEW_FAILURE items, prepare a bug draft using these fields. **Do NOT
file automatically — present the draft and ask the user for approval.**" to
align with the MCP wording, or alternatively change the MCP-related lines that
currently refer to "auto-filing" so they state that MCP is required only when
auto-filing is enabled and that by default agents must present a draft for user
approval; ensure both the "NEW_FAILURE" instruction and the MCP section use the
same approval-gated language (mentioning "present the draft and ask the user for
approval") and remove any language implying mandatory auto-creation to eliminate
ambiguity.
| ## Testing OPCT Report Changes | ||
|
|
||
| See the `webui-report-test` skill for the build-regenerate-serve workflow. | ||
| Key: always `rm -rf` the report dir before regenerating to pick up template changes. |
There was a problem hiding this comment.
Scope the destructive cleanup command to a concrete path.
rm -rf is documented without a guarded path pattern, which is risky for copy/paste usage. Please provide an explicit directory variable and safety check before deletion.
Suggested doc hardening
-Key: always `rm -rf` the report dir before regenerating to pick up template changes.
+Key: always remove only the explicit report output dir before regenerating (never run unscoped `rm -rf`).
+Example:
+```bash
+REPORT_DIR="${PWD}/build/report"
+test -n "${REPORT_DIR}" && test "${REPORT_DIR}" != "/" && rm -rf "${REPORT_DIR}"
+```As per coding guidelines "**: Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
📝 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
| Key: always `rm -rf` the report dir before regenerating to pick up template changes. | |
| Key: always remove only the explicit report output dir before regenerating (never run unscoped `rm -rf`). | |
| Example: |
🤖 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 @.claude/agents/opct-developer.md at line 74, Replace the naked rm -rf
instruction with a scoped REPORT_DIR variable and a safety check: set REPORT_DIR
to an explicit concrete path (e.g. "${PWD}/build/report"), assert it is
non-empty and not "/" (or other dangerous roots) before deleting, and only then
run rm -rf "${REPORT_DIR}". Update the doc text that currently mentions `rm -rf
the report dir` to reference the REPORT_DIR variable and the safety checks so
copy/paste usage is guarded.
| ### Project Conventions | ||
| - [ ] Commit messages follow Conventional Commits (`feat:`, `fix:`, `docs:`, etc.) | ||
| - [ ] AI sign-off present on all AI-generated commits and comments | ||
| - [ ] Branch naming follows convention (`feature/`, `fix/`, `dev/`) |
There was a problem hiding this comment.
Branch naming rule is likely too restrictive for this repo.
This enforces only feature/, fix/, dev/, but current project usage includes branch patterns like OPCT-419-agentic-assets. This will generate false review failures and reduce trust in the agent.
Consider referencing the canonical branch strategy in CLAUDE.md instead of hardcoding a narrow prefix list.
🤖 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 @.claude/agents/pr-reviewer.md at line 17, The branch-name checklist item "-
[ ] Branch naming follows convention (`feature/`, `fix/`, `dev/`)" is too
restrictive; update the rule to reference the canonical branch strategy in
CLAUDE.md (or accept a broader regex) instead of hardcoding only those prefixes.
Replace the hardcoded prefixes with a reference note like "see CLAUDE.md for
branch naming" or expand the allowed pattern to include ticket-style prefixes
(e.g., /^[A-Z]+-\d+-/ or configurable list) so branches like
OPCT-419-agentic-assets pass; ensure the checklist text and any validation
comment reflect this change.
Comment on lines
+73
to
+85
| ## CDN Libraries (loaded in report.html head) | ||
|
|
||
| | Library | Version | Purpose | | ||
| |---------|---------|---------| | ||
| | Vue.js | 2.x | Frontend framework | | ||
| | Bootstrap | latest | Layout and components | | ||
| | BootstrapVue | latest | Vue Bootstrap components | | ||
| | axios | latest | HTTP client | | ||
| | Chart.js | 4.4.9 | Charts (etcd page) | | ||
| | chartjs-adapter-date-fns | 3.0.0 | Time-series X axis | | ||
| | Hammer.js | 2.0.8 | Touch gestures for zoom | | ||
| | chartjs-plugin-zoom | 2.2.0 | Drag-to-zoom, pan | | ||
| | marked.js | 15.0.7 | Markdown rendering (chat) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# 1) Show the referenced section with line numbers
sed -n '60,100p' .claude/agents/webui-developer.md
# 2) Check for the listed CDN libraries elsewhere in the repo
rg -n --hidden --no-ignore-vcs -S "Vue\.js|BootstrapVue|Bootstrap|axios|Chart\.js|chartjs-adapter-date-fns|Hammer\.js|chartjs-plugin-zoom|marked\.js" . \
|| true
# 3) Specifically search for "latest" and "2.x" usage in that file
rg -n --hidden --no-ignore-vcs -S "(^|[^A-Za-z0-9_.-])(latest|2\.x|2\.X)([^A-Za-z0-9_.-]|$)" .claude/agents/webui-developer.md || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 6999
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the CDN script/style tags in report.html and filter.html
for f in data/templates/report/report.html data/templates/report/filter.html; do
echo "==== $f (head scripts) ===="
# show lines near unpkg/script tags and also around head start
rg -n "unpkg\.com|cdnjs\.|bootstrap|vue|axios|chart\.js|hammer\.js|marked\.js" "$f" || true
sed -n '1,80p' "$f" | cat
echo
done
# Look for any existing "pin", "pinned", "lock", or "version" policy in docs
rg -n --hidden --no-ignore-vcs -S "(pin(ned)?|lock(ed)?|version(ed)?|unpkg|CDN).* (Vue|Bootstrap|axios|Chart\.js|Hammer|marked)" . \
|| true
# Show the relevant part of .claude/agents/webui-developer.md around the table (to ensure exact wording)
sed -n '65,95p' .claude/agents/webui-developer.mdRepository: redhat-openshift-ecosystem/opct
Length of output: 12364
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find where the remaining CDN libs mentioned in the doc snippet are loaded in report.html
rg -n "chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|Hammer\.js|marked\.js|marked" data/templates/report/report.html || true
# Also look for their <script src=...> in filter.html (for completeness)
rg -n "chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|Hammer\.js|marked\.js|marked" data/templates/report/filter.html || true
# If found, print those lines with some nearby context
for f in data/templates/report/report.html data/templates/report/filter.html; do
echo "==== $f (matching CDN scripts) ===="
rg -n -C 2 "chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|Hammer\.js|marked\.js|marked" "$f" || true
doneRepository: redhat-openshift-ecosystem/opct
Length of output: 209
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for CDN/library loading patterns
rg -n --hidden --no-ignore-vcs -S "unpkg\.com/.*(chart\.js|chartjs-adapter-date-fns|hammer\.js|chartjs-plugin-zoom|marked(\.min)?\.js)" . || true
rg -n --hidden --no-ignore-vcs -S "jsdelivr\.net/.*(chart\.js|chartjs-adapter-date-fns|hammer\.js|chartjs-plugin-zoom|marked(\.min)?\.js)" . || true
rg -n --hidden --no-ignore-vcs -S "(^|[\"'`=])https?://(unpkg\.com|cdn\.jsdelivr\.net)/.*(chart\.js|chartjs-adapter-date-fns|hammer\.js|chartjs-plugin-zoom|marked(\.min)?\.js)" . || true
# Also search for non-CDN mentions (e.g., bundled local files)
rg -n --hidden --no-ignore-vcs -S "(Chart\.js|chart\.js|chartjs-adapter-date-fns|Hammer\.js|chartjs-plugin-zoom|marked\.js)" data/templates/report . || true
# Finally, show head of report.html more fully in case scripts are later in head
sed -n '1,160p' data/templates/report/report.html | catRepository: redhat-openshift-ecosystem/opct
Length of output: 144
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for Chart.js / adapter / hammer / zoom / marked script tags across repo
rg -n --hidden --no-ignore-vcs -S "unpkg\.com/.*(chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|hammer\.js|marked(\.min)?\.js)" . || true
rg -n --hidden --no-ignore-vcs -S "cdn\.jsdelivr\.net/.*(chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|hammer\.js|marked(\.min)?\.js)" . || true
rg -n --hidden --no-ignore-vcs -S "https?://(unpkg\.com|cdn\.jsdelivr\.net)/.*(chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|hammer\.js|marked(\.min)?\.js)" . || true
# Search for Vue/Bootstrap/axios CDN script/style tags across templates
rg -n --hidden --no-ignore-vcs -S "unpkg\.com/(vue@latest|vue@2|axios|bootstrap|bootstrap-vue|bootstrap-vue@latest)/" data/templates/report || true
rg -n --hidden --no-ignore-vcs -S "unpkg\.com/(vue@latest|vue@2|axios|bootstrap|bootstrap-vue|bootstrap-vue@latest)/" . || true
# Show the actual CDN tags we already saw in report.html/filter.html (for exactness)
rg -n --hidden --no-ignore-vcs -S "cdn\.jsdelivr\.net|unpkg\.com" data/templates/report/report.html data/templates/report/filter.html || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 5488
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for the libraries mentioned in the doc table across report templates
rg -n --hidden --no-ignore-vcs -S "(Chart\.js|chartjs-adapter-date-fns|chartjs-plugin-zoom|hammer\.js|marked(\.min)?\.js|plugin-zoom|adapter-date-fns|hammer)" data/templates/report || true
# Search for general "chart" / "marked" / "zoom" / "hammer" references (case-insensitive) too
rg -n --hidden --no-ignore-vcs -i -S "(chartjs|chart\.|zoom|hammer|marked)" data/templates/report || true
# Also list any <script src=...> in report.html and filter.html for context
for f in data/templates/report/report.html data/templates/report/filter.html; do
echo "==== $f scripts ===="
rg -n "<script[^>]+src=" "$f" || true
doneRepository: redhat-openshift-ecosystem/opct
Length of output: 1369
Pin exact CDN versions (and align the doc with real script includes).
.claude/agents/webui-developer.mdlines 73-85 listslatest/broad tags for Vue (2.x), Bootstrap (latest), BootstrapVue (latest), and axios (latest), while the templates loadbootstrapandaxioswithout pinned versions andbootstrap-vue@latest(plusvue@latestinfilter.html); pin exact versions (or enforce a locked upgrade policy) to keep UI/debug behavior reproducible.- The same table lists Chart.js/Hammer/zoom/marked, but
data/templates/report/report.htmlanddata/templates/report/filter.htmldon’t load those libraries; update the doc to match actual dependencies.
Suggested doc update
-| Vue.js | 2.x | Frontend framework |
-| Bootstrap | latest | Layout and components |
-| BootstrapVue | latest | Vue Bootstrap components |
-| axios | latest | HTTP client |
+| Vue.js | <exact-version> | Frontend framework |
+| Bootstrap | <exact-version> | Layout and components |
+| BootstrapVue | <exact-version> | Vue Bootstrap components |
+| axios | <exact-version> | HTTP client |🤖 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 @.claude/agents/webui-developer.md around lines 73 - 85, Update the CDN
dependency table to pin exact versions and make it match actual template usage:
replace ambiguous entries "Vue.js 2.x", "Bootstrap latest", "BootstrapVue
latest", and "axios latest" with concrete version numbers used by the templates
(or choose locked versions and note the upgrade policy), and either add
Chart.js, chartjs-adapter-date-fns, Hammer.js, chartjs-plugin-zoom, and
marked.js to the table if you will load them in
data/templates/report/report.html and data/templates/report/filter.html or
remove them from the table if those templates do not include them; ensure the
doc references the exact script tags/versions used in report.html and
filter.html (e.g., mention bootstrap-vue@X.Y.Z, vue@X.Y.Z, axios@A.B.C) so the
documentation and templates remain consistent.
Comment on lines
+72
to
+75
| ### Bug Draft (pending approval) | ||
| Title: OPCT/CI job failure: 4.18-platform-none-vsphere-upgrade | ||
| Project: OCPBUGS | ||
| ... |
There was a problem hiding this comment.
Unify Jira target project references (currently contradictory).
This skill simultaneously instructs filing in OCPBUGS (Line 74 / jira:ocpbugs) and OPCT (Line 90). That conflict can route bugs to the wrong project.
Suggested doc fix
-Project: OCPBUGS
+Project: OPCT
...
-- `jira:create-bug` + `jira:ocpbugs` — bug creation
+- `jira:create-bug` — bug creation in OPCTAlso applies to: 90-94, 107-107
🤖 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 @.claude/skills/ci-triage/SKILL.md around lines 72 - 75, The document mixes
two Jira target projects—jira:ocpbugs (OCPBUGS) and OPCT—causing conflicting
routing; pick the correct canonical project and update every reference to it
(search for literal strings "jira:ocpbugs", "OCPBUGS", and "OPCT" in the "Bug
Draft (pending approval)" section and elsewhere) so all templates and examples
consistently use the chosen project; ensure the Jira project value used in the
bug template metadata and any example ticket titles/comments are replaced
accordingly and run a quick grep to confirm no remaining contradictory
references.
Comment on lines
+48
to
+51
| | `no required module provides package` | Run `go get <package>@latest` then `go mod tidy` | | ||
| | `toolchain` directive in go.mod | Remove it — causes CI compatibility issues | | ||
| | Import cycle | Check `internal/` vs `pkg/` boundaries | | ||
| | `go.sum` mismatch | Delete `go.sum` and run `go mod tidy` to regenerate | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether dependency guidance is consistent across project docs.
# Expected: no other docs recommend broad `@latest` upgrades or blanket go.sum deletion.
rg -n -C2 'go get .*`@latest`|delete `go\.sum`|rm .*go\.sum|go\.sum mismatch' .claude CLAUDE.mdRepository: redhat-openshift-ecosystem/opct
Length of output: 959
Constrain @latest in Go module remediation to keep builds reproducible
In .claude/skills/go-validate/SKILL.md (lines 48-49), the suggested fix for no required module provides package uses go get <package>@latest``, which can pull newer versions on different runs and introduce unexpected changes. Prefer adding the dependency with an explicit, project-aligned version (or a version range/major-minor that you intend to allow), then run go mod tidy.
🤖 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 @.claude/skills/go-validate/SKILL.md around lines 48 - 51, Update the
remediation for the "no required module provides package" entry so it does not
recommend `@latest`; instead instruct to add the dependency with an explicit,
reproducible version (for example `go get <package>`@vX.Y.Z`` or a project-aligned
major/minor like `@vX.Y`) and then run `go mod tidy`; modify the line that
currently suggests `go get <package>`@latest`` in the `no required module provides
package` row to recommend specifying a fixed/versioned reference to keep builds
reproducible.
| -d '{"fields": {"project": {"key": "OPCT"}, "issuetype": {"name": "Bug"}, ...}}' | ||
| ``` | ||
|
|
||
| If credentials are not exported, ask the user where their Jira credentials file is located. |
There was a problem hiding this comment.
Avoid prompting for credential file paths; require pre-configured auth env vars.
Line 36 encourages ad-hoc secret handling. In agent workflows, this increases accidental secret exposure risk. Prefer a hard rule: do not request credential file locations/content; instead instruct users to set JIRA_USERNAME/JIRA_API_TOKEN (or approved secret manager flow) before running fallback commands.
As per coding guidelines, “Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.”
🤖 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 @.claude/skills/jira-ops/SKILL.md at line 36, The doc currently instructs
asking users for a Jira credentials file path; remove that prompt and instead
require pre-configured auth via environment variables or approved secret
manager. Update SKILL.md text (the sentence that reads "If credentials are not
exported, ask the user where their Jira credentials file is located.") to reject
ad-hoc file prompts and add a clear instruction to set JIRA_USERNAME and
JIRA_API_TOKEN (or follow the org secret-manager flow) before running fallback
commands; also add guidance to abort with a descriptive error message when those
env vars are missing rather than prompting for file input.
Comment on lines
+29
to
+33
| If `enabled: false`: | ||
| - For Vertex AI: `echo $GOOGLE_CLOUD_LOCATION $ANTHROPIC_VERTEX_PROJECT_ID` (both must be set) | ||
| - Fallbacks also checked: `CLOUD_ML_REGION`, `GOOGLE_CLOUD_PROJECT` | ||
| - For Anthropic API: `echo $ANTHROPIC_API_KEY` | ||
|
|
There was a problem hiding this comment.
Avoid printing API secrets during credential checks.
The current commands expose secret values in terminal output/log captures. Use presence checks that do not print the key contents.
Suggested doc update
-- For Vertex AI: `echo $GOOGLE_CLOUD_LOCATION $ANTHROPIC_VERTEX_PROJECT_ID` (both must be set)
+- For Vertex AI: `[[ -n "$GOOGLE_CLOUD_LOCATION" && -n "$ANTHROPIC_VERTEX_PROJECT_ID" ]] && echo "set" || echo "missing"`
- Fallbacks also checked: `CLOUD_ML_REGION`, `GOOGLE_CLOUD_PROJECT`
-- For Anthropic API: `echo $ANTHROPIC_API_KEY`
+- For Anthropic API: `[[ -n "$ANTHROPIC_API_KEY" ]] && echo "set" || echo "missing"`🤖 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 @.claude/skills/webui-chat-debug/SKILL.md around lines 29 - 33, The doc
currently shows shell commands that print sensitive environment variable values
(e.g., using echo on GOOGLE_CLOUD_LOCATION, ANTHROPIC_VERTEX_PROJECT_ID,
CLOUD_ML_REGION, GOOGLE_CLOUD_PROJECT, and ANTHROPIC_API_KEY); update the
guidance to use non-revealing presence checks instead (describe using
conditional tests or tools that check existence/exit status without echoing
values), and replace the explicit echo examples with statements that only verify
presence/absence of each variable for Vertex AI and Anthropic API credential
checks.
Comment on lines
+37
to
+46
| curl -s -X POST http://localhost:9090/api/v1/chat \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"message": "hello", "history": []}' 2>&1 | head -20 | ||
| ``` | ||
|
|
||
| Should stream SSE events like: | ||
| ``` | ||
| event: text | ||
| data: Hello... | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the referenced snippet with line numbers
echo "== SKILL.md lines 1-120 =="
nl -ba .claude/skills/webui-chat-debug/SKILL.md | sed -n '1,120p'
echo
echo "== Search for curl/api/v1/chat in the repo =="
rg -n "curl .*api/v1/chat|api/v1/chat|SSE|event:|--no-buffer|-N" .claude/skills/webui-chat-debug -S || true
echo
echo "== Search repo-wide for the exact curl snippet =="
rg -n "curl -s -X POST http://localhost:9090/api/v1/chat" -S . || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 163
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the referenced snippet with line numbers
echo "== SKILL.md lines 1-120 =="
nl -ba .claude/skills/webui-chat-debug/SKILL.md | sed -n '1,120p'
echo
echo "== Search for curl/api/v1/chat in the repo =="
rg -n "curl .*api/v1/chat|api/v1/chat|SSE|event:|--no-buffer|-N" .claude/skills/webui-chat-debug -S || true
echo
echo "== Search repo-wide for the exact curl snippet =="
rg -n "curl -s -X POST http://localhost:9090/api/v1/chat" -S . || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 163
🏁 Script executed:
#!/bin/bash
set -euo pipefail
nl -ba .claude/skills/webui-chat-debug/SKILL.md | sed -n '25,80p'
rg -n "api/v1/chat|SSE|event:|--no-buffer|-N" .claude/skills/webui-chat-debug -S || true
rg -n "curl -s -X POST http://localhost:9090/api/v1/chat" -S . || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 118
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== SKILL.md lines 1-120 =="
cat -n .claude/skills/webui-chat-debug/SKILL.md | sed -n '1,120p'
echo
echo "== Search within webui-chat-debug for SSE/curl/no-buffer guidance =="
rg -n "curl .*api/v1/chat|api/v1/chat|SSE|event:|--no-buffer|-N" .claude/skills/webui-chat-debug -S || true
echo
echo "== Search repo-wide for the exact curl snippet =="
rg -n "curl -s -X POST http://localhost:9090/api/v1/chat" -S . || trueRepository: redhat-openshift-ecosystem/opct
Length of output: 4103
Use unbuffered curl (-N/--no-buffer) for SSE validation.
Without -N, curl may buffer output, making the head -20 streaming check appear broken even when SSE is working. (File: .claude/skills/webui-chat-debug/SKILL.md, lines 37-46)
Suggested doc update
-curl -s -X POST http://localhost:9090/api/v1/chat \
+curl -sN -X POST http://localhost:9090/api/v1/chat \
-H "Content-Type: application/json" \
-d '{"message": "hello", "history": []}' 2>&1 | head -20📝 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
| curl -s -X POST http://localhost:9090/api/v1/chat \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"message": "hello", "history": []}' 2>&1 | head -20 | |
| ``` | |
| Should stream SSE events like: | |
| ``` | |
| event: text | |
| data: Hello... | |
| ``` | |
| curl -sN -X POST http://localhost:9090/api/v1/chat \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"message": "hello", "history": []}' 2>&1 | head -20 |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 @.claude/skills/webui-chat-debug/SKILL.md around lines 37 - 46, Update the
example curl invocation to use unbuffered mode so SSE events are emitted
immediately: add the -N (or --no-buffer) flag to the curl command in the chat
example (the line starting with curl -s -X POST ... -d '{"message": "hello",
"history": []}'). Keep the rest of the pipeline (2>&1 | head -20) intact and
ensure the README/SKILL.md example text still shows the expected SSE output
lines like "event: text" and "data: Hello...".
mtulio
commented
Jun 3, 2026
Comment on lines
+44
to
+48
| ### Chat backend | ||
| - Vertex AI: prefer `GOOGLE_CLOUD_LOCATION` over `CLOUD_ML_REGION` (which may be `global`) | ||
| - Model IDs: use alias form like `claude-sonnet-4-5` (not dated versions) | ||
| - Tool results are read from the report directory filesystem — tools must handle missing files gracefully | ||
| - SSE events: `text` (streaming tokens), `tool_call` (tool invocation), `done` (final text), `error` |
Collaborator
Author
There was a problem hiding this comment.
this feature is not added yet to the main stream, it's under experimental on https://github.com/redhat-openshift-ecosystem/opct/pull/213/changes
mtulio
commented
Jun 3, 2026
|
|
||
| ### Testing workflow | ||
| - ALWAYS rebuild (`make build`) after Go changes | ||
| - ALWAYS regenerate report (`rm -rf <dir> && opct report -s <dir> ...`) after template changes |
Collaborator
Author
There was a problem hiding this comment.
make sure <dir> willnever be black, or home directory, or root, or...? can we add this to general rules to increase guardrails?
mtulio
commented
Jun 3, 2026
| - ALWAYS rebuild (`make build`) after Go changes | ||
| - ALWAYS regenerate report (`rm -rf <dir> && opct report -s <dir> ...`) after template changes | ||
| - Test chat with Go server (not python) — python can't serve the API endpoints | ||
| - Check at least 3 pages (Summary, Checks, etcd) after any layout change |
Collaborator
Author
There was a problem hiding this comment.
this feature is not added yet to the main stream, it's under experimental on https://github.com/redhat-openshift-ecosystem/opct/pull/213/changes
mtulio
commented
Jun 3, 2026
Comment on lines
+102
to
+107
| ### Add a new chat tool | ||
| 1. Add tool definition in `internal/chat/tools.go` `ToolDefinitions()` function | ||
| 2. Add input struct if needed (with jsonschema tags) | ||
| 3. Add case in `Execute()` switch | ||
| 4. Implement the execution method reading from `te.reportDir` | ||
| 5. Tool results are returned as JSON strings to Claude |
Collaborator
Author
There was a problem hiding this comment.
this feature is not added yet to the main stream, it's under experimental on https://github.com/redhat-openshift-ecosystem/opct/pull/213/changes
mtulio
commented
Jun 3, 2026
| triage https://prow.ci.openshift.org/view/gs/test-platform-results/logs/periodic-ci-openshift-release-main-nightly-4.22-opct-platform-external-aws/2053264314218844160 | ||
| ``` | ||
|
|
||
| ## What the agent does |
Collaborator
Author
There was a problem hiding this comment.
this is a skill config, is it correct section referring to the agent?
mtulio
commented
Jun 3, 2026
| |-------|--------| | ||
| | Project | OPCT (not OCPBUGS — CI failures are not OCP product bugs) | | ||
| | Title | `OPCT/CI job failure: {VERSION}-{PLATFORM}-{PROVIDER}-{WORKFLOW}` | | ||
| | Labels | `splatteam`, `needs-refinement`, `needs-triage`, `openshift-{X.Y}`, `opct-{X.Y}` | |
Collaborator
Author
There was a problem hiding this comment.
also add the label opct to improve filter while building jira dashboards
mtulio
commented
Jun 3, 2026
| ## Prerequisites | ||
|
|
||
| - `KUBECONFIG` environment variable set to a valid cluster | ||
| - Cluster must have `opct` namespace (created by `opct adm setup`) |
Collaborator
Author
There was a problem hiding this comment.
no way, quite hallucinated. this command does not exist.
one pre-req is having a dedicated node created by opct adm e2e-dedicated taint-node --yes (automatically select the "best worker node" to be dedicated)
mtulio
changed the title
mtulio
commented
Jun 4, 2026
mtulio
left a comment
mtulio
left a comment
Collaborator
Author
There was a problem hiding this comment.
Still reviewing, sending buffered comments:
|
|
||
| ```bash | ||
| # 1. Fetch and checkout PR branch | ||
| gh pr checkout 214 # or: git fetch origin pull/214/head:pr-214 && git checkout pr-214 |
Collaborator
Author
There was a problem hiding this comment.
isnt github cli a pre-req?
| ./build/opct-linux-amd64 run -w --dev-count=1 | ||
|
|
||
| # 3. Monitor plugin progress | ||
| # In another terminal: |
Collaborator
Author
There was a problem hiding this comment.
Suggested change
| # In another terminal: | |
| # In another terminal (or remove -w from the run command): |
| @@ -0,0 +1,81 @@ | |||
| --- | |||
Collaborator
Author
There was a problem hiding this comment.
probably we need to remove this skill from this PR keeping it in the origina PR that is adding the feature https://github.com/redhat-openshift-ecosystem/opct/pull/213/changes
| @@ -0,0 +1,233 @@ | |||
| # CI Triage Agent | |||
Collaborator
Author
There was a problem hiding this comment.
first file/comment under .claude: we must ship a settings.json file with extra market place for ai-helpers, something like with more enabled plugins:
{
"extraKnownMarketplaces": {
"openshift-ai-helpers": {
"source": {
"source": "github",
"repo": "openshift-eng/ai-helpers"
}
}
},
"enabledPlugins": {
"git@ai-helpers": true
}
}
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
1 participant
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.
Summary
Add comprehensive AI/LLM development instructions and tools for the OPCT project to enable AI-assisted development workflows.
Changes
CLAUDE.md Enhancements
Agents (
.claude/agents/)Skills (
.claude/skills/)--dev-count=1)Key Features
✅ Comprehensive development procedures with exact commands
✅ Common pitfalls and troubleshooting guides
✅ Validation checklists for all changes
✅ AI SDLC traceability (required bot signatures)
✅ Project-specific patterns and conventions
Statistics
Testing
Related
devel-0.7-chatassistant🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com