Run any Skill in Manus with one click

Get Started

plan-to-ralph-spec

Stars3

Forks2

UpdatedApril 13, 2026 at 03:47

Convert a markdown implementation plan to a JSON spec file for ralph.sh execution

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

samjmarshall

samjmarshall/rekurve

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	plan-to-ralph-spec
description	Convert a markdown implementation plan to a JSON spec file for ralph.sh execution

Plan to Spec

Convert a markdown implementation plan into a structured .spec.json file that ralph.sh uses for execution.

Invocation

The user provides a path to a markdown plan:

/plan-to-ralph-spec thoughts/plans/2026-04-01-code-review-best-practices-checklist.md

Steps

Read the markdown plan file completely
Identify all leaf-level sections that contain checkbox task items (- [ ] lines)
For each section, extract:
- id: A normalized, stable, unique identifier derived from the heading structure (e.g., "1.1", "p2.cat1", "task-1"). Use numeric IDs when headings have numbers; use slugified IDs when they don't.
- title: The human-readable section title (heading text without the # prefix or numbering)
- tasks: Array of task strings from checkbox items (- [ ] lines), stripped of the - [ ] prefix
- files: Array of file paths mentioned in the section body (backtick-quoted paths matching src/, e2e/, scripts/, .claude/, .github/, thoughts/, docs/, or common extensions)
- verify: Array of make/shell commands from the section's success criteria. Default to ["make check"] if none specified
Skip sections with zero checkbox items — log a warning for each
Phases or groups (e.g., "Phase 1", "Phase 2") become ID prefixes on their child sections, not sections themselves. Only leaf-level items with tasks become sections.
Set all state fields to "pending"
Write to the same directory as the plan, replacing .md with .spec.json
Print a summary: section count, any warnings

Output Schema

{
  "version": 1,
  "plan": "<relative path to source markdown plan>",
  "title": "<plan title from first H1>",
  "sections": [
    {
      "id": "1.1",
      "title": "Section Title",
      "tasks": ["Task description 1", "Task description 2"],
      "files": ["src/app/page.tsx", "src/lib/utils.ts"],
      "verify": ["make check"],
      "state": "pending"
    }
  ]
}

Rules

Do NOT modify the original markdown plan
Heading format does not matter — handle ####, ###, ##, #####, numbered (1.1), named (Category 1:), etc.
The spec file must be valid JSON (use jq . to verify before writing)
If a section's success criteria mention specific commands (make test, make build, make test_e2e), include those in verify instead of the default
File paths in files should be relative to the repo root
IDs must be unique across all sections in the spec

More from this repository

same repository

commit

samjmarshall/rekurve

git commit code changes with clear messages

2026-07-083

document-feature

samjmarshall/rekurve

Interview a developer to produce a living feature doc at docs/feature/{slug}.md, capturing user value, architecture (with ADR links), and data/user flow with at least one Mermaid diagram. Use when the user says "document this feature", "write a feature doc", "create docs/feature/X", "explain feature X for new devs", or asks to onboard future engineers onto a shipped feature. Different from /create_plan (forward-looking design) and Epics (scope/sprint planning) — this is the present-tense "what does this thing do today" doc for engineers reading the codebase cold.

2026-07-073

domain-model

samjmarshall/rekurve

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

2026-07-073

pull-request

samjmarshall/rekurve

Create or update a Pull Request with a description tailored to its conventional-commit type (feat, fix, refactor, chore, perf, or trivial). Auto-detects whether to create or update based on branch state, detects type from branch/commits/issues, fills the matching bundled template, and runs verification only for what CI does not cover. Use when invoking /pull-request, when the user asks to open or update a PR, or after pushing work that needs a PR.

2026-07-073

writing-clearly-and-concisely

samjmarshall/rekurve

Apply writing rules to ANY prose humans will read — documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.

2026-07-073

ticket-writer

samjmarshall/rekurve

Single entry point for turning a design, plan, PRD, or in-chat spec into either a single GitHub Issue or a parent epic with child issues. Use when the user wants to create, review, or improve any ticket destined for a coding agent or another developer to pick up. Covers atomic issues, bug reports, technical tasks, spikes, and epic breakdowns using tracer-bullet vertical slices. Output is AFK-ready by default — written so a coding agent days later can produce the right work without the original chat context.

2026-06-303

Plan to Spec

Convert a markdown implementation plan into a structured .spec.json file that ralph.sh uses for execution.

Invocation

The user provides a path to a markdown plan:

/plan-to-ralph-spec thoughts/plans/2026-04-01-code-review-best-practices-checklist.md

Steps

Read the markdown plan file completely

Identify all leaf-level sections that contain checkbox task items (- [ ] lines)

For each section, extract:

id: A normalized, stable, unique identifier derived from the heading structure (e.g., "1.1", "p2.cat1", "task-1"). Use numeric IDs when headings have numbers; use slugified IDs when they don't.
title: The human-readable section title (heading text without the # prefix or numbering)
tasks: Array of task strings from checkbox items (- [ ] lines), stripped of the - [ ] prefix
files: Array of file paths mentioned in the section body (backtick-quoted paths matching src/, e2e/, scripts/, .claude/, .github/, thoughts/, docs/, or common extensions)
verify: Array of make/shell commands from the section's success criteria. Default to ["make check"] if none specified

Skip sections with zero checkbox items — log a warning for each

Phases or groups (e.g., "Phase 1", "Phase 2") become ID prefixes on their child sections, not sections themselves. Only leaf-level items with tasks become sections.

Set all state fields to "pending"

Write to the same directory as the plan, replacing .md with .spec.json

Print a summary: section count, any warnings

Output Schema

{ "version": 1, "plan": "<relative path to source markdown plan>", "title": "<plan title from first H1>", "sections": [ { "id": "1.1", "title": "Section Title", "tasks": ["Task description 1", "Task description 2"], "files": ["src/app/page.tsx", "src/lib/utils.ts"], "verify": ["make check"], "state": "pending" } ] }

Rules

Do NOT modify the original markdown plan

Heading format does not matter — handle ####, ###, ##, #####, numbered (1.1), named (Category 1:), etc.

The spec file must be valid JSON (use jq . to verify before writing)

If a section's success criteria mention specific commands (make test, make build, make test_e2e), include those in verify instead of the default

File paths in files should be relative to the repo root

IDs must be unique across all sections in the spec