@daonhan/ralph-core 0.1.0

package/Dockerfile

@@ -0,0 +1,49 @@
+FROM node:22-bookworm
+
+# System dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    jq \
+    wget \
+    ca-certificates \
+    gnupg \
+  && rm -rf /var/lib/apt/lists/*
+
+# .NET SDK 9 (Microsoft package feed for Debian 12 / Bookworm)
+RUN wget -qO /tmp/ms.deb https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb \
+  && dpkg -i /tmp/ms.deb \
+  && rm /tmp/ms.deb \
+  && apt-get update \
+  && apt-get install -y dotnet-sdk-9.0 \
+  && rm -rf /var/lib/apt/lists/*
+
+# GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+    | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+    | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+  && apt-get update \
+  && apt-get install -y gh \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN corepack enable
+
+# Rename the base image's "node" user (UID 1000) to "agent".
+# Keeps UID 1000 so --user 1000:1000 maps to the right home dir owner.
+RUN usermod -d /home/agent -m -l agent node
+USER agent
+
+# Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+ENV PATH="/home/agent/.local/bin:$PATH" \
+    DOTNET_CLI_TELEMETRY_OPTOUT=1 \
+    DOTNET_NOLOGO=1
+
+# main.ts bind-mounts the host workspace at /home/agent/workspace.
+WORKDIR /home/agent/workspace
+
+# Reset ENTRYPOINT so the orchestrator can pass a full `claude ...` argv.
+ENTRYPOINT []
+CMD ["claude"]

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@daonhan/ralph-core",
+  "version": "0.1.0",
+  "description": "Claude Code AFK orchestration: iteration loop, docker runner, template renderer.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./loop": {
+      "types": "./dist/loop.d.ts",
+      "import": "./dist/loop.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "import": "./dist/runner.js"
+    },
+    "./stages": {
+      "types": "./dist/stages.d.ts",
+      "import": "./dist/stages.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "Dockerfile",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/templates/afk.md

@@ -0,0 +1,13 @@
+<commits>
+
+!?`git log -n 5 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<inputs>
+
+{{ INPUTS }}
+
+</inputs>
+
+@include:prompt.md

package/templates/ghafk.md

@@ -0,0 +1,13 @@
+<commits>
+
+!?`git log -n 5 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<issues>
+
+!?`gh issue list --state open --json number,title,body,comments|||[]`
+
+</issues>
+
+@include:ghprompt.md

package/templates/ghprompt.md

@@ -0,0 +1,67 @@
+# ISSUES
+
+GitHub issues are provided at start of context. Parse it to get open issues with their bodies and comments.
+
+You will work on the AFK issues only, not the HITL ones.
+
+You've also been passed a file containing the last few commits. Review these to understand what work has been done.
+
+If all AFK tasks are complete, output <promise>NO MORE TASKS</promise>.
+
+# TASK SELECTION
+
+Pick the next task. Prioritize tasks in this order:
+
+1. Critical bugfixes
+2. Development infrastructure
+
+Getting development infrastructure like tests and types and dev scripts ready is an important precursor to building features.
+
+3. Tracer bullets for new features
+
+Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.
+
+TL;DR - build a tiny, end-to-end slice of the feature first, then expand it out.
+
+4. Polish and quick wins
+5. Refactors
+
+# EXPLORATION
+
+Explore the repo.
+
+# IMPLEMENTATION
+
+Complete the task.
+
+# FEEDBACK LOOPS
+
+Before committing, run the feedback loops:
+
+### Frontend / Node
+
+- `pnpm run test` to run the tests
+- `pnpm run typecheck` to run the type checker
+
+### Backend / Dotnet
+
+- `dotnet test` to run the tests
+- `dotnet build` to type-check
+
+# COMMIT
+
+Make a single `git commit -am` with a short message:
+
+- Subject line (≤72 chars): what changed
+- Optional body (≤3 bullets): key decision, blocker for next iteration
+- No file lists (git tracks them), no `Co-Authored-By`
+
+# THE ISSUE
+
+If the task is complete, close the original GitHub issue.
+
+If the task is not complete, leave a comment on the GitHub issue with what was done.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

package/templates/prompt.md

@@ -0,0 +1,80 @@
+# ISSUES
+
+GitHub issues are provided at start of context. Parse it to get open issues with their bodies and comments.
+
+You will work on the AFK issues only, not the HITL ones.
+
+You've also been passed a file containing the last few commits. Review these to understand what work has been done.
+
+If all AFK tasks are complete, output <promise>NO MORE TASKS</promise>.
+
+# TASK SELECTION
+
+Pick the next task. Prioritize tasks in this order:
+
+1. Critical bugfixes
+2. Development infrastructure
+
+Getting development infrastructure like tests and types and dev scripts ready is an important precursor to building features.
+
+3. Tracer bullets for new features
+
+Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.
+
+TL;DR - build a tiny, end-to-end slice of the feature first, then expand it out.
+
+4. Polish and quick wins
+5. Refactors
+
+# EXPLORATION
+
+Explore the repo.
+
+# IMPLEMENTATION
+
+Complete the task.
+
+# FEEDBACK LOOPS
+
+Before committing, run the feedback loops:
+
+### Frontend / Node
+
+- `pnpm run test` to run the tests
+- `pnpm run typecheck` to run the type checker
+
+### Backend / Dotnet
+
+- `dotnet test` to run the tests
+- `dotnet build` to type-check
+
+**If `dotnet test` or `dotnet build` fails with MSB3248** ("Could not resolve assembly reference" / "file is corrupt") — this is a known virtiofs/9p I/O quirk when the repo is mounted from the Windows host. It is NOT a code defect. Do not defer verification. Re-run with build outputs redirected to `/tmp` and parallelism disabled:
+
+```bash
+dotnet test <path-to-test-csproj> \
+  -m:1 \
+  /p:UseSharedCompilation=false \
+  /p:BuildInParallel=false \
+  /p:BaseIntermediateOutputPath=/tmp/ralph-obj/$(basename <path-to-test-csproj> .csproj)/ \
+  /p:BaseOutputPath=/tmp/ralph-bin/$(basename <path-to-test-csproj> .csproj)/
+```
+
+Only if that second attempt also fails may you defer and record the blocker in the commit message.
+
+# COMMIT
+
+Make a single `git commit -am` with a short message:
+
+- Subject line (≤72 chars): what changed
+- Optional body (≤3 bullets): key decision, blocker for next iteration
+- No file lists (git tracks them), no `Co-Authored-By`
+
+# THE ISSUE
+
+If the task is complete, close the original GitHub issue.
+
+If the task is not complete, leave a comment on the GitHub issue with what was done.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

package/templates/review.md

@@ -0,0 +1,51 @@
+<head>
+
+!?`git rev-parse HEAD|||(no commits)`
+
+</head>
+
+<recent-commits>
+
+!?`git log -n 3 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</recent-commits>
+
+<latest-diff>
+
+!?`git show --stat HEAD|||No diff`
+
+!?`git show HEAD | head -c 200000|||No diff body`
+
+</latest-diff>
+
+# REVIEWER
+
+You review the most recent commit (HEAD) produced by the implementer.
+
+If `<head>` shows `(no commits)` or HEAD is unchanged from the previous iteration, output `<review>SKIP</review>` and stop without making any commit.
+
+# CHECK
+
+1. Bugs and regressions
+2. Test coverage gaps for the changed code
+3. Style violations vs `CLAUDE.md` or project conventions
+4. Security issues (input validation, secrets, injection, auth bypass)
+5. Half-finished implementations, dead code, leftover TODO from this commit
+
+# ACTION
+
+If defects found:
+- Fix them directly in the working tree.
+- Run feedback loops:
+  - Frontend / Node: `pnpm run test`, `pnpm run typecheck`
+  - Backend / Dotnet: `dotnet test`, `dotnet build` (apply MSB3248 workaround from the implementer playbook if it triggers)
+- Commit with `git commit -am "fix(review): <short reason>"`. Subject ≤72 chars. No `Co-Authored-By` line. No file lists.
+
+If clean: output `<review>OK</review>` and stop. Do NOT commit.
+
+# RULES
+
+- Only review the latest commit. Do not touch unrelated code.
+- Do not add new features or refactor beyond the defect fix.
+- Never amend the implementer's commit — always a new `fix(review):` commit.
+- Single review pass. Do not loop.