ralphy-spec 0.1.0 → 0.1.1

package/README.ja.md

@@ -0,0 +1,182 @@
+# ralphy-spec
+
+[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
+以下のツール向けに **Ralph ループ + OpenSpec** ワークフローを1つのコマンドでセットアップ：
+- Cursor
+- OpenCode
+- Claude Code
+
+**ウェブサイト:** [https://ralphy-spec.org](https://ralphy-spec.org)
+
+## Ralphy-Specとは？
+
+Ralphy-Specは2つの強力なAI開発方法論を組み合わせています：
+
+### Ralph Wiggumループ
+
+Ralph方法論（[Geoffrey Huntley](https://ghuntley.com/ralph)が提唱）は、AIエージェントがタスクを完了するまで**同じプロンプトを繰り返し**受け取る開発アプローチです。各イテレーションで、AIはファイルとgit履歴で以前の作業を確認し、自己修正フィードバックループを形成します。
+
+```
+while true; do
+  ai_agent "機能Xを構築してください。完了したら<promise>DONE</promise>を出力してください。"
+  # AIは以前の作業を見て、ミスを修正し、進捗を続けます
+done
+```
+
+### OpenSpec（スペック駆動開発）
+
+[OpenSpec](https://github.com/Fission-AI/OpenSpec)は、コードの前にスペックを要求することでAIコーディングに構造をもたらします：
+- `openspec/specs/` - 真実の情報源となるスペック
+- `openspec/changes/` - 受け入れ基準を含む変更提案
+- 完了した変更をマージするアーカイブワークフロー
+
+### なぜ組み合わせるのか？
+
+| 問題 | 解決策 |
+|------|--------|
+| チャット履歴の曖昧な要件 | OpenSpecが意図を構造化されたスペックに固定 |
+| AIが途中で停止したりミスをする | Ralphループが完了するまでリトライ |
+| 正確性を検証する方法がない | 受け入れ基準 + テストで出力を検証 |
+| ツール固有のセットアップが面倒 | 1つのコマンドでCursor、OpenCode、Claude Codeをセットアップ |
+
+## プロジェクトにインストールされるもの
+
+- `openspec/` スキャフォールド：
+  - `openspec/specs/`（真実の情報源）
+  - `openspec/changes/`（アクティブな変更）
+  - `openspec/archive/`（完了した変更）
+  - `openspec/project.md`（プロジェクトコンテキスト）
+- ツール統合：
+  - Cursor: `.cursor/prompts/ralphy-*.md`
+  - Claude Code: `.claude/commands/ralphy-*.md`
+  - OpenCode: `AGENTS.md`
+- Ralphループ状態/設定：
+  - `.ralphy/config.json`
+  - `.ralphy/ralph-loop.state.json`
+
+## インストール
+
+### npm（グローバル）
+
+```bash
+npm install -g ralphy-spec
+```
+
+### npx（インストール不要）
+
+```bash
+npx ralphy-spec init
+```
+
+### curlインストールスクリプト
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
+```
+
+## 使用方法
+
+### プロジェクトで初期化
+
+```bash
+cd your-project
+ralphy-spec init
+```
+
+非対話的なツール選択：
+
+```bash
+ralphy-spec init --tools cursor,claude-code,opencode
+```
+
+既存ファイルの上書き：
+
+```bash
+ralphy-spec init --force
+```
+
+### セットアップの検証
+
+```bash
+ralphy-spec validate
+```
+
+### テンプレートの更新
+
+```bash
+ralphy-spec update --force
+```
+
+## ワークフロー（PRD -> リリース）
+
+```
+PRD/要件 --> OpenSpec（スペック + タスク + 受け入れ基準）
+                    |
+                    v
+              Ralphループ（テストが通るまで反復）
+                    |
+                    v
+              アーカイブ（ソーススペックにマージ）
+```
+
+### 1) 計画：PRD -> OpenSpec変更
+
+AIツールで`/ralphy:plan`（Cursor / Claude Code）を使用するか、OpenCodeに`AGENTS.md`に従うよう依頼します。
+
+リポジトリでの期待される出力：
+
+```
+openspec/changes/<change-name>/
+  proposal.md
+  tasks.md
+  specs/
+    <domain>/
+      spec.md
+```
+
+### 2) 実装：完了するまで反復
+
+`/ralphy:implement`を使用してタスクを実装し、テストを追加します。
+
+Ralphループランナーで実行する場合、エージェントは**すべてのタスクが完了しテストが通った場合のみ**以下を出力します：
+
+```
+<promise>TASK_COMPLETE</promise>
+```
+
+### 3) 検証：テストで受け入れ基準を証明
+
+`/ralphy:validate`を使用してテストを実行し、通過したテストをOpenSpecシナリオにマッピングします。
+
+### 4) アーカイブ：変更をスペックにマージ
+
+`/ralphy:archive`を使用し、利用可能であればOpenSpec CLIを使用します：
+
+```bash
+openspec archive <change-name> --yes
+```
+
+## 謝辞
+
+Ralphy-Specは巨人の肩の上に立っています：
+
+- **Ralph Wiggum方法論** - [Geoffrey Huntley](https://ghuntley.com/ralph)が考案。AIエージェントが反復を通じて自己修正できるという洞察は、AI支援開発についての私たちの考え方を変えました。
+
+- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 私たちの統合アプローチにインスピレーションを与えたOpenCode用のクリーンなRalphループCLI実装。
+
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AIコーディングに構造と予測可能性をもたらすスペック駆動開発フレームワーク。
+
+これらのアプローチを開拓したこれらのプロジェクトとメンテナーに感謝します。
+
+## 開発
+
+```bash
+npm install
+npm run build
+node bin/ralphy-spec.js --help
+```
+
+## ライセンス
+
+BSD-3-Clause

package/README.ko.md

@@ -0,0 +1,182 @@
+# ralphy-spec
+
+[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
+다음 도구를 위한 **Ralph 루프 + OpenSpec** 워크플로우를 한 번의 명령으로 설정:
+- Cursor
+- OpenCode
+- Claude Code
+
+**웹사이트:** [https://ralphy-spec.org](https://ralphy-spec.org)
+
+## Ralphy-Spec이란?
+
+Ralphy-Spec은 두 가지 강력한 AI 개발 방법론을 결합합니다:
+
+### Ralph Wiggum 루프
+
+Ralph 방법론([Geoffrey Huntley](https://ghuntley.com/ralph)가 제안)은 AI 에이전트가 작업을 완료할 때까지 **동일한 프롬프트를 반복적으로** 받는 개발 방식입니다. 각 반복에서 AI는 파일과 git 히스토리에서 이전 작업을 보고 자기 수정 피드백 루프를 형성합니다.
+
+```
+while true; do
+  ai_agent "기능 X를 구축하세요. 완료되면 <promise>DONE</promise>을 출력하세요."
+  # AI가 이전 작업을 보고, 실수를 수정하고, 진행을 계속합니다
+done
+```
+
+### OpenSpec (스펙 기반 개발)
+
+[OpenSpec](https://github.com/Fission-AI/OpenSpec)은 코드 전에 스펙을 요구하여 AI 코딩에 구조를 부여합니다:
+- `openspec/specs/` - 진실의 원천 스펙
+- `openspec/changes/` - 인수 기준이 있는 변경 제안
+- 완료된 변경을 다시 병합하는 아카이브 워크플로우
+
+### 왜 결합하는가?
+
+| 문제 | 해결책 |
+|------|--------|
+| 채팅 기록의 모호한 요구사항 | OpenSpec이 의도를 구조화된 스펙에 고정 |
+| AI가 중간에 멈추거나 실수함 | Ralph 루프가 완료될 때까지 재시도 |
+| 정확성을 검증할 방법 없음 | 인수 기준 + 테스트로 출력 검증 |
+| 도구별 설정이 번거로움 | 한 번의 명령으로 Cursor, OpenCode, Claude Code 설정 |
+
+## 프로젝트에 설치되는 내용
+
+- `openspec/` 스캐폴드:
+  - `openspec/specs/` (진실의 원천)
+  - `openspec/changes/` (활성 변경)
+  - `openspec/archive/` (완료된 변경)
+  - `openspec/project.md` (프로젝트 컨텍스트)
+- 도구 통합:
+  - Cursor: `.cursor/prompts/ralphy-*.md`
+  - Claude Code: `.claude/commands/ralphy-*.md`
+  - OpenCode: `AGENTS.md`
+- Ralph 루프 상태/설정:
+  - `.ralphy/config.json`
+  - `.ralphy/ralph-loop.state.json`
+
+## 설치
+
+### npm (전역)
+
+```bash
+npm install -g ralphy-spec
+```
+
+### npx (설치 없이)
+
+```bash
+npx ralphy-spec init
+```
+
+### curl 설치 스크립트
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
+```
+
+## 사용법
+
+### 프로젝트에서 초기화
+
+```bash
+cd your-project
+ralphy-spec init
+```
+
+비대화형 도구 선택:
+
+```bash
+ralphy-spec init --tools cursor,claude-code,opencode
+```
+
+기존 파일 덮어쓰기:
+
+```bash
+ralphy-spec init --force
+```
+
+### 설정 검증
+
+```bash
+ralphy-spec validate
+```
+
+### 템플릿 업데이트
+
+```bash
+ralphy-spec update --force
+```
+
+## 워크플로우 (PRD -> 출시)
+
+```
+PRD/요구사항 --> OpenSpec (스펙 + 작업 + 인수 기준)
+                      |
+                      v
+                Ralph 루프 (테스트 통과까지 반복)
+                      |
+                      v
+                아카이브 (소스 스펙에 병합)
+```
+
+### 1) 계획: PRD -> OpenSpec 변경
+
+AI 도구에서 `/ralphy:plan` (Cursor / Claude Code)을 사용하거나 OpenCode에 `AGENTS.md`를 따르도록 요청합니다.
+
+저장소에 예상되는 출력:
+
+```
+openspec/changes/<change-name>/
+  proposal.md
+  tasks.md
+  specs/
+    <domain>/
+      spec.md
+```
+
+### 2) 구현: 완료될 때까지 반복
+
+`/ralphy:implement`를 사용하여 작업을 구현하고 테스트를 추가합니다.
+
+Ralph 루프 러너를 통해 실행하는 경우, 에이전트는 **모든 작업이 완료되고 테스트가 통과했을 때만** 다음을 출력해야 합니다:
+
+```
+<promise>TASK_COMPLETE</promise>
+```
+
+### 3) 검증: 테스트로 인수 기준 증명
+
+`/ralphy:validate`를 사용하여 테스트를 실행하고 통과한 테스트를 OpenSpec 시나리오에 매핑합니다.
+
+### 4) 아카이브: 변경을 스펙에 병합
+
+`/ralphy:archive`를 사용하고, 가능하다면 OpenSpec CLI를 사용합니다:
+
+```bash
+openspec archive <change-name> --yes
+```
+
+## 감사의 말
+
+Ralphy-Spec은 거인의 어깨 위에 서 있습니다:
+
+- **Ralph Wiggum 방법론** - [Geoffrey Huntley](https://ghuntley.com/ralph)가 고안. AI 에이전트가 반복을 통해 자기 수정할 수 있다는 통찰력은 AI 지원 개발에 대한 우리의 생각을 바꾸었습니다.
+
+- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 우리의 통합 방식에 영감을 준 OpenCode용 깔끔한 Ralph 루프 CLI 구현.
+
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AI 코딩에 구조와 예측 가능성을 부여하는 스펙 기반 개발 프레임워크.
+
+이러한 접근 방식을 개척한 이 프로젝트들과 유지 관리자들에게 감사드립니다.
+
+## 개발
+
+```bash
+npm install
+npm run build
+node bin/ralphy-spec.js --help
+```
+
+## 라이선스
+
+BSD-3-Clause

package/README.md

@@ -1,5 +1,7 @@
 # ralphy-spec
 
+[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
 One-command setup for **Ralph loop + OpenSpec** workflows across:
 - Cursor
 - OpenCode

package/README.zh.md

@@ -0,0 +1,182 @@
+# ralphy-spec
+
+[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
+
+一条命令为以下工具设置 **Ralph 循环 + OpenSpec** 工作流：
+- Cursor
+- OpenCode
+- Claude Code
+
+**官网：** [https://ralphy-spec.org](https://ralphy-spec.org)
+
+## 什么是 Ralphy-Spec？
+
+Ralphy-Spec 结合了两种强大的 AI 开发方法：
+
+### Ralph Wiggum 循环
+
+Ralph 方法论（由 [Geoffrey Huntley](https://ghuntley.com/ralph) 提出）是一种开发方式，AI 代理会**重复接收相同的提示**直到完成任务。每次迭代，AI 都能看到之前在文件和 git 历史中的工作成果，形成自我纠正的反馈循环。
+
+```
+while true; do
+  ai_agent "构建功能 X。完成后输出 <promise>DONE</promise>。"
+  # AI 看到之前的工作，修复错误，继续进展
+done
+```
+
+### OpenSpec（规范驱动开发）
+
+[OpenSpec](https://github.com/Fission-AI/OpenSpec) 通过在编码前要求规范来为 AI 编码带来结构：
+- `openspec/specs/` - 真实来源的规范
+- `openspec/changes/` - 带验收标准的变更提案
+- 归档工作流将已完成的变更合并回来
+
+### 为什么要结合使用？
+
+| 问题 | 解决方案 |
+|------|----------|
+| 聊天记录中的需求模糊 | OpenSpec 将意图锁定在结构化规范中 |
+| AI 中途停止或出错 | Ralph 循环重试直到完成 |
+| 无法验证正确性 | 验收标准 + 测试验证输出 |
+| 特定工具的设置很繁琐 | 一条命令设置 Cursor、OpenCode、Claude Code |
+
+## 安装到项目中的内容
+
+- `openspec/` 脚手架：
+  - `openspec/specs/`（真实来源）
+  - `openspec/changes/`（活跃变更）
+  - `openspec/archive/`（已完成的变更）
+  - `openspec/project.md`（项目上下文）
+- 工具集成：
+  - Cursor：`.cursor/prompts/ralphy-*.md`
+  - Claude Code：`.claude/commands/ralphy-*.md`
+  - OpenCode：`AGENTS.md`
+- Ralph 循环状态/配置：
+  - `.ralphy/config.json`
+  - `.ralphy/ralph-loop.state.json`
+
+## 安装
+
+### npm（全局安装）
+
+```bash
+npm install -g ralphy-spec
+```
+
+### npx（无需安装）
+
+```bash
+npx ralphy-spec init
+```
+
+### curl 安装脚本
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
+```
+
+## 使用方法
+
+### 在项目中初始化
+
+```bash
+cd your-project
+ralphy-spec init
+```
+
+非交互式工具选择：
+
+```bash
+ralphy-spec init --tools cursor,claude-code,opencode
+```
+
+覆盖现有文件：
+
+```bash
+ralphy-spec init --force
+```
+
+### 验证设置
+
+```bash
+ralphy-spec validate
+```
+
+### 更新模板
+
+```bash
+ralphy-spec update --force
+```
+
+## 工作流程（PRD -> 交付）
+
+```
+PRD/需求 --> OpenSpec（规范 + 任务 + 验收标准）
+                    |
+                    v
+              Ralph 循环（迭代直到测试通过）
+                    |
+                    v
+              归档（合并回源规范）
+```
+
+### 1）规划：PRD -> OpenSpec 变更
+
+使用 AI 工具的 `/ralphy:plan`（Cursor / Claude Code），或让 OpenCode 遵循 `AGENTS.md`。
+
+仓库中的预期输出：
+
+```
+openspec/changes/<change-name>/
+  proposal.md
+  tasks.md
+  specs/
+    <domain>/
+      spec.md
+```
+
+### 2）实现：迭代直到完成
+
+使用 `/ralphy:implement` 实现任务并添加测试。
+
+如果通过 Ralph 循环运行器运行，代理应该只在**所有任务完成且测试通过**时输出：
+
+```
+<promise>TASK_COMPLETE</promise>
+```
+
+### 3）验证：测试证明验收标准
+
+使用 `/ralphy:validate` 运行测试并将通过的测试映射回 OpenSpec 场景。
+
+### 4）归档：将变更合并回规范
+
+使用 `/ralphy:archive`，如果可用的话，使用 OpenSpec CLI：
+
+```bash
+openspec archive <change-name> --yes
+```
+
+## 致谢
+
+Ralphy-Spec 站在巨人的肩膀上：
+
+- **Ralph Wiggum 方法论** - 由 [Geoffrey Huntley](https://ghuntley.com/ralph) 构思。AI 代理可以通过迭代进行自我纠正的洞见改变了我们对 AI 辅助开发的看法。
+
+- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 一个简洁的 OpenCode Ralph 循环 CLI 实现，启发了我们的集成方式。
+
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - 为 AI 编码带来结构和可预测性的规范驱动开发框架。他们的 `specs/` + `changes/` 模型优雅而实用。
+
+我们感谢这些项目及其维护者开创了这些方法。
+
+## 开发
+
+```bash
+npm install
+npm run build
+node bin/ralphy-spec.js --help
+```
+
+## 许可证
+
+BSD-3-Clause

package/dist/index.js

@@ -9,7 +9,7 @@ function buildProgram() {
     program
         .name("ralphy-spec")
         .description("One-command setup for Ralph loop + OpenSpec workflows across Cursor, OpenCode, and Claude Code.")
-        .version("0.1.0");
+        .version("0.1.1");
     (0, init_1.registerInitCommand)(program);
     (0, validate_1.registerValidateCommand)(program);
     (0, update_1.registerUpdateCommand)(program);

package/dist/templates/claude-code/ralphy-archive.md

@@ -0,0 +1,22 @@
+# /ralphy:archive (Archive completed change)
+
+You are archiving a completed OpenSpec change.
+
+## Preconditions
+- All tasks are complete
+- Tests are green
+- Spec deltas reflect final behavior
+
+## Steps
+1. Run tests to confirm green.
+2. If OpenSpec CLI is available, archive via:
+   - `openspec archive <change-name> --yes`
+3. Otherwise, move the change folder from:
+   - `openspec/changes/<change-name>/`
+   to:
+   - `openspec/archive/<change-name>/`
+4. Confirm `openspec/specs/` is updated appropriately.
+
+## Output
+Provide a short summary and a test plan.
+

package/dist/templates/claude-code/ralphy-implement.md

@@ -0,0 +1,30 @@
+# /ralphy:implement (Implement OpenSpec tasks)
+
+You are implementing an OpenSpec change located under `openspec/changes/<change-name>/`.
+
+## Goal
+Complete all tasks in `tasks.md` and satisfy the acceptance criteria from the spec scenarios.
+
+## Ralph loop compatibility
+If this command is being executed in an iterative loop:
+- Make progress each iteration
+- Run tests frequently
+- Only declare success when verification passes
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Read the change artifacts:
+   - `proposal.md`
+   - `tasks.md`
+   - spec deltas under `specs/`
+3. Implement tasks in order:
+   - Update code
+   - Add/update tests
+   - Run tests
+   - Mark tasks complete ONLY when verified
+
+## Completion promise
+Only output this exact text when ALL tasks are complete and tests pass:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/claude-code/ralphy-plan.md

@@ -0,0 +1,31 @@
+# /ralphy:plan (PRD -> OpenSpec change)
+
+You are an AI coding assistant. Convert the user's PRD/requirements into an OpenSpec change proposal with clear, testable acceptance criteria.
+
+## Deliverables (create/modify files)
+Create a new change folder:
+- `openspec/changes/<change-name>/proposal.md`
+- `openspec/changes/<change-name>/tasks.md`
+- `openspec/changes/<change-name>/specs/<domain>/spec.md` (and others as needed)
+
+## Rules
+- Use MUST/SHALL language for requirements.
+- Every `### Requirement:` MUST include at least one `#### Scenario:`.
+- Include acceptance criteria that can be validated by tests or deterministic commands.
+- Keep scope explicit; list non-goals.
+
+## Procedure
+1. Read `openspec/project.md` and relevant specs under `openspec/specs/`.
+2. Propose a kebab-case change name (e.g. `add-profile-filters`).
+3. Create `proposal.md` explaining why/what and the constraints.
+4. Write spec deltas under `specs/` using:
+   - `## ADDED Requirements`
+   - `## MODIFIED Requirements`
+   - `## REMOVED Requirements`
+5. Write `tasks.md` as a numbered checklist. Each task includes:
+   - Implementation notes
+   - Test plan (what to run, what to assert)
+
+## Output
+Summarize created files and tell the user what to run next (typically implementation).
+

package/dist/templates/claude-code/ralphy-validate.md

@@ -0,0 +1,21 @@
+# /ralphy:validate (Validate against acceptance criteria)
+
+You are validating an OpenSpec change.
+
+## Goal
+Prove that the implementation matches the requirements/scenarios and that tests pass.
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Extract acceptance criteria from:
+   - spec scenarios in `openspec/changes/<change-name>/specs/**`
+   - test plan notes in `tasks.md`
+3. Run tests and/or deterministic verification commands.
+4. If failures occur, fix them and re-run until green.
+
+## Output
+Report:
+- What passed
+- What failed (with next actions)
+- Any missing tests needed to satisfy acceptance criteria
+

package/dist/templates/cursor/ralphy-archive.md

@@ -0,0 +1,20 @@
+# /ralphy:archive (Archive completed change)
+
+You are an AI coding assistant archiving a completed OpenSpec change.
+
+## Preconditions
+- All tasks in `openspec/changes/<change-name>/tasks.md` are complete
+- Tests pass
+- Spec deltas are correct and reflect the final behavior
+
+## Steps
+1. Run validation (tests) and ensure green.
+2. Archive the change by moving it into `openspec/archive/` (or using the OpenSpec CLI if available).
+   - If OpenSpec CLI is installed, prefer:
+     - `openspec archive <change-name> --yes`
+3. Confirm the source-of-truth specs in `openspec/specs/` are updated appropriately.
+4. Provide a short release-style summary:
+   - What changed
+   - How to test
+   - Any follow-up work
+

package/dist/templates/cursor/ralphy-implement.md

@@ -0,0 +1,31 @@
+# /ralphy:implement (Implement OpenSpec tasks)
+
+You are an AI coding assistant implementing an existing OpenSpec change.
+
+## Goal
+Implement tasks from `openspec/changes/<change-name>/tasks.md` until acceptance criteria are met and tests pass.
+
+## Operating mode (Ralph loop compatible)
+If you are being run in an iterative loop, you may see the same prompt repeatedly. You MUST:
+- Use test failures as feedback
+- Keep making progress on the next incomplete task
+- Only claim completion when verification passes
+
+## Steps
+1. Identify the active change folder under `openspec/changes/` (ask the user if multiple exist).
+2. Read:
+   - `openspec/changes/<change-name>/proposal.md`
+   - `openspec/changes/<change-name>/tasks.md`
+   - Relevant spec deltas in `openspec/changes/<change-name>/specs/`
+   - Current specs in `openspec/specs/` as the baseline
+3. Implement tasks in order. For each task:
+   - Make the smallest correct change
+   - Update or add tests required by acceptance criteria
+   - Run tests and fix failures
+   - Mark the task as complete in `tasks.md` ONLY when verified
+
+## Completion promise (for Ralph loop runners)
+Only output this exact text when ALL tasks are complete AND tests pass:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/cursor/ralphy-plan.md

@@ -0,0 +1,39 @@
+# /ralphy:plan (PRD -> OpenSpec change)
+
+You are an AI coding assistant. Your job is to convert user requirements into an OpenSpec change proposal with clear acceptance criteria.
+
+## Goal
+Create a new OpenSpec change folder under `openspec/changes/<change-name>/` containing:
+- `proposal.md`
+- `tasks.md`
+- `specs/<domain>/spec.md` (or multiple specs if needed)
+
+## Inputs
+- A PRD, feature request, or requirements description from the user.
+- Existing specs in `openspec/specs/` (source of truth).
+
+## Requirements
+- Use MUST/SHALL language in requirements.
+- Every requirement MUST have at least one `#### Scenario:` block.
+- Add acceptance criteria that can be validated via tests/commands.
+- Keep changes scoped and explicitly list what is out-of-scope.
+
+## Steps
+1. Read `openspec/project.md` and any relevant specs in `openspec/specs/`.
+2. Propose a short, kebab-case `<change-name>` (e.g. `add-profile-filters`).
+3. Create `openspec/changes/<change-name>/proposal.md` describing:
+   - Summary
+   - Motivation
+   - Scope / Non-goals
+   - Risks
+4. Create `openspec/changes/<change-name>/specs/...` as spec deltas:
+   - `## ADDED Requirements`
+   - `## MODIFIED Requirements`
+   - `## REMOVED Requirements`
+5. Create `openspec/changes/<change-name>/tasks.md`:
+   - Break into numbered tasks with checkboxes
+   - Each task includes test plan notes (what to run, what to assert)
+
+## Output
+When the OpenSpec change artifacts are created and consistent, summarize what you created and what the next command should be.
+

package/dist/templates/cursor/ralphy-validate.md

@@ -0,0 +1,24 @@
+# /ralphy:validate (Validate against acceptance criteria)
+
+You are an AI coding assistant validating an OpenSpec change against its acceptance criteria.
+
+## Goal
+Confirm the implementation satisfies the requirements/scenarios in:
+- `openspec/changes/<change-name>/specs/**`
+and that all tests pass.
+
+## Steps
+1. Identify the active change folder under `openspec/changes/`.
+2. Extract acceptance criteria from the spec scenarios and `tasks.md` test plan notes.
+3. Run the project test command (prefer package scripts), for example:
+   - `npm test`
+   - `pnpm test`
+   - `bun test`
+4. If tests fail:
+   - Diagnose the failure
+   - Fix code/tests
+   - Re-run tests
+5. Report results:
+   - Which requirements are proven (by which tests/commands)
+   - Any gaps (missing tests or unclear acceptance criteria)
+

package/dist/templates/opencode/AGENTS.md

@@ -0,0 +1,46 @@
+# Ralphy-OpenSpec Agent Instructions (OpenCode)
+
+You are an AI coding assistant operating in a repository that uses:
+- **OpenSpec** for spec-driven development (`openspec/specs/` + `openspec/changes/`)
+- **Ralph loop** for iterative execution (the same prompt may be repeated)
+
+## Golden rules
+- Treat `openspec/specs/` as the source of truth (current behavior).
+- Treat `openspec/changes/<change-name>/` as the proposed/active change.
+- Only mark tasks complete when verification (tests) passes.
+- Keep changes small, deterministic, and test-backed.
+
+## Workflow
+
+### 1) Plan (PRD -> OpenSpec)
+When asked to plan or create specs:
+1. Read `openspec/project.md` and relevant files in `openspec/specs/`.
+2. Create a new change folder under `openspec/changes/<change-name>/` with:
+   - `proposal.md` (why/what/scope/non-goals/risks)
+   - `tasks.md` (checklist with test plan notes)
+   - `specs/**/spec.md` (deltas: ADDED/MODIFIED/REMOVED)
+3. Ensure requirements use MUST/SHALL and each requirement has at least one scenario.
+
+### 2) Implement (Tasks -> Code)
+When asked to implement:
+1. Identify the active change folder under `openspec/changes/`.
+2. Implement tasks in order from `tasks.md`.
+3. Run tests frequently and fix failures.
+4. Update the checkbox status in `tasks.md` only when verified.
+
+### 3) Validate (Acceptance criteria)
+When asked to validate:
+1. Map scenarios/acceptance criteria to tests/commands.
+2. Run the project test command (commonly `npm test`).
+3. Report which requirements are proven and what gaps remain.
+
+### 4) Archive
+When asked to archive:
+- Prefer `openspec archive <change-name> --yes` if OpenSpec CLI is available.
+- Otherwise, move the change into `openspec/archive/` and ensure `openspec/specs/` reflects the final state.
+
+## Ralph loop completion promise
+If you are being run in a loop, only output this exact text when ALL tasks are complete and tests are green:
+
+<promise>TASK_COMPLETE</promise>
+

package/dist/templates/shared/openspec-tasks-template.md

@@ -0,0 +1,28 @@
+# OpenSpec Tasks Template
+
+Use this structure for `openspec/changes/<change-name>/tasks.md`.
+
+## 1. Planning / Scaffolding
+- [ ] 1.1 Confirm scope and affected modules
+  - Test plan: N/A
+
+## 2. Implementation
+- [ ] 2.1 Implement feature behavior
+  - Acceptance criteria:
+    - GIVEN ...
+    - WHEN ...
+    - THEN ...
+  - Test plan:
+    - Run: `npm test`
+    - Assert: ...
+
+## 3. Validation
+- [ ] 3.1 Add/adjust tests to cover all scenarios
+  - Test plan:
+    - Run: `npm test`
+
+## 4. Documentation / Archive
+- [ ] 4.1 Update specs and archive change
+  - Test plan:
+    - Run: `npm test`
+

package/dist/templates/shared/ralph-loop-prompt-template.md

@@ -0,0 +1,25 @@
+# Ralph Loop Prompt Template (OpenSpec task runner)
+
+Use this template when running an AI agent in a loop (Ralph methodology). The same prompt may be repeated until the completion promise is printed.
+
+## Context
+You are implementing OpenSpec change: `{{change_name}}`
+
+## Current Task
+{{current_task_from_tasks_md}}
+
+## Acceptance Criteria
+{{acceptance_criteria}}
+
+## Instructions
+1. Read the spec at `openspec/changes/{{change_name}}/` and the baseline specs in `openspec/specs/`.
+2. Implement the current task.
+3. Run tests to verify the acceptance criteria.
+4. If tests pass, mark the task complete and output `<promise>TASK_COMPLETE</promise>`.
+5. If tests fail, fix issues and continue iterating.
+
+## Important
+- Do NOT output the promise until tests pass.
+- Prefer small, incremental changes.
+- Keep tests aligned with OpenSpec scenarios.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphy-spec",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-command setup for Ralph loop + OpenSpec workflows across Cursor, OpenCode, and Claude Code.",
   "license": "BSD-3-Clause",
   "author": "Wenqing Yu",
@@ -33,6 +33,9 @@
     "dist/",
     "scripts/",
     "README.md",
+    "README.zh.md",
+    "README.ko.md",
+    "README.ja.md",
     "LICENSE"
   ],
   "engines": {

package/scripts/copy-templates.mjs

@@ -16,7 +16,8 @@ async function copyDir(srcDir, dstDir) {
   }
 }
 
-const root = path.resolve(new URL(".", import.meta.url).pathname, "..", "..");
+const scriptsDir = path.dirname(new URL(import.meta.url).pathname);
+const root = path.resolve(scriptsDir, "..");
 const srcTemplates = path.join(root, "src", "templates");
 const dstTemplates = path.join(root, "dist", "templates");