@lnilluv/pi-ralph-loop 1.2.0 → 1.3.0

package/skills/ralph-loop/references/config-cookbook.md

@@ -0,0 +1,326 @@
+# Config Cookbook
+
+Frontmatter recipes for common scenarios. Copy, adjust, and run.
+
+## Minimal loop
+
+The simplest useful loop. Just a prompt and a max.
+
+```yaml
+---
+max_iterations: 10
+---
+Read TODO.md and implement the next task.
+Commit when done.
+```
+
+When to use: Quick tasks where you trust the agent to know when it's done, or you'll stop it manually with `/ralph-stop`.
+
+## Self-healing loop
+
+The workhorse pattern. Commands feed evidence, the completion gate stops the loop.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 60
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 20
+completion_promise: DONE
+guardrails:
+  block_commands:
+    - 'git\s+push'
+---
+
+Fix the failing auth tests for {{ args.owner }}.
+
+{{ commands.tests }}
+
+{{ commands.git-log }}
+
+If tests are failing, fix them before starting new work.
+Stop with <promise>DONE</promise> when all tests pass.
+```
+
+When to use: Bug fixing, test writing, any task where command output shows current state.
+
+## Gated completion loop
+
+Adds `required_outputs` to the completion gate. The loop won't stop until both the promise appears AND the files exist.
+
+```yaml
+---
+commands:
+  - name: build
+    run: npm run build
+    timeout: 60
+  - name: tests
+    run: npm test
+    timeout: 120
+max_iterations: 25
+completion_promise: DONE
+required_outputs:
+  - MIGRATION_NOTES.md
+---
+
+Migrate one module per iteration from the legacy API to the new one.
+
+{{ commands.build }}
+
+{{ commands.tests }}
+
+Stop with <promise>DONE</promise> only when all tests pass
+and MIGRATION_NOTES.md exists with a summary of changes.
+```
+
+When to use: Migration, documentation, research — any task where "done" means a deliverable file exists, not just that the agent says it's done.
+
+## Resilient loop
+
+Continues past errors. Use when individual iterations may fail but the overall task should keep going.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 120
+  - name: lint
+    run: npm run lint
+    timeout: 30
+max_iterations: 30
+completion_promise: DONE
+stop_on_error: false
+required_outputs:
+  - REFACTOR_LOG.md
+---
+
+Refactor one module per iteration.
+
+{{ commands.tests }}
+
+{{ commands.lint }}
+
+If an iteration fails, note it in REFACTOR_LOG.md and move to the next module.
+Stop with <promise>DONE</promise> when REFACTOR_LOG.md covers all modules.
+```
+
+When to use: Migration across many files, batch operations where some items may fail, long-running tasks that need resilience.
+
+## Parameterized loop
+
+Accepts runtime arguments via `--arg`. Makes the loop reusable across different targets.
+
+```yaml
+---
+args:
+  - env
+  - target
+commands:
+  - name: tests
+    run: npm test -- --env={{ args.env }}
+    timeout: 120
+  - name: coverage
+    run: npm run test:coverage -- --env={{ args.env }}
+    timeout: 120
+max_iterations: 15
+completion_promise: DONE
+guardrails:
+  protected_files:
+    - 'policy:secret-bearing-paths'
+---
+
+Environment: {{ args.env }}
+Target: {{ args.target }}
+
+{{ commands.tests }}
+
+{{ commands.coverage }}
+
+Increase test coverage for {{ args.target }}.
+Stop with <promise>DONE</promise> when coverage exceeds 80%.
+```
+
+Run with: `/ralph --path my-task --arg env=staging --arg target="src/auth"`
+
+When to use: Reusable loops for different environments, targets, or configurations.
+
+## Security audit loop
+
+Strict guardrails with evidence-driven improvement.
+
+```yaml
+---
+commands:
+  - name: scan
+    run: npm audit --audit-level=moderate
+    timeout: 60
+  - name: tests
+    run: npm test
+    timeout: 120
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 20
+completion_promise: DONE
+required_outputs:
+  - SECURITY_FINDINGS.md
+guardrails:
+  block_commands:
+    - 'git\s+push'
+    - 'npm\s+publish'
+  protected_files:
+    - '.env*'
+    - '*.pem'
+    - '*.key'
+    - 'policy:secret-bearing-paths'
+---
+
+Find and fix security vulnerabilities.
+
+{{ commands.scan }}
+
+{{ commands.tests }}
+
+{{ commands.git-log }}
+
+Pick one finding and fix it.
+Log everything in SECURITY_FINDINGS.md.
+Stop with <promise>DONE</promise> when the scan is clean and SECURITY_FINDINGS.md is complete.
+```
+
+When to use: Security audits, compliance checks, any task that handles sensitive data.
+
+## Research loop
+
+Long timeout, minimal commands, progress lives in files.
+
+```yaml
+---
+commands:
+  - name: git-log
+    run: git log --oneline -15
+max_iterations: 20
+timeout: 300
+completion_promise: DONE
+required_outputs:
+  - REPORT.md
+---
+
+Build a comprehensive research report on {{ args.topic }}.
+
+{{ commands.git-log }}
+
+Each iteration:
+1. Read REPORT.md to see what exists
+2. Identify the weakest section
+3. Research and write findings
+4. Commit your changes
+
+Stop with <promise>DONE</promise> when REPORT.md exists
+and all referenced sections have substantial content.
+```
+
+When to use: Deep research, documentation generation, knowledge base construction.
+
+## High-autonomy loop
+
+Trust the agent, minimize constraints. Use when you've verified the loop works correctly and want it to run freely.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 120
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 50
+completion_promise: DONE
+stop_on_error: false
+guardrails:
+  block_commands:
+    - 'git\s+push'
+---
+
+{{ commands.tests }}
+
+{{ commands.git-log }}
+
+Read TODO.md and implement the next task.
+Stop with <promise>DONE</promise> when all items are complete.
+```
+
+When to use: Long autonomous runs where you want maximum flexibility. Always keep at least `git push` blocked.
+
+## Low-autonomy loop
+
+Strict constraints, stop on any error. Use when exploring or when mistakes are costly.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 60
+  - name: lint
+    run: npm run lint
+    timeout: 30
+max_iterations: 10
+completion_promise: DONE
+stop_on_error: true
+guardrails:
+  block_commands:
+    - 'git\s+push'
+    - 'npm\s+publish'
+    - 'rm\s+-rf'
+  protected_files:
+    - '.env*'
+    - '*.pem'
+    - '*.key'
+    - 'config/production.*'
+    - 'policy:secret-bearing-paths'
+---
+
+Carefully improve one thing per iteration.
+
+{{ commands.test }}
+
+{{ commands.lint }}
+
+If anything is broken, fix it before doing anything else.
+Stop with <promise>DONE</promise> when all tests and lint pass.
+```
+
+When to use: Sensitive codebases, production-adjacent work, first loops on a new project.
+
+## Choosing stop_on_error
+
+| Value | Behavior | When to use |
+|---|---|---|
+| `true` (default) | Stop on any RPC error or timeout | Bug fixing, single-target tasks, cautious loops |
+| `false` | Continue past errors | Migration, batch operations, research, long autonomous runs |
+
+## Choosing guardrails
+
+| Guardrail | What it blocks | When to use |
+|---|---|---|
+| `git\s+push` | Pushes to remote | Almost always — prevents accidental publishes |
+| `npm\s+publish` | Package publishes | When working on published packages |
+| `rm\s+-rf\s+/` | Destructive root deletes | Always worth including |
+| `.env*` | Environment files | Any task touching config or deployment |
+| `*.pem`, `*.key` | Certificate and key files | Security-related tasks |
+| `policy:secret-bearing-paths` | All secret-bearing paths | Default good practice |
+
+## Choosing required_outputs
+
+| Scenario | required_outputs |
+|---|---|
+| Bug fixing | None — test pass is sufficient |
+| Migration | `[MIGRATION_NOTES.md]` — deliverable summary |
+| Documentation | `[DOCS_INDEX.md]` — proof of coverage |
+| Security audit | `[SECURITY_FINDINGS.md]` — audit deliverable |
+| Research | `[REPORT.md]` — final synthesis |
+| Test coverage | None — coverage command shows progress |

package/skills/ralph-loop/references/prompt-patterns.md

@@ -0,0 +1,405 @@
+# Prompt Patterns
+
+Detailed patterns for writing effective RALPH.md prompts. Each pattern includes the structure, when to use it, and a fully annotated example.
+
+## The five-section structure
+
+Every effective prompt follows the same skeleton:
+
+```markdown
+---
+frontmatter
+---
+
+## Orientation
+Who you are and how the loop works.
+
+## Evidence
+{{ commands.* }} — current state.
+
+## Task
+One specific thing to do this iteration.
+
+## Rules
+Constraints on what you can and can't do.
+
+## Completion
+When to stop and what <promise>DONE</promise> means.
+```
+
+Not every section needs a heading. Short prompts fold rules into the task. But every effective prompt addresses all five.
+
+## Pattern: Self-healing test loop
+
+The most common pattern. Run tests, see failures, fix them, verify. The command output is both evidence and a natural stopping signal.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 60
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 20
+completion_promise: DONE
+guardrails:
+  block_commands:
+    - 'git\s+push'
+---
+
+You are an autonomous coding agent running in a loop.
+Each iteration starts with a fresh context.
+Your progress lives in the code and git history.
+
+## Test results
+
+{{ commands.tests }}
+
+## Recent commits
+
+{{ commands.git-log }}
+
+If tests are failing, fix them before starting new work.
+Then pick the next task from TODO.md.
+
+## Rules
+
+- One task per iteration
+- No placeholder code — full, working implementations only
+- Run tests before committing
+- Commit with descriptive messages: `fix: ...`, `feat: ...`, `test: ...`
+
+## Completion
+
+Stop with <promise>DONE</promise> when all tests pass and TODO.md has no remaining items.
+```
+
+**Why it works:**
+- `tests` command gives the agent live evidence each iteration
+- `git-log` command reminds the agent what it already did
+- `completion_promise: DONE` gives a clear stop signal
+- `guardrails` prevents accidental pushes
+
+## Pattern: Ordered task list
+
+When work can be decomposed into a checklist. The agent works through items one at a time, marking them done.
+
+```yaml
+---
+commands:
+  - name: build
+    run: npm run build
+    timeout: 60
+  - name: tests
+    run: npm test
+    timeout: 120
+max_iterations: 30
+completion_promise: DONE
+required_outputs:
+  - MIGRATION_NOTES.md
+stop_on_error: false
+---
+
+You are migrating from REST to GraphQL. Work through MIGRATION_TODO.md one item at a time.
+
+## Build
+
+{{ commands.build }}
+
+## Tests
+
+{{ commands.tests }}
+
+If the build fails or tests fail, fix the issue before continuing migration.
+
+## Each iteration
+
+1. Read MIGRATION_TODO.md, pick the first incomplete item
+2. Migrate that one endpoint
+3. Verify the build passes and tests pass
+4. Mark the item complete in MIGRATION_TODO.md
+5. Commit: `refactor: migrate <endpoint> from REST to GraphQL`
+
+## Completion
+
+Stop with <promise>DONE</promise> when MIGRATION_TODO.md has no remaining items AND MIGRATION_NOTES.md exists with a summary of all changes.
+```
+
+**Why it works:**
+- `stop_on_error: false` — migration often has transient failures; the loop should keep going
+- `required_outputs` gates completion on an actual deliverable file
+- The task list in MIGRATION_TODO.md is the progress memory
+
+## Pattern: Evidence-driven improvement
+
+When there's no fixed checklist — the agent discovers what to improve from running commands.
+
+```yaml
+---
+commands:
+  - name: tests
+    run: uv run pytest -x
+    timeout: 120
+  - name: coverage
+    run: uv run pytest --cov=src --cov-report=term-missing -q
+    timeout: 120
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 15
+completion_promise: DONE
+args:
+  - target
+---
+
+You are increasing test coverage for {{ args.target }}.
+
+## Coverage report
+
+{{ commands.coverage }}
+
+## Test results
+
+{{ commands.tests }}
+
+## Recent commits
+
+{{ commands.git-log }}
+
+Pick the module with the most missing lines from the coverage report.
+Read the source code, understand what it does, and write thorough tests.
+Commit with `test: add coverage for <module>`.
+
+## Rules
+
+- One module per iteration
+- Write tests that verify behavior, not just hit lines
+- All existing tests must still pass
+- Do not add `# pragma: no cover` comments
+
+## Completion
+
+Stop with <promise>DONE</promise> when coverage for {{ args.target }} exceeds 80%.
+```
+
+**Why it works:**
+- Two evidence commands give the agent both test results and coverage data
+- `args.target` makes the loop reusable for different modules
+- The coverage report naturally focuses the agent on the biggest gap
+
+## Pattern: Research and synthesis
+
+For tasks that produce a document rather than code. The loop writes files, and `required_outputs` gates completion.
+
+```yaml
+---
+commands:
+  - name: git-log
+    run: git log --oneline -15
+max_iterations: 20
+timeout: 300
+completion_promise: DONE
+required_outputs:
+  - REPORT.md
+---
+
+You are a research agent building a comprehensive report.
+
+## Recent changes
+
+{{ commands.git-log }}
+
+## Each iteration
+
+1. Read REPORT.md to see what exists
+2. Identify the weakest or most incomplete section
+3. Research the topic using available tools
+4. Write detailed findings into the appropriate section
+5. Update the report outline if needed
+
+## Rules
+
+- Write to REPORT.md and section files in research/
+- One section per iteration
+- Cite sources with URLs
+- Do not fabricate references
+
+## Completion
+
+Stop with <promise>DONE</promise> when REPORT.md exists and all sections referenced in its table of contents have corresponding files with substantial content (>500 words each).
+```
+
+**Why it works:**
+- `timeout: 300` — research iterations need more time
+- `required_outputs: [REPORT.md]` — completion gated on the deliverable
+- Minimal commands — the agent does its own research each iteration
+- Progress lives in the files, not in commands
+
+## Pattern: Security audit
+
+Strict guardrails with self-healing.
+
+```yaml
+---
+commands:
+  - name: scan
+    run: npx audit-ci --moderate
+    timeout: 60
+  - name: tests
+    run: npm test
+    timeout: 120
+  - name: git-log
+    run: git log --oneline -10
+max_iterations: 20
+completion_promise: DONE
+required_outputs:
+  - SECURITY_FINDINGS.md
+guardrails:
+  block_commands:
+    - 'git\s+push'
+    - 'npm\s+publish'
+  protected_files:
+    - '.env*'
+    - '*.pem'
+    - '*.key'
+    - 'policy:secret-bearing-paths'
+---
+
+You are a security auditor. Find and fix vulnerabilities.
+
+## Vulnerability scan
+
+{{ commands.scan }}
+
+## Test results
+
+{{ commands.tests }}
+
+## Recent commits
+
+{{ commands.git-log }}
+
+If tests are failing, fix them before addressing security findings.
+
+## Each iteration
+
+1. Review the vulnerability scan above
+2. Pick one finding
+3. Fix the underlying issue (do not suppress warnings)
+4. Verify tests still pass
+5. Log the finding in SECURITY_FINDINGS.md with: severity, location, description, resolution
+
+## Rules
+
+- One finding per iteration
+- Fix root causes, never suppress warnings
+- Never modify .env, .pem, or .key files
+- Commit with `security: fix <description>`
+
+## Completion
+
+Stop with <promise>DONE</promise> when SECURITY_FINDINGS.md exists and the vulnerability scan reports no moderate or high issues.
+```
+
+**Why it works:**
+- Heavy guardrails — this is a security task, block pushes and protect secrets
+- `policy:secret-bearing-paths` as a catch-all for credential files
+- `required_outputs` gates on the audit deliverable
+- Self-healing: if code changes break tests, fix those first
+
+## Anti-patterns to avoid
+
+### Vague goals
+
+```markdown
+# Bad
+Improve the codebase.
+
+# Good
+Find the module with the lowest test coverage and write tests for it.
+```
+
+### Missing evidence
+
+```markdown
+# Bad — no commands, the agent is blind
+---
+max_iterations: 10
+---
+Fix the failing tests.
+
+# Good — agent sees current state each iteration
+---
+commands:
+  - name: tests
+    run: npm test
+    timeout: 60
+---
+{{ commands.tests }}
+
+Fix the failing tests.
+```
+
+### No completion criteria
+
+```markdown
+# Bad — the loop never knows when it's done
+---
+max_iterations: 20
+---
+Write tests until coverage is good.
+
+# Good — explicit completion gate
+---
+max_iterations: 20
+completion_promise: DONE
+required_outputs:
+  - COVERAGE_REPORT.md
+---
+Stop with <promise>DONE</promise> when all tests pass
+and COVERAGE_REPORT.md exists.
+```
+
+### Too many tasks per iteration
+
+```markdown
+# Bad — the agent tries to do everything at once
+Fix all the bugs, write docs, and refactor the API.
+
+# Good — one thing per iteration
+Pick the highest-priority bug from BUGS.md and fix it.
+Write a regression test that proves the fix.
+```
+
+### Missing progress memory
+
+Without RALPH_PROGRESS.md, the agent re-does work across iterations. Add a section:
+
+```markdown
+## Progress
+
+At the end of each iteration, append a one-line summary to RALPH_PROGRESS.md:
+- What you did
+- What files changed
+- What still needs doing
+```
+
+### Walls of text
+
+Keep prompts under 200 lines. The loop re-reads the entire prompt every iteration. Long prompts waste context window and dilute focus. If you're writing a novel, you're overthinking it.
+
+## Command selection guide
+
+| What you're measuring | Command to use |
+|---|---|
+| Test results | `npm test`, `pytest`, `go test ./...` |
+| Type checking | `tsc --noEmit`, `mypy .`, `go vet ./...` |
+| Linting | `eslint .`, `ruff check .`, `golangci-lint run` |
+| Build status | `npm run build`, `cargo build`, `go build ./...` |
+| Coverage | `pytest --cov`, `go test -cover` |
+| Git history | `git log --oneline -10` |
+| Changed files | `git diff --name-only HEAD~5` |
+| Vulnerability scan | `npm audit`, `bandit -r src/` |
+| Custom metrics | `./scripts/check-coverage.sh` |
+
+Commands starting with `./` run from the task directory. Others run from the project root.