spec-and-loop 1.0.8 → 2.0.0-rc.2

package/QUICKSTART.md

@@ -24,17 +24,17 @@ brew install jq
 git init
 ```
 
+> **Note:** No external `ralph` CLI needed — `spec-and-loop` includes its own internal
+> mini Ralph loop engine. Just install `opencode` and you're ready to go. The
+> runtime prompt is self-contained and does not depend on editor-specific slash
+> commands or local-only skills.
+
 ## Installation
 
 ```bash
 npm install -g spec-and-loop
 ```
 
-**Prerequisites:** Install openspec and opencode:
-```bash
-npm install -g @fission-ai/openspec@latest opencode-ai
-```
-
 ## Quick Demo (5 Minutes)
 
 ```bash
@@ -58,8 +58,8 @@ ralph-run --change add-hello-world
 
 **That's it!** The script will:
 - Read your OpenSpec artifacts (proposal, specs, design, tasks)
-- Execute each task with full context using opencode
-- Create a git commit after each task
+- Execute each task with full context using the internal mini Ralph engine
+- Create a git commit after each task (unless `--no-commit` is passed)
 - Track progress in tasks.md
 
 ## What Just Happened?
@@ -70,13 +70,13 @@ ralph-run --change add-hello-world
    - `design.md`: Technical decisions
    - `tasks.md`: Implementation tasks as checkboxes
 
-2. **Executed tasks** with opencode
-   - Each task got full context (proposal + specs + design + git history)
+2. **Executed tasks** with opencode via mini Ralph
+   - Each task got full context (proposal + specs + design + fresh task snapshot)
    - Git commits created after each task
    - Task checkboxes marked as complete
 
 3. **Iterated** until all tasks done
-   - Errors from previous tasks inform subsequent tasks
+   - Recent failures or no-progress iterations inform subsequent tasks
    - Each task builds on the previous commit
    - Full granular git history
 
@@ -91,6 +91,9 @@ ls -la openspec/changes/add-hello-world/
 
 # View the generated PRD (internal use)
 cat openspec/changes/add-hello-world/.ralph/PRD.md
+
+# Check loop status
+ralph-run --status
 ```
 
 ## Common Commands
@@ -109,10 +112,16 @@ openspec archive <name>          # Archive completed change
 ### Ralph Loop Commands
 
 ```bash
-ralph-run                      # Auto-detect most recent change and run
-ralph-run --change <name>      # Run for specific change
-ralph-run --verbose            # Run with debug output
-ralph-run --help                # Show help message
+ralph-run                                    # Auto-detect most recent change and run
+ralph-run --change <name>                    # Run for specific change
+ralph-run --verbose                          # Run with debug output
+ralph-run --no-commit                        # Run without auto-committing
+ralph-run --help                             # Show help message
+
+# Observability and control
+ralph-run --status                           # Show loop status dashboard
+ralph-run --add-context "guidance text"      # Inject context into next iteration
+ralph-run --clear-context                    # Remove pending context
 ```
 
 ## Real-World Example
@@ -141,12 +150,16 @@ ralph-run --change user-authentication
 # 6. Watch the magic happen!
 # [INFO] Found 15 tasks to execute
 # [INFO] Executing task 1/15: Create User model
-# ✓ Complete
 # [INFO] Executing task 2/15: Implement password hashing
-# ✓ Complete
 # ...
 
-# 7. Verify the implementation
+# 7. Add context mid-run if needed (from another terminal)
+ralph-run --add-context "Prefer bcrypt over argon2 for password hashing"
+
+# 8. Check status
+ralph-run --status
+
+# 9. Verify the implementation
 git log --oneline      # 15 commits, one per task
 git diff HEAD~15        # See full implementation
 ```
@@ -190,12 +203,12 @@ source ~/.bashrc
 
 ### "No tasks to execute"
 
-**Problem:** All tasks already complete!
+**Problem:** All tasks already complete (or tasks.md has no unchecked items)
 
 **Solution:**
 ```bash
 # Check tasks.md
-grep "^\- \[x\]" openspec/changes/my-feature/tasks.md
+grep "^\- \[ \]" openspec/changes/my-feature/tasks.md
 
 # Or create a new change
 openspec new another-feature
@@ -210,8 +223,9 @@ openspec new another-feature
 | **Iterative Loop** | Each task builds on previous commits |
 | **Error Propagation** | Failures inform subsequent tasks |
 | **Granular History** | One git commit per task |
-| **Auto-Resume** | Interrupted? Run again—picks up where left off |
-| **Context Injection** | Inject custom instructions during execution |
+| **Auto-Resume** | Interrupted? Run again — picks up where left off |
+| **Context Injection** | `--add-context` injects guidance into the next iteration |
+| **No External Ralph** | Self-contained mini Ralph engine — no `ralph` CLI needed |
 
 ## Testing
 
@@ -253,21 +267,18 @@ Tests run automatically on every push and pull request via GitHub Actions on bot
 
 1. **Read the full README.md** for detailed documentation
 2. **Try a real feature** in your project
-3. **Explore the .ralph/** directory to see internal state
-4. **Check out .hidden/** directory for advanced guides
-5. **Review TESTING.md** for testing guidelines
+3. **Explore `openspec/changes/<name>/.ralph/`** to see the per-change loop state
+4. **Review TESTING.md** for testing guidelines
 
 ## Resources
 
 - [Full README](./README.md) - Comprehensive documentation
 - [OpenSpec](https://openspec.ai) - Specification workflow
 - [opencode](https://opencode.ai) - Agentic coding assistant
-- [open-ralph-wiggum](https://github.com/Th0rgal/open-ralph-wiggum) - Iterative execution loop
 
 ## Need Help?
 
 - Check the **Troubleshooting** section above
 - Review the **Full README.md** for detailed info
-- Check **.hidden/** directory for advanced guides
 
-Happy coding! 🚀
+Happy coding!

package/README.md

@@ -6,11 +6,13 @@ OpenSpec + Ralph Loop integration for iterative development with opencode.
 ![Coverage](https://img.shields.io/badge/coverage-0%25-red)
 [![npm version](https://badge.fury.io/js/spec-and-loop.svg)](https://badge.fury.io/js/spec-and-loop)
 
-**[🚀 Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
+**[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
 
 ## Why This Exists
 
-OpenSpec provides excellent structure for planning (proposal → specs → design → tasks) but leaves execution manual. Ralph Wiggum's iterative development loop (execute → commit → repeat) is powerful but requires PRD format instead of OpenSpec specs.
+OpenSpec provides excellent structure for planning (proposal → specs → design → tasks) but leaves execution manual. This package provides an iterative development loop — execute → commit → repeat — driven by an internal mini Ralph implementation that works with OpenCode and eliminates the need for any external Ralph runtime.
+
+The runtime prompt is self-contained: it does not depend on Cursor-only slash commands or editor-local skills.
 
 ## Installation
 
@@ -21,26 +23,20 @@ npm install -g spec-and-loop
 **Prerequisites:** You need OpenSpec and the OpenCode AI agent installed:
 
 ```bash
-# Install OpenSpec and OpenCode (recommended)
 npm install -g @fission-ai/openspec@latest opencode-ai
 ```
 
-Alternative OpenCode install methods (if you prefer):
+Alternative OpenCode install methods:
 
 ```bash
-# npm (recommended)
-npm install -g opencode-ai
-
 # Install script (general use)
 curl -fsSL https://opencode.ai/install | bash
 
 # Homebrew (macOS / Linux)
 brew install anomalyco/tap/opencode
-
-# Windows: use WSL and install via one of the Linux methods above
 ```
 
-**[🚀 Get Started in 5 Minutes](./QUICKSTART.md)**
+**[Get Started in 5 Minutes](./QUICKSTART.md)**
 
 ```bash
 # 1. Initialize OpenSpec in your project
@@ -58,13 +54,11 @@ ralph-run --change add-user-auth
 
 For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
-<!-- Duplicate Quick Start removed; see QUICKSTART.md for full instructions -->
-
 ## Testing
 
 Spec-and-loop includes a comprehensive test suite to ensure reliability and cross-platform compatibility.
 
-**[📋 Testing Guide](./TESTING.md)** - Detailed instructions for running tests
+**[Testing Guide](./TESTING.md)** - Detailed instructions for running tests
 
 ### Quick Test Commands
 
@@ -93,81 +87,6 @@ npm run lint
 
 All tests are run automatically via GitHub Actions on every push and pull request.
 
-### CI/CD Workflow
-
-The CI/CD pipeline is defined in `.github/workflows/test.yml` and performs the following steps:
-
-1. **Checkout Code**: Pulls the latest code from the repository
-2. **Setup Node.js**: Installs Node.js version 24 with npm caching
-3. **Install System Dependencies**:
-   - Linux: `apt-get install bats-core jq shellcheck`
-   - macOS: `brew install bats-core jq shellcheck`
-4. **Install npm Dependencies**: Runs `npm ci` to install dependencies
-5. **Install Global CLIs**: Installs openspec, ralph, and opencode globally
-6. **Run Shellcheck Linting**: Checks bash scripts for errors and best practices
-7. **Run Unit Tests**: Executes bash and JavaScript unit tests
-8. **Run Integration Tests**: Validates full workflow end-to-end
-9. **Upload Artifacts**: Uploads test logs and coverage reports
-
-### Triggering CI/CD
-
-The workflow runs automatically on:
-- Push to `main` or `develop` branches
-- Pull requests to `main` or `develop` branches
-- Manual trigger via GitHub Actions UI
-
-To manually trigger:
-1. Go to Actions tab in GitHub
-2. Select "Test Suite" workflow
-3. Click "Run workflow"
-4. Select branch and test suite (all/unit/integration)
-
-### Troubleshooting CI/CD
-
-**Tests Failing on One Platform**
-
-If tests pass on Linux but fail on macOS (or vice versa):
-- Check for platform-specific command differences (GNU vs BSD tools)
-- Review platform-specific tests in `test-symlink-linux.bats`, `test-symlink-macos.bats`, etc.
-- Verify stat, md5sum/md5, and other commands use correct flags
-
-**Coverage Below Threshold**
-
-If coverage drops below 80%:
-- Review coverage reports uploaded as artifacts
-- Identify which functions lost coverage
-- Add tests to cover the missing code paths
-
-**Linting Failures**
-
-If shellcheck finds issues:
-- Review the warnings in the CI logs
-- Fix the issues locally: `npm run lint`
-- Commit the fixes
-
-**Timeout Issues**
-
-If tests timeout:
-- Integration tests may take longer than expected
-- Check for infinite loops or hanging processes
-- Review test fixture setup/teardown
-
-**Artifact Access**
-
-Download test logs and coverage reports:
-1. Go to the failed workflow run
-2. Scroll to "Artifacts" section
-3. Download relevant artifacts (test logs, coverage reports)
-4. Analyze locally to identify issues
-
-### Test Coverage
-
-Critical functions have >80% test coverage. View detailed coverage reports:
-```bash
-npm run test:coverage
-open coverage/index.html
-```
-
 ## Prerequisites
 
 Before using spec-and-loop, ensure you have:
@@ -184,7 +103,6 @@ Before using spec-and-loop, ensure you have:
 
 3. **opencode** - Agentic coding assistant
    ```bash
-   # Install via npm
    npm install -g opencode-ai
    ```
 
@@ -217,8 +135,20 @@ For complete installation instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
 ### Ralph Loop Commands
 
-- `ralph-run --change <name>` - Run the ralph loop for a specific change
-- `ralph-run` - Auto-detect most recent change and run
+```
+ralph-run [OPTIONS]
+
+OPTIONS:
+    --change <name>          OpenSpec change to execute (default: auto-detect)
+    --max-iterations <n>     Maximum iterations (default: 50)
+    --no-commit              Suppress automatic git commits
+    --verbose, -v            Enable verbose output
+
+OBSERVABILITY AND CONTROL:
+    --status                 Print loop status dashboard and exit
+    --add-context <text>     Add context to inject into the next iteration
+    --clear-context          Clear any pending context
+```
 
 ## How It Works
 
@@ -253,26 +183,29 @@ ralph-run --change my-feature
 
 **What happens:**
 
-1. **Validation**: Checks for required OpenSpec artifacts
-2. **PRD Generation**: Converts proposal + specs + design → PRD format (for internal use)
+1. **Validation**: Checks for required OpenSpec artifacts and git repository
+2. **PRD Generation**: Converts proposal + specs + design → PRD format for internal use
 3. **Task Execution**: For each incomplete task:
-   - Generates context-rich prompt (task + specs + design + git history + errors)
-   - Runs `opencode` with the prompt
-   - Creates git commit with task description
+   - Generates context-rich prompt (full OpenSpec artifacts + a fresh task snapshot + recent loop signals)
+   - Runs `opencode` with the prompt via the internal mini Ralph engine
+   - Creates git commit with task description (unless `--no-commit`)
    - Marks task complete in tasks.md
-4. **Completion**: All tasks done, errors cleared
+4. **Completion**: All tasks done
 
 ### Step 3: Monitor Progress
 
 ```bash
+# Check loop status
+ralph-run --status
+
 # Check remaining tasks
 grep "^- \[ \]" openspec/changes/my-feature/tasks.md
 
 # View git commits
 git log --oneline
 
-# See errors (if any failed)
-cat openspec/changes/my-feature/.ralph/errors.md
+# Inject context into next iteration
+ralph-run --add-context "Prefer async/await over callbacks"
 ```
 
 ## Example Workflow
@@ -288,9 +221,7 @@ ralph-run --change user-auth
 # Output:
 # [INFO] Found 15 tasks to execute
 # [INFO] Executing task 1/15: Create User model with password field
-# ✓ Complete
 # [INFO] Executing task 2/15: Implement password hashing
-# ✓ Complete
 # ...
 
 # 3. Verify implementation
@@ -305,21 +236,28 @@ git diff HEAD~15   # See full implementation
 | **Structured Planning** | OpenSpec workflow: proposal → specs → design → tasks |
 | **Agentic Execution** | opencode executes tasks with full context |
 | **Iterative Loop** | Each task builds on previous commits |
-| **Error Propagation** | Failures inform subsequent tasks |
+| **Iteration Feedback** | Recent failures and no-progress iterations inform the next pass |
 | **Granular History** | One git commit per task |
-| **Auto-Resume** | Interrupted? Run again—picks up where left off |
-| **Context Injection** | Inject custom instructions during execution |
-
-For detailed feature descriptions, see below.
+| **Auto-Resume** | Interrupted? Run again — picks up where left off |
+| **Context Injection** | `--add-context` injects guidance into the next iteration |
+| **Loop Status** | `--status` shows active state, history, and struggle indicators |
+| **No External Ralph** | Self-contained mini Ralph engine — no external `ralph` CLI needed |
 
 ## Features
 
-### Ralph Wiggum + Agentic Coding
+### Mini Ralph Loop Engine
+
+`spec-and-loop` includes a first-party mini Ralph implementation (`lib/mini-ralph/`) that
+provides the core iterative loop without any external Ralph dependency:
+
+- **Iterative execution**: Each task builds on previous commits with full context
+- **State and history**: Loop state, iteration history, and struggle indicators stored in each change's `.ralph/`
+- **Prompt templates**: Context-aware prompts generated from OpenSpec artifacts
+- **Completion promises**: Loop exits when a completion signal is detected
+- **Task progression**: Synchronized with `tasks.md` checkboxes as the source of truth
 
-- **Iterative refinement**: Each task builds on previous commits with full context
-- **Error propagation**: Failures inform subsequent iterations—don't repeat mistakes
-- **Granular history**: Commit per task makes debugging and rollback easy
-- **Context awareness**: AI sees proposal, specs, design, git history, and errors
+The supported subset intentionally excludes upstream features that are out of scope for
+this repository's OpenSpec-first workflow (multi-agent rotation, plugin toggles, etc.).
 
 ### OpenSpec + opencode Synergy
 
@@ -331,25 +269,43 @@ For detailed feature descriptions, see below.
 
 ### Script Features
 
-- **Auto-resume**: Interrupted? Run again—picks up where left off
-- **Context injection**: Inject custom instructions during execution
-- **Error recovery**: Errors propagate to guide subsequent tasks
-- **Bidirectional tracking**: Tasks.md and .ralph/tracking.json stay synced
+- **Auto-resume**: Interrupted? Run again — picks up where left off
+- **Context injection**: `--add-context` / `--clear-context` via each change's `.ralph/ralph-context.md`
+- **Error recovery**: Recent loop signals help guide subsequent tasks
+- **Task synchronization**: `tasks.md` and the per-change `.ralph/ralph-tasks.md` symlink stay in sync
 - **Idempotent**: Run multiple times safely
 
 ## Advanced Usage
 
 ### Context Injection
 
-Inject custom instructions during execution:
+Inject custom instructions into the next iteration:
+
+```bash
+ralph-run --add-context "Use Redis instead of Memcached"
+
+# Check current pending context
+ralph-run --status
+
+# Clear pending context
+ralph-run --clear-context
+```
+
+### Loop Status Dashboard
 
 ```bash
-# Create injection file
-echo "Use Redis instead of Memcached" > openspec/changes/my-feature/.ralph/.context_injection
+ralph-run --status
+```
+
+Shows: active loop state, current task, prompt summary, pending context, iteration history,
+and struggle indicators if the loop appears stuck.
+
+### No-Commit Mode
 
-# Next opencode invocation includes:
-## Injected Context
-Use Redis instead of Memcached
+Run without automatic git commits (useful for reviewing changes before committing):
+
+```bash
+ralph-run --change my-feature --no-commit
 ```
 
 ### Verbose Mode
@@ -366,36 +322,27 @@ ralph-run --verbose --change my-feature
 cat openspec/changes/my-feature/.ralph/PRD.md
 ```
 
-### Manually Inject Context
-
-```bash
-echo "Consider performance implications" > openspec/changes/my-feature/.ralph/.context_injection
-```
-
 ## Architecture
 
 This package integrates:
 - **OpenSpec**: Structured specification workflow
 - **opencode**: Agentic coding assistant for task execution
-- **Ralph Loop**: Iterative development with commits per task, error tracking
+- **Mini Ralph** (`lib/mini-ralph/`): Internal iterative loop engine
 
 ### Context Propagation
 
 Each task execution includes:
-- **Task description**: What to implement
-- **Proposal summary**: Why this change matters
-- **Relevant specs**: Requirements to satisfy
-- **Design decisions**: Architectural constraints
-- **Git history**: Last 10 commits (what's already done)
-- **Previous errors**: What failed before (to avoid repeating)
+- **OpenSpec artifacts**: Proposal, design, and spec content from the generated PRD
+- **Fresh task snapshot**: Raw `tasks.md` content plus the current task and completed-task summary rendered each iteration
+- **Recent loop signals**: Compact reminders about prior failed or no-progress iterations
+- **Pending context**: Any `--add-context` injection
 
 ### Task Tracking
 
-Bidirectional synchronization:
-- **tasks.md**: Human-readable checkboxes `[ ]` → `[x]`
-- **.ralph/tracking.json**: Machine-readable state
-- **Atomic updates**: Both succeed or both fail
-- **Stable IDs**: Line numbers persist across script runs
+Synchronized tracking:
+- **tasks.md**: Human-readable checkboxes `[ ]` → `[x]` (source of truth)
+- **.ralph/ralph-tasks.md**: Symlink to `tasks.md` for the loop engine
+- **Atomic updates**: Checkboxes updated after each completed task
 
 ### File Structure
 
@@ -403,18 +350,19 @@ Bidirectional synchronization:
 openspec/changes/<name>/
 ├── proposal.md          # Your "why"
 ├── design.md            # Your "how"
-├── tasks.md             # Your "what" (checkboxes)
-└── specs/               # Your requirements
-    ├── auth/
-    │   └── spec.md
-    └── api/
-        └── spec.md
-└── .ralph/             # Internal state (auto-generated)
-    ├── PRD.md                    # Generated from artifacts
-    ├── tracking.json             # Task completion state
-    ├── errors.md                 # Failure history
-    ├── context-injections.md      # Manual injections log
-    └── .context_injection        # Pending injection
+├── tasks.md             # Your "what" (checkboxes, source of truth)
+├── specs/               # Your requirements
+│   ├── auth/
+│   │   └── spec.md
+│   └── api/
+│       └── spec.md
+└── .ralph/              # Internal loop state (auto-generated, per change)
+    ├── PRD.md
+    ├── ralph-tasks.md
+    ├── ralph-context.md
+    ├── ralph-history.json
+    ├── ralph-loop.state.json
+    └── prompt-template.md
 ```
 
 ## Troubleshooting
@@ -440,7 +388,6 @@ export PATH="$PATH:$(npm root -g)/.bin"
 ## Resources
 
 - [OpenSpec](https://openspec.ai) - Structured specification workflow
-- [open-ralph-wiggum](https://github.com/Th0rgal/open-ralph-wiggum) - Iterative execution loop
 - [opencode](https://opencode.ai) - Agentic coding assistant
 
 ## License

package/lib/mini-ralph/context.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * context.js - Pending context management for mini-ralph.
+ *
+ * Manages reading, writing, adding, clearing, and consuming pending context
+ * from .ralph/ralph-context.md. Context is injected into the next iteration's
+ * prompt and then consumed (removed) so it does not carry forward indefinitely.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CONTEXT_FILE = 'ralph-context.md';
+
+/**
+ * Return the absolute path to the context file.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function contextPath(ralphDir) {
+  return path.join(ralphDir, CONTEXT_FILE);
+}
+
+/**
+ * Read the current pending context. Returns empty string if none.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function read(ralphDir) {
+  const file = contextPath(ralphDir);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8').trim();
+}
+
+/**
+ * Append text to the pending context file.
+ *
+ * @param {string} ralphDir
+ * @param {string} text
+ */
+function add(ralphDir, text) {
+  if (!text || !text.trim()) return;
+  _ensureDir(ralphDir);
+  const file = contextPath(ralphDir);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const separator = existing && !existing.endsWith('\n') ? '\n\n' : (existing ? '\n' : '');
+  fs.writeFileSync(file, `${existing}${separator}${text.trim()}`, 'utf8');
+}
+
+/**
+ * Clear all pending context.
+ *
+ * @param {string} ralphDir
+ */
+function clear(ralphDir) {
+  const file = contextPath(ralphDir);
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
+
+/**
+ * Read pending context and then clear it (consume it for one iteration).
+ * Returns the context string, or null if there was nothing pending.
+ *
+ * @param {string} ralphDir
+ * @returns {string|null}
+ */
+function consume(ralphDir) {
+  const text = read(ralphDir);
+  if (!text) return null;
+  clear(ralphDir);
+  return text;
+}
+
+/**
+ * Check whether there is pending context.
+ *
+ * @param {string} ralphDir
+ * @returns {boolean}
+ */
+function hasPending(ralphDir) {
+  return !!read(ralphDir);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _ensureDir(ralphDir) {
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+}
+
+module.exports = { read, add, clear, consume, hasPending, contextPath };