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.