ralphy-spec 0.1.1 → 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 +74 -130
- package/README.ko.md +74 -130
- package/README.md +75 -133
- package/README.zh.md +74 -130
- 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/shared/openspec-tasks-template.md +23 -3
- package/dist/templates/shared/project-template.yml +232 -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 +11 -4
package/README.md
CHANGED
|
@@ -2,182 +2,124 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- Cursor
|
|
7
|
-
- OpenCode
|
|
8
|
-
- Claude Code
|
|
5
|
+
**Spec-driven AI development with iterative execution.** Combines OpenSpec + Ralph Loop for predictable AI-assisted coding.
|
|
9
6
|
|
|
10
7
|
**Website:** [https://ralphy-spec.org](https://ralphy-spec.org)
|
|
11
8
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
Ralphy-Spec combines two powerful AI development methodologies:
|
|
15
|
-
|
|
16
|
-
### The Ralph Wiggum Loop
|
|
17
|
-
|
|
18
|
-
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.
|
|
19
|
-
|
|
20
|
-
```
|
|
21
|
-
while true; do
|
|
22
|
-
ai_agent "Build feature X. Output <promise>DONE</promise> when complete."
|
|
23
|
-
# AI sees previous work, fixes mistakes, continues progress
|
|
24
|
-
done
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
### OpenSpec (Spec-Driven Development)
|
|
28
|
-
|
|
29
|
-
[OpenSpec](https://github.com/Fission-AI/OpenSpec) brings structure to AI coding by requiring specs before code:
|
|
30
|
-
- `openspec/specs/` - Source of truth specifications
|
|
31
|
-
- `openspec/changes/` - Proposed changes with acceptance criteria
|
|
32
|
-
- Archive workflow to merge completed changes back
|
|
33
|
-
|
|
34
|
-
### Why Combine Them?
|
|
35
|
-
|
|
36
|
-
| Problem | Solution |
|
|
37
|
-
|---------|----------|
|
|
38
|
-
| Vague requirements in chat history | OpenSpec locks intent in structured specs |
|
|
39
|
-
| AI stops mid-task or makes mistakes | Ralph loop retries until completion |
|
|
40
|
-
| No way to verify correctness | Acceptance criteria + tests validate output |
|
|
41
|
-
| Tool-specific setup is tedious | One command sets up Cursor, OpenCode, Claude Code |
|
|
42
|
-
|
|
43
|
-
## What it installs into your project
|
|
44
|
-
|
|
45
|
-
- `openspec/` scaffold:
|
|
46
|
-
- `openspec/specs/` (source of truth)
|
|
47
|
-
- `openspec/changes/` (active changes)
|
|
48
|
-
- `openspec/archive/` (completed changes)
|
|
49
|
-
- `openspec/project.md` (project context)
|
|
50
|
-
- Tool integrations:
|
|
51
|
-
- Cursor: `.cursor/prompts/ralphy-*.md`
|
|
52
|
-
- Claude Code: `.claude/commands/ralphy-*.md`
|
|
53
|
-
- OpenCode: `AGENTS.md`
|
|
54
|
-
- Ralph loop state/config:
|
|
55
|
-
- `.ralphy/config.json`
|
|
56
|
-
- `.ralphy/ralph-loop.state.json`
|
|
57
|
-
|
|
58
|
-
## Installation
|
|
59
|
-
|
|
60
|
-
### npm (global)
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
npm install -g ralphy-spec
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### npx (no install)
|
|
9
|
+
## Quick Start
|
|
67
10
|
|
|
68
11
|
```bash
|
|
69
12
|
npx ralphy-spec init
|
|
70
13
|
```
|
|
71
14
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
|
|
76
|
-
```
|
|
15
|
+
Then use the commands for your AI tool:
|
|
77
16
|
|
|
78
|
-
|
|
17
|
+
### Cursor
|
|
79
18
|
|
|
80
|
-
|
|
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 |
|
|
81
25
|
|
|
82
|
-
|
|
83
|
-
cd your-project
|
|
84
|
-
ralphy-spec init
|
|
85
|
-
```
|
|
26
|
+
### Claude Code
|
|
86
27
|
|
|
87
|
-
|
|
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 |
|
|
88
34
|
|
|
89
|
-
|
|
90
|
-
ralphy-spec init --tools cursor,claude-code,opencode
|
|
91
|
-
```
|
|
35
|
+
### OpenCode
|
|
92
36
|
|
|
93
|
-
|
|
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]"`
|
|
94
42
|
|
|
43
|
+
**With Ralph Loop Runner:**
|
|
95
44
|
```bash
|
|
96
|
-
|
|
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
|
|
97
47
|
```
|
|
98
48
|
|
|
99
|
-
|
|
49
|
+
## Example Workflow
|
|
100
50
|
|
|
101
51
|
```bash
|
|
102
|
-
|
|
103
|
-
|
|
52
|
+
# 1. Plan: Create spec from your idea
|
|
53
|
+
You: /ralphy:plan Add user authentication with JWT
|
|
104
54
|
|
|
105
|
-
|
|
55
|
+
# 2. Implement: AI builds it iteratively
|
|
56
|
+
You: /ralphy:implement add-user-auth
|
|
106
57
|
|
|
107
|
-
|
|
108
|
-
ralphy
|
|
109
|
-
```
|
|
58
|
+
# 3. Validate: Verify tests pass
|
|
59
|
+
You: /ralphy:validate
|
|
110
60
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
```
|
|
114
|
-
PRD/Requirements --> OpenSpec (specs + tasks + acceptance criteria)
|
|
115
|
-
|
|
|
116
|
-
v
|
|
117
|
-
Ralph Loop (iterate until tests pass)
|
|
118
|
-
|
|
|
119
|
-
v
|
|
120
|
-
Archive (merge back to source specs)
|
|
61
|
+
# 4. Archive: Complete the change
|
|
62
|
+
You: /ralphy:archive add-user-auth
|
|
121
63
|
```
|
|
122
64
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
Use your AI tool with `/ralphy:plan` (Cursor / Claude Code), or ask OpenCode to follow `AGENTS.md`.
|
|
65
|
+
## What Gets Created
|
|
126
66
|
|
|
127
|
-
Expected output in your repo:
|
|
128
|
-
|
|
129
|
-
```
|
|
130
|
-
openspec/changes/<change-name>/
|
|
131
|
-
proposal.md
|
|
132
|
-
tasks.md
|
|
133
|
-
specs/
|
|
134
|
-
<domain>/
|
|
135
|
-
spec.md
|
|
136
67
|
```
|
|
68
|
+
.cursor/prompts/ # or .claude/commands/
|
|
69
|
+
├── ralphy-plan.md
|
|
70
|
+
├── ralphy-implement.md
|
|
71
|
+
├── ralphy-validate.md
|
|
72
|
+
└── ralphy-archive.md
|
|
137
73
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
Use `/ralphy:implement` to implement tasks and add tests.
|
|
74
|
+
AGENTS.md # For OpenCode
|
|
141
75
|
|
|
142
|
-
|
|
76
|
+
openspec/
|
|
77
|
+
├── specs/ # Source of truth
|
|
78
|
+
├── changes/ # Active work
|
|
79
|
+
├── archive/ # Completed
|
|
80
|
+
└── project.md # Context
|
|
143
81
|
|
|
82
|
+
.ralphy/
|
|
83
|
+
├── config.json
|
|
84
|
+
└── ralph-loop.state.json
|
|
144
85
|
```
|
|
145
|
-
<promise>TASK_COMPLETE</promise>
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
when **all tasks are done and tests pass**.
|
|
149
86
|
|
|
150
|
-
|
|
87
|
+
## How It Works
|
|
151
88
|
|
|
152
|
-
|
|
89
|
+
**Ralph Wiggum Loop:** AI receives the same prompt repeatedly until task completion. Each iteration, it sees previous work in files and self-corrects.
|
|
153
90
|
|
|
154
|
-
|
|
91
|
+
**OpenSpec:** Specs before code. Structured specifications with acceptance criteria ensure AI knows exactly what to build.
|
|
155
92
|
|
|
156
|
-
|
|
93
|
+
**The Combination:**
|
|
157
94
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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 |
|
|
163
101
|
|
|
164
|
-
|
|
102
|
+
## Installation Options
|
|
165
103
|
|
|
166
|
-
|
|
104
|
+
```bash
|
|
105
|
+
# npx (recommended)
|
|
106
|
+
npx ralphy-spec init
|
|
167
107
|
|
|
168
|
-
|
|
108
|
+
# Global install
|
|
109
|
+
npm install -g ralphy-spec
|
|
110
|
+
ralphy-spec init
|
|
169
111
|
|
|
170
|
-
|
|
112
|
+
# With specific tools
|
|
113
|
+
ralphy-spec init --tools cursor,claude-code,opencode
|
|
114
|
+
```
|
|
171
115
|
|
|
172
|
-
|
|
116
|
+
## Credits
|
|
173
117
|
|
|
174
|
-
|
|
118
|
+
Built on the work of:
|
|
175
119
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
node bin/ralphy-spec.js --help
|
|
180
|
-
```
|
|
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
|
|
181
123
|
|
|
182
124
|
## License
|
|
183
125
|
|
package/README.zh.md
CHANGED
|
@@ -2,180 +2,124 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | [简体中文](README.zh.md) | [한국어](README.ko.md) | [日本語](README.ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- Cursor
|
|
7
|
-
- OpenCode
|
|
8
|
-
- Claude Code
|
|
5
|
+
**规范驱动的 AI 开发 + 迭代执行。** 结合 OpenSpec 和 Ralph 循环,实现可预测的 AI 辅助编码。
|
|
9
6
|
|
|
10
7
|
**官网:** [https://ralphy-spec.org](https://ralphy-spec.org)
|
|
11
8
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
Ralphy-Spec 结合了两种强大的 AI 开发方法:
|
|
15
|
-
|
|
16
|
-
### Ralph Wiggum 循环
|
|
17
|
-
|
|
18
|
-
Ralph 方法论(由 [Geoffrey Huntley](https://ghuntley.com/ralph) 提出)是一种开发方式,AI 代理会**重复接收相同的提示**直到完成任务。每次迭代,AI 都能看到之前在文件和 git 历史中的工作成果,形成自我纠正的反馈循环。
|
|
19
|
-
|
|
20
|
-
```
|
|
21
|
-
while true; do
|
|
22
|
-
ai_agent "构建功能 X。完成后输出 <promise>DONE</promise>。"
|
|
23
|
-
# AI 看到之前的工作,修复错误,继续进展
|
|
24
|
-
done
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
### OpenSpec(规范驱动开发)
|
|
28
|
-
|
|
29
|
-
[OpenSpec](https://github.com/Fission-AI/OpenSpec) 通过在编码前要求规范来为 AI 编码带来结构:
|
|
30
|
-
- `openspec/specs/` - 真实来源的规范
|
|
31
|
-
- `openspec/changes/` - 带验收标准的变更提案
|
|
32
|
-
- 归档工作流将已完成的变更合并回来
|
|
33
|
-
|
|
34
|
-
### 为什么要结合使用?
|
|
35
|
-
|
|
36
|
-
| 问题 | 解决方案 |
|
|
37
|
-
|------|----------|
|
|
38
|
-
| 聊天记录中的需求模糊 | OpenSpec 将意图锁定在结构化规范中 |
|
|
39
|
-
| AI 中途停止或出错 | Ralph 循环重试直到完成 |
|
|
40
|
-
| 无法验证正确性 | 验收标准 + 测试验证输出 |
|
|
41
|
-
| 特定工具的设置很繁琐 | 一条命令设置 Cursor、OpenCode、Claude Code |
|
|
42
|
-
|
|
43
|
-
## 安装到项目中的内容
|
|
44
|
-
|
|
45
|
-
- `openspec/` 脚手架:
|
|
46
|
-
- `openspec/specs/`(真实来源)
|
|
47
|
-
- `openspec/changes/`(活跃变更)
|
|
48
|
-
- `openspec/archive/`(已完成的变更)
|
|
49
|
-
- `openspec/project.md`(项目上下文)
|
|
50
|
-
- 工具集成:
|
|
51
|
-
- Cursor:`.cursor/prompts/ralphy-*.md`
|
|
52
|
-
- Claude Code:`.claude/commands/ralphy-*.md`
|
|
53
|
-
- OpenCode:`AGENTS.md`
|
|
54
|
-
- Ralph 循环状态/配置:
|
|
55
|
-
- `.ralphy/config.json`
|
|
56
|
-
- `.ralphy/ralph-loop.state.json`
|
|
57
|
-
|
|
58
|
-
## 安装
|
|
59
|
-
|
|
60
|
-
### npm(全局安装)
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
npm install -g ralphy-spec
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### npx(无需安装)
|
|
9
|
+
## 快速开始
|
|
67
10
|
|
|
68
11
|
```bash
|
|
69
12
|
npx ralphy-spec init
|
|
70
13
|
```
|
|
71
14
|
|
|
72
|
-
|
|
15
|
+
然后使用你的 AI 工具对应的命令:
|
|
73
16
|
|
|
74
|
-
|
|
75
|
-
curl -fsSL https://raw.githubusercontent.com/anthropics/ralphy-openspec/main/scripts/install.sh | sh
|
|
76
|
-
```
|
|
17
|
+
### Cursor
|
|
77
18
|
|
|
78
|
-
|
|
19
|
+
| 命令 | 功能 |
|
|
20
|
+
|------|------|
|
|
21
|
+
| `/ralphy:plan` | 从需求创建规范 |
|
|
22
|
+
| `/ralphy:implement` | 迭代循环构建 |
|
|
23
|
+
| `/ralphy:validate` | 验证验收标准 |
|
|
24
|
+
| `/ralphy:archive` | 完成并归档 |
|
|
79
25
|
|
|
80
|
-
###
|
|
26
|
+
### Claude Code
|
|
81
27
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
ralphy
|
|
85
|
-
|
|
28
|
+
| 命令 | 功能 |
|
|
29
|
+
|------|------|
|
|
30
|
+
| `/ralphy:plan` | 从需求创建规范 |
|
|
31
|
+
| `/ralphy:implement` | 迭代循环构建 |
|
|
32
|
+
| `/ralphy:validate` | 验证验收标准 |
|
|
33
|
+
| `/ralphy:archive` | 完成并归档 |
|
|
86
34
|
|
|
87
|
-
|
|
35
|
+
### OpenCode
|
|
88
36
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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 [变更]"`
|
|
94
42
|
|
|
43
|
+
**配合 Ralph 循环运行器:**
|
|
95
44
|
```bash
|
|
96
|
-
|
|
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
|
|
97
47
|
```
|
|
98
48
|
|
|
99
|
-
|
|
49
|
+
## 工作流示例
|
|
100
50
|
|
|
101
51
|
```bash
|
|
102
|
-
|
|
103
|
-
|
|
52
|
+
# 1. 规划:从你的想法创建规范
|
|
53
|
+
You: /ralphy:plan 添加 JWT 用户认证
|
|
104
54
|
|
|
105
|
-
|
|
55
|
+
# 2. 实现:AI 迭代构建
|
|
56
|
+
You: /ralphy:implement add-user-auth
|
|
106
57
|
|
|
107
|
-
|
|
108
|
-
ralphy
|
|
58
|
+
# 3. 验证:确保测试通过
|
|
59
|
+
You: /ralphy:validate
|
|
60
|
+
|
|
61
|
+
# 4. 归档:完成变更
|
|
62
|
+
You: /ralphy:archive add-user-auth
|
|
109
63
|
```
|
|
110
64
|
|
|
111
|
-
##
|
|
65
|
+
## 创建的文件
|
|
112
66
|
|
|
113
67
|
```
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
v
|
|
120
|
-
归档(合并回源规范)
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
### 1)规划:PRD -> OpenSpec 变更
|
|
68
|
+
.cursor/prompts/ # 或 .claude/commands/
|
|
69
|
+
├── ralphy-plan.md
|
|
70
|
+
├── ralphy-implement.md
|
|
71
|
+
├── ralphy-validate.md
|
|
72
|
+
└── ralphy-archive.md
|
|
124
73
|
|
|
125
|
-
|
|
74
|
+
AGENTS.md # OpenCode 使用
|
|
126
75
|
|
|
127
|
-
|
|
76
|
+
openspec/
|
|
77
|
+
├── specs/ # 真实来源
|
|
78
|
+
├── changes/ # 进行中的工作
|
|
79
|
+
├── archive/ # 已完成
|
|
80
|
+
└── project.md # 上下文
|
|
128
81
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
tasks.md
|
|
133
|
-
specs/
|
|
134
|
-
<domain>/
|
|
135
|
-
spec.md
|
|
82
|
+
.ralphy/
|
|
83
|
+
├── config.json
|
|
84
|
+
└── ralph-loop.state.json
|
|
136
85
|
```
|
|
137
86
|
|
|
138
|
-
|
|
87
|
+
## 工作原理
|
|
139
88
|
|
|
140
|
-
|
|
89
|
+
**Ralph Wiggum 循环:** AI 重复接收相同提示直到任务完成。每次迭代,它都能看到文件中的之前工作并自我纠正。
|
|
141
90
|
|
|
142
|
-
|
|
91
|
+
**OpenSpec:** 先有规范后有代码。结构化的规范和验收标准确保 AI 知道要构建什么。
|
|
143
92
|
|
|
144
|
-
|
|
145
|
-
<promise>TASK_COMPLETE</promise>
|
|
146
|
-
```
|
|
93
|
+
**为什么结合使用:**
|
|
147
94
|
|
|
148
|
-
|
|
95
|
+
| 问题 | 解决方案 |
|
|
96
|
+
|------|----------|
|
|
97
|
+
| 聊天中的模糊需求 | 规范锁定意图 |
|
|
98
|
+
| AI 中途停止 | 循环重试直到完成 |
|
|
99
|
+
| 无法验证 | 测试验证输出 |
|
|
100
|
+
| 工具特定设置 | 一条命令搞定所有 |
|
|
149
101
|
|
|
150
|
-
|
|
102
|
+
## 安装选项
|
|
151
103
|
|
|
152
|
-
|
|
104
|
+
```bash
|
|
105
|
+
# npx(推荐)
|
|
106
|
+
npx ralphy-spec init
|
|
153
107
|
|
|
154
|
-
|
|
108
|
+
# 全局安装
|
|
109
|
+
npm install -g ralphy-spec
|
|
110
|
+
ralphy-spec init
|
|
155
111
|
|
|
156
|
-
|
|
157
|
-
|
|
112
|
+
# 指定工具
|
|
113
|
+
ralphy-spec init --tools cursor,claude-code,opencode
|
|
158
114
|
```
|
|
159
115
|
|
|
160
116
|
## 致谢
|
|
161
117
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
- **Ralph Wiggum 方法论** - 由 [Geoffrey Huntley](https://ghuntley.com/ralph) 构思。AI 代理可以通过迭代进行自我纠正的洞见改变了我们对 AI 辅助开发的看法。
|
|
118
|
+
基于以下项目:
|
|
165
119
|
|
|
166
|
-
- **[
|
|
167
|
-
|
|
168
|
-
- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by
|
|
169
|
-
|
|
170
|
-
我们感谢这些项目及其维护者开创了这些方法。
|
|
171
|
-
|
|
172
|
-
## 开发
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
npm install
|
|
176
|
-
npm run build
|
|
177
|
-
node bin/ralphy-spec.js --help
|
|
178
|
-
```
|
|
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
|
|
179
123
|
|
|
180
124
|
## 许可证
|
|
181
125
|
|
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"}
|
package/dist/cli/init.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
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.registerInitCommand = registerInitCommand;
|
|
7
|
+
const inquirer_1 = __importDefault(require("inquirer"));
|
|
8
|
+
const detector_1 = require("../utils/detector");
|
|
9
|
+
const installer_1 = require("../utils/installer");
|
|
10
|
+
const paths_1 = require("../utils/paths");
|
|
11
|
+
function parseToolsArg(arg) {
|
|
12
|
+
if (!arg)
|
|
13
|
+
return undefined;
|
|
14
|
+
const parts = arg
|
|
15
|
+
.split(",")
|
|
16
|
+
.map((s) => s.trim())
|
|
17
|
+
.filter(Boolean);
|
|
18
|
+
const allowed = ["cursor", "claude-code", "opencode"];
|
|
19
|
+
const tools = [];
|
|
20
|
+
for (const p of parts) {
|
|
21
|
+
if (allowed.includes(p))
|
|
22
|
+
tools.push(p);
|
|
23
|
+
}
|
|
24
|
+
return tools.length ? tools : undefined;
|
|
25
|
+
}
|
|
26
|
+
async function promptForTools(defaultTools) {
|
|
27
|
+
const { tools } = await inquirer_1.default.prompt([
|
|
28
|
+
{
|
|
29
|
+
type: "checkbox",
|
|
30
|
+
name: "tools",
|
|
31
|
+
message: "Which AI tools do you want to configure?",
|
|
32
|
+
choices: [
|
|
33
|
+
{ name: "Cursor", value: "cursor" },
|
|
34
|
+
{ name: "Claude Code", value: "claude-code" },
|
|
35
|
+
{ name: "OpenCode", value: "opencode" },
|
|
36
|
+
],
|
|
37
|
+
default: defaultTools,
|
|
38
|
+
},
|
|
39
|
+
]);
|
|
40
|
+
return tools;
|
|
41
|
+
}
|
|
42
|
+
function registerInitCommand(program) {
|
|
43
|
+
program
|
|
44
|
+
.command("init")
|
|
45
|
+
.description("Initialize Ralph + OpenSpec workflow files in a project")
|
|
46
|
+
.option("--dir <path>", "Target project directory (default: current directory)")
|
|
47
|
+
.option("--tools <list>", "Comma-separated list: cursor,claude-code,opencode")
|
|
48
|
+
.option("--force", "Overwrite existing files", false)
|
|
49
|
+
.action(async (opts) => {
|
|
50
|
+
const options = {
|
|
51
|
+
dir: (0, paths_1.resolveProjectDir)(opts.dir),
|
|
52
|
+
tools: parseToolsArg(opts.tools),
|
|
53
|
+
force: opts.force,
|
|
54
|
+
};
|
|
55
|
+
const detected = await (0, detector_1.detectExistingTools)(options.dir);
|
|
56
|
+
const defaultTools = options.tools ??
|
|
57
|
+
(detected.length
|
|
58
|
+
? detected
|
|
59
|
+
: ["cursor", "claude-code", "opencode"]);
|
|
60
|
+
const tools = options.tools ?? (await promptForTools(defaultTools));
|
|
61
|
+
await (0, installer_1.ensureOpenSpecScaffold)(options.dir);
|
|
62
|
+
await (0, installer_1.installToolTemplates)(options.dir, tools, { force: options.force });
|
|
63
|
+
process.stdout.write(`Initialized Ralph-OpenSpec in ${options.dir}\nConfigured tools: ${tools.join(", ")}\n`);
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
//# sourceMappingURL=init.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgD5D"}
|