Add Ralph loop scaffold with guard, workflow, and state files

[Copilot]

Ralph loop scaffold added to run one story per iteration with guardrails, state files, and CI workflow using OpenCode.

• State & Config: Added AGENTS.md, .opencode/opencode.json, and scripts/ralph/{prd.json,progress.txt,constraints.json,failure.json} to define stories, progress, constraints, and failure tracking.
• Guardrails: Introduced scripts/ralph/guard.sh to enforce pause flag, file/line limits, forbidden paths, and progress updates before commits.
• Automation: Added .github/workflows/ralph.yml to run a single OpenCode iteration, validate JSON, execute the guard, and commit/push with PAT and explicit permissions.
• Docs: Updated README with a brief Ralph loop overview and required secret.

Example guard check snippet:

bash scripts/ralph/guard.sh scripts/ralph/constraints.json
# Enforces pause, max files/lines, forbidden paths, and progress updates

Original prompt

You are Ralph.

Your task: set up a self-perpetuating RALPH LOOP in the current repo, modeled after the reference “ralph” repo pattern.

Outcome

Create the minimal files + GitHub Actions workflow so the loop can run one iteration at a time:

• read state from files
• choose exactly one story
• implement minimal change
• enforce guard constraints
• commit + push
• push re-triggers the workflow until no todo stories remain or PAUSED is true

Non-negotiables

• One story per run. Small commits.
• Never commit if guard fails.
• Keep AGENTS.md short (~70 lines). Only include repeated-footgun info.
• Persistent memory is ONLY repo files + git commits (no hidden memory).
• Prefer docs-only scaffolding first; don’t add deps unless a story requires it.

Create these files (if missing)

• AGENTS.md
• .opencode/opencode.json
• scripts/ralph/prd.json
• scripts/ralph/progress.txt
• scripts/ralph/constraints.json
• scripts/ralph/failure.json
• scripts/ralph/guard.sh (diff guard enforcing constraints)
• .github/workflows/ralph.yml
• README.md (briefly explains the RALPH LOOP + how to run)

RALPH LOOP rules (how to operate each iteration)

1. Load AGENTS.md and state files in scripts/ralph/
2. If - PAUSED: true → exit immediately
3. In prd.json, pick the first story with "status": "todo" (or highest priority todo)
4. Mark it "doing"
5. Implement minimal changes to satisfy the story acceptance criteria
6. Run verification (if the story specifies commands; otherwise keep docs-only)
7. Run bash scripts/ralph/guard.sh scripts/ralph/constraints.json
8. If green:
   • mark story "done" in prd.json
   • append learnings to progress.txt
   • commit + push with a bot identity
9. If failure:
   • update failure.json (increment consecutiveFailures, store run URL + timestamp)
   • if failures exceed MAX_FAILURE_RETRIES, set - PAUSED: true in AGENTS.md
   • commit + push failure state so the next run can retry (unless paused)

Initial PRD requirements

Initialize scripts/ralph/prd.json with 3–6 tiny stories:

• S1: Boot Ralph automation scaffold (files + workflow)
• S2: Add/verify diff guard in CI
• S3: Make README describe how to run
  (keep them small enough for one run each)

Workflow requirements

• Trigger on workflow_dispatch AND on pushes to AGENTS.md and scripts/ralph/**
• Auto-run only on bot pushes (manual dispatch always allowed)
• Use a PAT secret for checkout/push (do not hardcode tokens)
• Install Node + jq + OpenCode
• Run exactly one agent iteration with OpenCode using:
  AGENTS.md, prd.json, progress.txt, constraints.json, failure.json
• Validate JSON, run guard, then commit + push

Now implement the scaffold in this repo.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.