Skip to content

Commit 3c9e08b

Browse files
moisgobgmoisgobg
committed
feat(ralph): Pivot to Architect Mode (Plan Refinement Loop)
1 parent fee58cf commit 3c9e08b

6 files changed

Lines changed: 98 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,14 +91,19 @@ Conductor will:
9191
3. Update the status in the plan as it progresses.
9292
4. **Verify Progress**: Guide you through a manual verification step at the end of each phase to ensure everything works as expected.
9393

94-
#### Ralph Mode (Autonomous Loop)
95-
Ralph Mode is a functionality based on the Geoffrey Huntley's Ralph loop technique for the Gemini CLI that enables continuous autonomous development cycles. It allows the agent to iteratively improve your project until completion, following an automated Red-Green-Refactor loop with built-in safeguards to prevent infinite loops.
94+
#### Ralph Mode (Autonomous Architect)
95+
Ralph Mode upgrades the standard implementation flow into a two-phase autonomous process:
96+
97+
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.
98+
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).
9699

97100
```bash
98101
/conductor:implement --ralph
99102
```
100-
* `--max-iterations=N`: Change the retry limit (default: 10).
101-
* `--completion-word=WORD`: Change the work completion magic word (default: TRACK_COMPLETE).
103+
104+
**Options:**
105+
* `--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.
106+
* `--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.
102107

103108
> [!NOTE]
104109
> For a seamless autonomous experience, you may enable `accepts-edits` or YOLO mode in your configuration.
@@ -129,7 +134,7 @@ During implementation, you can also:
129134
| :--- | :--- | :--- |
130135
| `/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` |
131136
| `/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` |
132-
| /conductor:implement | Executes the tasks defined in the current track's plan. Use `--ralph` for autonomous TDD loop. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md` |
137+
| `/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` |
133138
| `/conductor:status` | Displays the current progress of the tracks file and active tracks. | Reads `conductor/tracks.md` |
134139
| `/conductor:revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history |
135140
| `/conductor:review` | Reviews completed work against guidelines and the plan. | Reads `plan.md`, `product-guidelines.md` |

‎commands/conductor/implement.toml‎

Lines changed: 42 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,6 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
77
88
---
99
10-
## 1.0.1 RALPH INITIALIZATION
11-
**PROTOCOL: If autonomous mode is requested, initialize the Ralph loop.**
12-
13-
1. **Check for Ralph Flag:** Check if the user provided the `--ralph` flag in their command.
14-
2. **Initialize Loop:** If (and ONLY if) the `--ralph` flag is present:
15-
- You MUST immediately call the tool `ralph_start` with the following arguments:
16-
- `prompt`: The full text of the user's current request.
17-
- `maxIterations`: The value of the `--max-iterations` flag if provided, otherwise 10.
18-
- `completionWord`: The value of the `--completion-word` flag if provided, otherwise "TRACK_COMPLETE".
19-
- **CRITICAL:** Do NOT proceed to any other steps until this tool call returns successfully.
20-
21-
---
22-
2310
## 1.1 SETUP CHECK
2411
**PROTOCOL: Verify that the Conductor environment is properly set up.**
2512
@@ -85,16 +72,52 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
8572
- If in Ralph Mode: Call `ralph_end` with `status='FAILURE'` and `message='Failed to read track context files.'`.
8673
- Otherwise: Stop and inform the user of the error.
8774
88-
4. **Execute Tasks and Update Track Plan:**
89-
a. **Announce:** State that you will now execute the tasks from the track's **Implementation Plan** by following the procedures in the **Workflow**.
90-
b. **Iterate Through Tasks:** You MUST now loop through each task in the track's **Implementation Plan** one by one.
91-
c. **For Each Task, You MUST:**
92-
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.
75+
---
76+
77+
## 3.1 RALPH ARCHITECT PHASE
78+
**PROTOCOL: If autonomous mode is requested, refine the plan before execution.**
79+
80+
1. **Check for Ralph Flag:** Check if the user provided the `--ralph` flag in their command.
81+
2. **Execute Architect Loop:** If (and ONLY if) the `--ralph` flag is present:
82+
- **Announce:** "Entering Ralph Architect Mode to refine the plan..."
83+
- **Start Loop:** Call `ralph_start` with the following arguments:
84+
- `prompt`: "Analyze and refine the Implementation Plan based on the Specification. Ensure 100% coverage, atomic tasks, and correct dependencies."
85+
- `maxIterations`: The value of the `--max-iterations` flag if provided, otherwise 10.
86+
- **CRITICAL:** Do NOT proceed to the Execution Phase until this tool call returns successfully.
87+
88+
---
89+
90+
## 3.2 EXECUTION PHASE (CONDUCTOR STANDARD)
91+
**PROTOCOL: Execute the tasks from the finalized plan.**
92+
93+
1. **Announce:** State that you will now execute the tasks from the track's **Implementation Plan** by following the procedures in the **Workflow**.
94+
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.
95+
3. **Autonomy Directive:**
96+
- **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.
97+
- **Re-planning (Default):** If you encounter a fundamental blocker or determine the future plan is invalid:
98+
- 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.
99+
- 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?"
100+
- **If `--ralph` is NOT present:** Follow the standard interactive workflow, prompting the user for confirmation as needed.
101+
3. **Iterate Through Tasks:** You MUST now loop through each task in the track's **Implementation Plan** one by one.
102+
4. **For Each Task, You MUST:**
103+
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.
93104
94105
5. **Finalize Track:**
95106
- After all tasks in the track's local **Implementation Plan** are completed, you MUST update the track's status in the **Tracks Registry**.
96107
- 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>`).
97108
- **Commit Changes:** Stage the **Tracks Registry** file and commit with the message `chore(conductor): Mark track '<track_description>' as complete`.
109+
- **Verification Summary:** Announce completion by providing a detailed summary in the following format:
110+
111+
**Automated Verification:**
112+
- [Result 1 (e.g., Tests: X% coverage)]
113+
- [Result 2 (e.g., Build: Successful)]
114+
- [Result 3 (e.g., Execution: Command X works as expected)]
115+
116+
**Manual Verification Steps:**
117+
1. [Step 1]
118+
2. [Step 2]
119+
3. [Expected Outcome]
120+
98121
- Announce that the track is fully complete and the tracks file has been updated.
99122
100123
---
@@ -165,7 +188,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
165188
166189
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.
167190
168-
2. **Ask for User Choice:** You MUST prompt the user with the available options for the completed track.
191+
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.
169192
> "Track '<track_description>' is now complete. What would you like to do?
170193
> A. **Review (Recommended):** Run the review command to verify changes before finalizing.
171194
> B. **Archive:** Move the track's folder to `conductor/archive/` and remove it from the tracks file.

‎hooks/ralph-mode/controller.js‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -92,21 +92,20 @@ async function main() {
9292
return;
9393
}
9494

95-
9695
// Prepare Re-injection Context
97-
const directive = directiveContent.replace('{{COMPLETION_WORD}}', state.completionWord);
96+
const directive = directiveContent;
9897

9998
const failureContext = `
100-
[RALPH SYSTEM MESSAGE]:
101-
The previous session context was cleared to ensure focus.
102-
LAST STATUS: ${status} (Iteration ${state.iteration - 1} of ${state.maxIterations})
99+
[RALPH ARCHITECT MESSAGE]:
100+
The previous planning step was interrupted or incomplete.
101+
LAST STATUS: ${status} (Iteration ${state.iteration} of ${state.maxIterations})
103102
REASON: ${message || "No specific reason provided."}
104103
105104
ACTION REQUIRED:
106-
1. **RE-ORIENT:** Analyze the current project state (git status, diff, logs).
107-
2. **FIX:** Modify the code, tests, or **Strategy** based on the failure reason.
108-
3. **VERIFY:** Run tests again.
109-
4. **FINALIZE:** Call 'ralph_end' with status 'SUCCESS' only when all tests pass and requirements are met.
105+
1. **RE-ORIENT:** Re-read the **Specification** and current **Implementation Plan**.
106+
2. **FIX:** Address the gaps, ambiguities, or dependency issues identified in the 'REASON'.
107+
3. **VERIFY:** Ensure 100% coverage and atomic tasks.
108+
4. **FINALIZE:** Call 'ralph_end' with status 'SUCCESS' only when the Plan is fully certified.
110109
`;
111110

112111
const fullContextPrompt = `

‎hooks/ralph-mode/directive.md‎

Lines changed: 36 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,39 @@
1-
## 🔴 RALPH MODE ACTIVE: TASK EXECUTION OVERRIDE
1+
## 🔴 RALPH ARCHITECT MODE: PLAN REFINEMENT LOOP
22
**ATTENTION:** Announce verbatim
3-
> 🔁 Operating in **RALPH MODE** autonomous loop.
3+
> 🔁 Operating in **RALPH MODE** (Architect Phase). Analyzing and refining the plan...
44

55
**INSTRUCTIONS:**
6-
1. **Initialization Hygiene:** Ensure the **Ralph Loop State** (resolved via the **Universal File Resolution Protocol**) 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.
7-
2. **Execute Standard Protocol:** You MUST follow Steps **3.1**, **3.2**, **3.3**, and **3.5** of the "TRACK IMPLEMENTATION" protocol exactly as defined in the prompt.
8-
3. **Shell Command Execution:** Use flags that reject or prevent interactive user input (e.g., "-n", "--no-input").
9-
4. **AUTONOMOUS CYCLE:**
10-
- For each task, execute this **RALPH CYCLE**:
11-
1. **RED:** Write failing tests based on the **Specification**.
12-
2. **GREEN:** Implement code to pass tests.
13-
3. **VERIFY:** Run tests.
14-
- **IF FAIL:** Attempt to fix and re-run. If still failing, call 'ralph_end' with status='FAILURE' and include the error details in the message.
15-
- **PASS:** Proceed to the next task.
16-
4. **RECORD:** Update plan status to [x] and commit changes.
17-
5. **SKIP MANUAL TASKS:** Mark any task involving "Manual Verification" or "User Feedback" as [x] immediately and proceed. Ralph's tests are the only source of truth.
18-
6. **COMPLETION:**
19-
- **WHEN DONE:** If all tests pass and the track is [x]:
20-
1. Call 'ralph_end' with status='SUCCESS' and message='Task complete: {{COMPLETION_WORD}}'.
21-
2. **AFTER THE TOOL:** You will receive a confirmation message. **IMMEDIATELY** proceed to **Section 5.0** (Track Cleanup) and prompt the user.
22-
- **IF STUCK:** If you are unable to proceed due to ambiguity or tool failures, call 'ralph_end' with status='STUCK' and explain why.
6+
7+
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.
8+
9+
2. **Context Resolution:**
10+
* **Source of Truth:** Read the **Specification** (Immutable).
11+
* **Working Draft:** Read the **Implementation Plan** (Mutable).
12+
13+
3. **ARCHITECT LOOP:**
14+
Execute the following cycle iteratively until the plan is perfect:
15+
1. **ANALYZE:** Compare the **Implementation Plan** against the **Specification**.
16+
* **Spec Quality:** Is the **Specification** detailed enough? Does it contain explicit Acceptance Criteria?
17+
(If NO: Call 'ralph_end' with status='STUCK' and request details).
18+
* **Completeness:** Is every requirement in the **Specification** covered by a task?
19+
* **Granularity:** Are all tasks atomic?
20+
- **Rule of Thumb:** If a task description implies multiple distinct actions (e.g., uses the word "and"), it MUST be split.
21+
- No task should represent more than a single logical implementation step.
22+
- Break down vague or complex tasks into clear, executable sub-tasks.
23+
* **Dependencies:** Is the execution order logical?
24+
* **Risk Assessment:** Identify tasks requiring User Intervention (e.g., API keys, Secrets, Physical Device Access).
25+
2. **REFINE:**
26+
* **IF Gaps/Issues:** Edit the **Implementation Plan** to fix them, explain the user the changes and the reason for the changes.
27+
* **IF Risks Found:** Mark these tasks in the plan with `(REQUIRES USER INPUT)`.
28+
* **CONTINUE LOOP.**
29+
3. **CERTIFY:**
30+
* **IF Perfect:** Certify the plan is 100% complete, granular, ordered, and risks are flagged.
31+
* **PROCEED TO COMPLETION.**
32+
33+
4. **COMPLETION:**
34+
* **WHEN PLAN IS CERTIFIED:**
35+
36+
1. Call 'ralph_end' with status='SUCCESS' and message='Plan finalized and certified.'.
37+
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.
38+
* **IF STUCK:**
39+
* Call 'ralph_end' with status='STUCK' and explain the specific blocker.

‎hooks/ralph-mode/setup.js‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,10 @@ async function main() {
2828
// --- RALPH MODE DETECTED ---
2929

3030
const prompt = tool_input.prompt || "";
31-
const completionWord = tool_input.completionWord || 'TRACK_COMPLETE';
3231
const maxIterations = tool_input.maxIterations || 10;
3332

3433
// Create State File
3534
const state = {
36-
completionWord: completionWord,
3735
maxIterations: maxIterations,
3836
iteration: 1,
3937
startedAt: new Date().toISOString(),
@@ -67,15 +65,15 @@ async function main() {
6765
return;
6866
}
6967

70-
const directive = directiveContent.replace('{{COMPLETION_WORD}}', completionWord);
68+
const directive = directiveContent;
7169

7270
// Output the JSON response
7371
console.log(JSON.stringify({
7472
hookSpecificOutput: {
7573
hookEventName: "AfterTool",
7674
additionalContext: directive
7775
},
78-
systemMessage: "🔴 Ralph Mode Activated: TDD Loop Engaged.",
76+
systemMessage: "🔴 Ralph Mode Activated: Architect Phase Engaged.",
7977
}));
8078
}
8179

‎mcp-server/src/index.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ server.registerTool(
2323
inputSchema: {
2424
prompt: z.string().describe('The full text of the user\'s request.'),
2525
maxIterations: z.number().describe('The maximum number of iterations for the loop.'),
26-
completionWord: z.string().describe('The word that signals completion.'),
2726
} as any,
2827
},
2928
async (args: any) => {

0 commit comments

Comments
 (0)