@ai-dev-methodologies/rlp-desk 0.0.1

package/examples/calculator/.claude/ralph-desk/plans/prd-loop-test.md

@@ -0,0 +1,37 @@
+# PRD: loop-test
+
+## Objective
+Implement a Python calculator module: calc.py + test_calc.py
+
+## User Stories
+
+### US-001: calc.py — Basic Operations
+- **Priority**: P0
+- **Acceptance Criteria**:
+  - [ ] calc.py exists at the project root
+  - [ ] Implements add(a, b), subtract(a, b), multiply(a, b), divide(a, b)
+  - [ ] divide(a, 0) raises ValueError
+  - [ ] All functions have type hints: (a: float, b: float) -> float
+- **Status**: not started
+
+### US-002: test_calc.py — Tests
+- **Priority**: P0
+- **Acceptance Criteria**:
+  - [ ] test_calc.py exists at the project root
+  - [ ] Uses pytest (import pytest)
+  - [ ] At least 2 test cases per function (8+ total)
+  - [ ] Includes divide-by-zero test (pytest.raises)
+  - [ ] python3 -m pytest test_calc.py -v → ALL PASSED
+- **Status**: not started
+
+## Non-Goals
+- CLI interface, complex math operations
+
+## Technical Constraints
+- Python 3 standard library + pytest only
+- Work on only one story per iteration
+
+## Done When
+- US-001 and US-002 acceptance criteria all pass
+- python3 -m pytest test_calc.py -v → ALL PASSED
+- Independent verifier confirms

package/examples/calculator/.claude/ralph-desk/plans/test-spec-loop-test.md

@@ -0,0 +1,29 @@
+# Test Specification: loop-test
+
+## Verification Commands
+### Test
+```bash
+python3 -m pytest test_calc.py -v
+```
+### Type hint check
+```bash
+grep -c "def.*float.*float.*float" calc.py
+```
+### Divide by zero
+```bash
+python3 -c "from calc import divide; divide(1, 0)"
+# must raise ValueError
+```
+
+## Criteria → Verification Mapping
+| Criterion | Method | Command |
+|-----------|--------|---------|
+| US-001 AC1: calc.py exists | automated | `test -f calc.py` |
+| US-001 AC2: 4 functions | automated | `python3 -c "from calc import add, subtract, multiply, divide"` |
+| US-001 AC3: divide by zero | automated | `python3 -c "from calc import divide; divide(1, 0)"` → ValueError |
+| US-001 AC4: type hints | automated | `grep "def add" calc.py` must show float annotations |
+| US-002 AC1: test_calc.py exists | automated | `test -f test_calc.py` |
+| US-002 AC2: uses pytest | automated | `grep "import pytest" test_calc.py` |
+| US-002 AC3: 8+ tests | automated | `python3 -m pytest test_calc.py -v` → count PASSED >= 8 |
+| US-002 AC4: divide zero test | automated | `grep "pytest.raises" test_calc.py` |
+| US-002 AC5: ALL PASSED | automated | `python3 -m pytest test_calc.py -v` exit code 0 |

package/examples/calculator/.claude/ralph-desk/prompts/loop-test.verifier.prompt.md

@@ -0,0 +1,29 @@
+Independent verifier for RLP Desk: loop-test
+
+STRICT VERIFICATION RULES:
+- Run EVERY command in the test spec. Do not skip any.
+- A single failing criterion = verdict FAIL.
+- Do NOT modify any code files.
+
+Required reads:
+- PRD: .claude/ralph-desk/plans/prd-loop-test.md
+- Test Spec: .claude/ralph-desk/plans/test-spec-loop-test.md
+- Campaign Memory: .claude/ralph-desk/memos/loop-test-memory.md
+- Done Claim: .claude/ralph-desk/memos/loop-test-done-claim.json
+
+Verification process:
+1. Read PRD - get all acceptance criteria
+2. Read done claim
+3. Run EVERY verification command from test spec:
+   - test -f calc.py
+   - python3 -c "from calc import add, subtract, multiply, divide"
+   - python3 -c "from calc import divide; divide(1, 0)" → must raise ValueError
+   - grep for type hints in calc.py (all 4 functions must have float annotations)
+   - test -f test_calc.py
+   - grep "import pytest" test_calc.py
+   - grep "pytest.raises" test_calc.py
+   - python3 -m pytest test_calc.py -v → must show 8+ PASSED, 0 FAILED, exit code 0
+4. Write verdict JSON to: .claude/ralph-desk/memos/loop-test-verify-verdict.json
+
+CRITICAL: If even ONE criterion fails, verdict must be "fail" with recommended_state_transition "continue".
+Include the specific failure in next_iteration_contract so the next worker knows what to fix.

package/examples/calculator/.claude/ralph-desk/prompts/loop-test.worker.prompt.md

@@ -0,0 +1,32 @@
+Execute the plan for loop-test.
+
+Required reads every iteration:
+- PRD: .claude/ralph-desk/plans/prd-loop-test.md
+- Test Spec: .claude/ralph-desk/plans/test-spec-loop-test.md
+- Campaign Memory: .claude/ralph-desk/memos/loop-test-memory.md
+- Latest Context: .claude/ralph-desk/context/loop-test-latest.md
+
+CRITICAL RULE: Work on only ONE User Story per iteration.
+- Check campaign memory's "Next Iteration Contract" first and do that.
+- Do not touch already-completed stories.
+
+Iteration rules:
+- Use fresh context only; do NOT depend on prior chat history.
+- Execute exactly ONE bounded next action (ONE user story).
+- Refresh context file with the current frontier.
+- Rewrite campaign memory in full.
+
+MANDATORY: When done, write the following signal file:
+- Path: .claude/ralph-desk/memos/loop-test-iter-signal.json
+- Format: {"iteration": N, "status": "continue|verify|blocked", "timestamp": "ISO"}
+- Status values:
+  - "continue" = current story done but other stories remain
+  - "verify" = all stories complete + done-claim written
+  - "blocked" = autonomous blocker
+
+Stop behavior:
+- Current story done but other stories remain → memory stop=continue, signal status=continue
+- All stories complete + all tests pass → write done-claim JSON (.claude/ralph-desk/memos/loop-test-done-claim.json) + signal status=verify
+- Autonomous blocker → write blocked.md + signal status=blocked
+
+Objective: Implement a Python calculator module: calc.py (4 functions + type hints + ValueError) + test_calc.py (pytest, 8+ tests, all passed)

package/install.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+set -euo pipefail
+
+# =============================================================================
+# RLP Desk Installer
+#
+# Installs the RLP Desk slash command and support files into ~/.claude/
+#
+# Usage:
+#   curl -sSL https://raw.githubusercontent.com/ai-dev-methodologies/rlp-desk/main/install.sh | bash
+#
+# Safe to run multiple times (idempotent).
+# =============================================================================
+
+REPO_URL="https://raw.githubusercontent.com/ai-dev-methodologies/rlp-desk/main"
+CLAUDE_DIR="$HOME/.claude"
+COMMANDS_DIR="$CLAUDE_DIR/commands"
+DESK_DIR="$CLAUDE_DIR/ralph-desk"
+
+echo ""
+echo "  RLP Desk Installer"
+echo "  ==================="
+echo ""
+
+# Create directories
+mkdir -p "$COMMANDS_DIR"
+mkdir -p "$DESK_DIR"
+
+# Download slash command
+echo "  Downloading slash command..."
+curl -sSL "$REPO_URL/src/commands/rlp-desk.md" -o "$COMMANDS_DIR/rlp-desk.md"
+
+# Download init script
+echo "  Downloading init script..."
+curl -sSL "$REPO_URL/src/scripts/init_ralph_desk.zsh" -o "$DESK_DIR/init_ralph_desk.zsh"
+chmod +x "$DESK_DIR/init_ralph_desk.zsh"
+
+# Download governance protocol
+echo "  Downloading governance protocol..."
+curl -sSL "$REPO_URL/src/governance.md" -o "$DESK_DIR/governance.md"
+
+echo ""
+echo "  Done! Installed to:"
+echo ""
+echo "    Slash command:  $COMMANDS_DIR/rlp-desk.md"
+echo "    Init script:    $DESK_DIR/init_ralph_desk.zsh"
+echo "    Governance:     $DESK_DIR/governance.md"
+echo ""
+echo "  Usage:"
+echo "    1. Open Claude Code in your project directory"
+echo "    2. Run: /rlp-desk brainstorm \"your task description\""
+echo "    3. Run: /rlp-desk run <slug>"
+echo ""

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ai-dev-methodologies/rlp-desk",
+  "version": "0.0.1",
+  "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "uninstall": "node scripts/uninstall.js"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "docs/",
+    "examples/",
+    "install.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "ralph-loop",
+    "ai-coding",
+    "fresh-context",
+    "agent-loop",
+    "autonomous",
+    "verification"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-dev-methodologies/rlp-desk.git"
+  },
+  "homepage": "https://github.com/ai-dev-methodologies/rlp-desk",
+  "bugs": {
+    "url": "https://github.com/ai-dev-methodologies/rlp-desk/issues"
+  },
+  "license": "MIT",
+  "author": "ai-dev-methodologies",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const home = os.homedir();
+const claudeDir = path.join(home, ".claude");
+const commandsDir = path.join(claudeDir, "commands");
+const deskDir = path.join(claudeDir, "ralph-desk");
+const pkgDir = path.join(__dirname, "..");
+
+console.log("");
+console.log("  RLP Desk v0.0.1");
+console.log("  ================");
+console.log("");
+
+// Create directories
+fs.mkdirSync(commandsDir, { recursive: true });
+fs.mkdirSync(deskDir, { recursive: true });
+
+// Copy files
+const copies = [
+  ["src/commands/rlp-desk.md", path.join(commandsDir, "rlp-desk.md")],
+  [
+    "src/scripts/init_ralph_desk.zsh",
+    path.join(deskDir, "init_ralph_desk.zsh"),
+  ],
+  ["src/governance.md", path.join(deskDir, "governance.md")],
+];
+
+for (const [src, dest] of copies) {
+  fs.copyFileSync(path.join(pkgDir, src), dest);
+  console.log("  + " + dest);
+}
+
+// Make scripts executable
+try {
+  fs.chmodSync(path.join(deskDir, "init_ralph_desk.zsh"), 0o755);
+} catch (_) {
+  // chmod may fail on Windows — not critical
+}
+
+console.log("");
+console.log("  Done! Open Claude Code and run:");
+console.log("    /rlp-desk brainstorm \"your task description\"");
+console.log("");

package/scripts/uninstall.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const home = os.homedir();
+const claudeDir = path.join(home, ".claude");
+const commandsDir = path.join(claudeDir, "commands");
+const deskDir = path.join(claudeDir, "ralph-desk");
+
+console.log("");
+console.log("  Uninstalling RLP Desk...");
+console.log("");
+
+const files = [
+  path.join(commandsDir, "rlp-desk.md"),
+  path.join(deskDir, "init_ralph_desk.zsh"),
+  path.join(deskDir, "governance.md"),
+];
+
+for (const f of files) {
+  try {
+    fs.unlinkSync(f);
+    console.log("  - " + f);
+  } catch (_) {
+    // File may not exist
+  }
+}
+
+// Remove ralph-desk dir if empty
+try {
+  const remaining = fs.readdirSync(deskDir);
+  if (remaining.length === 0) {
+    fs.rmdirSync(deskDir);
+    console.log("  - " + deskDir);
+  }
+} catch (_) {
+  // Directory may not exist
+}
+
+console.log("");
+console.log("  RLP Desk uninstalled.");
+console.log("");

package/src/commands/rlp-desk.md

@@ -0,0 +1,164 @@
+---
+description: "Fresh-context RLP Desk — brainstorm, init, run, status, logs, clean"
+argument-hint: "<brainstorm|init|run|status|logs|clean> <slug> [options]"
+---
+
+# RLP Desk for Claude Code
+
+**YOU are the leader.** You orchestrate fresh-context workers/verifiers via Agent().
+
+The user invoked: `/rlp-desk $ARGUMENTS`
+
+Parse the first word of `$ARGUMENTS` as the subcommand.
+
+---
+
+## `brainstorm <description>`
+
+Planning phase BEFORE init. Interactively define the contract with the user.
+
+Determine all of the following:
+1. **Slug** — short identifier (e.g., `auth-refactor`)
+2. **Objective** — what the loop achieves
+3. **User Stories** — discrete units with testable acceptance criteria
+4. **Iteration Unit** — one worker does per iteration (default: one user story)
+5. **Verification Commands** — build, test, lint commands
+6. **Completion / Blocked Criteria**
+7. **Worker / Verifier Model** — haiku, sonnet, opus
+8. **Max Iterations**
+
+Present the contract summary. On approval, offer to run `init`.
+Do NOT create files during brainstorm.
+
+---
+
+## `init <slug> [objective]`
+
+Run: `~/.claude/ralph-desk/init_ralph_desk.zsh <slug> "<objective>"`
+If brainstorm was done, auto-fill PRD and test-spec with the results.
+
+---
+
+## `run <slug> [options]`
+
+**YOU are the leader. Do NOT delegate leadership.**
+
+Options (parse from `$ARGUMENTS`):
+- `--max-iter N` (default: 100)
+- `--worker-model MODEL` (default: sonnet)
+- `--verifier-model MODEL` (default: sonnet)
+
+### Preparation
+1. Validate scaffold: `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
+2. Check sentinels (complete/blocked). Found → tell user `/rlp-desk clean <slug>`.
+3. Clean previous `done-claim.json`, `verify-verdict.json`.
+
+### Leader Loop
+
+For each iteration (1 to max_iter):
+
+**① Check sentinels**
+```bash
+test -f .claude/ralph-desk/memos/<slug>-complete.md  # → done
+test -f .claude/ralph-desk/memos/<slug>-blocked.md   # → stop
+```
+
+**② Read memory.md** → Stop Status, Next Iteration Contract
+
+**③ Decide model** (§4 of governance.md)
+- Previous iteration failed → upgrade model
+- Simple task → downgrade
+- User specified → use that
+
+**④ Build worker prompt**
+- Read `.claude/ralph-desk/prompts/<slug>.worker.prompt.md`
+- Combine with iteration number + memory contract
+- Write to `.claude/ralph-desk/logs/<slug>/iter-NNN.worker-prompt.md` (audit trail)
+
+**⑤ Execute Worker via Agent()**
+```
+Agent(
+  description="rlp-desk worker iter-NNN",
+  subagent_type="executor",
+  model=<worker_model>,
+  mode="bypassPermissions",
+  prompt=<full worker prompt text>
+)
+```
+- Agent returns synchronously. No polling needed.
+- Each Agent() = fresh context. Guaranteed.
+
+**⑥ Read memory.md again** (Worker updated it)
+- `stop=continue` → go to ⑧
+- `stop=verify` → go to ⑦
+- `stop=blocked` → write BLOCKED sentinel, stop
+
+**⑦ Execute Verifier via Agent()**
+- Build verifier prompt, write to `iter-NNN.verifier-prompt.md`
+```
+Agent(
+  description="rlp-desk verifier iter-NNN",
+  subagent_type="executor",
+  model=<verifier_model>,
+  mode="bypassPermissions",
+  prompt=<full verifier prompt text>
+)
+```
+- Read `verify-verdict.json`:
+  - `pass` + `complete` → write COMPLETE sentinel, report done!
+  - `fail` + `continue` → go to ⑧
+  - `blocked` → write BLOCKED sentinel, stop
+
+**⑧ Report iteration result to user, continue loop**
+- Write `status.json`
+- Report: iteration N, phase, model used, result
+- Clean `done-claim.json`, `verify-verdict.json` for next iteration
+
+### Circuit Breaker
+- context-latest.md unchanged 3 iterations → BLOCKED
+- Same error 2x → upgrade model, retry once, then BLOCKED
+- max_iter reached → TIMEOUT, report to user
+
+### Important Rules
+- Each Agent() = new process = fresh context
+- YOU track iteration count
+- Write `status.json` after each iteration
+- Worker claim ≠ complete. Only YOU write COMPLETE sentinel after verifier pass.
+
+---
+
+## `status <slug>`
+Read `.claude/ralph-desk/logs/<slug>/status.json` and display.
+
+## `logs <slug> [N]`
+- No N: show latest `iter-*.worker-prompt.md` summary
+- With N: read `iter-N.worker-prompt.md` and `iter-N.verifier-prompt.md`
+
+## `clean <slug>`
+Remove:
+- `.claude/ralph-desk/memos/<slug>-complete.md`
+- `.claude/ralph-desk/memos/<slug>-blocked.md`
+- `.claude/ralph-desk/memos/<slug>-done-claim.json`
+- `.claude/ralph-desk/memos/<slug>-verify-verdict.json`
+- `.claude/ralph-desk/logs/<slug>/circuit-breaker.json`
+
+## No args or `help`
+```
+/rlp-desk brainstorm <description>     Plan before init (interactive)
+/rlp-desk init  <slug> [objective]     Create project scaffold
+/rlp-desk run   <slug> [--opts]        Run loop (this session = leader)
+/rlp-desk status <slug>                Show loop status
+/rlp-desk logs  <slug> [N]             Show iteration log
+/rlp-desk clean <slug>                 Reset for re-run
+```
+
+## Architecture
+```
+[This session = LEADER]
+        │
+  Agent()├──▶ [Worker: executor (fresh context)]
+        │     └── reads desk files, implements, updates memory
+        │
+  Agent()└──▶ [Verifier: executor (fresh context)]
+              └── reads done-claim, runs checks, writes verdict
+```

package/src/governance.md

@@ -0,0 +1,170 @@
+# Ralph Desk Governance v2
+
+Fresh-context independent verification protocol.
+The Leader orchestrates, while Worker/Verifier run in isolated fresh contexts every iteration.
+
+---
+
+## 1. Core Principles
+
+- **Fresh context per iteration**: Worker/Verifier start fresh every time. No prior conversation.
+- **Filesystem = memory**: State exists only on the filesystem (PRD, memory, context, memos).
+- **Worker claim ≠ complete**: A Worker's DONE is merely a claim. The Verifier must independently verify before it's confirmed.
+- **Verifier is independent**: The Verifier judges based on evidence alone, without knowledge of the Worker's reasoning process.
+- **Sentinels are Leader-owned**: Only the Leader writes COMPLETE/BLOCKED sentinels.
+- **Claude models only**: haiku, sonnet, opus.
+
+## 2. Roles
+
+### Leader (current session)
+- Operates the loop, selects models, controls flow
+- Dispatches Worker/Verifier via Agent()
+- Reads memory to assess state, writes sentinels
+- **Does NOT write or execute code**
+
+### Worker (fresh context)
+- Performs one bounded action per iteration
+- Updates context and memory (so the next fresh worker can continue)
+- Writes done-claim.json when claiming completion
+
+### Verifier (fresh context)
+- Independently verifies Worker's done claim
+- Runs commands directly to collect fresh evidence
+- Writes verdict (pass/fail/blocked)
+- **Must NEVER modify code**
+
+## 3. State Flow
+
+```
+RUNNING → DONE_CLAIMED → VERIFYING → COMPLETE | CONTINUE | BLOCKED
+```
+
+## 4. Model Routing (Claude only)
+
+| Role | Default Model | Override Criteria |
+|------|---------------|-------------------|
+| Worker (simple) | haiku | Single file, clear change |
+| Worker (standard) | sonnet | Most tasks (default) |
+| Worker (complex) | opus | Architecture changes, multi-file, prior iteration failure |
+| Verifier | sonnet | Sufficient for most cases |
+| Verifier (strict) | opus | Security/critical logic verification |
+
+The Leader decides each iteration. Decision criteria:
+- Previous iteration failed → upgrade model
+- Simple repetitive task → downgrade model
+- User explicitly specified → use as given
+
+## 5. Execution: Unified Agent() Approach
+
+All environments (Claude Code, OpenCode) use the same Agent tool.
+
+```
+# Worker
+Agent(
+  subagent_type="executor",
+  model="sonnet",
+  prompt=worker_prompt,
+  mode="bypassPermissions"
+)
+
+# Verifier
+Agent(
+  subagent_type="executor",
+  model="sonnet",
+  prompt=verifier_prompt,
+  mode="bypassPermissions"
+)
+```
+
+Characteristics:
+- Each call = fresh context (new subprocess)
+- Synchronous return. No polling or signal files needed.
+- After Agent completes, read memory.md to assess state.
+- No tmux required.
+- Monitor in real-time via ctrl+o (Claude Code UI).
+- Prompts are still logged to logs/ for audit trail.
+
+## 6. File Structure
+
+### User-level (central)
+```
+~/.claude/ralph-desk/
+├── init_ralph_desk.zsh        # Scaffold generator (automation)
+├── governance.md              # This document
+└── templates/                 # Prompt templates
+```
+
+### Project-local
+```
+.claude/ralph-desk/
+├── prompts/
+│   ├── <slug>.worker.prompt.md      # Worker base prompt
+│   └── <slug>.verifier.prompt.md    # Verifier base prompt
+├── context/
+│   └── <slug>-latest.md             # Current frontier (Worker updates)
+├── memos/
+│   ├── <slug>-memory.md             # Campaign memory (Worker updates)
+│   ├── <slug>-done-claim.json       # Worker's completion claim (runtime)
+│   ├── <slug>-verify-verdict.json   # Verifier's verdict (runtime)
+│   ├── <slug>-complete.md           # SENTINEL (Leader only)
+│   └── <slug>-blocked.md            # SENTINEL (Leader only)
+├── plans/
+│   ├── prd-<slug>.md                # PRD (shared contract)
+│   └── test-spec-<slug>.md          # Verification criteria
+└── logs/<slug>/
+    ├── iter-NNN.worker-prompt.md    # Audit trail prompt copy
+    ├── iter-NNN.verifier-prompt.md  # Audit trail prompt copy
+    └── status.json                  # Leader's loop state
+```
+
+## 7. Leader Loop Protocol
+
+```
+for iteration in 1..max_iter:
+
+  ① Check sentinels
+     - complete.md exists → stop
+     - blocked.md exists → stop
+
+  ② Read memory.md → check Stop Status, Next Iteration Contract
+
+  ③ Select model
+     - Default or situational decision (see §4)
+     - Context unchanged for 3 consecutive iterations → BLOCKED
+
+  ④ Build Worker prompt
+     - Base prompt + iteration number + contract from memory
+     - Log to logs/<slug>/iter-NNN.worker-prompt.md
+
+  ⑤ Execute Worker: Agent(subagent_type="executor", model=selected, prompt=prompt)
+     - Synchronous return, wait for completion
+
+  ⑥ Read memory.md again → check Worker's updated state
+     - "continue" → go to ⑧
+     - "verify"   → go to ⑦
+     - "blocked"  → write BLOCKED sentinel, stop
+
+  ⑦ Execute Verifier
+     - Build prompt → log to logs/<slug>/iter-NNN.verifier-prompt.md
+     - Agent(subagent_type="executor", model=selected, prompt=prompt)
+     - Read verify-verdict.json:
+       • pass + complete → write COMPLETE sentinel, stop
+       • fail + continue → go to ⑧
+       • blocked → write BLOCKED sentinel, stop
+
+  ⑧ Update status.json, report to user, continue to next iteration
+```
+
+## 8. Circuit Breaker
+
+| Condition | Verdict |
+|-----------|---------|
+| context-latest.md unchanged for 3 consecutive iterations | BLOCKED |
+| Worker repeats the same error twice | Upgrade model, retry once; if still failing → BLOCKED |
+| max_iter reached | TIMEOUT (report to user) |
+
+## 9. Change Policy
+
+- Changes to the shared workflow → modify this document
+- Project-specific objectives/criteria → modify project-local files
+- Init script changes → modify init_ralph_desk.zsh