ralphex

All converted plans must strictly follow these structural rules to be compatible with the ralphex parser:

• H1 Title: The file must start with # <Plan Title>.
• Standard Sections: Sections must appear in this order:
  1. ## Overview
  2. ## Context
  3. ## Development Approach
  4. ## Testing Strategy
  5. ## Progress Tracking
  6. ## Technical Details (optional)
  7. ## Implementation Steps
  8. ## Post-Completion (optional)
• Task Headers: Use the exact English format ### Task <N>: <title>. The keyword Task must be English, even if the rest of the plan is in another language.
• Checkboxes: Use - [ ] or - [x]. These must appear only inside Task sections. Placing checkboxes in other sections (like Overview or Context) will cause the executor to incorrectly spawn extra iterations.
• Mandatory Task Endings: Every Task must end with two specific checkboxes:
  • - [ ] write tests
  • - [ ] run project tests
• Final Task: The last task must always be ### Task <last>: Verify acceptance criteria, which includes items to re-run the test suite, run the linter, and confirm requirements from the Overview.

When using a Mercurial backend via a wrapper script like hg2git.sh, ralphex follows a 'single-diff model' using Mercurial's phases to mimic Git's branching and committing behavior:

1. Branch Detection: ralphex uses symbolic-ref --short HEAD. The script maps the Mercurial phase to a branch name:
   • public phase $\rightarrow$ returns master (signals ralphex to create a new branch).
   • draft phase $\rightarrow$ returns the bookmark name or draft (signals ralphex to skip branch creation as it is already working on an unsent commit).
2. Committing Logic:
   • The first commit from a public state triggers hg commit -m "msg", creating a new draft commit.
   • All subsequent commit calls trigger hg amend [files...]. This allows a single commit to grow with each task in a plan execution.
3. Status Conversion: The script must convert Mercurial's 1-character status to Git's 2-character XY porcelain format (e.g., padding the single char) so that extractPathFromPorcelain() in the Go backend can parse it correctly.

The ralphex processor execution is orchestrated by a Runner that coordinates a pipeline of specialized Phase Engines.

Core Components

• pkg/processor.Runner: Acts as a pipeline coordinator. It manages mode selection and phase ordering but does not own the specific logic for each phase. It holds unexported phase interfaces.
• Phase Engines: Concrete types located in pkg/processor/phase. They implement specific stages of the execution lifecycle.
• phase.Deps: A mechanism for handling dependencies that are set after construction (late-bound). Phases read from this holder at runtime, allowing the Runner to update dependencies via setters without causing nil pointer errors or requiring phases to call back into the Runner.
• executionPolicy: A service that handles shared executor behavior, including runWithLimitRetry, runWithSessionTimeout, and idle-timeout tracking.
• promptBuilder: A service that handles prompt rendering. Phases request final prompts from this builder rather than managing template replacement details themselves.
• planLocator: Manages plan path resolution, shared by the promptBuilder and task-phase plan state checks.

Dependency Injection and Lifecycle

• Production: Standard constructors like New and NewWithExecutors build the Runner with default concrete phase engines.
• Testing: A test-only phase injection helper is exposed via export_test.go to allow orchestration tests to inject mock phases.
• Post-Construction Setters: The Runner supports existing setters that affect already-constructed runners:
  • SetInputCollector
  • SetGitChecker
  • SetBreakCh
  • SetPauseHandler

The Ralphex web dashboard uses position-based matching to highlight tasks. Instead of relying on the integer number found in markdown headers (which can fail if tasks are non-integers like Task 2.5 or if the plan is edited mid-run), the system uses the task's 1-indexed position in the plan array.

Data Flow:

1. Plan Parsing: plan.ParsePlanFile() converts the markdown plan into a slice of Task objects.
2. Runner Execution: The runner calls nextPlanTaskPosition() to find the 1-indexed position of the first task where status != TaskStatusDone.
3. Event Broadcasting: The runner passes this position to NewTaskIterationSection(pos), which the BroadcastLogger includes in events as TaskNum.
4. Frontend Rendering: The dashboard renders task elements with a data-task-num attribute corresponding to their position (index + 1). When a task starts, the frontend matches the incoming task_num against these elements to apply highlighting.

The Plan Draft Preview introduces a feedback loop during plan creation. Instead of Claude writing a plan file directly to disk, it emits a PLAN_DRAFT signal. This allows the user to review the proposed plan in the terminal before any files are actually changed.

The Workflow

1. Draft Generation: Claude generates a plan and wraps it in the PLAN_DRAFT signal markers.
2. User Review: The plan is rendered in the terminal (using glamour for markdown styling).
3. User Action: The user chooses one of three actions:
   • Accept: The plan is approved, and Claude proceeds to write the files and emit PLAN_READY.
   • Revise: The user provides free-form feedback. This feedback is logged to the progress file, and Claude is re-run with the feedback context to generate a new draft.
   • Reject: The process exits gracefully with an error, indicating the user rejected the plan.

Signal Format

Claude uses the following format to trigger the preview:

<<<RALPHEX:PLAN_DRAFT>>>
# Plan Title

## Overview
...

## Tasks
...
<<<RALPHEX:END>>>