1. Deprecate the "Instructions" Primitive ✅
The Action: Remove "Instructions" as a distinct concept.
The Logic: Currently, an "Instruction" is just static text injected into a prompt. This is 100% redundant with a "Context" that has no command.
Simplification: Merge the two. A context with no command field in its frontmatter is just a static instruction. This cuts the primitive types from 4 down to 3 and removes the confusing {{ instructions.name }} syntax.
2. Remove the --prompt-file and --prompt Flags ✅
The Action: Eliminate the specific flags for prompt overrides.
The Logic: These flags create a four-level priority conflict with the ralph.toml config and positional arguments.
Simplification: Use the positional argument [PROMPT_NAME] for everything. If the name exists in .ralphify/ralphs/, use that; if it's a valid file path, use the file; if it's neither, treat it as an ad-hoc inline prompt string. This cleans up the run command's help output significantly.
3. Kill the Banner and Promotional Text ✅
The Action: Permanently remove the 8-line ASCII art banner and the "Star us on GitHub" link from the run command.
The Logic: Every line of vertical space matters during a loop. The banner creates "scroll-blindness," pushing the actual configuration and first iteration headers off-screen (F155).
Simplification: Move the branding to the ralph root command only. Keep ralph run strictly functional.
4. Eliminate the "Silent Drop" Placeholder Logic
The Action: Remove the complex tri-modal resolution logic (F157).
The Logic: The tool currently switches modes based on whether you used a named placeholder, which is the single most common reason users lose data.
Simplification: Default to one single mode: Always append. Placeholders determine where specific text goes, but anything not explicitly placed is always appended to the tail. No more "modes" to learn.
5. Remove Implicit ralph init --force Overwriting ✅
The Action: Stop ralph init --force from being a "nuke" option.
The Logic: Currently, --force overwrites both your config and your carefully crafted RALPH.md prompt.
Simplification: Make init non-destructive by default for existing files. If a user wants to reset the config, they delete the .toml. Removing the "overwrite" functionality protects the user's most valuable asset: the prompt.
6. Strip HTML Comments from Templates
The Action: Remove the multi-line HTML "explainer" comments from the scaffolded markdown files.
The Logic: While the engine strips them, they create massive visual noise when a user opens a file to edit it (F4).
Simplification: Use clean, minimal templates. If the user needs documentation, they can run ralph help or check the site. Let the code/config speak for itself.
7. Remove Manual ralph status Validation
The Action: Stop requiring the user to run ralph status to check for PATH issues.
The Logic: If the tool knows the agent command is missing or the check script isn't executable, it shouldn't wait for a manual "status" check to say so.
Simplification: Remove the "readiness" check from the UI. Build it directly into the run command's startup. If a command is missing, throw a clean error and stop immediately.
8. Deprioritize/Hide the Dashboard Event Infrastructure
The Action: Remove or hide the WebSocket and Event Fanout logic from the core CLI.
The Logic: The codebase is heavily weighted with "QueueEmitters" and "RunManagers" intended for a web UI that doesn't exist yet. This adds complexity to the CLI startup.
Simplification: Strip the CLI back to a simple, direct synchronous emitter. The dashboard-ready architecture can live in a separate branch until the UI is actually released.
9. Replace YAML-Style Multi-Line Frontmatter with Key-Value Pairs
The Action: Formally limit frontmatter to a flat set of keys.
The Logic: The current parser is a "pseudo-YAML" parser that fails on complex indentation or colons within values (F75).
Simplification: Remove support for nested structures. If a check needs complex config, it should live in the markdown body or a separate file. This makes the parser bulletproof and its errors easier to catch.
10. Kill the --stop-on-error Flag
The Action: Remove the flag and bake the behavior into the core loop logic.
The Logic: Users find the distinction between "agent error" and "check failure" confusing (F33).
Simplification: The loop should always stop on a fatal agent crash (exit code 127, etc.) and always continue on a check failure. Removing the flag removes the ambiguity.
1.
Deprecate the "Instructions" Primitive✅The Action: Remove "Instructions" as a distinct concept.
The Logic: Currently, an "Instruction" is just static text injected into a prompt. This is 100% redundant with a "Context" that has no command.
Simplification: Merge the two. A context with no
commandfield in its frontmatter is just a static instruction. This cuts the primitive types from 4 down to 3 and removes the confusing{{ instructions.name }}syntax.2.
Remove the✅--prompt-fileand--promptFlagsThe Action: Eliminate the specific flags for prompt overrides.
The Logic: These flags create a four-level priority conflict with the
ralph.tomlconfig and positional arguments.Simplification: Use the positional argument
[PROMPT_NAME]for everything. If the name exists in.ralphify/ralphs/, use that; if it's a valid file path, use the file; if it's neither, treat it as an ad-hoc inline prompt string. This cleans up theruncommand's help output significantly.3.
Kill the Banner and Promotional Text✅The Action: Permanently remove the 8-line ASCII art banner and the "Star us on GitHub" link from the
runcommand.The Logic: Every line of vertical space matters during a loop. The banner creates "scroll-blindness," pushing the actual configuration and first iteration headers off-screen (F155).
Simplification: Move the branding to the
ralphroot command only. Keepralph runstrictly functional.4. Eliminate the "Silent Drop" Placeholder Logic
The Action: Remove the complex tri-modal resolution logic (F157).
The Logic: The tool currently switches modes based on whether you used a named placeholder, which is the single most common reason users lose data.
Simplification: Default to one single mode: Always append. Placeholders determine where specific text goes, but anything not explicitly placed is always appended to the tail. No more "modes" to learn.
5.
Remove Implicit✅ralph init --forceOverwritingThe Action: Stop
ralph init --forcefrom being a "nuke" option.The Logic: Currently,
--forceoverwrites both your config and your carefully craftedRALPH.mdprompt.Simplification: Make
initnon-destructive by default for existing files. If a user wants to reset the config, they delete the.toml. Removing the "overwrite" functionality protects the user's most valuable asset: the prompt.6. Strip HTML Comments from Templates
The Action: Remove the multi-line HTML "explainer" comments from the scaffolded markdown files.
The Logic: While the engine strips them, they create massive visual noise when a user opens a file to edit it (F4).
Simplification: Use clean, minimal templates. If the user needs documentation, they can run
ralph helpor check the site. Let the code/config speak for itself.7. Remove Manual
ralph statusValidationThe Action: Stop requiring the user to run
ralph statusto check for PATH issues.The Logic: If the tool knows the agent command is missing or the check script isn't executable, it shouldn't wait for a manual "status" check to say so.
Simplification: Remove the "readiness" check from the UI. Build it directly into the
runcommand's startup. If a command is missing, throw a clean error and stop immediately.8. Deprioritize/Hide the Dashboard Event Infrastructure
The Action: Remove or hide the WebSocket and Event Fanout logic from the core CLI.
The Logic: The codebase is heavily weighted with "QueueEmitters" and "RunManagers" intended for a web UI that doesn't exist yet. This adds complexity to the CLI startup.
Simplification: Strip the CLI back to a simple, direct synchronous emitter. The dashboard-ready architecture can live in a separate branch until the UI is actually released.
9. Replace YAML-Style Multi-Line Frontmatter with Key-Value Pairs
The Action: Formally limit frontmatter to a flat set of keys.
The Logic: The current parser is a "pseudo-YAML" parser that fails on complex indentation or colons within values (F75).
Simplification: Remove support for nested structures. If a check needs complex config, it should live in the markdown body or a separate file. This makes the parser bulletproof and its errors easier to catch.
10. Kill the
--stop-on-errorFlagThe Action: Remove the flag and bake the behavior into the core loop logic.
The Logic: Users find the distinction between "agent error" and "check failure" confusing (F33).
Simplification: The loop should always stop on a fatal agent crash (exit code 127, etc.) and always continue on a check failure. Removing the flag removes the ambiguity.