@weppy/ralph 0.1.0

package/dist/index.js

@@ -0,0 +1,28 @@
+// src/shared/constants/index.ts
+var packageName = "@weppy/ralph";
+var version = "0.1.0";
+
+// src/cli/catalog/index.ts
+var commandCatalog = [
+  "start",
+  "status",
+  "resume",
+  "cancel",
+  "result",
+  "mcp"
+];
+
+// src/mcp/tools/index.ts
+var mcpToolCatalog = [
+  "start_job",
+  "get_status",
+  "get_result",
+  "resume_job",
+  "cancel_job"
+];
+export {
+  commandCatalog,
+  mcpToolCatalog,
+  packageName,
+  version
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@weppy/ralph",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Independent Ralph orchestrator with CLI and MCP entrypoints.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "bin": {
+    "ralph": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "specs"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "tsc --noEmit",
+    "test": "npm run build && node --test test/**/*.test.mjs",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hope1026/aiagent-plugins",
+    "directory": "ralph-package"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "agent",
+    "orchestrator",
+    "cli",
+    "mcp",
+    "codex",
+    "claude"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.8.0"
+  }
+}

package/specs/00-/352/260/234/354/232/224.md

@@ -0,0 +1,40 @@
+# 개요
+
+이 문서는 `@weppy/ralph`의 목적, 범위, 용어를 정의한다. 구조, 상태 모델, 실행 규칙, 인터페이스 계약의 상세 내용은 다른 문서가 단일 출처로 소유한다.
+
+## 목적
+
+`@weppy/ralph`는 특정 프로젝트 구조나 특정 AI 에이전트 대화 세션에 종속되지 않는 독립 실행 오케스트레이터다. 사용자는 Ralph에 작업 문서와 요구사항을 넘기고, Ralph는 이를 job으로 등록한 뒤 계획 수립, task 분해, 반복 실행, 검증, 재시도, 완료 판정, 최종 결과 정리를 끝까지 담당한다.
+
+## 핵심 목표
+
+- Ralph 자체는 독립 프로세스로 동작한다.
+- 실행 에이전트는 `codex`, `claude-code` 등 adapter로 교체 가능하다.
+- 상태는 대화 컨텍스트가 아니라 파일 기반 저장소에 영속화된다.
+- 기본 상태 저장소는 agent 작업 경로 아래 `.ralph-cache/`이며 필요 시 별도 경로로 override 가능하다.
+- 각 iteration은 fresh context로 실행된다.
+- validation, retry, completion 판정은 Ralph가 직접 수행한다.
+- 사람용 CLI와 상위 agent용 MCP가 같은 core를 공유한다.
+
+## 비목표
+
+- 특정 IDE 플러그인 전용 구현
+- 특정 프로젝트 구조를 전제한 설계
+- 장기 메모리를 LLM 대화창에 의존하는 구조
+- MVP 단계의 병렬 분산 실행기
+- MVP 단계의 원격 큐 또는 멀티 워커
+
+## 용어
+
+- `job`: 사용자가 Ralph에 등록한 전체 작업 단위
+- `phase`: 여러 task를 묶는 상위 실행 단계
+- `task`: 한 iteration에서 하나의 에이전트에게 맡기는 최소 실행 단위
+- `run`: 한 번의 에이전트 실행과 그 결과물
+- `validation`: Ralph가 직접 수행하는 검증 단계
+- `adapter`: 특정 에이전트 CLI와 Ralph core 사이를 연결하는 실행 계층
+
+## 문서 맵
+
+- 전체 구조와 실행 계층은 [아키텍처](./10-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98.md)에서 정의한다.
+- 상태 저장 구조와 iteration 규칙은 [상태와 실행](./20-%EC%83%81%ED%83%9C%EC%99%80-%EC%8B%A4%ED%96%89.md)에서 정의한다.
+- CLI, MCP, adapter, result contract는 [인터페이스](./30-%EC%9D%B8%ED%84%B0%ED%8E%98%EC%9D%B4%EC%8A%A4.md)에서 정의한다.

package/specs/10-/354/225/204/355/202/244/355/205/215/354/262/230.md

@@ -0,0 +1,89 @@
+# 아키텍처
+
+이 문서는 `@weppy/ralph`의 전체 구조와 각 계층의 책임을 정의한다. 상태 파일 구조나 상태 전이 규칙은 여기서 반복하지 않고 [상태와 실행](./20-%EC%83%81%ED%83%9C%EC%99%80-%EC%8B%A4%ED%96%89.md)을 단일 출처로 참조한다.
+
+## 최상위 구조
+
+`@weppy/ralph`는 하나의 독립 패키지 안에 core와 두 개의 access layer를 포함한다.
+
+- CLI: 사람이 직접 호출하거나 상위 자동화가 shell command로 사용할 수 있는 인터페이스
+- MCP: Codex, Claude 같은 상위 AI agent가 구조화된 tool 호출로 사용할 수 있는 인터페이스
+
+두 인터페이스는 공통 core를 공유하며, 상태 판정 규칙이나 validation 로직을 별도로 구현하지 않는다.
+
+## src 구조 원칙
+
+`src/`는 레이어보다 기능 기준으로 구분한다.
+
+- `shared/`: 여러 기능이 공통으로 사용하는 타입, 상수, 에러, 유틸
+- `job/`: job 생성, 로드, 상태 조회, 취소, 재개
+- `planning/`: 입력 정규화, planning prompt, plan 파싱, dependency 생성
+- `execution/`: next task 선택, iteration 실행, retry, completion 판정
+- `validation/`: command, file, custom validation과 phase gate 계산
+- `adapters/`: 에이전트별 adapter 구현과 공통 실행 계약
+- `state/`: 파일 시스템 저장소, atomic write, run artifact 관리
+- `reporting/`: final summary, user checks, blocked report, handoff
+- `cli/`: CLI 진입점과 command handler
+- `mcp/`: MCP 서버와 tool handler
+
+## 책임 분리
+
+### Core
+
+Core는 다음 기능을 소유한다.
+
+- job lifecycle 관리
+- plan과 task graph 생성
+- iteration orchestration
+- validation 실행
+- retry와 blocked 전환
+- completion 판정
+- 최종 결과 문서 생성
+
+### State Storage
+
+- 기본 상태 저장소 root는 agent 작업 경로인 `workspacePath` 아래의 `.ralph-cache/`다.
+- 호출자는 CLI 또는 MCP 입력 파라미터로 상태 저장소 root를 override할 수 있다.
+- core는 항상 resolved absolute state path를 기준으로 상태 파일을 읽고 써야 한다.
+- 입력 reference는 path metadata로 저장하며, 원본 파일 내용을 상태 저장소나 실행 프롬프트에 복사하지 않는다.
+
+### Access Layer
+
+CLI와 MCP는 core를 호출하는 얇은 계층이어야 한다.
+
+- CLI는 사람이 읽기 쉬운 출력과 JSON 출력 모드를 제공한다.
+- MCP는 구조화된 DTO만 반환한다.
+- CLI와 MCP는 상태 파일을 직접 수정하지 않는다.
+
+### Adapter Layer
+
+Adapter는 에이전트별 프로세스 실행 차이만 처리한다.
+
+- prompt 조립 입력값 수신
+- CLI 프로세스 실행
+- stdout/stderr 수집
+- 결과 파일 경로 전달
+- 에러 정규화
+- 입력 file/image path reference 전달
+
+Adapter 계약 상세는 [인터페이스](./30-%EC%9D%B8%ED%84%B0%ED%8E%98%EC%9D%B4%EC%8A%A4.md)를 따른다.
+
+## 실행 흐름
+
+1. 사용자가 CLI 또는 MCP로 job을 시작한다.
+2. Ralph가 입력 문서를 정규화하고 plan과 task graph를 만든다.
+3. Ralph가 현재 실행 가능한 최소 task를 고른다.
+4. Ralph가 실행 시작 전에 `running` 상태와 run placeholder artifact를 먼저 기록한다.
+5. Ralph가 선택된 adapter로 에이전트를 fresh context에서 한 번 실행한다.
+6. Ralph가 `result.json`을 읽고 validation을 수행한다.
+7. Ralph가 task 완료, retry, follow-up task 생성, blocked 전환 중 하나를 결정한다.
+8. 모든 phase gate가 통과하면 최종 summary를 생성하고 job을 완료한다.
+
+상세 상태 전이와 iteration 규칙은 [상태와 실행](./20-%EC%83%81%ED%83%9C%EC%99%80-%EC%8B%A4%ED%96%89.md)을 따른다.
+
+## 배포 원칙
+
+- 패키지명은 `@weppy/ralph`
+- CLI 엔트리는 `ralph`
+- MCP는 같은 패키지 내부에서 `ralph mcp` 또는 내부 bootstrap 모듈로 제공한다
+- 배포는 npm public registry를 기준으로 한다

package/specs/20-/354/203/201/355/203/234/354/231/200-/354/213/244/355/226/211.md

@@ -0,0 +1,161 @@
+# 상태와 실행
+
+이 문서는 `.ralph-cache/` 기본 상태 저장 구조, 핵심 persisted file, 상태 전이, iteration loop, validation 및 completion 규칙의 단일 출처다.
+
+## 상태 저장 위치
+
+- 기본 상태 저장소 root는 `workspacePath/.ralph-cache`다.
+- `workspacePath`는 Ralph가 adapter를 통해 AI agent를 실행하고 validation을 수행하는 작업 경로다.
+- 호출자는 CLI `--state-dir <path>` 또는 MCP의 동등한 입력 필드로 상태 저장소 root를 override할 수 있다.
+- override가 있으면 아래 구조는 override된 directory를 root로 사용한다.
+
+## 상태 저장 구조
+
+```text
+.ralph-cache/
+├── current-job.txt
+└── jobs/
+    └── {job-id}/
+        ├── job.json
+        ├── inputs.json
+        ├── spec.md
+        ├── plan.md
+        ├── tasks.json
+        ├── runtime.json
+        ├── final-summary.md
+        ├── user-checks.md
+        ├── validations/
+        │   └── validation-*.json
+        ├── runs/
+        │   └── run-001/
+        │       ├── prompt.md
+        │       ├── result.json
+        │       ├── run-record.json
+        │       ├── stdout.log
+        │       └── stderr.log
+        └── artifacts/
+```
+
+## 핵심 파일
+
+### `job.json`
+
+- `id`
+- `title`
+- `requestedAgent`
+- `status`
+- `workspacePath`
+- `stateDirectoryPath`
+- `inputDocuments`
+- `validationProfile`
+- `retryPolicy`
+- `createdAt`
+- `updatedAt`
+
+### `inputs.json`
+
+- `path`
+- `kind`
+- Ralph가 agent에게 직접 열어보라고 전달할 입력 reference 목록
+- 입력 파일의 본문이나 이미지 binary를 복사해 저장하지 않는다
+
+### `tasks.json`
+
+- `phases`
+- `tasks`
+- `dependencies`
+- `retryCounts`
+- `evidenceLinks`
+- `phaseGateStatus`
+
+### `runtime.json`
+
+- `currentPhaseId`
+- `currentTaskId`
+- `remainingTaskCount`
+- `lastRunId`
+- `nextAction`
+- `blockedReason`
+- `lastValidationStatus`
+
+### run artifact 규칙
+
+- `result.json`은 agent가 반환한 구조화된 결과 계약만 저장한다.
+- `run-record.json`은 Ralph가 계산한 run 메타데이터, exit code, signal, error code를 저장한다.
+- `stdout.log`, `stderr.log`는 adapter process의 raw output을 저장한다.
+- agent 실행 직전 `run-record.json`, `stdout.log`, `stderr.log`, `prompt.md`는 placeholder를 먼저 기록한다.
+
+## 상태 전이 원칙
+
+### Job 상태
+
+- `draft`
+- `planned`
+- `running`
+- `blocked`
+- `completed`
+- `failed`
+- `cancelled`
+
+### Task 상태
+
+- `pending`
+- `running`
+- `completed`
+- `partial`
+- `blocked`
+- `failed`
+- `cancelled`
+
+### Phase Gate 상태
+
+- `pending`
+- `failed`
+- `passed`
+
+## Iteration Loop
+
+각 iteration은 짧고 독립적이어야 한다.
+
+1. Ralph가 현재 상태를 로드한다.
+2. 현재 phase에서 실행 가능한 next task를 선택한다.
+3. agent 실행 전에 job과 current task를 `running`으로 기록하고 `runs/run-xxx/` placeholder artifact를 먼저 생성한다.
+4. adapter를 통해 에이전트를 fresh context로 1회 실행한다.
+5. `runs/run-xxx/result.json`을 읽는다.
+6. Ralph가 validation을 실행한다.
+7. validation 결과와 run 결과를 반영해 task 상태를 갱신한다.
+8. 남은 task가 있으면 다음 iteration으로 이동한다.
+9. 더 진행할 수 없으면 `blocked`, 모두 충족되면 `completed`로 종료한다.
+
+## Validation 소유권
+
+Validation은 Ralph 소유다.
+
+- 에이전트는 validation hint만 남길 수 있다.
+- 실제 `build`, `test`, `lint`, file check, custom script 실행은 Ralph가 수행한다.
+- 에이전트가 자연어로 완료를 선언해도 validation 실패 시 완료로 처리하지 않는다.
+
+## Retry 규칙
+
+- 결과 파일이 없으면 iteration 실패로 간주한다.
+- `partial` 결과는 follow-up task 또는 retry 판단 대상이다.
+- `blocked` 결과는 blocker reason이 필수다.
+- 동일 task의 retry 횟수가 한도를 넘으면 job 또는 task는 `blocked` 또는 `failed`로 전환된다.
+
+## Completion 규칙
+
+다음 조건이 모두 충족될 때만 job을 완료 처리한다.
+
+- 모든 필수 task가 `completed`
+- 현재 phase gate가 모두 `passed`
+- 필수 validation이 성공
+- 남은 blocker가 없음
+
+## 파일 쓰기 규칙
+
+- JSON 파일은 atomic write를 사용한다.
+- 중간 실패 후에도 기존 유효 상태를 복구할 수 있어야 한다.
+- 각 run artifact는 iteration별로 분리 저장한다.
+- `--input`으로 받은 파일이나 이미지의 내용은 프롬프트 본문에 인라인하지 않고 path reference로만 전달한다.
+
+실행 인터페이스와 `result.json` 계약은 [인터페이스](./30-%EC%9D%B8%ED%84%B0%ED%8E%98%EC%9D%B4%EC%8A%A4.md)에서 정의한다.

package/specs/30-/354/235/270/355/204/260/355/216/230/354/235/264/354/212/244.md

@@ -0,0 +1,137 @@
+# 인터페이스
+
+이 문서는 adapter contract, `result.json` contract, CLI contract, MCP contract의 단일 출처다. 아키텍처 개요는 [아키텍처](./10-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98.md), 상태 전이와 저장 구조는 [상태와 실행](./20-%EC%83%81%ED%83%9C%EC%99%80-%EC%8B%A4%ED%96%89.md)을 참조한다.
+
+## Result Contract
+
+에이전트는 자연어 선언 대신 구조화된 `result.json`을 남겨야 한다.
+
+```json
+{
+  "status": "completed",
+  "task_id": "TASK-003",
+  "summary": "Implemented retry-safe task runner",
+  "changed_files": [
+    "src/execution/run-iteration/index.ts"
+  ],
+  "artifacts": [],
+  "follow_up_tasks": [],
+  "user_checks": [],
+  "validation_hints": [],
+  "blockers": []
+}
+```
+
+### 허용 상태
+
+- `completed`
+- `partial`
+- `blocked`
+- `failed`
+
+### 규칙
+
+- `completed`라도 Ralph validation이 실패하면 실제 완료가 아니다.
+- `blocked`면 blocker reason이 필요하다.
+- 결과 JSON이 없으면 malformed result로 간주한다.
+
+## Adapter Contract
+
+각 adapter는 최소 다음 기능을 제공해야 한다.
+
+- `preparePrompt(context)`
+- `execute(runContext)`
+- `normalizeError(error)`
+
+### 표준 에러 분류
+
+- `timeout`
+- `cli_missing`
+- `auth_required`
+- `malformed_result`
+- `execution_failed`
+
+### 초기 adapter 범위
+
+- `codex`
+- `claude-code`
+- `custom-command`
+
+### 현재 실행 방식
+
+- `codex` adapter는 `codex exec`를 사용한다.
+- `claude-code` adapter는 `claude -p`를 사용한다.
+- `custom-command` adapter는 `RALPH_CUSTOM_AGENT_COMMAND` shell command를 실행한다.
+- `custom-command`는 `RALPH_OUTPUT_PATH`에 `result.json` 계약을 만족하는 JSON을 기록해야 한다.
+- adapter prompt는 입력 파일의 내용 복사본 대신 absolute path reference를 포함해야 한다.
+- 이미지 입력도 설명문으로 변환하지 않고 path reference로 넘기고 agent가 직접 확인해야 한다.
+
+## CLI Contract
+
+초기 CLI command는 다음과 같다.
+
+- `ralph start`
+- `ralph status`
+- `ralph resume`
+- `ralph cancel`
+- `ralph result`
+- `ralph mcp`
+
+### 공통 입력 규칙
+
+- `--workspace <path>`: Ralph가 AI agent 실행과 validation의 working directory로 사용하는 작업 경로. `start`에서 필수, 나머지에서는 `--state-dir`와 둘 중 하나 필수
+- `--state-dir <path>`: 상태 저장소 root override. 생략 시 기본값은 `{workspacePath}/.ralph-cache`
+- `--job <id>`: 대상 job ID. 생략 시 `current-job.txt`에 기록된 현재 job을 사용한다
+- `--input <path>`: agent가 직접 확인할 입력 file/image/directory reference. Ralph는 path metadata만 저장하고 본문은 프롬프트에 인라인하지 않는다. `start`에서만 사용
+- `--validate-cmd <command>`: validation 단계에서 workspace 기준으로 실행할 shell command. repeatable. `start`에서만 사용
+- `--max-retries <n>`: task별 최대 retry 횟수. `start`에서만 사용
+- `--max-iterations <n>`: `resume` 한 번 호출에서 실행할 최대 iteration 수. `resume`에서만 사용
+- `--json`: JSON 형식으로 출력. 모든 커맨드에서 사용 가능
+
+### 예시
+
+```bash
+ralph start --title "Implement auth flow" --agent codex --workspace /path/to/project --input docs/spec.md
+ralph start --title "Implement auth flow" --agent codex --workspace /path/to/project --state-dir /tmp/ralph-auth-cache --input docs/spec.md
+ralph start --title "Implement auth flow" --agent custom-command --workspace /path/to/project --validate-cmd "npm test" --max-retries 2
+ralph status --workspace /path/to/project --job job-20260307-auth
+ralph resume --workspace /path/to/project --job job-20260307-auth --max-iterations 5
+ralph result --workspace /path/to/project --job job-20260307-auth
+ralph cancel --workspace /path/to/project --job job-20260307-auth
+ralph status --state-dir /tmp/ralph-auth-cache
+ralph mcp
+```
+
+## MCP Contract
+
+MCP는 CLI와 다른 접근 계층이지만 같은 core를 사용한다.
+
+### 초기 tool 범위
+
+- `start_job`
+- `get_status`
+- `get_result`
+- `resume_job`
+- `cancel_job`
+
+### 입력 규칙
+
+- `start_job`은 `workspace_path`를 필수로 받고 `state_dir`를 optional로 받을 수 있다.
+- `get_status`, `get_result`, `resume_job`, `cancel_job`은 `workspace_path` 또는 `state_dir` 중 최소 하나를 필수로 받는다.
+- `state_dir`가 없으면 기본 상태 저장소는 `{workspace_path}/.ralph-cache`다.
+- `job_id`는 모든 조회/실행 tool에서 optional이며, 생략 시 `current-job.txt`의 현재 job을 사용한다.
+- `validation_commands`는 repeatable shell validation command 목록이다.
+- `max_retries_per_task`와 `max_iterations`를 각각 `start_job`, `resume_job`에서 받을 수 있다.
+
+### 설계 원칙
+
+- MCP tool은 thin wrapper여야 한다.
+- core를 직접 호출해야 하며 CLI subprocess를 재호출하지 않는다.
+- 반환값은 항상 구조화된 DTO여야 한다.
+- polling 기반 상태 조회를 기본으로 한다.
+
+## CLI와 MCP의 관계
+
+- CLI와 MCP는 같은 job 상태 저장소를 읽고 쓴다.
+- validation, retry, completion 판정은 공통 core가 수행한다.
+- 출력 형식만 다르고 실행 규칙은 동일하다.