ralphex-adopt

Convert external plan formats into ralphex-format plan files in docs/plans.

1.5k|123|Updated Jan 19, 2026
One-click install
npx skills add https://github.com/umputun/ralphex --skill ralphex-adopt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ralphex-adopt
Source: https://github.com/umputun/ralphex/tree/main/assets/claude/skills/ralphex-adopt
Command: npx skills add https://github.com/umputun/ralphex --skill ralphex-adopt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Teams keep implementation plans in many formats—OpenSpec changes, spec-kit specs, GitHub or GitLab issues with checklists, generic task lists, or free-form notes—but ralphex only executes plans written in its own strict markdown structure. Manually rewriting these sources into the required docs/plans/YYYYMMDD-slug.md format with proper Task sections and checkboxes is tedious and error-prone.

Core Features & Use Cases

  • Multi-format source resolution: Accepts URLs, issue references (#N, owner/repo#N), file paths, directories, or bare names, fetching content via gh, glab, or direct file reads.
  • Format detection and mapping: Classifies sources as OpenSpec, spec-kit, issue-with-checklist, generic task-list, or free-form, then maps each into ralphex's required sections (Overview, Context, Implementation Steps with ### Task N: headers).
  • Guarded drafting workflow: Asks clarifying questions before drafting, runs a revdiff review loop (with in-chat fallback), confirms the output slug, and never silently overwrites existing plan files.
  • Use Case: You have a GitHub issue with a 12-item checklist describing a feature. Run the skill with the issue number to produce a ready-to-execute ralphex plan grouped into Tasks with test checkboxes and a final acceptance-criteria verification task.

Quick Start

Ask the assistant to adopt the plan from GitHub issue #42 into a ralphex plan file under docs/plans.

Frequently Asked Questions about ralphex-adopt

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a GitHub issue into a ralphex plan?

Pass the issue URL, `#N`, or `owner/repo#N` as the argument. The skill fetches the issue body with the gh CLI, maps prose to Overview and Context, groups checklist items into Task sections, and writes the result to docs/plans after you confirm the filename.

What plan formats can be converted to ralphex format?

Supported sources are OpenSpec change directories (proposal.md plus tasks.md), spec-kit specs, GitHub or GitLab issues with checklists, generic structured task lists, and free-form markdown prose. Each format has specific mapping rules into ralphex's required sections.

Does converting a plan require the ralphex CLI to be installed?

No. The skill runs an informational `which ralphex` check but continues regardless of the result. The CLI is only needed later to execute the converted plan with `ralphex docs/plans/<file>.md`.

What happens if the target plan file already exists?

The skill never silently overwrites. It asks whether to bump the slug with a `-v2`, `-v3` suffix (checking both docs/plans and docs/plans/completed), pick a new slug, or cancel the conversion.

Can the skill handle non-English source plans?

Yes. It asks whether to translate or preserve the original language for prose sections. The structural `Task` keyword in headers always stays English because ralphex's parser only recognizes English Task and Iteration keywords.

What if gh or glab CLI is not installed for issue sources?

The skill falls back gracefully: it asks you to paste the issue body manually instead of failing. The same fallback applies when URL fetches fail or a bare issue reference cannot be resolved.