feat: initial ralph-workplan skill

Standalone Claude Code skill that ties a ralph loop to a workplan file.
Retires automatically when all tasks are done — no external dependencies.

- plugin/ralph-workplan.md      skill entrypoint
- plugin/scripts/check-done.sh  pre-start guard (reads workplan status)
- plugin/scripts/setup.sh       writes ralph state file with workplan-aware prompt
- install.sh                    copies plugin files to ~/.claude/plugins/
- workplan-spec.md              workplan file format reference
- README.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

plugin/scripts/check-done.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# check-done.sh
+# Exit 0 if the workplan is done, 1 if not.
+# Used as the pre-start guard in the ralph-workplan skill.
+#
+# Usage: check-done.sh <workplan_file>
+
+set -euo pipefail
+
+WORKPLAN_FILE="${1:?workplan_file required}"
+
+if [[ ! -f "$WORKPLAN_FILE" ]]; then
+  echo "❌ Workplan file not found: $WORKPLAN_FILE" >&2
+  exit 2
+fi
+
+# Extract status from YAML frontmatter (first occurrence between --- markers)
+STATUS=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$WORKPLAN_FILE" \
+  | grep '^status:' \
+  | head -1 \
+  | sed 's/status:[[:space:]]*//' \
+  | tr -d '"'"'" )
+
+if [[ -z "$STATUS" ]]; then
+  echo "⚠️  No status field found in frontmatter of: $WORKPLAN_FILE" >&2
+  exit 1
+fi
+
+if [[ "$STATUS" == "done" ]]; then
+  exit 0
+else
+  exit 1
+fi

plugin/scripts/setup.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# setup.sh
+# Writes the .claude/ralph-loop.local.md state file with a workplan-aware prompt.
+# Called by the /ralph-workplan skill after the pre-start guard passes.
+#
+# Usage: setup.sh <workplan_file> <workplan_id> <title> <max_iterations>
+
+set -euo pipefail
+
+WORKPLAN_FILE="${1:?workplan_file required}"
+WORKPLAN_ID="${2:?workplan_id required}"
+TITLE="${3:?title required}"
+MAX_ITERATIONS="${4:-20}"
+SESSION_ID="${CLAUDE_CODE_SESSION_ID:-}"
+
+STATE_FILE=".claude/ralph-loop.local.md"
+
+mkdir -p .claude
+
+# Extract workplan body — everything after the second ---
+WORKPLAN_BODY=$(awk '/^---$/{i++; next} i>=2' "$WORKPLAN_FILE")
+
+cat > "$STATE_FILE" <<EOF
+---
+active: true
+iteration: 1
+session_id: ${SESSION_ID}
+max_iterations: ${MAX_ITERATIONS}
+completion_promise: "HEUREKA"
+workplan_id: ${WORKPLAN_ID}
+workplan_file: ${WORKPLAN_FILE}
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+## Workplan Status Check — Do This First, Every Iteration
+
+Read the workplan file at: \`${WORKPLAN_FILE}\`
+
+Count the task blocks (fenced code blocks with language tag \`task\`):
+- How many tasks exist in total?
+- How many have \`status: done\`?
+
+If **every task** has \`status: done\` AND the frontmatter \`status\` is \`done\`:
+  The workplan is complete. Output exactly: <promise>HEUREKA</promise>
+  Do nothing else. Stop here.
+
+Otherwise: continue with the implementation below.
+
+---
+
+## Workplan: ${WORKPLAN_ID} — ${TITLE}
+**File:** \`${WORKPLAN_FILE}\`
+
+${WORKPLAN_BODY}
+
+---
+
+## How to Work
+
+- Stay strictly within the scope of the workplan above
+- Work through tasks in priority order (high → medium → low)
+- Use TDD where applicable: write a failing test, make it pass, then refactor
+- Use whatever test runner, linter, and build tools this repository already uses
+- Consult existing documentation (README, docs/, wiki/, specs/) for context
+- Document significant architecture decisions as ADRs if the project uses them
+
+## Updating Task Status
+
+As you complete each task, edit the workplan file to update its status:
+
+\`\`\`
+status: todo       →   status: in_progress   (when you start it)
+status: in_progress →  status: done          (when it is verified complete)
+\`\`\`
+
+When **every task** is \`done\`, also update the workplan frontmatter:
+
+\`\`\`
+status: active  →  status: done
+\`\`\`
+
+## Success Criteria
+
+Before marking the workplan done and outputting \`<promise>HEUREKA</promise>\`,
+verify all of the following are true:
+
+1. Every task block in \`${WORKPLAN_FILE}\` has \`status: done\`
+2. The workplan frontmatter \`status\` is \`done\`
+3. The full test suite passes with no failures
+4. The codebase passes the project's standard code-quality checks
+   (linting, type checking, formatting — whatever applies to this project)
+5. Documentation reflects the implemented behaviour
+
+Output \`<promise>HEUREKA</promise>\` only when all five are genuinely true.
+
+EOF
+
+echo "✅ Ralph state file written: $STATE_FILE"
+echo "   Workplan : $WORKPLAN_ID — $TITLE"
+echo "   File     : $WORKPLAN_FILE"
+echo "   Max iter : $MAX_ITERATIONS"
+echo "   Promise  : HEUREKA (output only when workplan is genuinely done)"