From 70ca2e50e5a07ba05fd0a49069067d9fa16a4213 Mon Sep 17 00:00:00 2001 From: Bryan Joshua Pedini Date: Thu, 5 Mar 2026 01:32:03 +0100 Subject: [PATCH] ralph loop --- AGENTS.md | 29 +++++++++++++++++++++++ PLAN.md | 28 ++++++++++++++++++++++ PROMPT.md | 22 +++++++++++++++++ ralph.sh | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 150 insertions(+) create mode 100644 AGENTS.md create mode 100644 PLAN.md create mode 100644 PROMPT.md create mode 100755 ralph.sh diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ca7b797 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +## Build & Run +Succinct rules for how to BUILD the project: +- Build binary: `go build -o gocv .` +- Run CLI mode: `./gocv` (Reads `./content`, writes to `./output`, exits) +- Run Serve mode: `./gocv serve` (Starts HTTP server, watches `./content`, live updates) +- Configuration: Edit `config.yaml` for template name and HTTP port. Do not use CLI flags. + +## Validation +Run these after implementing to get immediate feedback: +- Tests: `go test ./... -v` +- Typecheck: `go vet ./...` +- Lint: `golangci-lint run` (if available) +- Format: `go fmt ./...` + +## Operational Notes +Succinct learnings about how to RUN the project: +- The binary must be standalone (static linking preferred). +- Do not introduce external dependencies for PDF generation (no wkhtmltopdf, no chrome). +- Graceful shutdown is required for `serve` mode (handle SIGINT/SIGTERM). +- Assume reverse proxy handles SSL; server runs on HTTP only. +- Update `PLAN.md` at the end of every session. + +### Codebase Patterns +- Use `html/template` for rendering. +- Use `goldmark` or similar for Markdown parsing. +- Use `fsnotify` or similar for file watching in `serve` mode. +- Keep `main.go` clean; delegate logic to packages (`pkg/` or `internal/`). +- Config loading should happen at startup; validate required fields. +- Error handling should be explicit; avoid panics in production paths. diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..820cfbe --- /dev/null +++ b/PLAN.md @@ -0,0 +1,28 @@ +# Implementation Plan + +## Project Constraints +- [ ] Pure Go binary (no external system dependencies for PDF). +- [ ] Config via `config.yaml` only (no CLI flags). +- [ ] Hardcoded paths: `./content` (input), `./output` (build artifacts). +- [ ] Modes: `gocv` (CLI), `gocv serve` (Daemon). +- [ ] Commit at every loop iteration. Do not push. Do not tag. + +## Current Status +- [x] Project backbone exists (HTTP server, graceful shutdown, config reading). +- [ ] Markdown parsing logic implemented. +- [ ] HTML Template engine integrated (Hugo-like theme selection). +- [ ] PDF Generation implemented (Pure Go library selected and integrated). +- [ ] CLI Mode (`gocv`) generates static files to `./output` and exits. +- [ ] Serve Mode (`gocv serve`) hosts HTML and serves PDF on demand. +- [ ] File Watcher implemented for live reload in Serve Mode. +- [ ] Dockerfile created for multi-stage build. + +## Active Task +- [ ] Analyze existing backbone code and integrate Markdown parsing. + +## Known Issues / Blockers +- [ ] Identify best Pure Go PDF library that supports HTML/CSS (or define CSS subset). + +## Completed Log +- [x] Initial project structure defined. +- [x] Basic HTTP server and signal handling implemented. diff --git a/PROMPT.md b/PROMPT.md new file mode 100644 index 0000000..41afe9b --- /dev/null +++ b/PROMPT.md @@ -0,0 +1,22 @@ +0a. Study `PLAN.md` to understand the current implementation status and next tasks. +0b. Study `AGENTS.md` for build, run, and validation rules. +0c. For reference, the application source code is in the root directory. +1. Your task is to implement functionality per the `PLAN.md` items. Choose the most important pending item. Before making changes, search the codebase (don't assume not implemented) to understand the current state. +2. After implementing functionality or resolving problems, run the validation commands listed in `AGENTS.md`. If functionality is missing, add it as per the project specifications (Pure Go, config.yaml, hardcoded paths). +3. When you discover issues or complete tasks, immediately update `PLAN.md` with your findings. Mark items as completed `[x]` or add new findings as unchecked `[ ]` items. +4. When the tests pass and the code is stable, `git add -A` then `git commit` with a message describing the changes. **You must commit at every loop iteration.** +5. **DO NOT push.** **DO NOT create git tags.** +99999. Important: When authoring documentation, capture the why — tests and implementation importance. +999999. Important: Single sources of truth, no migrations/adapters. If tests unrelated to your work fail, resolve them as part of the increment. +9999999. You may add extra logging if required to debug issues. +99999999. Keep `PLAN.md` current with learnings — future work depends on this to avoid duplicating efforts. Update especially after finishing your turn. +999999999. For any bugs you notice, resolve them or document them in `PLAN.md` even if it is unrelated to the current piece of work. +9999999999. Implement functionality completely. Placeholders and stubs waste efforts and time redoing the same work. +99999999999. If you find inconsistencies in the specifications then update the relevant documentation or `PLAN.md`. +999999999999. IMPORTANT: Keep `AGENTS.md` operational only — status updates and progress notes belong in `PLAN.md`. A bloated `AGENTS.md` pollutes every future loop's context. +9999999999999. Project Specifics: + - No CLI flags. Configuration is via `config.yaml`. + - Content path is hardcoded `./content`. + - Output path is hardcoded `./output`. + - Modes: `gocv` (CLI generate), `gocv serve` (HTTP server). + - PDF Generation must be Pure Go (no external binaries). diff --git a/ralph.sh b/ralph.sh new file mode 100755 index 0000000..658212f --- /dev/null +++ b/ralph.sh @@ -0,0 +1,71 @@ +#!/bin/bash +# Usage: ./loop.sh [plan] [max_iterations] +# Examples: +# ./loop.sh # Build mode, unlimited tasks +# ./loop.sh 20 # Build mode, max 20 tasks +# ./loop.sh plan # Plan mode, unlimited tasks +# ./loop.sh plan 5 # Plan mode, max 5 tasks + +# Parse arguments +if [ "$1" = "plan" ]; then + # Plan mode + MODE="plan" + PROMPT_FILE="PROMPT_plan.md" + MAX_ITERATIONS=${2:-0} +elif [[ "$1" =~ ^[0-9]+$ ]]; then + # Build mode with max tasks + MODE="build" + PROMPT_FILE="PROMPT.md" + MAX_ITERATIONS=$1 +else + # Build mode, unlimited (no arguments or invalid input) + MODE="build" + PROMPT_FILE="PROMPT_build.md" + MAX_ITERATIONS=0 +fi + +ITERATION=0 +CURRENT_BRANCH=$(git branch --show-current) + +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "Mode: $MODE" +echo "Prompt: $PROMPT_FILE" +echo "Branch: $CURRENT_BRANCH" +[ $MAX_ITERATIONS -gt 0 ] && echo "Max: $MAX_ITERATIONS iterations (number of tasks)" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + +# Verify prompt file exists +if [ ! -f "$PROMPT_FILE" ]; then + echo "Error: $PROMPT_FILE not found" + exit 1 +fi + +while true; do + if [ $MAX_ITERATIONS -gt 0 ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then + echo "Reached max iterations (number of tasks): $MAX_ITERATIONS" + break + fi + + # Run Ralph iteration with selected prompt + # -p: Headless mode (non-interactive, reads from stdin) + # --dangerously-skip-permissions: Auto-approve all tool calls (YOLO mode) + # --output-format=stream-json: Structured output for logging/monitoring + # --model opus: Primary agent uses Opus for complex reasoning (task selection, prioritization) + # Can use 'sonnet' in build mode for speed if plan is clear and tasks well-defined + # --verbose: Detailed execution logging + cat "$PROMPT_FILE" | claude -p \ + --dangerously-skip-permissions \ + --output-format=stream-json \ + --verbose + + # Push changes after each iteration + git push origin "$CURRENT_BRANCH" || { + echo "Failed to push. Creating remote branch..." + git push -u origin "$CURRENT_BRANCH" + } + + ITERATION=$((ITERATION + 1)) + echo -e "\n\n=================================================================\n" + echo -e "\n\n======================== LOOP $ITERATION ========================\n" + echo -e "\n\n=================================================================\n" +done