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.
- package/README.ja.md +126 -0
- package/README.ko.md +126 -0
- package/README.md +77 -133
- package/README.zh.md +126 -0
- package/bin/ralphy-spec.js +0 -0
- package/dist/cli/checkpoint.d.ts +3 -0
- package/dist/cli/checkpoint.d.ts.map +1 -0
- package/dist/cli/checkpoint.js +23 -0
- package/dist/cli/checkpoint.js.map +1 -0
- package/dist/cli/init.d.ts +3 -0
- package/dist/cli/init.d.ts.map +1 -0
- package/dist/cli/init.js +66 -0
- package/dist/cli/init.js.map +1 -0
- package/dist/cli/report.d.ts +3 -0
- package/dist/cli/report.d.ts.map +1 -0
- package/dist/cli/report.js +53 -0
- package/dist/cli/report.js.map +1 -0
- package/dist/cli/run.d.ts +3 -0
- package/dist/cli/run.d.ts.map +1 -0
- package/dist/cli/run.js +79 -0
- package/dist/cli/run.js.map +1 -0
- package/dist/cli/status.d.ts +3 -0
- package/dist/cli/status.d.ts.map +1 -0
- package/dist/cli/status.js +45 -0
- package/dist/cli/status.js.map +1 -0
- package/dist/cli/tail.d.ts +3 -0
- package/dist/cli/tail.d.ts.map +1 -0
- package/dist/cli/tail.js +46 -0
- package/dist/cli/tail.js.map +1 -0
- package/dist/cli/update.d.ts +3 -0
- package/dist/cli/update.d.ts.map +1 -0
- package/dist/cli/update.js +62 -0
- package/dist/cli/update.js.map +1 -0
- package/dist/cli/validate.d.ts +3 -0
- package/dist/cli/validate.d.ts.map +1 -0
- package/dist/cli/validate.js +83 -0
- package/dist/cli/validate.js.map +1 -0
- package/dist/core/backends/claude-code.d.ts +17 -0
- package/dist/core/backends/claude-code.d.ts.map +1 -0
- package/dist/core/backends/claude-code.js +75 -0
- package/dist/core/backends/claude-code.js.map +1 -0
- package/dist/core/backends/cursor.d.ts +17 -0
- package/dist/core/backends/cursor.d.ts.map +1 -0
- package/dist/core/backends/cursor.js +75 -0
- package/dist/core/backends/cursor.js.map +1 -0
- package/dist/core/backends/noop.d.ts +10 -0
- package/dist/core/backends/noop.d.ts.map +1 -0
- package/dist/core/backends/noop.js +17 -0
- package/dist/core/backends/noop.js.map +1 -0
- package/dist/core/backends/opencode.d.ts +16 -0
- package/dist/core/backends/opencode.d.ts.map +1 -0
- package/dist/core/backends/opencode.js +73 -0
- package/dist/core/backends/opencode.js.map +1 -0
- package/dist/core/backends/types.d.ts +21 -0
- package/dist/core/backends/types.d.ts.map +1 -0
- package/dist/core/backends/types.js +3 -0
- package/dist/core/backends/types.js.map +1 -0
- package/dist/core/budgets/manager.d.ts +21 -0
- package/dist/core/budgets/manager.d.ts.map +1 -0
- package/dist/core/budgets/manager.js +48 -0
- package/dist/core/budgets/manager.js.map +1 -0
- package/dist/core/budgets/state.d.ts +25 -0
- package/dist/core/budgets/state.d.ts.map +1 -0
- package/dist/core/budgets/state.js +33 -0
- package/dist/core/budgets/state.js.map +1 -0
- package/dist/core/budgets/tiers.d.ts +32 -0
- package/dist/core/budgets/tiers.d.ts.map +1 -0
- package/dist/core/budgets/tiers.js +67 -0
- package/dist/core/budgets/tiers.js.map +1 -0
- package/dist/core/engine/context-pack.d.ts +12 -0
- package/dist/core/engine/context-pack.d.ts.map +1 -0
- package/dist/core/engine/context-pack.js +45 -0
- package/dist/core/engine/context-pack.js.map +1 -0
- package/dist/core/engine/loop.d.ts +28 -0
- package/dist/core/engine/loop.d.ts.map +1 -0
- package/dist/core/engine/loop.js +366 -0
- package/dist/core/engine/loop.js.map +1 -0
- package/dist/core/engine/phases.d.ts +2 -0
- package/dist/core/engine/phases.d.ts.map +1 -0
- package/dist/core/engine/phases.js +3 -0
- package/dist/core/engine/phases.js.map +1 -0
- package/dist/core/engine/repair.d.ts +6 -0
- package/dist/core/engine/repair.d.ts.map +1 -0
- package/dist/core/engine/repair.js +23 -0
- package/dist/core/engine/repair.js.map +1 -0
- package/dist/core/folders.d.ts +26 -0
- package/dist/core/folders.d.ts.map +1 -0
- package/dist/core/folders.js +58 -0
- package/dist/core/folders.js.map +1 -0
- package/dist/core/memory/ledger.d.ts +13 -0
- package/dist/core/memory/ledger.d.ts.map +1 -0
- package/dist/core/memory/ledger.js +24 -0
- package/dist/core/memory/ledger.js.map +1 -0
- package/dist/core/memory/persistence.d.ts +45 -0
- package/dist/core/memory/persistence.d.ts.map +1 -0
- package/dist/core/memory/persistence.js +162 -0
- package/dist/core/memory/persistence.js.map +1 -0
- package/dist/core/reporting/spend.d.ts +40 -0
- package/dist/core/reporting/spend.d.ts.map +1 -0
- package/dist/core/reporting/spend.js +157 -0
- package/dist/core/reporting/spend.js.map +1 -0
- package/dist/core/spec/dag.d.ts +7 -0
- package/dist/core/spec/dag.d.ts.map +1 -0
- package/dist/core/spec/dag.js +65 -0
- package/dist/core/spec/dag.js.map +1 -0
- package/dist/core/spec/file-contract.d.ts +13 -0
- package/dist/core/spec/file-contract.d.ts.map +1 -0
- package/dist/core/spec/file-contract.js +29 -0
- package/dist/core/spec/file-contract.js.map +1 -0
- package/dist/core/spec/loader.d.ts +8 -0
- package/dist/core/spec/loader.d.ts.map +1 -0
- package/dist/core/spec/loader.js +51 -0
- package/dist/core/spec/loader.js.map +1 -0
- package/dist/core/spec/schemas.d.ts +278 -0
- package/dist/core/spec/schemas.d.ts.map +1 -0
- package/dist/core/spec/schemas.js +207 -0
- package/dist/core/spec/schemas.js.map +1 -0
- package/dist/core/spec/types.d.ts +71 -0
- package/dist/core/spec/types.d.ts.map +1 -0
- package/dist/core/spec/types.js +3 -0
- package/dist/core/spec/types.js.map +1 -0
- package/dist/core/validators/parsers/eslint.d.ts +3 -0
- package/dist/core/validators/parsers/eslint.d.ts.map +1 -0
- package/dist/core/validators/parsers/eslint.js +35 -0
- package/dist/core/validators/parsers/eslint.js.map +1 -0
- package/dist/core/validators/parsers/jest.d.ts +3 -0
- package/dist/core/validators/parsers/jest.d.ts.map +1 -0
- package/dist/core/validators/parsers/jest.js +16 -0
- package/dist/core/validators/parsers/jest.js.map +1 -0
- package/dist/core/validators/parsers/tsc.d.ts +3 -0
- package/dist/core/validators/parsers/tsc.d.ts.map +1 -0
- package/dist/core/validators/parsers/tsc.js +32 -0
- package/dist/core/validators/parsers/tsc.js.map +1 -0
- package/dist/core/validators/runner.d.ts +8 -0
- package/dist/core/validators/runner.d.ts.map +1 -0
- package/dist/core/validators/runner.js +85 -0
- package/dist/core/validators/runner.js.map +1 -0
- package/dist/core/validators/signatures.d.ts +3 -0
- package/dist/core/validators/signatures.d.ts.map +1 -0
- package/dist/core/validators/signatures.js +10 -0
- package/dist/core/validators/signatures.js.map +1 -0
- package/dist/core/validators/types.d.ts +27 -0
- package/dist/core/validators/types.d.ts.map +1 -0
- package/dist/core/validators/types.js +3 -0
- package/dist/core/validators/types.js.map +1 -0
- package/dist/core/workspace/contract-enforcer.d.ts +54 -0
- package/dist/core/workspace/contract-enforcer.d.ts.map +1 -0
- package/dist/core/workspace/contract-enforcer.js +128 -0
- package/dist/core/workspace/contract-enforcer.js.map +1 -0
- package/dist/core/workspace/manager.d.ts +28 -0
- package/dist/core/workspace/manager.d.ts.map +1 -0
- package/dist/core/workspace/manager.js +3 -0
- package/dist/core/workspace/manager.js.map +1 -0
- package/dist/core/workspace/merge.d.ts +38 -0
- package/dist/core/workspace/merge.d.ts.map +1 -0
- package/dist/core/workspace/merge.js +92 -0
- package/dist/core/workspace/merge.js.map +1 -0
- package/dist/core/workspace/patch-mode.d.ts +22 -0
- package/dist/core/workspace/patch-mode.d.ts.map +1 -0
- package/dist/core/workspace/patch-mode.js +91 -0
- package/dist/core/workspace/patch-mode.js.map +1 -0
- package/dist/core/workspace/worktree-mode.d.ts +28 -0
- package/dist/core/workspace/worktree-mode.d.ts.map +1 -0
- package/dist/core/workspace/worktree-mode.js +156 -0
- package/dist/core/workspace/worktree-mode.js.map +1 -0
- package/dist/index.js +14 -4
- package/dist/index.js.map +1 -1
- package/dist/templates/claude-code/ralphy-archive.md +22 -0
- package/dist/templates/claude-code/ralphy-implement.md +30 -0
- package/dist/templates/claude-code/ralphy-plan.md +31 -0
- package/dist/templates/claude-code/ralphy-validate.md +21 -0
- package/dist/templates/cursor/ralphy-archive.md +20 -0
- package/dist/templates/cursor/ralphy-implement.md +31 -0
- package/dist/templates/cursor/ralphy-plan.md +39 -0
- package/dist/templates/cursor/ralphy-validate.md +24 -0
- package/dist/templates/opencode/AGENTS.md +46 -0
- package/dist/templates/shared/openspec-tasks-template.md +48 -0
- package/dist/templates/shared/project-template.yml +232 -0
- package/dist/templates/shared/ralph-loop-prompt-template.md +25 -0
- package/dist/utils/installer.d.ts.map +1 -1
- package/dist/utils/installer.js +31 -1
- package/dist/utils/installer.js.map +1 -1
- package/dist/utils/validator.d.ts.map +1 -1
- package/dist/utils/validator.js +10 -0
- package/dist/utils/validator.js.map +1 -1
- package/package.json +14 -4
- 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
|
-
|
|
4
|
-
- Cursor
|
|
5
|
-
- OpenCode
|
|
6
|
-
- Claude Code
|
|
3
|
+
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
|
|
7
4
|
|
|
8
|
-
**
|
|
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
|
-
|
|
61
|
-
npm install -g ralphy-spec
|
|
62
|
-
```
|
|
7
|
+
**Website:** [https://ralphy-spec.org](https://ralphy-spec.org)
|
|
63
8
|
|
|
64
|
-
|
|
9
|
+
## Quick Start
|
|
65
10
|
|
|
66
11
|
```bash
|
|
67
12
|
npx ralphy-spec init
|
|
68
13
|
```
|
|
69
14
|
|
|
70
|
-
|
|
15
|
+
Then use the commands for your AI tool:
|
|
71
16
|
|
|
72
|
-
|
|
73
|
-
curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
|
|
74
|
-
```
|
|
17
|
+
### Cursor
|
|
75
18
|
|
|
76
|
-
|
|
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
|
-
###
|
|
26
|
+
### Claude Code
|
|
79
27
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
ralphy
|
|
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
|
-
|
|
35
|
+
### OpenCode
|
|
86
36
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
49
|
+
## Example Workflow
|
|
98
50
|
|
|
99
51
|
```bash
|
|
100
|
-
|
|
101
|
-
|
|
52
|
+
# 1. Plan: Create spec from your idea
|
|
53
|
+
You: /ralphy:plan Add user authentication with JWT
|
|
102
54
|
|
|
103
|
-
|
|
55
|
+
# 2. Implement: AI builds it iteratively
|
|
56
|
+
You: /ralphy:implement add-user-auth
|
|
104
57
|
|
|
105
|
-
|
|
106
|
-
ralphy
|
|
107
|
-
```
|
|
58
|
+
# 3. Validate: Verify tests pass
|
|
59
|
+
You: /ralphy:validate
|
|
108
60
|
|
|
109
|
-
|
|
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
|
-
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
Use `/ralphy:implement` to implement tasks and add tests.
|
|
74
|
+
AGENTS.md # For OpenCode
|
|
139
75
|
|
|
140
|
-
|
|
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
|
-
|
|
87
|
+
## How It Works
|
|
149
88
|
|
|
150
|
-
|
|
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
|
-
|
|
91
|
+
**OpenSpec:** Specs before code. Structured specifications with acceptance criteria ensure AI knows exactly what to build.
|
|
153
92
|
|
|
154
|
-
|
|
93
|
+
**The Combination:**
|
|
155
94
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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
|
-
|
|
102
|
+
## Installation Options
|
|
163
103
|
|
|
164
|
-
|
|
104
|
+
```bash
|
|
105
|
+
# npx (recommended)
|
|
106
|
+
npx ralphy-spec init
|
|
165
107
|
|
|
166
|
-
|
|
108
|
+
# Global install
|
|
109
|
+
npm install -g ralphy-spec
|
|
110
|
+
ralphy-spec init
|
|
167
111
|
|
|
168
|
-
|
|
112
|
+
# With specific tools
|
|
113
|
+
ralphy-spec init --tools cursor,claude-code,opencode
|
|
114
|
+
```
|
|
169
115
|
|
|
170
|
-
|
|
116
|
+
## Credits
|
|
171
117
|
|
|
172
|
-
|
|
118
|
+
Built on the work of:
|
|
173
119
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
package/bin/ralphy-spec.js
CHANGED
|
File without changes
|
|
@@ -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 @@
|
|
|
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"}
|