Skip to content

Commit c5107f7

Browse files
anushibinjanushibinj
committed
✨ Update README.md to enhance feature descriptions and add Quick Start workflow and status bar integration
1 parent 5fa76ec commit c5107f7

File tree

1 file changed

+54
-50
lines changed

1 file changed

+54
-50
lines changed

‎README.md‎

Lines changed: 54 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -8,65 +8,68 @@ Use it for migrations, bug fixes, feature implementation, refactoring, test crea
88

99
## Features
1010

11-
- **Autonomous looping** — Executes up to 2 steps per run (configurable), then pauses so you can review before continuing.
11+
- **Autonomous looping** — Executes up to a configurable number of steps per run (default: 2), then pauses for review before continuing.
1212
- **Three action types:**
13-
- `copilot_task` — Sends a detailed prompt to Copilot Chat and waits for it to finish making changes.
14-
- `run_terminal` — Opens a terminal, runs a shell command, and waits for completion.
15-
- `create_file` — Delegates file creation to Copilot with contextual instructions.
13+
- `copilot_task` — Sends a detailed prompt to Copilot Chat and waits for it to finish making changes.
14+
- `run_terminal` — Opens a terminal, runs a shell command, and waits for completion.
15+
- `create_file` — Delegates file creation to Copilot with contextual instructions.
1616
- **Activity-based completion detection** — Monitors workspace events (file edits, file creation, terminal activity) to determine when Copilot has finished processing a step.
1717
- **Persistent status tracking** — All progress is written to `STATUS.md` so you can stop, restart VS Code, or resume at any time.
1818
- **Smart skip detection** — Before executing a step, RALPH checks whether the outcome already exists (e.g., file already created, directory already exists, `node_modules` already installed) and skips it automatically.
1919
- **Fully resumable** — If a step is left `in-progress`, RALPH picks it up on the next start. Failed steps are logged and skipped so the pipeline continues.
20+
- **Quick Start workflow** — Easily generate or import `PLAN.md` and `STATUS.md` using the built-in Quick Start, including Copilot-powered plan generation from a user goal.
21+
- **Status bar integration** — Shows RALPH's current state and provides quick access to commands.
22+
- **Comprehensive status and reset commands** — View progress, reset steps, and manage the plan directly from the command palette or status bar menu.
2023

2124
## Requirements
2225

2326
- **VS Code** 1.109.0 or later
2427
- **GitHub Copilot Chat** extension installed and signed in — RALPH delegates code tasks to Copilot via the chat API.
2528
- Two markdown files in your workspace root:
26-
- **`PLAN.md`** — Contains a fenced ` ```json ` block with a `{ "steps": [...] }` array defining each step.
27-
- **`STATUS.md`** — A markdown table tracking the status of each step (`pending`, `in-progress`, `done`, `failed`, `skipped`) along with timestamps and notes. Also includes a quick-status summary section that RALPH updates automatically.
29+
- **`PLAN.md`** — Contains a fenced ` ```json ` block with a `{ "steps": [...] }` array defining each step.
30+
- **`STATUS.md`** — A markdown table tracking the status of each step (`pending`, `in-progress`, `done`, `failed`, `skipped`) along with timestamps and notes. Also includes a quick-status summary section that RALPH updates automatically.
2831

2932
### PLAN.md format
3033

3134
The plan file must contain a fenced JSON block with a `steps` array. Each step has the following fields:
3235

3336
```json
3437
{
35-
"steps": [
36-
{
37-
"id": 1,
38-
"phase": "Setup",
39-
"action": "run_terminal",
40-
"command": "mkdir -p src/main/java",
41-
"description": "Create project directory structure"
42-
},
43-
{
44-
"id": 2,
45-
"phase": "Configuration",
46-
"action": "create_file",
47-
"path": "src/main/resources/application.properties",
48-
"description": "Create Spring Boot application properties"
49-
},
50-
{
51-
"id": 3,
52-
"phase": "Implementation",
53-
"action": "copilot_task",
54-
"instruction": "Add unit tests for all service classes in src/services/...",
55-
"description": "Create unit tests for services"
56-
}
57-
]
38+
"steps": [
39+
{
40+
"id": 1,
41+
"phase": "Setup",
42+
"action": "run_terminal",
43+
"command": "mkdir -p src/main/java",
44+
"description": "Create project directory structure"
45+
},
46+
{
47+
"id": 2,
48+
"phase": "Configuration",
49+
"action": "create_file",
50+
"path": "src/main/resources/application.properties",
51+
"description": "Create Spring Boot application properties"
52+
},
53+
{
54+
"id": 3,
55+
"phase": "Implementation",
56+
"action": "copilot_task",
57+
"instruction": "Add unit tests for all service classes in src/services/...",
58+
"description": "Create unit tests for services"
59+
}
60+
]
5861
}
5962
```
6063

61-
| Field | Required | Description |
62-
| ------------- | -------- | ------------------------------------------------------------ |
63-
| `id` | Yes | Unique numeric step identifier |
64-
| `phase` | Yes | Logical grouping label (e.g., "Setup", "Implementation") |
65-
| `action` | Yes | One of `run_terminal`, `create_file`, or `copilot_task` |
66-
| `description` | Yes | Human-readable summary of what the step does |
67-
| `command` | If `run_terminal` | Shell command to execute |
68-
| `path` | If `create_file` | Workspace-relative path of the file to create |
69-
| `instruction` | If `copilot_task` | Detailed instructions for Copilot to follow |
64+
| Field | Required | Description |
65+
| ------------- | ----------------- | -------------------------------------------------------- |
66+
| `id` | Yes | Unique numeric step identifier |
67+
| `phase` | Yes | Logical grouping label (e.g., "Setup", "Implementation") |
68+
| `action` | Yes | One of `run_terminal`, `create_file`, or `copilot_task` |
69+
| `description` | Yes | Human-readable summary of what the step does |
70+
| `command` | If `run_terminal` | Shell command to execute |
71+
| `path` | If `create_file` | Workspace-relative path of the file to create |
72+
| `instruction` | If `copilot_task` | Detailed instructions for Copilot to follow |
7073

7174
### STATUS.md format
7275

@@ -81,28 +84,29 @@ It also looks for a quick-status summary section with lines like `| Total Steps
8184
## Usage
8285

8386
1. Create `PLAN.md` and `STATUS.md` in your workspace root (see formats above), or use **RALPH: Quick Start** to generate them.
84-
2. Open the Command Palette (`Ctrl+Shift+P`) and run one of the RALPH commands.
87+
2. Open the Command Palette (`Ctrl+Shift+P`) or use the status bar menu to run RALPH commands.
8588
3. RALPH will begin processing pending steps, logging progress to the **RALPH Runner** output channel.
86-
4. After the configured number of steps (default: 2), RALPH pauses — review the changes, then run **RALPH: Start** again to continue.
89+
4. After the configured number of steps, RALPH pauses — review the changes, then run **RALPH: Start** again to continue.
8790

8891
## Commands
8992

90-
| Command | Description |
91-
| -------------------------- | --------------------------------------------------------------------------- |
92-
| `RALPH: Start` | Begin (or resume) the autonomous loop from the next pending step. |
93-
| `RALPH: Stop` | Cancel the current run immediately. |
94-
| `RALPH: Show Status` | Display a summary of step progress in the output channel and as a notification. |
95-
| `RALPH: Reset Step` | Pick a completed, failed, or in-progress step and reset it back to `pending`. |
96-
| `RALPH: Quick Start` | Set up plan & status files — provide existing ones or generate via Copilot. |
97-
| `RALPH: Open Settings` | Configure RALPH Runner options. |
93+
| Command | Description |
94+
| ---------------------- | ------------------------------------------------------------------------------- |
95+
| `RALPH: Start` | Begin (or resume) the autonomous loop from the next pending step. |
96+
| `RALPH: Stop` | Cancel the current run immediately. |
97+
| `RALPH: Show Status` | Display a summary of step progress in the output channel and as a notification. |
98+
| `RALPH: Reset Step` | Pick a completed, failed, or in-progress step and reset it back to `pending`. |
99+
| `RALPH: Quick Start` | Set up plan & status files — provide existing ones or generate via Copilot. |
100+
| `RALPH: Open Settings` | Configure RALPH Runner options. |
101+
| Status Bar Menu | Access all commands and see current state from the VS Code status bar. |
98102

99103
## How it works
100104

101105
1. **Parse** — RALPH reads the JSON step definitions from `PLAN.md` and the current status from `STATUS.md`.
102106
2. **Find next step** — It looks for the first `in-progress` step (to resume) or the first `pending` step.
103107
3. **Verify** — Before executing, it checks whether the step's outcome already exists in the workspace (smart skip).
104108
4. **Execute** — Depending on the action type, RALPH either runs a terminal command, or sends a prompt to Copilot Chat and waits.
105-
5. **Wait for completion** — For Copilot tasks, RALPH monitors workspace activity (file edits, saves, terminal events). Once no activity is detected for 30 seconds (after a minimum 15-second wait), it considers the step complete.
109+
5. **Wait for completion** — For Copilot tasks, RALPH monitors workspace activity (file edits, saves, terminal events). Once no activity is detected for a configurable idle period (default: 30 seconds, after a minimum 15-second wait), it considers the step complete.
106110
6. **Update status** — The step is marked `done` or `failed` in `STATUS.md`, and the quick-status summary is refreshed.
107111
7. **Loop** — Repeat from step 2 until the loop limit is reached or all steps are done.
108112

@@ -115,4 +119,4 @@ It also looks for a quick-status summary section with lines like `| Total Steps
115119

116120
### 0.0.1
117121

118-
- Initial release with autonomous loop, Copilot Chat integration, activity-based completion detection, persistent status tracking, and smart skip verification.
122+
- Initial release with autonomous loop, Copilot Chat integration, activity-based completion detection, persistent status tracking, smart skip verification, Quick Start workflow, and status bar integration.

0 commit comments

Comments
 (0)