Skip to content

feat(implement): add ralph mode loop #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
moisgobg wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

feat(implement): add ralph mode loop #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ea2e8e2
feat(implement): add ralph mode loop
moisgobg Jan 27, 2026
c337c49
feat(ralph): refactor autonomous loop to MCP-based AfterTool hooks
moisgobg Jan 29, 2026
14068e5
chore(conductor): Ensure Ralph state file is ignored in VCS
moisgobg Jan 29, 2026
63a3c52
refactor(ralph): Move directive to Markdown and use relative path res…
moisgobg Jan 30, 2026
b843867
feat(ralph): Pivot to Architect Mode (Plan Refinement Loop)
moisgobg Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,3 +209,6 @@ __marimo__/
tmp/

/.gemini/tmp/

# JavaScript
node_modules/
1 change: 1 addition & 0 deletions GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ To find a file (e.g., "**Product Definition**") within a specific context (Proje
- **Product Guidelines**: `conductor/product-guidelines.md`
- **Tracks Registry**: `conductor/tracks.md`
- **Tracks Directory**: `conductor/tracks/`
- **Ralph Loop State**: `conductor/.ralph-state.json` (optional)

**Standard Default Paths (Track):**
- **Specification**: `conductor/tracks/<track_id>/spec.md`
Expand Down
23 changes: 22 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,27 @@ Conductor will:
3. Update the status in the plan as it progresses.
4. **Verify Progress**: Guide you through a manual verification step at the end of each phase to ensure everything works as expected.

#### Ralph Mode (Autonomous Architect)
Ralph Mode upgrades the standard implementation flow into a two-phase autonomous process:

1. **Architect Phase:** The agent iteratively analyzes and refines the track's implementation plan against it's specification until it guarantees a perfect, atomic plan. It acts as a senior architect, ensuring the blueprint is solid before a single line of code is written.
2. **Builder Phase:** Once the plan is certified, the agent switches to autonomous execution. It implements tasks sequentially, running tests and committing code without stopping for confirmation unless it encounters a critical risk (e.g., API keys required).

```bash
/conductor:implement --ralph
```

**Options:**
* `--max-iterations=N`: Sets the retry limit for the Architect Phase (default: 10). If the agent cannot perfect the plan within N attempts, it will stop and ask for help.
* `--manual-replan`: Disables "Autonomous Re-planning." By default, if the agent gets stuck during execution, it will automatically re-enter the Architect Phase to fix the plan. Use this flag to force the agent to PAUSE and ask for your permission before changing the plan.

> [!NOTE]
> For a seamless autonomous experience, you may enable `accepts-edits` or YOLO mode in your configuration.

> [!WARNING]
> Using Gemini CLI in YOLO mode allows the agent to modify files and use tools without explicit confirmation and authorization from the user.


During implementation, you can also:

- **Check status**: Get a high-level overview of your project's progress.
Expand All @@ -113,7 +134,7 @@ During implementation, you can also:
| :--- | :--- | :--- |
| `/conductor:setup` | Scaffolds the project and sets up the Conductor environment. Run this once per project. | `conductor/product.md`<br>`conductor/product-guidelines.md`<br>`conductor/tech-stack.md`<br>`conductor/workflow.md`<br>`conductor/tracks.md` |
| `/conductor:newTrack` | Starts a new feature or bug track. Generates `spec.md` and `plan.md`. | `conductor/tracks/<id>/spec.md`<br>`conductor/tracks/<id>/plan.md`<br>`conductor/tracks.md` |
| `/conductor:implement` | Executes the tasks defined in the current track's plan. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md` |
| `/conductor:implement` | Executes the tasks defined in the current track's plan. Use `--ralph` for autonomous Architect loop. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md` |
| `/conductor:status` | Displays the current progress of the tracks file and active tracks. | Reads `conductor/tracks.md` |
| `/conductor:revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history |
| `/conductor:review` | Reviews completed work against guidelines and the plan. | Reads `plan.md`, `product-guidelines.md` |
Expand Down
64 changes: 53 additions & 11 deletions commands/conductor/implement.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
- **Tech Stack**
- **Workflow**

2. **Handle Failure:** If ANY of these are missing (or their resolved paths do not exist), Announce: "Conductor is not set up. Please run `/conductor:setup`." and HALT.
2. **Handle Failure:** If ANY of these are missing (or their resolved paths do not exist):
- If in Ralph Mode: Call `ralph_end` with `status='FAILURE'` and `message='Conductor is not set up.'`.
- Otherwise: Announce: "Conductor is not set up. Please run `/conductor:setup`." and HALT.


---
Expand All @@ -28,7 +30,9 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
2. **Locate and Parse Tracks Registry:**
- Resolve the **Tracks Registry**.
- Read and parse this file. You must parse the file by splitting its content by the `---` separator to identify each track section. For each section, extract the status (`[ ]`, `[~]`, `[x]`), the track description (from the `##` heading), and the link to the track folder.
- **CRITICAL:** If no track sections are found after parsing, announce: "The tracks file is empty or malformed. No tracks to implement." and halt.
- **CRITICAL:** If no track sections are found after parsing:
- If in Ralph Mode: Call `ralph_end` with `status='FAILURE'` and `message='Tracks file is empty or malformed.'`.
- Otherwise: Announce: "The tracks file is empty or malformed. No tracks to implement." and halt.

3. **Continue:** Immediately proceed to the next step to select a track.

Expand All @@ -43,8 +47,8 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
- Announce: "No track name provided. Automatically selecting the next incomplete track: '<track_description>'."
- Proceed with this track.
3. **If no incomplete tracks are found:**
- Announce: "No incomplete tracks found in the tracks file. All tasks are completed!"
- Halt the process and await further user instructions.
- If in Ralph Mode: Call `ralph_end` with `status='SUCCESS'` and `message='All tracks completed.'`.
- Otherwise: Announce: "No incomplete tracks found in the tracks file. All tasks are completed!" and halt.

5. **Handle No Selection:** If no track is selected, inform the user and await further instructions.

Expand All @@ -64,18 +68,56 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
b. **Read Files:**
- **Track Context:** Using the **Universal File Resolution Protocol**, resolve and read the **Specification** and **Implementation Plan** for the selected track.
- **Workflow:** Resolve **Workflow** (via the **Universal File Resolution Protocol** using the project's index file).
c. **Error Handling:** If you fail to read any of these files, you MUST stop and inform the user of the error.
c. **Error Handling:** If you fail to read any of these files:
- If in Ralph Mode: Call `ralph_end` with `status='FAILURE'` and `message='Failed to read track context files.'`.
- Otherwise: Stop and inform the user of the error.

4. **Execute Tasks and Update Track Plan:**
a. **Announce:** State that you will now execute the tasks from the track's **Implementation Plan** by following the procedures in the **Workflow**.
b. **Iterate Through Tasks:** You MUST now loop through each task in the track's **Implementation Plan** one by one.
c. **For Each Task, You MUST:**
i. **Defer to Workflow:** The **Workflow** file is the **single source of truth** for the entire task lifecycle. You MUST now read and execute the procedures defined in the "Task Workflow" section of the **Workflow** file you have in your context. Follow its steps for implementation, testing, and committing precisely.
---

## 3.1 RALPH ARCHITECT PHASE
**PROTOCOL: If autonomous mode is requested, refine the plan before execution.**

1. **Check for Ralph Flag:** Check if the user provided the `--ralph` flag in their command.
2. **Execute Architect Loop:** If (and ONLY if) the `--ralph` flag is present:
- **Announce:** "Entering Ralph Architect Mode to refine the plan..."
- **Start Loop:** Call `ralph_start` with the following arguments:
- `prompt`: "Analyze and refine the Implementation Plan based on the Specification. Ensure 100% coverage, atomic tasks, and correct dependencies."
- `maxIterations`: The value of the `--max-iterations` flag if provided, otherwise 10.
- **CRITICAL:** Do NOT proceed to the Execution Phase until this tool call returns successfully.

---

## 3.2 EXECUTION PHASE (CONDUCTOR STANDARD)
**PROTOCOL: Execute the tasks from the finalized plan.**

1. **Announce:** State that you will now execute the tasks from the track's **Implementation Plan** by following the procedures in the **Workflow**.
2. **Tool usage:** Do NOT call `ralph_start` or `ralph_end` during this phase. Standard text output is sufficient to communicate progress. These tools are reserved for the Architect Phase only.
3. **Autonomy Directive:**
- **If `--ralph` is present:** You MUST execute the tasks **autonomously** and **sequentially**. Do NOT stop for user confirmation between tasks unless a task is explicitly marked with `(REQUIRES USER INPUT)` or a critical error occurs.
- **Re-planning (Default):** If you encounter a fundamental blocker or determine the future plan is invalid:
- If the `--manual-replan` flag is NOT provided: **Autonomously** announce the issue and re-trigger Section 3.1 (Ralph Architect Phase) by calling `ralph_start` to fix the plan.
- If the `--manual-replan` flag IS provided: **PAUSE** and ask: "I'm stuck. The plan seems invalid given [reason]. Do you want to re-enter the Architect Phase to refine the plan?"
- **If `--ralph` is NOT present:** Follow the standard interactive workflow, prompting the user for confirmation as needed.
3. **Iterate Through Tasks:** You MUST now loop through each task in the track's **Implementation Plan** one by one.
4. **For Each Task, You MUST:**
i. **Defer to Workflow:** The **Workflow** file is the **single source of truth** for the entire task lifecycle. You MUST now read and execute the procedures defined in the "Task Workflow" section of the **Workflow** file you have in your context. Follow its steps for implementation, testing, and committing precisely.

5. **Finalize Track:**
- After all tasks in the track's local **Implementation Plan** are completed, you MUST update the track's status in the **Tracks Registry**.
- This requires finding the specific heading for the track (e.g., `## [~] Track: <Description>`) and replacing it with the completed status (e.g., `## [x] Track: <Description>`).
- **Commit Changes:** Stage the **Tracks Registry** file and commit with the message `chore(conductor): Mark track '<track_description>' as complete`.
- **Verification Summary:** Announce completion by providing a detailed summary in the following format:

**Automated Verification:**
- [Result 1 (e.g., Tests: X% coverage)]
- [Result 2 (e.g., Build: Successful)]
- [Result 3 (e.g., Execution: Command X works as expected)]

**Manual Verification Steps:**
1. [Step 1]
2. [Step 2]
3. [Expected Outcome]

- Announce that the track is fully complete and the tracks file has been updated.

---
Expand Down Expand Up @@ -146,7 +188,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai

1. **Execution Trigger:** This protocol MUST only be executed after the current track has been successfully implemented and the `SYNCHRONIZE PROJECT DOCUMENTATION` step is complete.

2. **Ask for User Choice:** You MUST prompt the user with the available options for the completed track.
2. **Ask for User Choice:** This step is NOT autonomous. Even in Ralph Mode, you MUST PAUSE and prompt the user with the available options for the completed track.
> "Track '<track_description>' is now complete. What would you like to do?
> A. **Review (Recommended):** Run the review command to verify changes before finalizing.
> B. **Archive:** Move the track's folder to `conductor/archive/` and remove it from the tracks file.
Expand Down
10 changes: 8 additions & 2 deletions gemini-extension.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
{
"name": "conductor",
"version": "0.2.0",
"contextFileName": "GEMINI.md"
}
"contextFileName": "GEMINI.md",
"mcpServers": {
"conductorServer": {
"command": "node",
"args": ["${extensionPath}/mcp-server/dist/index.js"]
}
}
}
26 changes: 26 additions & 0 deletions hooks/hooks.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"hooks": {
"AfterTool": [
{
"matcher": "ralph_start",
"hooks": [
{
"type": "command",
"command": "node ${extensionPath}/hooks/ralph-mode/setup.js",
"name": "Ralph Mode Initializer"
}
]
},
{
"matcher": "ralph_end",
"hooks": [
{
"type": "command",
"command": "node ${extensionPath}/hooks/ralph-mode/controller.js",
"name": "Ralph Mode Controller"
}
]
}
]
}
}
147 changes: 147 additions & 0 deletions hooks/ralph-mode/controller.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
const fs = require('fs');
const path = require('path');

/**
* MANAGES THE AUTONOMOUS RALPH LOOP VIA AfterTool HOOK.
*/

const STATE_FILE = path.join(process.cwd(), 'conductor', '.ralph-state.json');

async function main() {
// State File Missing (Quiet Exit)
if (!fs.existsSync(STATE_FILE)) {
console.log(JSON.stringify({}));
return;
}

// Read & Parse Input
let context;
try {
context = JSON.parse(fs.readFileSync(0, 'utf8'));
} catch (e) {
console.log(JSON.stringify({}));
return;
}

const { hook_event_name, tool_name, tool_input } = context;

// Check if this is the end tool
if (hook_event_name !== 'AfterTool' || !tool_name.endsWith('ralph_end')) {
console.log(JSON.stringify({}));
return;
}

// Load current Ralph loop state
let state;
try {
state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
} catch (e) {
console.log(JSON.stringify({}));
return;
}

const { status, message } = tool_input;

// Case: SUCCESS (Loop Complete)
if (status === 'SUCCESS') {
try {
fs.unlinkSync(STATE_FILE);
} catch (e) {
console.error(`[Ralph] Warning: Could not delete state file: ${e.message}`);
}

console.log(JSON.stringify({
decision: "allow",
systemMessage: "✅ Ralph: Cycle complete. Plan Certified.",
}));
return;
}

// Case: STUCK (Loop Aborted by Agent)
// The agent cannot solve the problem (e.g., Bad Spec).
if (status === 'STUCK') {
try {
fs.unlinkSync(STATE_FILE);
} catch (e) {
console.error(`[Ralph] Warning: Could not delete state file: ${e.message}`);
}

console.log(JSON.stringify({
decision: "allow",
systemMessage: "🛑 Ralph: Stuck. Aborting loop to request user input.",
}));
return;
}

// Case: RETRY LOOP (Auto-Correction)

// Check Iteration Limit
if (state.iteration >= state.maxIterations) {
try {
fs.unlinkSync(STATE_FILE);
} catch (e) {
console.error(`[Ralph] Warning: Could not delete state file after max iterations: ${e.message}`);
}
console.log(JSON.stringify({
continue: false,
stopReason: "🛑 Ralph: Max iterations reached.",
}));
return;
}

// Increment Iteration for the next turn
state.iteration += 1;
fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));

// Load Directive
let directiveContent = "";
try {
const directivePath = path.join(__dirname, 'directive.md');
directiveContent = fs.readFileSync(directivePath, 'utf8');
} catch (e) {
console.log(JSON.stringify({
decision: "deny",
reason: `CRITICAL: Ralph Mode controller failed. Could not read directive file (${e.message}). Aborting loop.`,
systemMessage: "🛑 Ralph Controller Failed: Missing directive."
}));
return;
}

// Prepare Re-injection Context
const directive = directiveContent;

const failureContext = `
[RALPH ARCHITECT MESSAGE]:
The previous planning step was interrupted or incomplete.
LAST STATUS: ${status} (Iteration ${state.iteration} of ${state.maxIterations})
REASON: ${message || "No specific reason provided."}

ACTION REQUIRED:
1. **RE-ORIENT:** Re-read the **Specification** and current **Implementation Plan**.
2. **FIX:** Address the gaps, ambiguities, or dependency issues identified in the 'REASON'.
3. **VERIFY:** Ensure 100% coverage and atomic tasks.
4. **FINALIZE:** Call 'ralph_end' with status 'SUCCESS' only when the Plan is fully certified.
`;

const fullContextPrompt = `
${state.originalPrompt || ""}

---
${directive}
---

${failureContext}
`;

// FORCE RETRY
console.log(JSON.stringify({
decision: "deny",
reason: fullContextPrompt, // Re-injects full context prompt.
systemMessage: `🔄 Ralph: ${status} detected. Auto-retrying (Iter ${state.iteration}/${state.maxIterations})...`
}));
}

main().catch(err => {
console.error(`[Ralph Controller] Fatal: ${err.message}`);
process.exit(1);
});
43 changes: 43 additions & 0 deletions hooks/ralph-mode/directive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
## 🔴 RALPH ARCHITECT MODE: PLAN REFINEMENT LOOP
**ATTENTION:** Announce verbatim
> 🔁 Operating in **RALPH MODE** (Architect Phase). Analyzing and refining the plan...

**INSTRUCTIONS:**

1. **Initialization Hygiene:** Ensure the **Ralph Loop State** is excluded from version control and the agent's context. Add it to the appropriate ignore files for the active VCS (e.g., .gitignore, .hgignore) and tool configuration (e.g., .geminiignore) if not already present.

2. **Context Resolution:**
* **Source of Truth:** Read the **Specification**.
* **CRITICAL:** This file is **READ-ONLY**. You MUST NOT edit it.
* If the Specification is empty, missing, or vague, you CANNOT fix it yourself. You MUST call 'ralph_end' with status='STUCK'.
* **Working Draft:** Read the **Implementation Plan** (Mutable).

3. **ARCHITECT LOOP:**
Execute the following cycle iteratively until the plan is perfect:
1. **ANALYZE:** Compare the **Implementation Plan** against the **Specification**.
* **Spec Quality:** Is the **Specification** detailed enough? Does it contain explicit Acceptance Criteria?
(If NO: Call 'ralph_end' with status='STUCK' and request details).
* **Completeness:** Is every requirement in the **Specification** covered by a task?
* **Granularity:** Are all tasks atomic?
- **Rule of Thumb:** If a task description implies multiple distinct actions (e.g., uses the word "and"), it MUST be split.
- No task should represent more than a single logical implementation step.
- Break down vague or complex tasks into clear, executable sub-tasks.
* **Dependencies:** Is the execution order logical?
* **Risk Assessment:** Identify tasks requiring User Intervention (e.g., API keys, Secrets, Physical Device Access).
2. **REFINE:**
* **IF Gaps/Issues:** Edit the **Implementation Plan** to fix them, explain the user the changes and the reason for the changes.
* **IF Risks Found:** Mark these tasks in the plan with `(REQUIRES USER INPUT)`.
* **IF Confused/Inconsistent:** If the plan has become messy or you are unsure how to proceed, call 'ralph_end' with status='RETRY'. This will reset your thought process for the next iteration.
* **CONTINUE LOOP.**
3. **CERTIFY:**
* **IF Perfect:** Certify the plan is 100% complete, granular, ordered, and risks are flagged.
* **PROCEED TO COMPLETION.**

4. **COMPLETION:**
* **WHEN PLAN IS CERTIFIED:**

1. Call 'ralph_end' with status='SUCCESS' and message='Plan finalized and certified.'.
2. **AFTER THE TOOL:** You will receive a confirmation message. **IMMEDIATELY** announce the start of the **Execution Phase** and begin executing Task 1 of the finalized plan.
* **IF STUCK:**
1. Call 'ralph_end' with status='STUCK' and explain the specific blocker.
2. **AFTER THE TOOL:** Inform the user clearly why you are stuck and what specific information or action you need from them to proceed.
Loading
Loading