from-file

Create a structured execution plan based on an existing markdown file.

Arguments

• file_path (required): Path to the markdown file containing the task/feature description
• --type (optional): Work type template to use (feature, bugfix, refactor, migration, performance)
• --output (optional): Path to save the generated plan (e.g., ./plans/my-plan.md)

Instructions

Language: Generate the plan in the same language as the source file content.

You are a planning assistant. Create a structured plan based on the content of a file.

Step 1: Read the File

Read the file at the specified path: $ARGUMENTS

Extract parameters from arguments:

• file_path: The path to the source file
• --type <type>: (optional) Use specific template
• --output <path>: (optional) Save plan to this file

If no type specified, analyze the content to determine the best template.

Step 2: Analyze Content

Read and understand the file content. Look for:

• What is being requested/described?
• What is the scope and complexity?
• Are there acceptance criteria or requirements listed?
• What type of work is this? (feature, bugfix, refactor, migration, performance)

Step 3: Select Template

If --type was specified, use that template. Otherwise, auto-detect:

Content indicators	Template
"add", "implement", "create", "new feature"	feature
"fix", "bug", "issue", "broken", "error"	bugfix
"refactor", "restructure", "clean up", "improve code"	refactor
"migrate", "move", "upgrade", "convert"	migration
"performance", "optimize", "slow", "speed", "latency"	performance

Step 4: Generate Plan

Using the selected template, generate a structured plan that:

1. Uses the phases from the template
2. Creates specific tasks based on the file content
3. Includes verifiable promises from the template
4. Incorporates any requirements/criteria from the file

Output format:

## Plan: [Title derived from file content]

**Source:** [file path]
**Template:** [selected template type]

### Phase 1: [Phase Name from template]
**Tasks:**
- [ ] [Task derived from file content]
- [ ] ...

**Completion Criteria:** [From template + file specifics]

[Continue for all phases...]

---

**Total Tasks:** [count]
**Estimated Iterations:** [count × 3]

🏷️ **Promise Tag:** [Verifiable promises from template]

⚠️ **Completion Signal:** When ALL criteria above are met, output:
<promise>COMPLETE</promise>

Step 5: Generate Loop Command

After the plan, output the ready-to-run command using the correct ralph-wiggum format:

Format (with --output):

/ralph-wiggum:ralph-loop "Implement [summary] from [plan-path]. DONE when: [criteria]. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations [iterations]

Format (without --output):

/ralph-wiggum:ralph-loop "[summary]. DONE when: [criteria]. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations [iterations]

Examples:

# With --output (includes plan path):
/ralph-wiggum:ralph-loop "Implement auth features from ./plans/auth-plan.md. DONE when: login works, tests pass. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 42

# Without --output:
/ralph-wiggum:ralph-loop "Implement auth features. DONE when: login works, tests pass. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 42

Step 6: Save Plan (if --output specified)

If --output <path> was provided:

1. Create the directory if it doesn't exist
2. Save ONLY the plan from Step 4 to the file (phases, tasks, criteria, promise tag)
3. DO NOT save the execution commands (Step 5) to the file — they go only in chat
4. Confirm: "Plan saved to [path]"

Why? The execution commands are for the USER to copy/run. If saved in the plan file, ralph-loop might misinterpret them as tasks to execute.

After saving, display the execution commands in the chat so the user can copy them.

Step 7: STOP - Do Not Execute

CRITICAL: After completing steps 1-6, you are DONE.

⛔ DO NOT:

• Start implementing any tasks
• Run any ralph-loop commands
• Begin coding or making changes
• Execute anything from the plan

✅ DO:

• Display the plan summary
• Show the execution commands for the user to copy
• Wait for the user to manually run the commands

The user will copy and run the ralph-loop command themselves when ready.

Examples

/ralph-planner:from-file "./docs/auth-feature.md"
/ralph-planner:from-file "./issues/bug-123.md" --type bugfix
/ralph-planner:from-file "./specs/api-migration.md" --type migration
/ralph-planner:from-file "./docs/feature.md" --output "./plans/feature-plan.md"
/ralph-planner:from-file ".serena/memory/tasks.md" --type feature --output "./plans/tasks-plan.md"

Guidelines

• Preserve important details from the source file
• Map file requirements to specific tasks
• If file has acceptance criteria, incorporate into completion criteria
• Auto-detection is best-effort; use --type when certain