feat: add ralphex-adopt skill for converting plans to ralphex format#313
Merged
feat: add ralphex-adopt skill for converting plans to ralphex format#313
Conversation
new claude code skill `/ralphex-adopt` converts source plans from various formats into ralphex-format plans in `docs/plans/`. supported inputs: OpenSpec change directories, spec-kit specs, GitHub/GitLab issues with checklists, generic task-lists in unknown structured formats, and free-form markdown brain dumps. source is never modified. output is always a new dated file at `docs/plans/YYYYMMDD-<slug>.md`. existing target files are never silently overwritten. on uncertainty during conversion, the skill asks the user via AskUserQuestion before drafting rather than embedding placeholder markers in output. review loop uses revdiff directly (not draft-review.sh, which has a writing-style lint gate that misfires on plan content). falls back to in-chat AskUser Accept/Revise/Reject if revdiff is missing. skill content is language-agnostic. test/run-test checkboxes the skill instructs the agent to emit are phrased generically, matching the existing ralphex-plan convention. wiring: - assets/claude/skills/ralphex-adopt/SKILL.md (skill content) - assets/claude/ralphex-adopt.md (symlink for direct URL fetch) - llms.txt and README.md updated with install instructions - CLAUDE.md mentions /ralphex-adopt in skill list - plugin and marketplace version bumped 0.18.0 -> 0.19.0
Deploying ralphex with
|
| Latest commit: |
4b1b6b5
|
| Status: | ⚡️ Build in progress... |
There was a problem hiding this comment.
Pull request overview
Adds a new Claude Code skill (/ralphex-adopt) to convert existing plans/specs/issues/task-lists into ralphex-format plans under docs/plans/, and wires it into the project’s docs and plugin release metadata.
Changes:
- Add
assets/claude/skills/ralphex-adopt/SKILL.mddefining the end-to-end conversion + review flow. - Update docs (
README.md,llms.txt,CLAUDE.md) to list and describe/ralphex-adoptand its install steps. - Bump plugin/marketplace version to
0.19.0.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
assets/claude/skills/ralphex-adopt/SKILL.md |
New skill definition for adopting external plan formats into ralphex plan structure. |
llms.txt |
Adds install instructions + mentions /ralphex-adopt in the skills list. |
README.md |
Documents /ralphex-adopt alongside other Claude Code commands + links to hosted command file. |
CLAUDE.md |
Adds /ralphex-adopt to the customization/skills guidance. |
docs/plans/completed/20260430-ralphex-adopt-skill.md |
Adds a completed implementation plan/record for the feature. |
.claude-plugin/plugin.json |
Version bump to 0.19.0. |
.claude-plugin/marketplace.json |
Version bump to 0.19.0 to match plugin manifest. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+244
to
+252
| LAUNCHER="$HOME/.claude/plugins/marketplaces/revdiff/.claude-plugin/skills/revdiff/scripts/launch-revdiff.sh" | ||
| test -x "$LAUNCHER" && "$LAUNCHER" --wrap --only=<draft-path> | ||
| ``` | ||
|
|
||
| If the launcher path does not exist (`test -x` fails), skip directly to the in-chat fallback below — the user has revdiff installed via Homebrew or `go install` but does not have the Claude marketplace plugin layout. | ||
|
|
||
| Capture stdout into a variable. | ||
|
|
||
| - **Empty stdout** → user reviewed and approved silently. Proceed to Step 6. |
There was a problem hiding this comment.
Step 5 falls back to in-chat review when the marketplace launcher script is missing, even though revdiff may still be installed and runnable (e.g., via revdiff on PATH). This contradicts the stated behavior of using revdiff when available and only falling back when revdiff is actually missing. Consider detecting revdiff via command -v revdiff and using it when the launcher isn’t present, and clarify how the agent should determine approval/annotations from the Bash tool stdout (vs. persisting shell variables across tool calls).
Comment on lines
+69
to
+70
| - **Step 5**: Write draft to `/tmp/ralphex-adopt-<slug>.md`. Run `launch-revdiff.sh --wrap --only=<file>` directly. Empty stdout means user approved. Non-empty means address annotations, rewrite, re-run revdiff. Fallback to in-chat AskUser Accept/Revise/Reject if revdiff not installed. | ||
| - **Step 6**: Compute target filename `docs/plans/YYYYMMDD-<slug>.md`, AskUser to confirm/edit slug. If target exists, AskUser to bump suffix (-2, -3) or rename or cancel; never silent overwrite. Sanity-check the draft before writing: at least one `### Task N:` header and at least one `- [ ]` checkbox under a Task; if it fails, revise and retry. Write file, clean up temp file with a trap so cleanup runs on early exit. |
There was a problem hiding this comment.
This completed plan describes writing the draft to a fixed /tmp/ralphex-adopt-<slug>.md path and cleaning it up with a shell trap, but the implemented skill uses mktemp + rename and explicitly avoids traps due to per-call subshells. Please update this plan’s Step 5/6 description to match the actual SKILL.md behavior so future readers aren’t misled.
Suggested change
| - **Step 5**: Write draft to `/tmp/ralphex-adopt-<slug>.md`. Run `launch-revdiff.sh --wrap --only=<file>` directly. Empty stdout means user approved. Non-empty means address annotations, rewrite, re-run revdiff. Fallback to in-chat AskUser Accept/Revise/Reject if revdiff not installed. | |
| - **Step 6**: Compute target filename `docs/plans/YYYYMMDD-<slug>.md`, AskUser to confirm/edit slug. If target exists, AskUser to bump suffix (-2, -3) or rename or cancel; never silent overwrite. Sanity-check the draft before writing: at least one `### Task N:` header and at least one `- [ ]` checkbox under a Task; if it fails, revise and retry. Write file, clean up temp file with a trap so cleanup runs on early exit. | |
| - **Step 5**: Write the draft to a uniquely named temp file created with `mktemp`. Run `launch-revdiff.sh --wrap --only=<file>` directly against that temp draft. Empty stdout means user approved. Non-empty means address annotations, rewrite the temp draft, and re-run revdiff. Fallback to in-chat AskUser Accept/Revise/Reject if revdiff is not installed. | |
| - **Step 6**: Compute target filename `docs/plans/YYYYMMDD-<slug>.md`, AskUser to confirm/edit slug. If target exists, AskUser to bump suffix (`-2`, `-3`) or rename or cancel; never silent overwrite. Sanity-check the draft before finalizing: at least one `### Task N:` header and at least one `- [ ]` checkbox under a Task; if it fails, revise and retry. When approved, rename/move the reviewed temp draft into the final target path. If finalization does not happen, remove the temp file explicitly; do not rely on a shell trap, because each shell call runs in its own subshell. |
Step 5 said "Capture stdout into a variable" which contradicted the preamble note that shell variables don't persist between Bash tool calls. Reword to instruct the agent to read the launcher's stdout from the tool result directly. Other Copilot review points rejected: detecting revdiff binary directly via "command -v revdiff" would fail because revdiff is a TUI that needs a TTY (the launcher's terminal-overlay machinery is the only viable invocation path); modifying the completed plan to match implementation drift violates the immutable-completed-plans rule in CLAUDE.md.
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
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.
New Claude Code skill
/ralphex-adoptconverts source plans from various formats into ralphex-format plans indocs/plans/. Supported inputs: OpenSpec change directories, spec-kit specs, GitHub/GitLab issues with checklists, generic task-lists in unknown structured formats, and free-form markdown brain dumps.Source is never modified. Output is always a new dated file at
docs/plans/YYYYMMDD-<slug>.md. Existing target files are never silently overwritten. On uncertainty during conversion, the skill asks the user via AskUserQuestion before drafting rather than embedding placeholder markers in output.Review loop uses revdiff directly (not
draft-review.sh, which has a writing-style lint gate that misfires on plan content). Falls back to in-chat AskUser Accept/Revise/Reject if revdiff is missing.Skill content is language-agnostic. Test/run-test checkboxes the skill instructs the agent to emit are phrased generically, matching the existing
ralphex-planconvention. The skill can be used against any project regardless of language.Wiring
assets/claude/skills/ralphex-adopt/SKILL.md(skill content)assets/claude/ralphex-adopt.md(symlink for direct URL fetch)llms.txtandREADME.mdupdated with install instructionsCLAUDE.mdmentions/ralphex-adoptin skill list