Help us improve
Share bugs, ideas, or general feedback.
From ralphex
Converts plans from OpenSpec, spec-kit, GitHub/GitLab issues, task-lists, or free-form markdown into ralphex format in docs/plans/.
npx claudepluginhub umputun/ralphex --plugin ralphexHow this skill is triggered — by the user, by Claude, or both
Slash command
/ralphex:ralphex-adoptThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**SCOPE**: Read a source plan in some other format and produce a new ralphex-format plan at `docs/plans/YYYYMMDD-<slug>.md`. The source is never modified. Existing target files are never silently overwritten.
Creates a structured implementation plan in docs/plans/ with interactive context gathering via Explore agent. Supports feature, bugfix, refactor, and migration plans.
Generates structured implementation plans from spec files using ralph-starter CLI. Breaks specs into actionable checkboxed tasks in IMPLEMENTATION_PLAN.md. Use after verifying specs/ directory.
Creates detailed implementation plans through interactive, iterative collaboration. Useful for planning features, refactoring, or tasks.
Share bugs, ideas, or general feedback.
SCOPE: Read a source plan in some other format and produce a new ralphex-format plan at docs/plans/YYYYMMDD-<slug>.md. The source is never modified. Existing target files are never silently overwritten.
Supported source shapes:
proposal.md, tasks.md, optional specs/**/spec.md#N, or owner/repo#N with body that contains a task checklistThis is a single-skill conversion: discover, classify, ask focused questions when in doubt, draft, review, write. Do not modify code, do not run tests, do not commit. Output is the new plan file only.
This check is informational only. Missing ralphex CLI must NOT break the flow — conversion does not require it. Do NOT block, exit, prompt the user, or wait for installation. Always continue to Step 1 regardless of the result.
which ralphex
If which ralphex returns non-zero, briefly mention that ralphex is needed to execute the converted plan later (not now), list install options once, and continue immediately:
brew install umputun/apps/ralphex.deb from https://github.com/umputun/ralphex/releases.rpm from https://github.com/umputun/ralphex/releasesgo install github.com/umputun/ralphex/cmd/ralphex@latestIf which ralphex succeeds, say nothing and proceed.
Inspect $ARGUMENTS and pick exactly one source by shape, in this order:
Full URL (starts with http:// or https://):
gh issue view <url> --json title,body,labels (or gh pr view)glab issue view <url> (or glab mr view)curl -fsSL only if it points at a raw markdown file; otherwise AskUser to paste the bodyBare reference #N:
git remote get-url origin and choose gh or glab accordingly.git remote get-url origin fails (not a git repo, or no origin remote), AskUserQuestion to disambiguate: "GitHub", "GitLab", "Provide qualified owner/repo#N instead", "Cancel". Re-resolve based on the answer.gh issue view N --json title,body (try gh pr view N if issue not found)glab issue view N (try glab mr view N if not found)Qualified reference owner/repo#N or group/project#N:
gh issue view N --repo owner/repoglab issue view N --repo group/projectExisting path — first probe the literal argument as a filesystem path with test -e "$ARGUMENTS":
ls -la <path> and inspect contents
proposal.md AND tasks.md → likely OpenSpec, proceed to Step 2*.md → use that fileBare name — only if the argument failed every check above (not a URL, not #N or owner/repo#N, and test -e returned false). A bare name has no path separators and contains no path-like characters:
**/*<name>*.md, **/*<name>*/proposal.md)No argument:
After resolving, store: source kind (github-issue, gitlab-issue, file, directory, pasted), source content (full text or directory listing + key files), and source identifier for the slug suggestion.
Look at the resolved content and classify it as one of:
proposal.md and tasks.md. May also have specs/**/spec.md deltas.github-issue or gitlab-issue, and the body contains one or more - [ ] items.If multiple signals point in different directions (e.g., a directory with both a proposal.md and a clearly spec-kit-shaped plan.md), AskUser to confirm which format to use before drafting.
Before writing any draft, scan the source for items the agent cannot confidently map. For each uncertainty, AskUser before drafting, never embed placeholder markers (???, TBD, [FIXME]) into the converted plan.
Common uncertainties:
Task in headers is always English regardless).Use AskUserQuestion with concrete options. If the question is genuinely open-ended (more than 4 possibilities), present a numbered list in chat and ask the user to reply with a number.
Do not draft, then ask. Ask, then draft.
All converted plans must satisfy ralphex's plan-format rules:
# <Plan Title> H1.## Overview, ## Context, ## Development Approach, ## Testing Strategy, ## Progress Tracking, optional ## Technical Details (when source has architecture/spec details to preserve), ## Implementation Steps, optional ## Post-Completion.### Task <N>: <title>. The keyword Task is always English, even when the plan title and task titles are in another natural language. ralphex's plan parser only recognizes English Task and Iteration keywords; localized variants (Задача, タスク, Tarea, etc.) will not be detected.- [ ] / - [x]) appear only inside Task sections. Do not put checkboxes in Overview, Context, Success criteria, or any other section — they cause the executor to spawn extra iterations.### Task <last>: Verify acceptance criteria containing items that re-run the test suite, run the project linter, and confirm requirements from Overview were met.Per-format mapping rules:
proposal.md "## Why" or equivalent → ## Overview (the problem statement and motivation)proposal.md "## What Changes" → ## Context (impacted components and constraints)specs/**/spec.md delta sections (ADDED / MODIFIED / REMOVED requirements) → ## Technical Details (concrete behavior changes)tasks.md numbered list → ## Implementation Steps grouped into ### Task N: sections. Each top-level numbered group becomes a Task; sub-bullets become checkboxes.write tests and run project tests checkboxes to each Task even if absent in source.### Task <last>: Verify acceptance criteria Task.## Overview and ## Context## Technical Details## Implementation Steps with one ### Task N: per logical phasewrite tests, run project tests, and final Verify acceptance criteria Task.# <Plan Title> (drop trailing punctuation, normalize whitespace)## Overview## Context (e.g., "Reported in repo X, labels: bug, p1, area/auth")- [ ] items in body → ## Implementation Steps
- [x] checked state from the source.write tests and run project tests per Task; append final Verify acceptance criteria Task.#, ##, ###, or numbered headings) from the source.- [ ], * [ ], 1., -, plain dashes).### Task N: <title> (use English Task keyword regardless of the source language).- [ ] checkboxes inside the Task.write tests, run project tests, and final Verify acceptance criteria Task.## Overview.## Context.[FIXME] or ??? — if a phrase is too vague, AskUser in Step 3 first.write tests, run project tests, and final Verify acceptance criteria Task.# <Plan Title>
## Overview
<one or two paragraphs describing what is being built and why>
## Context
- <impacted components>
- <relevant constraints>
- <reference to source: e.g., "Adopted from issue #312" or "Adopted from OpenSpec change auth-rework">
## Development Approach
- Testing approach: regular (or TDD if source explicitly calls it out)
- Complete each task fully before moving to the next
- Update this plan when scope changes during implementation
## Testing Strategy
- Unit tests required for every code-changing Task
- Run project tests after each Task before proceeding
## Progress Tracking
- Mark completed items with `[x]` immediately when done
- Update plan if implementation deviates from original scope
## Technical Details
<optional: detailed behavior, data shapes, references to spec sections; omit this section if the source had no such content>
## Implementation Steps
### Task 1: <title>
- [ ] <concrete action>
- [ ] <concrete action>
- [ ] write tests for new functionality
- [ ] run project tests - must pass before next task
### Task 2: <title>
- [ ] <concrete action>
- [ ] write tests for new/changed functionality
- [ ] run project tests - must pass before next task
### Task <last>: Verify acceptance criteria
- [ ] verify all requirements from Overview are implemented
- [ ] run full project test suite
- [ ] run project linter - all issues must be fixed
## Post-Completion
*Items requiring manual intervention - no checkboxes, informational only*
- <manual verification steps if any>
- <external system updates if any>
Create a temp file and capture its path. Each Bash tool call runs in its own subshell, so shell variables (including $DRAFT) do not persist between calls. You must capture the literal path printed by mktemp and substitute that exact string into every subsequent tool call (Write, launcher, rm) — do not rely on $VAR references across calls.
Use a portable mktemp form. The -t prefix form differs between macOS BSD and Linux GNU. A template ending in XXXXXX is portable, but a suffix after XXXXXX (e.g., XXXXXX.md) is silently treated as a literal filename by BSD mktemp and would cause concurrent runs to collide on the same path. Generate the random path first, then rename to add the .md extension:
TMP=$(mktemp "${TMPDIR:-/tmp}/ralphex-adopt-XXXXXX") && mv "$TMP" "$TMP.md" && printf '%s\n' "$TMP.md"
Read the path from stdout (e.g., /tmp/ralphex-adopt-aB3xY9.md) and remember it. Refer to that literal string below as <draft-path>. Write the draft content to <draft-path> via the Write tool.
An EXIT trap is not used because each Bash call is its own subshell — the trap would fire immediately. Cleanup is explicit at the end of Step 6 (success) and on every cancel path (rm -f <draft-path> with the literal path substituted).
Run revdiff directly on the draft (bypass ~/.claude/scripts/draft-review.sh — that wrapper runs a writing-style lint that misfires on plan-shaped content and writes a publish-approval marker this skill does not need). Substitute the literal <draft-path> you captured above:
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.
Read the launcher's stdout from the Bash tool result directly. Do not assign it to a shell variable — variables do not persist between Bash tool calls (see Step 5 preamble).
<draft-path> in place via Write), then re-run revdiff. Repeat until stdout is empty.If the launcher path is missing, OR launch-revdiff.sh fails with any revdiff-related error (exit code non-zero with "revdiff" in stderr — "not found in PATH", "command not found", etc.), fall back to in-chat review:
Compute the target filename:
YYYYMMDD form (no dashes, e.g., 20260430).-, max ~50 characters. Drop articles (a/an/the) and trailing punctuation.Use AskUserQuestion to confirm or edit the slug before writing:
<computed-slug> for docs/plans/<date>-<slug>.md?"If the target file already exists:
docs/plans/<filename> already exists. What should we do?"-v2, then -v3, ... to the slug; check docs/plans/ and docs/plans/completed/ for collisions, increment until both are clearSanity-check the draft before writing:
### Task line that matches the form ### Task <N>: <title>.- [ ] checkbox under a Task section.Once the filename is confirmed and sanity checks pass:
mkdir -p docs/plans
Write the draft content to docs/plans/<final-name>.md via the Write tool. Then explicitly clean up the temp file by substituting the literal <draft-path> captured in Step 5:
rm -f <draft-path>
Also run the same rm -f <draft-path> on any cancel path before exiting (Step 1, Step 3, Step 5 reject, Step 6 cancel) — always with the literal path substituted, never as $DRAFT.
Report to the user:
Adopted plan: docs/plans/<final-name>.md
Source: <source kind and identifier>
Tasks: <N>
Next: run `ralphex docs/plans/<final-name>.md` to execute.
Task keyword stays English regardless.docs/plans/completed/ are never modified.#N argument: AskUser to paste the issue body or provide a different reference.docs/plans/ without an explicit user-confirmed slug.???, TBD, [FIXME]) in the output — AskUser before drafting instead.pkg/...) in the converted plan content.