@canivel/ralph 0.2.0

package/.agents/ralph/PROMPT_build.md

@@ -0,0 +1,126 @@
+# Build
+
+You are an autonomous coding agent. Your task is to complete the work for exactly one story and record the outcome.
+
+## Paths
+- PRD: {{PRD_PATH}}
+- AGENTS (optional): {{AGENTS_PATH}}
+- Progress Log: {{PROGRESS_PATH}}
+- Guardrails: {{GUARDRAILS_PATH}}
+- Guardrails Reference: {{GUARDRAILS_REF}}
+- Context Reference: {{CONTEXT_REF}}
+- Errors Log: {{ERRORS_LOG_PATH}}
+- Activity Log: {{ACTIVITY_LOG_PATH}}
+- Activity Logger: {{ACTIVITY_CMD}}
+- No-commit: {{NO_COMMIT}}
+- Repo Root: {{REPO_ROOT}}
+- Run ID: {{RUN_ID}}
+- Iteration: {{ITERATION}}
+- Run Log: {{RUN_LOG_PATH}}
+- Run Summary: {{RUN_META_PATH}}
+
+## Global Quality Gates (apply to every story)
+{{QUALITY_GATES}}
+
+## Selected Story (Do not change scope)
+ID: {{STORY_ID}}
+Title: {{STORY_TITLE}}
+
+Story details:
+{{STORY_BLOCK}}
+
+If the story details are empty or missing, STOP and report that the PRD story format could not be parsed.
+
+## Rules (Non-Negotiable)
+- Implement **only** the work required to complete the selected story.
+- Complete all tasks associated with this story (and only this story).
+- Do NOT ask the user questions.
+- Do NOT change unrelated code.
+- Do NOT assume something is unimplemented — confirm by reading code.
+- Implement completely; no placeholders or stubs.
+- If No-commit is true, do NOT commit or push changes.
+- Do NOT edit the PRD JSON (status is handled by the loop).
+- All changes made during the run must be committed (including updates to progress/logs).
+ - Before committing, perform a final **security**, **performance**, and **regression** review of your changes.
+
+## Your Task (Do this in order)
+1. Read {{GUARDRAILS_PATH}} before any code changes.
+2. Read {{ERRORS_LOG_PATH}} for repeated failures to avoid.
+3. Read {{PRD_PATH}} for global context (do not edit).
+4. Fully audit and read all necessary files to understand the task end-to-end before implementing. Do not assume missing functionality.
+5. If {{AGENTS_PATH}} exists, follow its build/test instructions.
+6. Implement only the tasks that belong to {{STORY_ID}}.
+7. Run verification commands listed in the story, the global quality gates, and in {{AGENTS_PATH}} (if required).
+8. If the project has a build or dev workflow, run what applies:
+   - Build step (e.g., `npm run build`) if defined.
+   - Dev server (e.g., `npm run dev`, `wrangler dev`) if it is the normal validation path.
+   - Confirm no runtime/build errors in the console.
+9. Perform a brief audit before committing:
+   - **Security:** check for obvious vulnerabilities or unsafe handling introduced by your changes.
+   - **Performance:** check for avoidable regressions (extra queries, heavy loops, unnecessary re-renders).
+   - **Regression:** verify existing behavior that could be impacted still works.
+10. If No-commit is false, commit changes using the `$commit` skill.
+    - Stage everything: `git add -A`
+    - Confirm a clean working tree after commit: `git status --porcelain` should be empty.
+    - After committing, capture the commit hash and subject using:
+      `git show -s --format="%h %s" HEAD`.
+11. Append a progress entry to {{PROGRESS_PATH}} with run/commit/test details (format below).
+    If No-commit is true, skip committing and note it in the progress entry.
+
+## Progress Entry Format (Append Only)
+```
+## [Date/Time] - {{STORY_ID}}: {{STORY_TITLE}}
+Thread: [codex exec session id if available, otherwise leave blank]
+Run: {{RUN_ID}} (iteration {{ITERATION}})
+Run log: {{RUN_LOG_PATH}}
+Run summary: {{RUN_META_PATH}}
+- Guardrails reviewed: yes
+- No-commit run: {{NO_COMMIT}}
+- Commit: <hash> <subject> (or `none` + reason)
+- Post-commit status: `clean` or list remaining files
+- Verification:
+  - Command: <exact command> -> PASS/FAIL
+  - Command: <exact command> -> PASS/FAIL
+- Files changed:
+  - <file path>
+  - <file path>
+- What was implemented
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+  - Useful context
+---
+```
+
+## Completion Signal
+Only output the completion signal when the **selected story** is fully complete and verified.
+When the selected story is complete, output:
+<promise>COMPLETE</promise>
+
+Otherwise, end normally without the signal.
+
+## Additional Guardrails
+- When authoring documentation, capture the why (tests + implementation intent).
+- If you learn how to run/build/test the project, update {{AGENTS_PATH}} briefly (operational only).
+- Keep AGENTS operational only; progress notes belong in {{PROGRESS_PATH}}.
+- If you hit repeated errors, log them in {{ERRORS_LOG_PATH}} and add a Sign to {{GUARDRAILS_PATH}} using {{GUARDRAILS_REF}} as the template.
+
+## Activity Logging (Required)
+Log major actions to {{ACTIVITY_LOG_PATH}} using the helper:
+```
+{{ACTIVITY_CMD}} "message"
+```
+Log at least:
+- Start of work on the story
+- After major code changes
+- After tests/verification
+- After updating progress log
+
+## Browser Testing (Required for Frontend Stories)
+If the selected story changes UI, you MUST verify it in the browser:
+1. Load the `dev-browser` skill.
+2. Navigate to the relevant page.
+3. Verify the UI changes work as expected.
+4. Take a screenshot if helpful for the progress log.
+
+A frontend story is NOT complete until browser verification passes.

package/.agents/ralph/agents.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Default agent command templates (used by loop.sh and CLI).
+
+AGENT_CODEX_CMD="codex exec --yolo --skip-git-repo-check -"
+AGENT_CODEX_INTERACTIVE_CMD="codex --yolo {prompt}"
+AGENT_CLAUDE_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
+AGENT_CLAUDE_INTERACTIVE_CMD="claude --dangerously-skip-permissions {prompt}"
+AGENT_DROID_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
+AGENT_DROID_INTERACTIVE_CMD="droid --skip-permissions-unsafe {prompt}"
+AGENT_OPENCODE_CMD="opencode run \"\$(cat {prompt})\""
+AGENT_OPENCODE_INTERACTIVE_CMD="opencode --prompt {prompt}"
+# Uncomment to use server mode (faster, avoids cold boot):
+# AGENT_OPENCODE_CMD="opencode run --attach http://localhost:4096 \"\$(cat {prompt})\""
+# AGENT_OPENCODE_INTERACTIVE_CMD="opencode --prompt {prompt} --attach http://localhost:4096"
+DEFAULT_AGENT="${DEFAULT_AGENT:-codex}"

package/.agents/ralph/config.sh

@@ -0,0 +1,25 @@
+# Optional Ralph config overrides.
+# All paths are relative to repo root unless absolute.
+# Uncomment and edit as needed.
+
+# PRD_PATH=".agents/tasks/prd.json"
+# PROGRESS_PATH=".ralph/progress.md"
+# GUARDRAILS_PATH=".ralph/guardrails.md"
+# ERRORS_LOG_PATH=".ralph/errors.log"
+# ACTIVITY_LOG_PATH=".ralph/activity.log"
+# TMP_DIR=".ralph/.tmp"
+# RUNS_DIR=".ralph/runs"
+# GUARDRAILS_REF=".agents/ralph/references/GUARDRAILS.md"
+# CONTEXT_REF=".agents/ralph/references/CONTEXT_ENGINEERING.md"
+# ACTIVITY_CMD=".agents/ralph/log-activity.sh"
+# AGENT_CMD defaults are defined in agents.sh. Override here if needed.
+# AGENT_CMD="codex exec --yolo --skip-git-repo-check -"
+# PRD_AGENT_CMD defaults are defined in agents.sh (interactive).
+# PRD_AGENT_CMD="codex --yolo --skip-git-repo-check {prompt}"
+# AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
+# AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
+# AGENTS_PATH="AGENTS.md"
+# PROMPT_BUILD=".agents/ralph/PROMPT_build.md"
+# NO_COMMIT=false
+# MAX_ITERATIONS=25
+# STALE_SECONDS=0

package/.agents/ralph/log-activity.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+ACTIVITY_LOG="$ROOT_DIR/.ralph/activity.log"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 \"message\""
+  exit 1
+fi
+
+mkdir -p "$(dirname "$ACTIVITY_LOG")"
+TS=$(date '+%Y-%m-%d %H:%M:%S')
+echo "[$TS] $*" >> "$ACTIVITY_LOG"