/ralphex-adopt

description: Convert plans from various source formats (OpenSpec, spec-kit, GitHub/GitLab issues with checklists, generic task-lists, free-form markdown) into ralphex-format plans in docs/plans/. Triggers on "ralphex-adopt", "adopt plan", "convert plan to ralphex", "import plan as ralphex".
allowed-tools: [Bash, Read, Write, Glob, Grep, AskUserQuestion]

ralphex-adopt - Convert Plans Into ralphex Format

**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:

• **OpenSpec change**: directory containing `proposal.md`, `tasks.md`, optional `specs/**/spec.md`
• **spec-kit spec**: directory or file with spec/plan/tasks separation
• **GitHub or GitLab issue**: URL, `#N`, or `owner/repo#N` with body that contains a task checklist
• **Generic task-list**: any structured markdown/text with headings and bullet items
• **Free-form markdown**: prose brain dump with no fixed structure

This 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.

Step 0: Optional CLI Check

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:

• **macOS (Homebrew)**: `brew install umputun/apps/ralphex`
• **Linux (Debian/Ubuntu)**: download `.deb` from https://github.com/umputun/ralphex/releases
• **Linux (RHEL/Fedora)**: download `.rpm` from https://github.com/umputun/ralphex/releases
• **Any platform with Go**: `go install github.com/umputun/ralphex/cmd/ralphex@latest`

If `which ralphex` succeeds, say nothing and proceed.

Step 1: Resolve Source From Argument Shape

Inspect `$ARGUMENTS` and pick exactly one source by shape, in this order:

1. **Full URL** (starts with `http://` or `https://`):

• GitHub issue/PR URL → use `gh issue view <url> --json title,body,labels` (or `gh pr view`)
• GitLab issue/MR URL → use `glab issue view <url>` (or `glab mr view`)
• Other URL → fetch with `curl -fsSL` only if it points at a raw markdown file; otherwise AskUser to paste the body

2. **Bare reference** `#N`:

• Use the current git repository's host. Detect with `git remote get-url origin` and choose `gh` or `glab` accordingly.
• If `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.
• GitHub: `gh issue view N --json title,body` (try `gh pr view N` if issue not found)
• GitLab: `glab issue view N` (try `glab mr view N` if not found)

3. **Qualified reference** `owner/repo#N` or `group/project#N`:

• GitHub: `gh issue view N --repo owner/repo`
• GitLab: `glab issue view N --repo group/project`

4. **Existing path** — first probe the literal argument as a filesystem path with `test -e "$ARGUMENTS"`:

• **File**: read with the Read tool
• **Directory**: list with `ls -la <path>` and inspect contents
• If contains `proposal.md` AND `tasks.md` → likely OpenSpec, proceed to Step 2
• If contains a single `*.md` → use that file
• Otherwise AskUser which file inside the directory is the plan

5. **Bare 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:

• Search filesystem with Glob for plausible matches (e.g., `**/*<name>*.md`, `**/*<name>*/proposal.md`)
• If exactly one match → use it
• If multiple matches → AskUser to pick one (use AskUserQuestion with up to 4 most relevant; if more, summarize and AskUser to paste the path)
• If no matches → AskUser whether they meant a path, an issue number, or something else

6. **No argument**:

• Use AskUserQuestion: "Where is the source plan?" with options like "Paste it", "Provide a file path", "Provide an issue number/URL", "Cancel".

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.

Step 2: Detect Format

Look at the resolved content and classify it as one of:

• **OpenSpec**: directory has both `proposal.md` and `tasks.md`. May also have `specs/**/spec.md` deltas.
• **spec-kit**: directory or single file shows the spec-kit shape — separate spec/plan/tasks sections, often with explicit "Specification", "Implementation Plan", "Tasks" headings.
• **Issue with checklist**: source kind is `github-issue` or `gitlab-issue`, and the body contains one or more `- [ ]` items.
• **Generic task-list**: any structured source with headings and bullet items that is not OpenSpec, spec-kit, or an issue. Section heading style and item-marker style may vary.
• **Free-form**: prose-only or near-prose source with no clear task list. Includes brain-dump style text.

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.

Step 3: Confidence Guard — Ask 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:

• Which headings should become Task sectio