ralphy-spec 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-23
+
+### Added
+- Initial public release of `ralphy-spec`.
+- Astro-powered documentation site with i18n (en/zh/ko/ja).
+
+### Changed
+- N/A
+
+### Fixed
+- N/A
+
+## [0.3.0] - 2026-01-23
+
+### Added
+- Budget intelligence: three-tier budgets (optimal → warning → hard) with hard-cap blocking + failure summaries.
+- Sprint semantics: `sprint.size` defaults, `sprint.intent` constraints, and configurable scope guard policy (`off|warn|block`).
+- Artifact system: `ralphy-spec/` folder, STATUS/TASKS/BUDGET writers, per-task artifacts, immutable run logs, and `--artifact-dir`.
+- New CLI command: `ralphy-spec budget` and a full CLI docs page on the website.
+- Test suite (Vitest) covering the above behaviors.
+
+### Changed
+- `ralphy-spec run` now supports `worktree` mode and real backend selection (`cursor|opencode|claude-code|noop`).
+- Docs + README (all languages) updated to reflect the new artifacts and CLI.
+

package/README.ja.md

@@ -2,180 +2,147 @@
 
 [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
 
-以下のツール向けに **Ralph ループ + OpenSpec** ワークフローを1つのコマンドでセットアップ：
-- Cursor
-- OpenCode
-- Claude Code
+**スペック駆動AI開発 + 反復実行。** OpenSpecとRalph Loopを組み合わせて、予測可能なAI支援コーディングを実現します。
 
 **ウェブサイト:** [https://ralphy-spec.org](https://ralphy-spec.org)
+**ドキュメント:** [https://ralphy-spec.org/ja/docs/](https://ralphy-spec.org/ja/docs/)
+**変更履歴:** [https://ralphy-spec.org/ja/changelog/](https://ralphy-spec.org/ja/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
-## 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インストールスクリプト
+CLI 基本:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
 ```
 
-## 使用方法
-
-### プロジェクトで初期化
+次に、AIツールに対応するコマンドを使用します：
 
-```bash
-cd your-project
-ralphy-spec init
-```
+### Cursor
 
-非対話的なツール選択：
+| コマンド | 機能 |
+|----------|------|
+| `/ralphy-plan` | 要件からスペック作成 |
+| `/ralphy-implement` | 反復ループでビルド |
+| `/ralphy-validate` | 受け入れ基準を検証 |
+| `/ralphy-archive` | 完了してアーカイブ |
 
-```bash
-ralphy-spec init --tools cursor,claude-code,opencode
-```
+### Claude Code
 
-既存ファイルの上書き：
+| コマンド | 機能 |
+|----------|------|
+| `/ralphy-plan` | 要件からスペック作成 |
+| `/ralphy-implement` | 反復ループでビルド |
+| `/ralphy-validate` | 受け入れ基準を検証 |
+| `/ralphy-archive` | 完了してアーカイブ |
 
-```bash
-ralphy-spec init --force
-```
+### OpenCode
 
-### セットアップの検証
+AGENTS.mdと自然言語を使用：
+- `"Follow AGENTS.md to plan [機能]"`
+- `"Follow AGENTS.md to implement [変更]"`
+- `"Follow AGENTS.md to validate"`
+- `"Follow AGENTS.md to archive [変更]"`
 
+**Ralph Loopランナーと一緒に:**
 ```bash
-ralphy-spec validate
+npm install -g @th0rgal/ralph-wiggum
+ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
 ```
 
-### テンプレートの更新
+## ワークフロー例
 
 ```bash
-ralphy-spec update --force
-```
+# 1. 計画: アイデアからスペック作成
+You: /ralphy-plan JWT ユーザー認証を追加
 
-## ワークフロー（PRD -> リリース）
-
-```
-PRD/要件 --> OpenSpec（スペック + タスク + 受け入れ基準）
-                    |
-                    v
-              Ralphループ（テストが通るまで反復）
-                    |
-                    v
-              アーカイブ（ソーススペックにマージ）
-```
+# 2. 実装: AIが反復的にビルド
+You: /ralphy-implement add-user-auth
 
-### 1) 計画：PRD -> OpenSpec変更
+# 3. 検証: テストパスを確認
+You: /ralphy-validate
 
-AIツールで`/ralphy:plan`（Cursor / Claude Code）を使用するか、OpenCodeに`AGENTS.md`に従うよう依頼します。
+# 4. アーカイブ: 変更を完了
+You: /ralphy-archive add-user-auth
+```
 
-リポジトリでの期待される出力：
+## 作成されるファイル
 
 ```
-openspec/changes/<change-name>/
-  proposal.md
-  tasks.md
-  specs/
-    <domain>/
-      spec.md
-```
-
-### 2) 実装：完了するまで反復
+.cursor/prompts/          # または .claude/commands/
+├── ralphy-plan.md
+├── ralphy-implement.md
+├── ralphy-validate.md
+└── ralphy-archive.md
 
-`/ralphy:implement`を使用してタスクを実装し、テストを追加します。
+AGENTS.md                 # OpenCode用
 
-Ralphループランナーで実行する場合、エージェントは**すべてのタスクが完了しテストが通った場合のみ**以下を出力します：
+openspec/
+├── specs/                # 真実の情報源
+├── changes/              # 進行中の作業
+├── archive/              # 完了
+└── project.md            # コンテキスト
 
-```
-<promise>TASK_COMPLETE</promise>
+ralphy-spec/              # ローカル状態 + アーティファクト（IDE向け）
+├── state.db              # SQLite 実行/タスクログ
+├── STATUS.md             # ライブ状態（`ralphy-spec status` が優先）
+├── TASKS.md              # タスクボード
+├── BUDGET.md             # コスト/予算
+├── runs/                 # 不変の実行ログ（`runs/<runId>.md`）
+├── logs/                 # バックエンド出力（ベストエフォート）
+├── worktrees/            # Git worktree（worktreeモード時）
+└── tasks/                # タスク別アーティファクト（CONTEXT / REPAIR / NOTES）
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
-### 3) 検証：テストで受け入れ基準を証明
+> 注: 既存の `.ralphy/` フォルダが見つかった場合、`ralphy-spec/` へ自動的に移行します。
 
-`/ralphy:validate`を使用してテストを実行し、通過したテストをOpenSpecシナリオにマッピングします。
+## 仕組み
 
-### 4) アーカイブ：変更をスペックにマージ
+**Ralph Wiggum Loop:** AIがタスク完了まで同じプロンプトを繰り返し受け取ります。各イテレーションで、ファイルの以前の作業を見て自己修正します。
 
-`/ralphy:archive`を使用し、利用可能であればOpenSpec CLIを使用します：
+**OpenSpec:** コードの前にスペック。構造化されたスペックと受け入れ基準により、AIが何をビルドすべきか正確に分かります。
 
-```bash
-openspec archive <change-name> --yes
-```
+**組み合わせる理由：**
 
-## 謝辞
+| 問題 | 解決策 |
+|------|--------|
+| チャットの曖昧な要件 | スペックが意図を固定 |
+| AIが途中で停止 | 完了するまでループがリトライ |
+| 検証方法がない | テストが出力を検証 |
+| ツール固有のセットアップ | 1つのコマンドですべて解決 |
 
-Ralphy-Specは巨人の肩の上に立っています：
+## インストールオプション
 
-- **Ralph Wiggum方法論** - [Geoffrey Huntley](https://ghuntley.com/ralph)が考案。AIエージェントが反復を通じて自己修正できるという洞察は、AI支援開発についての私たちの考え方を変えました。
+```bash
+# npx（推奨）
+npx ralphy-spec init
 
-- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 私たちの統合アプローチにインスピレーションを与えたOpenCode用のクリーンなRalphループCLI実装。
+# グローバルインストール
+npm install -g ralphy-spec
+ralphy-spec init
 
-- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AIコーディングに構造と予測可能性をもたらすスペック駆動開発フレームワーク。
+# 特定のツールを指定
+ralphy-spec init --tools cursor,claude-code,opencode
+```
 
-これらのアプローチを開拓したこれらのプロジェクトとメンテナーに感謝します。
+## 謝辞
 
-## 開発
+以下のプロジェクトに基づいています：
 
-```bash
-npm install
-npm run build
-node bin/ralphy-spec.js --help
-```
+- **[Ralph方法論](https://ghuntley.com/ralph)** by Geoffrey Huntley
+- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal  
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
 
 ## ライセンス
 

package/README.ko.md

@@ -2,180 +2,147 @@
 
 [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
 
-다음 도구를 위한 **Ralph 루프 + OpenSpec** 워크플로우를 한 번의 명령으로 설정:
-- Cursor
-- OpenCode
-- Claude Code
+**스펙 기반 AI 개발 + 반복 실행.** OpenSpec과 Ralph Loop를 결합하여 예측 가능한 AI 지원 코딩을 실현합니다.
 
 **웹사이트:** [https://ralphy-spec.org](https://ralphy-spec.org)
+**문서:** [https://ralphy-spec.org/ko/docs/](https://ralphy-spec.org/ko/docs/)
+**변경 로그:** [https://ralphy-spec.org/ko/changelog/](https://ralphy-spec.org/ko/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
-## 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 설치 스크립트
+CLI 기본 사용:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
 ```
 
-## 사용법
-
-### 프로젝트에서 초기화
+그런 다음 AI 도구에 맞는 명령을 사용하세요:
 
-```bash
-cd your-project
-ralphy-spec init
-```
+### Cursor
 
-비대화형 도구 선택:
+| 명령 | 기능 |
+|------|------|
+| `/ralphy-plan` | 요구사항에서 스펙 생성 |
+| `/ralphy-implement` | 반복 루프로 빌드 |
+| `/ralphy-validate` | 인수 기준 검증 |
+| `/ralphy-archive` | 완료 및 아카이브 |
 
-```bash
-ralphy-spec init --tools cursor,claude-code,opencode
-```
+### Claude Code
 
-기존 파일 덮어쓰기:
+| 명령 | 기능 |
+|------|------|
+| `/ralphy-plan` | 요구사항에서 스펙 생성 |
+| `/ralphy-implement` | 반복 루프로 빌드 |
+| `/ralphy-validate` | 인수 기준 검증 |
+| `/ralphy-archive` | 완료 및 아카이브 |
 
-```bash
-ralphy-spec init --force
-```
+### OpenCode
 
-### 설정 검증
+AGENTS.md와 함께 자연어 사용:
+- `"Follow AGENTS.md to plan [기능]"`
+- `"Follow AGENTS.md to implement [변경]"`
+- `"Follow AGENTS.md to validate"`
+- `"Follow AGENTS.md to archive [변경]"`
 
+**Ralph Loop 러너와 함께:**
 ```bash
-ralphy-spec validate
+npm install -g @th0rgal/ralph-wiggum
+ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
 ```
 
-### 템플릿 업데이트
+## 워크플로우 예시
 
 ```bash
-ralphy-spec update --force
-```
+# 1. 계획: 아이디어에서 스펙 생성
+You: /ralphy-plan JWT 사용자 인증 추가
 
-## 워크플로우 (PRD -> 출시)
-
-```
-PRD/요구사항 --> OpenSpec (스펙 + 작업 + 인수 기준)
-                      |
-                      v
-                Ralph 루프 (테스트 통과까지 반복)
-                      |
-                      v
-                아카이브 (소스 스펙에 병합)
-```
+# 2. 구현: AI가 반복적으로 빌드
+You: /ralphy-implement add-user-auth
 
-### 1) 계획: PRD -> OpenSpec 변경
+# 3. 검증: 테스트 통과 확인
+You: /ralphy-validate
 
-AI 도구에서 `/ralphy:plan` (Cursor / Claude Code)을 사용하거나 OpenCode에 `AGENTS.md`를 따르도록 요청합니다.
+# 4. 아카이브: 변경 완료
+You: /ralphy-archive add-user-auth
+```
 
-저장소에 예상되는 출력:
+## 생성되는 파일
 
 ```
-openspec/changes/<change-name>/
-  proposal.md
-  tasks.md
-  specs/
-    <domain>/
-      spec.md
-```
-
-### 2) 구현: 완료될 때까지 반복
+.cursor/prompts/          # 또는 .claude/commands/
+├── ralphy-plan.md
+├── ralphy-implement.md
+├── ralphy-validate.md
+└── ralphy-archive.md
 
-`/ralphy:implement`를 사용하여 작업을 구현하고 테스트를 추가합니다.
+AGENTS.md                 # OpenCode용
 
-Ralph 루프 러너를 통해 실행하는 경우, 에이전트는 **모든 작업이 완료되고 테스트가 통과했을 때만** 다음을 출력해야 합니다:
+openspec/
+├── specs/                # 진실의 원천
+├── changes/              # 진행 중인 작업
+├── archive/              # 완료됨
+└── project.md            # 컨텍스트
 
-```
-<promise>TASK_COMPLETE</promise>
+ralphy-spec/              # 로컬 상태 + 아티팩트(IDE 친화적)
+├── state.db              # SQLite 실행/태스크 로그
+├── STATUS.md             # 라이브 상태(`ralphy-spec status`가 우선 사용)
+├── TASKS.md              # 태스크 보드
+├── BUDGET.md             # 비용/예산
+├── runs/                 # 불변 실행 로그(`runs/<runId>.md`)
+├── logs/                 # 백엔드 원본 출력(가능한 경우)
+├── worktrees/            # Git worktree(worktree 모드 사용 시)
+└── tasks/                # 태스크별 아티팩트(CONTEXT / REPAIR / NOTES)
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
-### 3) 검증: 테스트로 인수 기준 증명
+> 참고: 기존 `.ralphy/` 폴더가 있으면 자동으로 `ralphy-spec/`로 마이그레이션됩니다.
 
-`/ralphy:validate`를 사용하여 테스트를 실행하고 통과한 테스트를 OpenSpec 시나리오에 매핑합니다.
+## 작동 방식
 
-### 4) 아카이브: 변경을 스펙에 병합
+**Ralph Wiggum Loop:** AI가 작업 완료까지 동일한 프롬프트를 반복적으로 받습니다. 각 반복에서 파일의 이전 작업을 보고 자기 수정합니다.
 
-`/ralphy:archive`를 사용하고, 가능하다면 OpenSpec CLI를 사용합니다:
+**OpenSpec:** 코드 전에 스펙. 구조화된 스펙과 인수 기준으로 AI가 무엇을 빌드해야 하는지 정확히 알 수 있습니다.
 
-```bash
-openspec archive <change-name> --yes
-```
+**결합하는 이유:**
 
-## 감사의 말
+| 문제 | 해결책 |
+|------|--------|
+| 채팅의 모호한 요구사항 | 스펙이 의도를 고정 |
+| AI가 중간에 멈춤 | 완료될 때까지 루프 재시도 |
+| 검증 방법 없음 | 테스트가 출력 검증 |
+| 도구별 설정 | 하나의 명령으로 모두 해결 |
 
-Ralphy-Spec은 거인의 어깨 위에 서 있습니다:
+## 설치 옵션
 
-- **Ralph Wiggum 방법론** - [Geoffrey Huntley](https://ghuntley.com/ralph)가 고안. AI 에이전트가 반복을 통해 자기 수정할 수 있다는 통찰력은 AI 지원 개발에 대한 우리의 생각을 바꾸었습니다.
+```bash
+# npx (권장)
+npx ralphy-spec init
 
-- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - 우리의 통합 방식에 영감을 준 OpenCode용 깔끔한 Ralph 루프 CLI 구현.
+# 전역 설치
+npm install -g ralphy-spec
+ralphy-spec init
 
-- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - AI 코딩에 구조와 예측 가능성을 부여하는 스펙 기반 개발 프레임워크.
+# 특정 도구 지정
+ralphy-spec init --tools cursor,claude-code,opencode
+```
 
-이러한 접근 방식을 개척한 이 프로젝트들과 유지 관리자들에게 감사드립니다.
+## 감사의 말
 
-## 개발
+다음 프로젝트를 기반으로 합니다:
 
-```bash
-npm install
-npm run build
-node bin/ralphy-spec.js --help
-```
+- **[Ralph 방법론](https://ghuntley.com/ralph)** by Geoffrey Huntley
+- **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal  
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
 
 ## 라이선스