spec-and-loop 1.0.7 → 1.2.0

package/QUICKSTART.md

@@ -1,5 +1,7 @@
 # Quick Start Guide
 
+> **Version Compatibility:** OpenSpec 1.2.0 | spec-and-loop 2.0.0
+
 Get up and running with **spec-and-loop** in 5 minutes!
 
 ## Prerequisites
@@ -7,8 +9,8 @@ Get up and running with **spec-and-loop** in 5 minutes!
 Install these tools (one-time setup):
 
 ```bash
-# 1. Install openspec (OpenSpec CLI)
-npm install -g @fission-ai/openspec@latest
+# 1. Install openspec (OpenSpec CLI) - pinned to version 1.2.0
+npm install -g @fission-ai/openspec@1.2.0
 
 # 2. Install opencode (agentic coding assistant)
 npm install -g opencode-ai
@@ -24,15 +26,16 @@ brew install jq
 git init
 ```
 
-## Installation
+> **Note:** This guide is for OpenSpec 1.2.0 and spec-and-loop 2.0.0.
+> 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.
 
-```bash
-npm install -g spec-and-loop
-```
+## Installation
 
-**Prerequisites:** Install openspec and opencode:
 ```bash
-npm install -g @fission-ai/openspec@latest opencode-ai
+npm install -g spec-and-loop@2.0.0
 ```
 
 ## Quick Demo (5 Minutes)
@@ -47,10 +50,13 @@ git init
 openspec init
 
 # 3. Create a new change
-openspec new add-hello-world
+openspec new change add-hello-world
 
-# 4. Fast-forward through artifact creation
-openspec ff
+# 4. Review and complete the OpenSpec artifacts
+#    (openspec/changes/add-hello-world/proposal.md)
+#    (openspec/changes/add-hello-world/design.md)
+#    (openspec/changes/add-hello-world/specs/*/spec.md)
+#    (openspec/changes/add-hello-world/tasks.md)
 
 # 5. Run the ralph loop (executes tasks with opencode)
 ralph-run --change add-hello-world
@@ -58,8 +64,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 +76,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 +97,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
@@ -98,21 +107,42 @@ cat openspec/changes/add-hello-world/.ralph/PRD.md
 ### OpenSpec Commands
 
 ```bash
-openspec init                  # Initialize in current directory
-openspec new <name>             # Start a new change
-openspec continue <name>         # Continue working on change
-openspec ff <name>              # Fast-forward artifact creation
-openspec apply <name>           # Apply change (implementation)
-openspec archive <name>          # Archive completed change
+# Core workflow
+openspec init                  # Initialize OpenSpec in current directory
+openspec new change <name>      # Create a new change directory
+openspec show <item-name>      # Show a change or spec in detail
+openspec archive <change-name> # Archive a completed change
+
+# Information and status
+openspec list                  # List all active changes (use --specs to list specs)
+openspec status --change <name> # Display artifact completion status for a change
+openspec validate <item-name> # Validate changes and specs
+
+# View and manage
+openspec view                  # Display interactive dashboard of specs and changes
+openspec update                # Update OpenSpec instruction files
+openspec config                # View and modify global OpenSpec configuration
+
+# Advanced
+openspec spec                  # Manage and view OpenSpec specifications
+openspec instructions         # Output enriched instructions for creating artifacts
+openspec templates             # Show resolved template paths for artifacts
+openspec schemas               # List available workflow schemas
 ```
 
 ### 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
@@ -124,7 +154,7 @@ git init
 openspec init
 
 # 2. Create a feature
-openspec new user-authentication
+openspec new change user-authentication
 
 # 3. Go through the workflow
 # - Create proposal: Why add auth?
@@ -132,73 +162,257 @@ openspec new user-authentication
 # - Create design: Use JWT, store hashed passwords
 # - Create tasks: 15 checkboxes for implementation
 
-# 4. Fast-forward to create all artifacts
-openspec ff user-authentication
-
-# 5. Execute the implementation
+# 4. Execute the implementation
 ralph-run --change user-authentication
 
-# 6. Watch the magic happen!
+# 5. 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
+# 6. Add context mid-run if needed (from another terminal)
+ralph-run --add-context "Prefer bcrypt over argon2 for password hashing"
+
+# 7. Check status
+ralph-run --status
+
+# 8. Verify the implementation
 git log --oneline      # 15 commits, one per task
 git diff HEAD~15        # See full implementation
 ```
 
 ## Troubleshooting
 
-### "openspec CLI not found" or "opencode CLI not found"
+### "openspec: command not found"
+
+**Problem:** OpenSpec CLI is not installed or not in PATH
+
+**Solution:**
+```bash
+# Install with pinned version (recommended)
+npm install -g @fission-ai/openspec@1.2.0
+
+# Verify installation
+openspec --version
+
+# If command still not found, add npm global bin to PATH
+export PATH="$PATH:$(npm root -g)/.bin"
+```
+
+### "opencode: command not found"
+
+**Problem:** opencode CLI is not installed or not in PATH
 
+**Solution:**
 ```bash
-npm install -g @fission-ai/openspec@latest opencode-ai
+# Install opencode
+npm install -g opencode-ai
+
+# Verify installation
+opencode --version
+
+# If command still not found, add npm global bin to PATH
+export PATH="$PATH:$(npm root -g)/.bin"
 ```
 
 ### "jq CLI not found"
 
+**Problem:** jq (JSON processor) is not installed
+
+**Solution:**
 ```bash
 # Ubuntu/Debian
 sudo apt install jq
 
 # macOS
 brew install jq
+
+# Verify installation
+jq --version
 ```
 
 ### "Not a git repository"
 
+**Problem:** You're not in a git repository
+
+**Solution:**
 ```bash
+# Initialize git in current directory
 git init
+
+# Verify
+git status
 ```
 
 ### "command not found: ralph-run"
 
-**Problem:** npm bin directory not in PATH
+**Problem:** spec-and-loop npm bin directory not in PATH
 
 **Solution:**
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
-export PATH="$PATH:$(npm root -g)/.bin"
+# Add npm global bin directory to PATH
+echo 'export PATH="$PATH:$(npm root -g)/.bin"' >> ~/.bashrc
+# Or for zsh:
+echo 'export PATH="$PATH:$(npm root -g)/.bin"' >> ~/.zshrc
 
 # Reload shell
 source ~/.bashrc
+# or
+source ~/.zshrc
+
+# Verify
+ralph-run --help
+```
+
+### "Internal mini Ralph runtime not found"
+
+**Problem:** spec-and-loop installation is incomplete or node is missing
+
+**Solution:**
+```bash
+# Ensure spec-and-loop is properly installed
+npm uninstall -g spec-and-loop
+npm install -g spec-and-loop
+
+# Ensure Node.js is installed (version 24.0.0 or higher)
+node --version
+
+# If node is not installed, install from https://nodejs.org
+```
+
+### "OpenSpec changes directory not found"
+
+**Problem:** OpenSpec has not been initialized or no changes exist
+
+**Solution:**
+```bash
+# Initialize OpenSpec
+openspec init
+
+# Create a new change
+openspec new change my-feature
+
+# Verify directory exists
+ls -la openspec/changes/
+```
+
+### "No changes found with tasks.md"
+
+**Problem:** No OpenSpec changes with tasks files exist
+
+**Solution:**
+```bash
+# List available changes
+openspec list
+
+# Create a new change if needed
+openspec new change my-new-feature
+
+# Ensure tasks.md exists in your change directory
+ls -la openspec/changes/my-new-feature/tasks.md
 ```
 
 ### "No tasks to execute"
 
-**Problem:** All tasks already complete!
+**Problem:** All tasks in tasks.md are already marked complete
+
+**Solution:**
+```bash
+# Check tasks.md for incomplete tasks
+grep "^\- \[ \]" openspec/changes/my-new-feature/tasks.md
+
+# If no incomplete tasks, create a new change
+openspec new change another-feature
+
+# Or uncheck a task by editing tasks.md manually:
+# Change: - [x] This task is done
+# To:     - [ ] This task needs work
+```
+
+### "Required artifact not found"
+
+**Problem:** OpenSpec artifacts (proposal.md, design.md, tasks.md) are missing
 
 **Solution:**
 ```bash
-# Check tasks.md
-grep "^\- \[x\]" openspec/changes/my-feature/tasks.md
+# Check what artifacts exist in your change directory
+ls -la openspec/changes/my-new-feature/
+
+# Create missing artifacts manually or use openspec new change
+openspec new change my-new-feature
+
+# Or manually create the required files:
+# - openspec/changes/my-new-feature/proposal.md
+# - openspec/changes/my-new-feature/design.md
+# - openspec/changes/my-new-feature/specs/spec-name/spec.md
+# - openspec/changes/my-new-feature/tasks.md
+```
+
+### "Required directory not found: specs/"
+
+**Problem:** The specs directory is missing from your change
+
+**Solution:**
+```bash
+# Create the specs directory
+mkdir -p openspec/changes/my-new-feature/specs
+
+# Create at least one spec file
+mkdir -p openspec/changes/my-new-feature/specs/main-feature
+echo "# Main Feature Spec" > openspec/changes/my-new-feature/specs/main-feature/spec.md
+
+# Verify
+ls -la openspec/changes/my-new-feature/specs/
+```
+
+### "opencode CLI not found"
+
+**Problem:** opencode is not installed globally
+
+**Solution:**
+```bash
+# Install opencode
+npm install -g opencode-ai
+
+# Verify installation
+opencode --version
+
+# Add to PATH if needed
+export PATH="$PATH:$(npm root -g)/.bin"
+```
+
+### "Node.js version too old"
+
+**Problem:** Node.js version is below the required version (24.0.0+)
+
+**Solution:**
+```bash
+# Check current Node.js version
+node --version
+
+# If version is below 24.0.0, upgrade Node.js:
+# Using nvm (recommended):
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 24
+nvm use 24
+
+# Or install from https://nodejs.org
+```
+
+### "npm: command not found"
+
+**Problem:** npm is not installed or not in PATH
+
+**Solution:**
+```bash
+# npm comes with Node.js. Install Node.js from https://nodejs.org
+
+# After installing Node.js, verify:
+npm --version
+node --version
 
-# Or create a new change
-openspec new another-feature
+# If still not found, restart your terminal or add to PATH
 ```
 
 ## Features at a Glance
@@ -210,8 +424,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 +468,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!