Sketch out onboarding commands to setup enhancements repo and learn from #152
Conversation
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: dgoodwin The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
bot
added
the
approved
WalkthroughA new onboarding plugin is introduced with configuration, comprehensive documentation, and skill implementation guides. The plugin registers in the marketplace and provides two primary commands— Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Onboarding Plugin
participant System Checks
participant JIRA Config
participant Commands List
User->>Onboarding Plugin: /onboarding:start
activate Onboarding Plugin
Onboarding Plugin->>System Checks: Detect enhancements repo
System Checks-->>Onboarding Plugin: Repo status
Onboarding Plugin->>JIRA Config: Check JIRA_URL & token
JIRA Config-->>Onboarding Plugin: Config status
alt Repo + JIRA configured
Onboarding Plugin->>Commands List: List available commands
Commands List-->>Onboarding Plugin: Command groups (JIRA, CI, etc)
else Repo missing
Onboarding Plugin-->>User: Provide clone instructions
end
alt JIRA not configured
Onboarding Plugin-->>User: Provide setup commands
end
Onboarding Plugin-->>User: Setup Status Report
deactivate Onboarding Plugin
sequenceDiagram
participant User
participant Onboarding Plugin
participant AI Helpers
participant Enhancements Repo
User->>Onboarding Plugin: /onboarding:search [term]
activate Onboarding Plugin
Onboarding Plugin->>Onboarding Plugin: Validate & normalize term
Onboarding Plugin->>AI Helpers: Search markdown files
AI Helpers-->>Onboarding Plugin: Results (KEPs, tools, docs)
opt Enhancements repo available
Onboarding Plugin->>Enhancements Repo: Search content
Enhancements Repo-->>Onboarding Plugin: KEPs & automation results
end
Onboarding Plugin->>Onboarding Plugin: Categorize & prioritize results
alt Results found
Onboarding Plugin-->>User: Formatted results (KEPs, tools, suggestions)
else No results
Onboarding Plugin-->>User: Guidance for no matches
end
deactivate Onboarding Plugin
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Pre-merge checks and finishing touches✅ Passed checks (7 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
plugins/onboarding/commands/search.md (1)
79-81: Remove redundant grep pattern.
--include="README.md"is already matched by--include="*.md"and adds no additional files to the search.- AI_HELPERS_RESULTS=$(grep -r -i "$SEARCH_TERM" \ - --include="*.md" \ - --include="README.md" \ + AI_HELPERS_RESULTS=$(grep -r -i "$SEARCH_TERM" \ + --include="*.md" \Apply the same change to lines 97-99.
Also applies to: 98-99
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (9)
.claude-plugin/marketplace.json(1 hunks)README.md(1 hunks)openshift-eng.code-workspace(1 hunks)plugins/onboarding/.claude-plugin/plugin.json(1 hunks)plugins/onboarding/README.md(1 hunks)plugins/onboarding/commands/search.md(1 hunks)plugins/onboarding/commands/start.md(1 hunks)plugins/onboarding/skills/search/SKILL.md(1 hunks)plugins/onboarding/skills/start/SKILL.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
plugins/onboarding/commands/start.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
84-84: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
133-133: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
197-197: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
224-224: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
271-271: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
279-279: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/onboarding/README.md
13-13: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
19-19: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
55-55: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
66-66: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
175-175: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
176-176: Dollar signs used before commands without showing output
(MD014, commands-show-output)
177-177: Dollar signs used before commands without showing output
(MD014, commands-show-output)
178-178: Dollar signs used before commands without showing output
(MD014, commands-show-output)
255-255: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
plugins/onboarding/skills/search/SKILL.md
129-129: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
153-153: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
174-174: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
193-193: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
264-264: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
292-292: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/onboarding/skills/start/SKILL.md
100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
186-186: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
261-261: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
304-304: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (27)
README.md (3)
5-33: Excellent framing of general vs. team-specific resources.This clearly sets expectations for new hires about the scope of these resources and directs them to their team for component-specific onboarding. The distinction helps avoid confusion about what this onboarding covers.
34-103: Clear, actionable setup instructions.The step-by-step flow with command examples is well-structured. The workspace file approach (Option A) provides a smooth multi-repo experience for new hires.
104-137: Helpful navigation guidance for multi-repo workflow.This section effectively explains when to use each repository and how to navigate between them, which is essential for new hires working across multiple codebases.
openshift-eng.code-workspace (1)
1-49: Well-configured workspace for multi-repo onboarding.The workspace configuration correctly sets up both repositories with appropriate settings and helpful comments guiding users to add team-specific repos. The path assumption (
../enhancements) aligns with the setup instructions in README.md.plugins/onboarding/.claude-plugin/plugin.json (1)
1-8: Plugin metadata is properly configured.The configuration matches the marketplace entry and follows the standard plugin structure.
.claude-plugin/marketplace.json (1)
52-56: Marketplace entry correctly registers the onboarding plugin.The plugin entry has the proper structure with matching name, source path, and description.
plugins/onboarding/README.md (3)
1-31: Clear plugin purpose and scope definition.The documentation effectively establishes that this plugin covers general OpenShift resources, not team-specific onboarding, which aligns with the messaging in the main README.
32-94: Comprehensive command documentation.The
/onboarding:startand/onboarding:searchcommands are well-documented with clear purposes, usage examples, and expected outputs. The distinction between general and team-specific searches is appropriately emphasized.
141-176: Solid architecture design with graceful degradation.The repository detection strategy (checking common paths) and graceful degradation when components are missing demonstrates thoughtful design. This ensures the plugin remains helpful even with incomplete setup.
plugins/onboarding/skills/search/SKILL.md (4)
28-80: Well-structured search term validation and repository detection.The implementation properly validates input and searches common clone locations for the enhancements repository, covering typical user setups. The graceful handling when the repo is missing is user-friendly.
82-124: Efficient search implementation with appropriate constraints.The grep commands use sensible flags (
-m 1for first match per file, excluding common non-doc directories) to balance thoroughness with performance. The separate search passes for each repository enable clear result categorization.
125-188: Smart result prioritization strategy.Categorizing results into KEPs, commands, and documentation with KEPs ranked highest provides the most valuable information first. The extraction logic properly handles file paths and line numbers for actionable output.
189-260: User-friendly output format with clear next steps.The formatted output is scannable, includes contextual previews, and provides ready-to-use commands. This makes the search results immediately actionable for users.
plugins/onboarding/skills/start/SKILL.md (3)
1-92: Thorough environment detection and validation.The implementation systematically detects the enhancements repository and checks JIRA configuration, providing a complete picture of the user's setup. The consistent search paths across skills ensure predictable behavior.
93-298: Excellent branching logic for different setup states.The three detailed report templates (complete, incomplete, missing env vars) provide targeted guidance based on the user's actual setup state. The encouraging tone and actionable commands make this genuinely helpful for new hires.
339-367: Robust error handling and clear output philosophy.The non-blocking, guidance-oriented approach ensures the skill never fails and always provides actionable next steps. The documented output format principles (visual clarity, actionability, prioritization) guide consistent implementation.
plugins/onboarding/commands/start.md (4)
1-30: Clear command description with important context.The documentation effectively communicates that this command focuses on general OpenShift resources (ai-helpers, enhancements) rather than team-specific repositories, setting appropriate expectations for new hires.
31-78: Solid implementation foundation with consistent detection logic.The repository detection paths and environment variable checks match those in the SKILL.md file, ensuring consistency across documentation and implementation guidance.
79-255: Comprehensive scenario coverage with actionable guidance.The detailed output templates for different setup states (enhancements found/not found, JIRA configured/not configured) provide clear next steps. The emphasis on team-specific onboarding being separate is consistently reinforced.
256-305: Well-documented return values and usage examples.The return value documentation and examples clarify what users can expect from the command. The idempotence note is helpful for users who might run the command multiple times.
plugins/onboarding/commands/search.md (7)
1-14: Well-structured command definition.The YAML frontmatter and synopsis are clear and follow documentation conventions. The argument hint guides users on expected input format.
16-38: Clear scope definition prevents user confusion.The description effectively distinguishes between general OpenShift knowledge and team-specific documentation, with concrete use cases and prioritization that help users understand the command's role in their workflow.
41-45: Add validation details for search term handling.The validation step mentions "clean and normalize" but lacks specifics:
- What does normalization include (trim whitespace, lowercase, escape regex characters)?
- Are special grep metacharacters (
.,*,[,],\) escaped or rejected?- Is an empty search term explicitly rejected with a helpful error message?
Please clarify the search term validation strategy to ensure robustness against edge cases and unintended regex behavior.
241-293: Examples and return value documentation are clear and practical.The examples cover common search scenarios (component lookup, multi-word terms, specific features) and the return value structure is well-explained with three logical sections. This guidance will help new hires use the command effectively.
294-321: Arguments and prerequisites are clearly documented.The description of the required search-term argument is practical with diverse examples. Prerequisites appropriately position the enhancements repo as optional-but-recommended, with concrete clone instructions.
323-326: Verify referenced skill file exists.The "See Also" section references
plugins/onboarding/skills/search/SKILL.md. This should exist or be documented in the PR to ensure cross-file references remain consistent during development.Confirm that
plugins/onboarding/skills/search/SKILL.mdexists and contains the actual skill implementation logic referenced earlier, or update this file to reflect the authoritative location of implementation details.
39-114: Verify implementation strategy - referenced skill file does not exist in repository.The review comment raises valid concerns. Upon examination:
Implementation section is incomplete: Lines 88-114 describe only high-level steps and output examples. Step 5 ("Categorize and Prioritize Results") lists categories but provides no parsing or filtering logic.
Referenced skill file is missing: Line 325 references
plugins/onboarding/skills/search/SKILL.md, but this file does not exist in the repository. Onlyplugins/onboarding/commands/search.mdis present.Search term handling is vague: The phrase "clean and normalize the search term" (lines 41-45) lacks specification of what transformations occur or how special characters/regex are escaped.
The review's request is appropriate: either expand the Implementation section with actual parsing logic, or confirm the skill implementation exists (in which case the documentation should reference it more explicitly and include an authoritative link).
| 📚 DOCUMENTATION & ONBOARDING | ||
| /onboarding:start - This command (environment check) | ||
| /onboarding:search - Search across repos (coming soon) |
There was a problem hiding this comment.
Update command description - search is not "coming soon".
Line 328 indicates /onboarding:search is "coming soon", but this PR includes complete documentation and implementation for this command in plugins/onboarding/commands/search.md and plugins/onboarding/skills/search/SKILL.md.
Apply this diff:
📚 DOCUMENTATION & ONBOARDING
/onboarding:start - This command (environment check)
- /onboarding:search - Search across repos (coming soon)
+ /onboarding:search - Search across repos🤖 Prompt for AI Agents
In plugins/onboarding/skills/start/SKILL.md around lines 326 to 328, the command
list currently marks `/onboarding:search` as "coming soon" even though the
command and docs exist; update that line to reflect that `/onboarding:search` is
implemented (remove "coming soon" and optionally add a short note pointing to
plugins/onboarding/commands/search.md and
plugins/onboarding/skills/search/SKILL.md for docs/examples).
1 participant
An attempt at an onboarding entry point that guides new hires/transfers through the basics of openshift by ensuring the enhancements directory is checked out, at which point claude becomes quite good at answering questions on the general overview of what OpenShift is and how it works.
Open to feedback.