ralphy-spec 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/README.ja.md +126 -0
  2. package/README.ko.md +126 -0
  3. package/README.md +77 -133
  4. package/README.zh.md +126 -0
  5. package/bin/ralphy-spec.js +0 -0
  6. package/dist/cli/checkpoint.d.ts +3 -0
  7. package/dist/cli/checkpoint.d.ts.map +1 -0
  8. package/dist/cli/checkpoint.js +23 -0
  9. package/dist/cli/checkpoint.js.map +1 -0
  10. package/dist/cli/init.d.ts +3 -0
  11. package/dist/cli/init.d.ts.map +1 -0
  12. package/dist/cli/init.js +66 -0
  13. package/dist/cli/init.js.map +1 -0
  14. package/dist/cli/report.d.ts +3 -0
  15. package/dist/cli/report.d.ts.map +1 -0
  16. package/dist/cli/report.js +53 -0
  17. package/dist/cli/report.js.map +1 -0
  18. package/dist/cli/run.d.ts +3 -0
  19. package/dist/cli/run.d.ts.map +1 -0
  20. package/dist/cli/run.js +79 -0
  21. package/dist/cli/run.js.map +1 -0
  22. package/dist/cli/status.d.ts +3 -0
  23. package/dist/cli/status.d.ts.map +1 -0
  24. package/dist/cli/status.js +45 -0
  25. package/dist/cli/status.js.map +1 -0
  26. package/dist/cli/tail.d.ts +3 -0
  27. package/dist/cli/tail.d.ts.map +1 -0
  28. package/dist/cli/tail.js +46 -0
  29. package/dist/cli/tail.js.map +1 -0
  30. package/dist/cli/update.d.ts +3 -0
  31. package/dist/cli/update.d.ts.map +1 -0
  32. package/dist/cli/update.js +62 -0
  33. package/dist/cli/update.js.map +1 -0
  34. package/dist/cli/validate.d.ts +3 -0
  35. package/dist/cli/validate.d.ts.map +1 -0
  36. package/dist/cli/validate.js +83 -0
  37. package/dist/cli/validate.js.map +1 -0
  38. package/dist/core/backends/claude-code.d.ts +17 -0
  39. package/dist/core/backends/claude-code.d.ts.map +1 -0
  40. package/dist/core/backends/claude-code.js +75 -0
  41. package/dist/core/backends/claude-code.js.map +1 -0
  42. package/dist/core/backends/cursor.d.ts +17 -0
  43. package/dist/core/backends/cursor.d.ts.map +1 -0
  44. package/dist/core/backends/cursor.js +75 -0
  45. package/dist/core/backends/cursor.js.map +1 -0
  46. package/dist/core/backends/noop.d.ts +10 -0
  47. package/dist/core/backends/noop.d.ts.map +1 -0
  48. package/dist/core/backends/noop.js +17 -0
  49. package/dist/core/backends/noop.js.map +1 -0
  50. package/dist/core/backends/opencode.d.ts +16 -0
  51. package/dist/core/backends/opencode.d.ts.map +1 -0
  52. package/dist/core/backends/opencode.js +73 -0
  53. package/dist/core/backends/opencode.js.map +1 -0
  54. package/dist/core/backends/types.d.ts +21 -0
  55. package/dist/core/backends/types.d.ts.map +1 -0
  56. package/dist/core/backends/types.js +3 -0
  57. package/dist/core/backends/types.js.map +1 -0
  58. package/dist/core/budgets/manager.d.ts +21 -0
  59. package/dist/core/budgets/manager.d.ts.map +1 -0
  60. package/dist/core/budgets/manager.js +48 -0
  61. package/dist/core/budgets/manager.js.map +1 -0
  62. package/dist/core/budgets/state.d.ts +25 -0
  63. package/dist/core/budgets/state.d.ts.map +1 -0
  64. package/dist/core/budgets/state.js +33 -0
  65. package/dist/core/budgets/state.js.map +1 -0
  66. package/dist/core/budgets/tiers.d.ts +32 -0
  67. package/dist/core/budgets/tiers.d.ts.map +1 -0
  68. package/dist/core/budgets/tiers.js +67 -0
  69. package/dist/core/budgets/tiers.js.map +1 -0
  70. package/dist/core/engine/context-pack.d.ts +12 -0
  71. package/dist/core/engine/context-pack.d.ts.map +1 -0
  72. package/dist/core/engine/context-pack.js +45 -0
  73. package/dist/core/engine/context-pack.js.map +1 -0
  74. package/dist/core/engine/loop.d.ts +28 -0
  75. package/dist/core/engine/loop.d.ts.map +1 -0
  76. package/dist/core/engine/loop.js +366 -0
  77. package/dist/core/engine/loop.js.map +1 -0
  78. package/dist/core/engine/phases.d.ts +2 -0
  79. package/dist/core/engine/phases.d.ts.map +1 -0
  80. package/dist/core/engine/phases.js +3 -0
  81. package/dist/core/engine/phases.js.map +1 -0
  82. package/dist/core/engine/repair.d.ts +6 -0
  83. package/dist/core/engine/repair.d.ts.map +1 -0
  84. package/dist/core/engine/repair.js +23 -0
  85. package/dist/core/engine/repair.js.map +1 -0
  86. package/dist/core/folders.d.ts +26 -0
  87. package/dist/core/folders.d.ts.map +1 -0
  88. package/dist/core/folders.js +58 -0
  89. package/dist/core/folders.js.map +1 -0
  90. package/dist/core/memory/ledger.d.ts +13 -0
  91. package/dist/core/memory/ledger.d.ts.map +1 -0
  92. package/dist/core/memory/ledger.js +24 -0
  93. package/dist/core/memory/ledger.js.map +1 -0
  94. package/dist/core/memory/persistence.d.ts +45 -0
  95. package/dist/core/memory/persistence.d.ts.map +1 -0
  96. package/dist/core/memory/persistence.js +162 -0
  97. package/dist/core/memory/persistence.js.map +1 -0
  98. package/dist/core/reporting/spend.d.ts +40 -0
  99. package/dist/core/reporting/spend.d.ts.map +1 -0
  100. package/dist/core/reporting/spend.js +157 -0
  101. package/dist/core/reporting/spend.js.map +1 -0
  102. package/dist/core/spec/dag.d.ts +7 -0
  103. package/dist/core/spec/dag.d.ts.map +1 -0
  104. package/dist/core/spec/dag.js +65 -0
  105. package/dist/core/spec/dag.js.map +1 -0
  106. package/dist/core/spec/file-contract.d.ts +13 -0
  107. package/dist/core/spec/file-contract.d.ts.map +1 -0
  108. package/dist/core/spec/file-contract.js +29 -0
  109. package/dist/core/spec/file-contract.js.map +1 -0
  110. package/dist/core/spec/loader.d.ts +8 -0
  111. package/dist/core/spec/loader.d.ts.map +1 -0
  112. package/dist/core/spec/loader.js +51 -0
  113. package/dist/core/spec/loader.js.map +1 -0
  114. package/dist/core/spec/schemas.d.ts +278 -0
  115. package/dist/core/spec/schemas.d.ts.map +1 -0
  116. package/dist/core/spec/schemas.js +207 -0
  117. package/dist/core/spec/schemas.js.map +1 -0
  118. package/dist/core/spec/types.d.ts +71 -0
  119. package/dist/core/spec/types.d.ts.map +1 -0
  120. package/dist/core/spec/types.js +3 -0
  121. package/dist/core/spec/types.js.map +1 -0
  122. package/dist/core/validators/parsers/eslint.d.ts +3 -0
  123. package/dist/core/validators/parsers/eslint.d.ts.map +1 -0
  124. package/dist/core/validators/parsers/eslint.js +35 -0
  125. package/dist/core/validators/parsers/eslint.js.map +1 -0
  126. package/dist/core/validators/parsers/jest.d.ts +3 -0
  127. package/dist/core/validators/parsers/jest.d.ts.map +1 -0
  128. package/dist/core/validators/parsers/jest.js +16 -0
  129. package/dist/core/validators/parsers/jest.js.map +1 -0
  130. package/dist/core/validators/parsers/tsc.d.ts +3 -0
  131. package/dist/core/validators/parsers/tsc.d.ts.map +1 -0
  132. package/dist/core/validators/parsers/tsc.js +32 -0
  133. package/dist/core/validators/parsers/tsc.js.map +1 -0
  134. package/dist/core/validators/runner.d.ts +8 -0
  135. package/dist/core/validators/runner.d.ts.map +1 -0
  136. package/dist/core/validators/runner.js +85 -0
  137. package/dist/core/validators/runner.js.map +1 -0
  138. package/dist/core/validators/signatures.d.ts +3 -0
  139. package/dist/core/validators/signatures.d.ts.map +1 -0
  140. package/dist/core/validators/signatures.js +10 -0
  141. package/dist/core/validators/signatures.js.map +1 -0
  142. package/dist/core/validators/types.d.ts +27 -0
  143. package/dist/core/validators/types.d.ts.map +1 -0
  144. package/dist/core/validators/types.js +3 -0
  145. package/dist/core/validators/types.js.map +1 -0
  146. package/dist/core/workspace/contract-enforcer.d.ts +54 -0
  147. package/dist/core/workspace/contract-enforcer.d.ts.map +1 -0
  148. package/dist/core/workspace/contract-enforcer.js +128 -0
  149. package/dist/core/workspace/contract-enforcer.js.map +1 -0
  150. package/dist/core/workspace/manager.d.ts +28 -0
  151. package/dist/core/workspace/manager.d.ts.map +1 -0
  152. package/dist/core/workspace/manager.js +3 -0
  153. package/dist/core/workspace/manager.js.map +1 -0
  154. package/dist/core/workspace/merge.d.ts +38 -0
  155. package/dist/core/workspace/merge.d.ts.map +1 -0
  156. package/dist/core/workspace/merge.js +92 -0
  157. package/dist/core/workspace/merge.js.map +1 -0
  158. package/dist/core/workspace/patch-mode.d.ts +22 -0
  159. package/dist/core/workspace/patch-mode.d.ts.map +1 -0
  160. package/dist/core/workspace/patch-mode.js +91 -0
  161. package/dist/core/workspace/patch-mode.js.map +1 -0
  162. package/dist/core/workspace/worktree-mode.d.ts +28 -0
  163. package/dist/core/workspace/worktree-mode.d.ts.map +1 -0
  164. package/dist/core/workspace/worktree-mode.js +156 -0
  165. package/dist/core/workspace/worktree-mode.js.map +1 -0
  166. package/dist/index.js +14 -4
  167. package/dist/index.js.map +1 -1
  168. package/dist/templates/claude-code/ralphy-archive.md +22 -0
  169. package/dist/templates/claude-code/ralphy-implement.md +30 -0
  170. package/dist/templates/claude-code/ralphy-plan.md +31 -0
  171. package/dist/templates/claude-code/ralphy-validate.md +21 -0
  172. package/dist/templates/cursor/ralphy-archive.md +20 -0
  173. package/dist/templates/cursor/ralphy-implement.md +31 -0
  174. package/dist/templates/cursor/ralphy-plan.md +39 -0
  175. package/dist/templates/cursor/ralphy-validate.md +24 -0
  176. package/dist/templates/opencode/AGENTS.md +46 -0
  177. package/dist/templates/shared/openspec-tasks-template.md +48 -0
  178. package/dist/templates/shared/project-template.yml +232 -0
  179. package/dist/templates/shared/ralph-loop-prompt-template.md +25 -0
  180. package/dist/utils/installer.d.ts.map +1 -1
  181. package/dist/utils/installer.js +31 -1
  182. package/dist/utils/installer.js.map +1 -1
  183. package/dist/utils/validator.d.ts.map +1 -1
  184. package/dist/utils/validator.js +10 -0
  185. package/dist/utils/validator.js.map +1 -1
  186. package/package.json +14 -4
  187. package/scripts/copy-templates.mjs +2 -1
package/README.ja.md ADDED
@@ -0,0 +1,126 @@
1
+ # ralphy-spec
2
+
3
+ [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4
+
5
+ **スペック駆動AI開発 + 反復実行。** OpenSpecとRalph Loopを組み合わせて、予測可能なAI支援コーディングを実現します。
6
+
7
+ **ウェブサイト:** [https://ralphy-spec.org](https://ralphy-spec.org)
8
+
9
+ ## クイックスタート
10
+
11
+ ```bash
12
+ npx ralphy-spec init
13
+ ```
14
+
15
+ 次に、AIツールに対応するコマンドを使用します:
16
+
17
+ ### Cursor
18
+
19
+ | コマンド | 機能 |
20
+ |----------|------|
21
+ | `/ralphy:plan` | 要件からスペック作成 |
22
+ | `/ralphy:implement` | 反復ループでビルド |
23
+ | `/ralphy:validate` | 受け入れ基準を検証 |
24
+ | `/ralphy:archive` | 完了してアーカイブ |
25
+
26
+ ### Claude Code
27
+
28
+ | コマンド | 機能 |
29
+ |----------|------|
30
+ | `/ralphy:plan` | 要件からスペック作成 |
31
+ | `/ralphy:implement` | 反復ループでビルド |
32
+ | `/ralphy:validate` | 受け入れ基準を検証 |
33
+ | `/ralphy:archive` | 完了してアーカイブ |
34
+
35
+ ### OpenCode
36
+
37
+ AGENTS.mdと自然言語を使用:
38
+ - `"Follow AGENTS.md to plan [機能]"`
39
+ - `"Follow AGENTS.md to implement [変更]"`
40
+ - `"Follow AGENTS.md to validate"`
41
+ - `"Follow AGENTS.md to archive [変更]"`
42
+
43
+ **Ralph Loopランナーと一緒に:**
44
+ ```bash
45
+ npm install -g @th0rgal/ralph-wiggum
46
+ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
47
+ ```
48
+
49
+ ## ワークフロー例
50
+
51
+ ```bash
52
+ # 1. 計画: アイデアからスペック作成
53
+ You: /ralphy:plan JWT ユーザー認証を追加
54
+
55
+ # 2. 実装: AIが反復的にビルド
56
+ You: /ralphy:implement add-user-auth
57
+
58
+ # 3. 検証: テストパスを確認
59
+ You: /ralphy:validate
60
+
61
+ # 4. アーカイブ: 変更を完了
62
+ You: /ralphy:archive add-user-auth
63
+ ```
64
+
65
+ ## 作成されるファイル
66
+
67
+ ```
68
+ .cursor/prompts/ # または .claude/commands/
69
+ ├── ralphy-plan.md
70
+ ├── ralphy-implement.md
71
+ ├── ralphy-validate.md
72
+ └── ralphy-archive.md
73
+
74
+ AGENTS.md # OpenCode用
75
+
76
+ openspec/
77
+ ├── specs/ # 真実の情報源
78
+ ├── changes/ # 進行中の作業
79
+ ├── archive/ # 完了
80
+ └── project.md # コンテキスト
81
+
82
+ .ralphy/
83
+ ├── config.json
84
+ └── ralph-loop.state.json
85
+ ```
86
+
87
+ ## 仕組み
88
+
89
+ **Ralph Wiggum Loop:** AIがタスク完了まで同じプロンプトを繰り返し受け取ります。各イテレーションで、ファイルの以前の作業を見て自己修正します。
90
+
91
+ **OpenSpec:** コードの前にスペック。構造化されたスペックと受け入れ基準により、AIが何をビルドすべきか正確に分かります。
92
+
93
+ **組み合わせる理由:**
94
+
95
+ | 問題 | 解決策 |
96
+ |------|--------|
97
+ | チャットの曖昧な要件 | スペックが意図を固定 |
98
+ | AIが途中で停止 | 完了するまでループがリトライ |
99
+ | 検証方法がない | テストが出力を検証 |
100
+ | ツール固有のセットアップ | 1つのコマンドですべて解決 |
101
+
102
+ ## インストールオプション
103
+
104
+ ```bash
105
+ # npx(推奨)
106
+ npx ralphy-spec init
107
+
108
+ # グローバルインストール
109
+ npm install -g ralphy-spec
110
+ ralphy-spec init
111
+
112
+ # 特定のツールを指定
113
+ ralphy-spec init --tools cursor,claude-code,opencode
114
+ ```
115
+
116
+ ## 謝辞
117
+
118
+ 以下のプロジェクトに基づいています:
119
+
120
+ - **[Ralph方法論](https://ghuntley.com/ralph)** by Geoffrey Huntley
121
+ - **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal
122
+ - **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
123
+
124
+ ## ライセンス
125
+
126
+ BSD-3-Clause
package/README.ko.md ADDED
@@ -0,0 +1,126 @@
1
+ # ralphy-spec
2
+
3
+ [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4
+
5
+ **스펙 기반 AI 개발 + 반복 실행.** OpenSpec과 Ralph Loop를 결합하여 예측 가능한 AI 지원 코딩을 실현합니다.
6
+
7
+ **웹사이트:** [https://ralphy-spec.org](https://ralphy-spec.org)
8
+
9
+ ## 빠른 시작
10
+
11
+ ```bash
12
+ npx ralphy-spec init
13
+ ```
14
+
15
+ 그런 다음 AI 도구에 맞는 명령을 사용하세요:
16
+
17
+ ### Cursor
18
+
19
+ | 명령 | 기능 |
20
+ |------|------|
21
+ | `/ralphy:plan` | 요구사항에서 스펙 생성 |
22
+ | `/ralphy:implement` | 반복 루프로 빌드 |
23
+ | `/ralphy:validate` | 인수 기준 검증 |
24
+ | `/ralphy:archive` | 완료 및 아카이브 |
25
+
26
+ ### Claude Code
27
+
28
+ | 명령 | 기능 |
29
+ |------|------|
30
+ | `/ralphy:plan` | 요구사항에서 스펙 생성 |
31
+ | `/ralphy:implement` | 반복 루프로 빌드 |
32
+ | `/ralphy:validate` | 인수 기준 검증 |
33
+ | `/ralphy:archive` | 완료 및 아카이브 |
34
+
35
+ ### OpenCode
36
+
37
+ AGENTS.md와 함께 자연어 사용:
38
+ - `"Follow AGENTS.md to plan [기능]"`
39
+ - `"Follow AGENTS.md to implement [변경]"`
40
+ - `"Follow AGENTS.md to validate"`
41
+ - `"Follow AGENTS.md to archive [변경]"`
42
+
43
+ **Ralph Loop 러너와 함께:**
44
+ ```bash
45
+ npm install -g @th0rgal/ralph-wiggum
46
+ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
47
+ ```
48
+
49
+ ## 워크플로우 예시
50
+
51
+ ```bash
52
+ # 1. 계획: 아이디어에서 스펙 생성
53
+ You: /ralphy:plan JWT 사용자 인증 추가
54
+
55
+ # 2. 구현: AI가 반복적으로 빌드
56
+ You: /ralphy:implement add-user-auth
57
+
58
+ # 3. 검증: 테스트 통과 확인
59
+ You: /ralphy:validate
60
+
61
+ # 4. 아카이브: 변경 완료
62
+ You: /ralphy:archive add-user-auth
63
+ ```
64
+
65
+ ## 생성되는 파일
66
+
67
+ ```
68
+ .cursor/prompts/ # 또는 .claude/commands/
69
+ ├── ralphy-plan.md
70
+ ├── ralphy-implement.md
71
+ ├── ralphy-validate.md
72
+ └── ralphy-archive.md
73
+
74
+ AGENTS.md # OpenCode용
75
+
76
+ openspec/
77
+ ├── specs/ # 진실의 원천
78
+ ├── changes/ # 진행 중인 작업
79
+ ├── archive/ # 완료됨
80
+ └── project.md # 컨텍스트
81
+
82
+ .ralphy/
83
+ ├── config.json
84
+ └── ralph-loop.state.json
85
+ ```
86
+
87
+ ## 작동 방식
88
+
89
+ **Ralph Wiggum Loop:** AI가 작업 완료까지 동일한 프롬프트를 반복적으로 받습니다. 각 반복에서 파일의 이전 작업을 보고 자기 수정합니다.
90
+
91
+ **OpenSpec:** 코드 전에 스펙. 구조화된 스펙과 인수 기준으로 AI가 무엇을 빌드해야 하는지 정확히 알 수 있습니다.
92
+
93
+ **결합하는 이유:**
94
+
95
+ | 문제 | 해결책 |
96
+ |------|--------|
97
+ | 채팅의 모호한 요구사항 | 스펙이 의도를 고정 |
98
+ | AI가 중간에 멈춤 | 완료될 때까지 루프 재시도 |
99
+ | 검증 방법 없음 | 테스트가 출력 검증 |
100
+ | 도구별 설정 | 하나의 명령으로 모두 해결 |
101
+
102
+ ## 설치 옵션
103
+
104
+ ```bash
105
+ # npx (권장)
106
+ npx ralphy-spec init
107
+
108
+ # 전역 설치
109
+ npm install -g ralphy-spec
110
+ ralphy-spec init
111
+
112
+ # 특정 도구 지정
113
+ ralphy-spec init --tools cursor,claude-code,opencode
114
+ ```
115
+
116
+ ## 감사의 말
117
+
118
+ 다음 프로젝트를 기반으로 합니다:
119
+
120
+ - **[Ralph 방법론](https://ghuntley.com/ralph)** by Geoffrey Huntley
121
+ - **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal
122
+ - **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
123
+
124
+ ## 라이선스
125
+
126
+ BSD-3-Clause
package/README.md CHANGED
@@ -1,181 +1,125 @@
1
1
  # ralphy-spec
2
2
 
3
- One-command setup for **Ralph loop + OpenSpec** workflows across:
4
- - Cursor
5
- - OpenCode
6
- - Claude Code
3
+ [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
7
4
 
8
- **Website:** [https://ralphy-spec.org](https://ralphy-spec.org)
9
-
10
- ## What is Ralphy-Spec?
11
-
12
- Ralphy-Spec combines two powerful AI development methodologies:
13
-
14
- ### The Ralph Wiggum Loop
15
-
16
- The Ralph methodology (coined by [Geoffrey Huntley](https://ghuntley.com/ralph)) is a development approach where an AI agent receives the **same prompt repeatedly** until it completes a task. Each iteration, the AI sees its previous work in files and git history, creating a self-correction feedback loop.
17
-
18
- ```
19
- while true; do
20
- ai_agent "Build feature X. Output <promise>DONE</promise> when complete."
21
- # AI sees previous work, fixes mistakes, continues progress
22
- done
23
- ```
24
-
25
- ### OpenSpec (Spec-Driven Development)
26
-
27
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) brings structure to AI coding by requiring specs before code:
28
- - `openspec/specs/` - Source of truth specifications
29
- - `openspec/changes/` - Proposed changes with acceptance criteria
30
- - Archive workflow to merge completed changes back
31
-
32
- ### Why Combine Them?
33
-
34
- | Problem | Solution |
35
- |---------|----------|
36
- | Vague requirements in chat history | OpenSpec locks intent in structured specs |
37
- | AI stops mid-task or makes mistakes | Ralph loop retries until completion |
38
- | No way to verify correctness | Acceptance criteria + tests validate output |
39
- | Tool-specific setup is tedious | One command sets up Cursor, OpenCode, Claude Code |
40
-
41
- ## What it installs into your project
42
-
43
- - `openspec/` scaffold:
44
- - `openspec/specs/` (source of truth)
45
- - `openspec/changes/` (active changes)
46
- - `openspec/archive/` (completed changes)
47
- - `openspec/project.md` (project context)
48
- - Tool integrations:
49
- - Cursor: `.cursor/prompts/ralphy-*.md`
50
- - Claude Code: `.claude/commands/ralphy-*.md`
51
- - OpenCode: `AGENTS.md`
52
- - Ralph loop state/config:
53
- - `.ralphy/config.json`
54
- - `.ralphy/ralph-loop.state.json`
55
-
56
- ## Installation
57
-
58
- ### npm (global)
5
+ **Spec-driven AI development with iterative execution.** Combines OpenSpec + Ralph Loop for predictable AI-assisted coding.
59
6
 
60
- ```bash
61
- npm install -g ralphy-spec
62
- ```
7
+ **Website:** [https://ralphy-spec.org](https://ralphy-spec.org)
63
8
 
64
- ### npx (no install)
9
+ ## Quick Start
65
10
 
66
11
  ```bash
67
12
  npx ralphy-spec init
68
13
  ```
69
14
 
70
- ### curl install script
15
+ Then use the commands for your AI tool:
71
16
 
72
- ```bash
73
- curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
74
- ```
17
+ ### Cursor
75
18
 
76
- ## Usage
19
+ | Command | What it does |
20
+ |---------|--------------|
21
+ | `/ralphy:plan` | Create specs from requirements |
22
+ | `/ralphy:implement` | Build with iterative loop |
23
+ | `/ralphy:validate` | Verify acceptance criteria |
24
+ | `/ralphy:archive` | Complete and archive |
77
25
 
78
- ### Initialize in a project
26
+ ### Claude Code
79
27
 
80
- ```bash
81
- cd your-project
82
- ralphy-spec init
83
- ```
28
+ | Command | What it does |
29
+ |---------|--------------|
30
+ | `/ralphy:plan` | Create specs from requirements |
31
+ | `/ralphy:implement` | Build with iterative loop |
32
+ | `/ralphy:validate` | Verify acceptance criteria |
33
+ | `/ralphy:archive` | Complete and archive |
84
34
 
85
- Non-interactive tool selection:
35
+ ### OpenCode
86
36
 
87
- ```bash
88
- ralphy-spec init --tools cursor,claude-code,opencode
89
- ```
90
-
91
- Overwrite existing files:
37
+ Use natural language with AGENTS.md:
38
+ - `"Follow AGENTS.md to plan [feature]"`
39
+ - `"Follow AGENTS.md to implement [change]"`
40
+ - `"Follow AGENTS.md to validate"`
41
+ - `"Follow AGENTS.md to archive [change]"`
92
42
 
43
+ **With Ralph Loop Runner:**
93
44
  ```bash
94
- ralphy-spec init --force
45
+ npm install -g @th0rgal/ralph-wiggum
46
+ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
95
47
  ```
96
48
 
97
- ### Validate setup
49
+ ## Example Workflow
98
50
 
99
51
  ```bash
100
- ralphy-spec validate
101
- ```
52
+ # 1. Plan: Create spec from your idea
53
+ You: /ralphy:plan Add user authentication with JWT
102
54
 
103
- ### Update templates
55
+ # 2. Implement: AI builds it iteratively
56
+ You: /ralphy:implement add-user-auth
104
57
 
105
- ```bash
106
- ralphy-spec update --force
107
- ```
58
+ # 3. Validate: Verify tests pass
59
+ You: /ralphy:validate
108
60
 
109
- ## Workflow (PRD -> Ship)
110
-
111
- ```
112
- PRD/Requirements --> OpenSpec (specs + tasks + acceptance criteria)
113
- |
114
- v
115
- Ralph Loop (iterate until tests pass)
116
- |
117
- v
118
- Archive (merge back to source specs)
61
+ # 4. Archive: Complete the change
62
+ You: /ralphy:archive add-user-auth
119
63
  ```
120
64
 
121
- ### 1) Plan: PRD -> OpenSpec change
122
-
123
- Use your AI tool with `/ralphy:plan` (Cursor / Claude Code), or ask OpenCode to follow `AGENTS.md`.
65
+ ## What Gets Created
124
66
 
125
- Expected output in your repo:
126
-
127
- ```
128
- openspec/changes/<change-name>/
129
- proposal.md
130
- tasks.md
131
- specs/
132
- <domain>/
133
- spec.md
134
67
  ```
68
+ .cursor/prompts/ # or .claude/commands/
69
+ ├── ralphy-plan.md
70
+ ├── ralphy-implement.md
71
+ ├── ralphy-validate.md
72
+ └── ralphy-archive.md
135
73
 
136
- ### 2) Implement: iterate until done
137
-
138
- Use `/ralphy:implement` to implement tasks and add tests.
74
+ AGENTS.md # For OpenCode
139
75
 
140
- If you run this via a Ralph loop runner, the agent should only output:
76
+ openspec/
77
+ ├── specs/ # Source of truth
78
+ ├── changes/ # Active work
79
+ ├── archive/ # Completed
80
+ └── project.md # Context
141
81
 
82
+ .ralphy/
83
+ ├── config.json
84
+ └── ralph-loop.state.json
142
85
  ```
143
- <promise>TASK_COMPLETE</promise>
144
- ```
145
-
146
- when **all tasks are done and tests pass**.
147
86
 
148
- ### 3) Validate: tests prove acceptance criteria
87
+ ## How It Works
149
88
 
150
- Use `/ralphy:validate` to run tests and map passing tests back to OpenSpec scenarios.
89
+ **Ralph Wiggum Loop:** AI receives the same prompt repeatedly until task completion. Each iteration, it sees previous work in files and self-corrects.
151
90
 
152
- ### 4) Archive: merge change back into specs
91
+ **OpenSpec:** Specs before code. Structured specifications with acceptance criteria ensure AI knows exactly what to build.
153
92
 
154
- Use `/ralphy:archive` and (if available) the OpenSpec CLI:
93
+ **The Combination:**
155
94
 
156
- ```bash
157
- openspec archive <change-name> --yes
158
- ```
159
-
160
- ## Credits and Appreciation
95
+ | Problem | Solution |
96
+ |---------|----------|
97
+ | Vague requirements in chat | Specs lock intent |
98
+ | AI stops mid-task | Loop retries until done |
99
+ | No way to verify | Tests validate output |
100
+ | Tool-specific setup | One command for all |
161
101
 
162
- Ralphy-Spec stands on the shoulders of giants:
102
+ ## Installation Options
163
103
 
164
- - **Ralph Wiggum Methodology** - Conceived by [Geoffrey Huntley](https://ghuntley.com/ralph). The insight that AI agents can self-correct through iteration changed how we think about AI-assisted development.
104
+ ```bash
105
+ # npx (recommended)
106
+ npx ralphy-spec init
165
107
 
166
- - **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by [@Th0rgal](https://github.com/Th0rgal) - A clean CLI implementation of the Ralph loop for OpenCode that inspired our integration approach.
108
+ # Global install
109
+ npm install -g ralphy-spec
110
+ ralphy-spec init
167
111
 
168
- - **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by [Fission-AI](https://github.com/Fission-AI) - The spec-driven development framework that brings structure and predictability to AI coding. Their `specs/` + `changes/` model is elegant and practical.
112
+ # With specific tools
113
+ ralphy-spec init --tools cursor,claude-code,opencode
114
+ ```
169
115
 
170
- We are grateful to these projects and their maintainers for pioneering these approaches.
116
+ ## Credits
171
117
 
172
- ## Development
118
+ Built on the work of:
173
119
 
174
- ```bash
175
- npm install
176
- npm run build
177
- node bin/ralphy-spec.js --help
178
- ```
120
+ - **[Ralph Methodology](https://ghuntley.com/ralph)** by Geoffrey Huntley
121
+ - **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal
122
+ - **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
179
123
 
180
124
  ## License
181
125
 
package/README.zh.md ADDED
@@ -0,0 +1,126 @@
1
+ # ralphy-spec
2
+
3
+ [English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
4
+
5
+ **规范驱动的 AI 开发 + 迭代执行。** 结合 OpenSpec 和 Ralph 循环,实现可预测的 AI 辅助编码。
6
+
7
+ **官网:** [https://ralphy-spec.org](https://ralphy-spec.org)
8
+
9
+ ## 快速开始
10
+
11
+ ```bash
12
+ npx ralphy-spec init
13
+ ```
14
+
15
+ 然后使用你的 AI 工具对应的命令:
16
+
17
+ ### Cursor
18
+
19
+ | 命令 | 功能 |
20
+ |------|------|
21
+ | `/ralphy:plan` | 从需求创建规范 |
22
+ | `/ralphy:implement` | 迭代循环构建 |
23
+ | `/ralphy:validate` | 验证验收标准 |
24
+ | `/ralphy:archive` | 完成并归档 |
25
+
26
+ ### Claude Code
27
+
28
+ | 命令 | 功能 |
29
+ |------|------|
30
+ | `/ralphy:plan` | 从需求创建规范 |
31
+ | `/ralphy:implement` | 迭代循环构建 |
32
+ | `/ralphy:validate` | 验证验收标准 |
33
+ | `/ralphy:archive` | 完成并归档 |
34
+
35
+ ### OpenCode
36
+
37
+ 使用自然语言配合 AGENTS.md:
38
+ - `"Follow AGENTS.md to plan [功能]"`
39
+ - `"Follow AGENTS.md to implement [变更]"`
40
+ - `"Follow AGENTS.md to validate"`
41
+ - `"Follow AGENTS.md to archive [变更]"`
42
+
43
+ **配合 Ralph 循环运行器:**
44
+ ```bash
45
+ npm install -g @th0rgal/ralph-wiggum
46
+ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20
47
+ ```
48
+
49
+ ## 工作流示例
50
+
51
+ ```bash
52
+ # 1. 规划:从你的想法创建规范
53
+ You: /ralphy:plan 添加 JWT 用户认证
54
+
55
+ # 2. 实现:AI 迭代构建
56
+ You: /ralphy:implement add-user-auth
57
+
58
+ # 3. 验证:确保测试通过
59
+ You: /ralphy:validate
60
+
61
+ # 4. 归档:完成变更
62
+ You: /ralphy:archive add-user-auth
63
+ ```
64
+
65
+ ## 创建的文件
66
+
67
+ ```
68
+ .cursor/prompts/ # 或 .claude/commands/
69
+ ├── ralphy-plan.md
70
+ ├── ralphy-implement.md
71
+ ├── ralphy-validate.md
72
+ └── ralphy-archive.md
73
+
74
+ AGENTS.md # OpenCode 使用
75
+
76
+ openspec/
77
+ ├── specs/ # 真实来源
78
+ ├── changes/ # 进行中的工作
79
+ ├── archive/ # 已完成
80
+ └── project.md # 上下文
81
+
82
+ .ralphy/
83
+ ├── config.json
84
+ └── ralph-loop.state.json
85
+ ```
86
+
87
+ ## 工作原理
88
+
89
+ **Ralph Wiggum 循环:** AI 重复接收相同提示直到任务完成。每次迭代,它都能看到文件中的之前工作并自我纠正。
90
+
91
+ **OpenSpec:** 先有规范后有代码。结构化的规范和验收标准确保 AI 知道要构建什么。
92
+
93
+ **为什么结合使用:**
94
+
95
+ | 问题 | 解决方案 |
96
+ |------|----------|
97
+ | 聊天中的模糊需求 | 规范锁定意图 |
98
+ | AI 中途停止 | 循环重试直到完成 |
99
+ | 无法验证 | 测试验证输出 |
100
+ | 工具特定设置 | 一条命令搞定所有 |
101
+
102
+ ## 安装选项
103
+
104
+ ```bash
105
+ # npx(推荐)
106
+ npx ralphy-spec init
107
+
108
+ # 全局安装
109
+ npm install -g ralphy-spec
110
+ ralphy-spec init
111
+
112
+ # 指定工具
113
+ ralphy-spec init --tools cursor,claude-code,opencode
114
+ ```
115
+
116
+ ## 致谢
117
+
118
+ 基于以下项目:
119
+
120
+ - **[Ralph 方法论](https://ghuntley.com/ralph)** by Geoffrey Huntley
121
+ - **[opencode-ralph-wiggum](https://github.com/Th0rgal/opencode-ralph-wiggum)** by @Th0rgal
122
+ - **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission-AI
123
+
124
+ ## 许可证
125
+
126
+ BSD-3-Clause
File without changes
@@ -0,0 +1,3 @@
1
+ import type { Command } from "commander";
2
+ export declare function registerCheckpointCommand(program: Command): void;
3
+ //# sourceMappingURL=checkpoint.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/cli/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAahE"}
@@ -0,0 +1,23 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.registerCheckpointCommand = registerCheckpointCommand;
7
+ const node_path_1 = __importDefault(require("node:path"));
8
+ const patch_mode_1 = require("../core/workspace/patch-mode");
9
+ function registerCheckpointCommand(program) {
10
+ program
11
+ .command("checkpoint")
12
+ .description("Create a manual checkpoint commit (patch-mode only)")
13
+ .requiredOption("--task <taskId>", "Task id")
14
+ .requiredOption("--message <message>", "Checkpoint message")
15
+ .action(async (opts) => {
16
+ const repoRoot = process.cwd();
17
+ const ws = new patch_mode_1.PatchModeWorkspace(node_path_1.default.resolve(repoRoot));
18
+ await ws.prepare(opts.task);
19
+ const ref = await ws.checkpoint(opts.task, opts.message);
20
+ process.stdout.write(`Checkpoint ${ref.ref}\n`);
21
+ });
22
+ }
23
+ //# sourceMappingURL=checkpoint.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/cli/checkpoint.ts"],"names":[],"mappings":";;;;;AAIA,8DAaC;AAhBD,0DAA6B;AAC7B,6DAAkE;AAElE,SAAgB,yBAAyB,CAAC,OAAgB;IACxD,OAAO;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,WAAW,CAAC,qDAAqD,CAAC;SAClE,cAAc,CAAC,iBAAiB,EAAE,SAAS,CAAC;SAC5C,cAAc,CAAC,qBAAqB,EAAE,oBAAoB,CAAC;SAC3D,MAAM,CAAC,KAAK,EAAE,IAAuC,EAAE,EAAE;QACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,IAAI,+BAAkB,CAAC,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1D,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACP,CAAC"}
@@ -0,0 +1,3 @@
1
+ import type { Command } from "commander";
2
+ export declare function registerInitCommand(program: Command): void;
3
+ //# sourceMappingURL=init.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkC1D"}