ralph loop

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.

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.

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).

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