@graypark/loophaus 3.4.1 → 3.5.1
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.ko.md +117 -77
- package/README.md +110 -74
- package/dist/.claude-plugin/plugin.json +11 -0
- package/dist/LICENSE +21 -0
- package/dist/README.ko.md +398 -0
- package/dist/README.md +318 -0
- package/dist/bin/install.d.ts +3 -0
- package/dist/bin/install.d.ts.map +1 -0
- package/{bin/install.mjs → dist/bin/install.js} +3 -5
- package/dist/bin/install.js.map +1 -0
- package/dist/bin/loophaus.d.ts +3 -0
- package/dist/bin/loophaus.d.ts.map +1 -0
- package/dist/bin/loophaus.js +654 -0
- package/dist/bin/loophaus.js.map +1 -0
- package/dist/bin/uninstall.d.ts +8 -0
- package/dist/bin/uninstall.d.ts.map +1 -0
- package/dist/bin/uninstall.js +209 -0
- package/dist/bin/uninstall.js.map +1 -0
- package/dist/codex/commands/cancel-ralph.md +30 -0
- package/dist/codex/commands/ralph-loop.md +73 -0
- package/dist/commands/cancel-ralph.md +23 -0
- package/dist/commands/help.md +96 -0
- package/dist/commands/loop-plan.md +257 -0
- package/dist/commands/loop-pulse.md +38 -0
- package/dist/commands/loop-stop.md +29 -0
- package/dist/commands/loop.md +17 -0
- package/dist/commands/ralph-loop.md +18 -0
- package/dist/core/cost-tracker.d.ts +33 -0
- package/dist/core/cost-tracker.d.ts.map +1 -0
- package/dist/core/cost-tracker.js +41 -0
- package/dist/core/cost-tracker.js.map +1 -0
- package/dist/core/engine.d.ts +4 -0
- package/dist/core/engine.d.ts.map +1 -0
- package/dist/core/engine.js +109 -0
- package/dist/core/engine.js.map +1 -0
- package/dist/core/event-logger.d.ts +5 -0
- package/dist/core/event-logger.d.ts.map +1 -0
- package/dist/core/event-logger.js +48 -0
- package/dist/core/event-logger.js.map +1 -0
- package/dist/core/events.d.ts +34 -0
- package/dist/core/events.d.ts.map +1 -0
- package/dist/core/events.js +44 -0
- package/dist/core/events.js.map +1 -0
- package/dist/core/io-helpers.d.ts +3 -0
- package/dist/core/io-helpers.d.ts.map +1 -0
- package/dist/core/io-helpers.js +65 -0
- package/dist/core/io-helpers.js.map +1 -0
- package/dist/core/loop-registry.d.ts +10 -0
- package/dist/core/loop-registry.d.ts.map +1 -0
- package/dist/core/loop-registry.js +37 -0
- package/dist/core/loop-registry.js.map +1 -0
- package/dist/core/merge-strategy.d.ts +7 -0
- package/dist/core/merge-strategy.d.ts.map +1 -0
- package/dist/core/merge-strategy.js +82 -0
- package/dist/core/merge-strategy.js.map +1 -0
- package/dist/core/parallel-runner.d.ts +32 -0
- package/dist/core/parallel-runner.d.ts.map +1 -0
- package/dist/core/parallel-runner.js +88 -0
- package/dist/core/parallel-runner.js.map +1 -0
- package/dist/core/policy.d.ts +22 -0
- package/dist/core/policy.d.ts.map +1 -0
- package/dist/core/policy.js +54 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/quality-scorer.d.ts +40 -0
- package/dist/core/quality-scorer.d.ts.map +1 -0
- package/dist/core/quality-scorer.js +128 -0
- package/dist/core/quality-scorer.js.map +1 -0
- package/dist/core/refine-loop.d.ts +16 -0
- package/dist/core/refine-loop.d.ts.map +1 -0
- package/dist/core/refine-loop.js +26 -0
- package/dist/core/refine-loop.js.map +1 -0
- package/dist/core/session.d.ts +27 -0
- package/dist/core/session.d.ts.map +1 -0
- package/dist/core/session.js +67 -0
- package/dist/core/session.js.map +1 -0
- package/dist/core/trace-analyzer.d.ts +28 -0
- package/dist/core/trace-analyzer.d.ts.map +1 -0
- package/dist/core/trace-analyzer.js +46 -0
- package/dist/core/trace-analyzer.js.map +1 -0
- package/dist/core/types.d.ts +99 -0
- package/dist/core/types.d.ts.map +1 -0
- package/dist/core/types.js +2 -0
- package/dist/core/types.js.map +1 -0
- package/dist/core/validate.d.ts +7 -0
- package/dist/core/validate.d.ts.map +1 -0
- package/dist/core/validate.js +55 -0
- package/dist/core/validate.js.map +1 -0
- package/dist/core/worktree.d.ts +13 -0
- package/dist/core/worktree.d.ts.map +1 -0
- package/dist/core/worktree.js +108 -0
- package/dist/core/worktree.js.map +1 -0
- package/dist/hooks/hooks.json +15 -0
- package/dist/hooks/stop-hook.mjs +111 -0
- package/dist/lib/paths.d.ts +18 -0
- package/dist/lib/paths.d.ts.map +1 -0
- package/dist/lib/paths.js +74 -0
- package/dist/lib/paths.js.map +1 -0
- package/dist/lib/stop-hook-core.d.ts +19 -0
- package/dist/lib/stop-hook-core.d.ts.map +1 -0
- package/dist/lib/stop-hook-core.js +36 -0
- package/dist/lib/stop-hook-core.js.map +1 -0
- package/dist/package.json +61 -0
- package/dist/platforms/claude-code/adapter.mjs +20 -0
- package/dist/platforms/claude-code/installer.d.mts +3 -0
- package/dist/platforms/claude-code/installer.mjs +173 -0
- package/dist/platforms/codex-cli/adapter.mjs +20 -0
- package/dist/platforms/codex-cli/installer.d.mts +2 -0
- package/dist/platforms/codex-cli/installer.mjs +247 -0
- package/dist/platforms/kiro-cli/adapter.mjs +21 -0
- package/dist/platforms/kiro-cli/installer.d.mts +3 -0
- package/dist/platforms/kiro-cli/installer.mjs +257 -0
- package/dist/scripts/setup-ralph-loop.sh +145 -0
- package/dist/skills/ralph-claude-cancel/SKILL.md +23 -0
- package/dist/skills/ralph-claude-interview/SKILL.md +184 -0
- package/dist/skills/ralph-claude-loop/SKILL.md +101 -0
- package/dist/skills/ralph-claude-orchestrator/SKILL.md +129 -0
- package/dist/skills/ralph-interview/SKILL.md +275 -0
- package/dist/skills/ralph-orchestrator/SKILL.md +254 -0
- package/dist/store/state-store.d.ts +17 -0
- package/dist/store/state-store.d.ts.map +1 -0
- package/dist/store/state-store.js +108 -0
- package/dist/store/state-store.js.map +1 -0
- package/hooks/stop-hook.mjs +6 -6
- package/package.json +11 -7
- package/platforms/claude-code/installer.d.mts +3 -0
- package/platforms/claude-code/installer.mjs +2 -2
- package/platforms/codex-cli/installer.d.mts +2 -0
- package/platforms/codex-cli/installer.mjs +1 -1
- package/platforms/kiro-cli/installer.d.mts +3 -0
- package/bin/loophaus.mjs +0 -521
- package/bin/uninstall.mjs +0 -255
- package/core/cost-tracker.mjs +0 -44
- package/core/engine.mjs +0 -123
- package/core/event-logger.mjs +0 -37
- package/core/events.mjs +0 -48
- package/core/io-helpers.mjs +0 -33
- package/core/loop-registry.mjs +0 -37
- package/core/loop.schema.json +0 -29
- package/core/merge-strategy.mjs +0 -72
- package/core/parallel-runner.mjs +0 -94
- package/core/policy.mjs +0 -58
- package/core/quality-scorer.mjs +0 -136
- package/core/refine-loop.mjs +0 -29
- package/core/session.mjs +0 -66
- package/core/state.schema.json +0 -24
- package/core/trace-analyzer.mjs +0 -51
- package/core/validate.mjs +0 -54
- package/core/worktree.mjs +0 -97
- package/lib/paths.mjs +0 -99
- package/lib/stop-hook-core.mjs +0 -42
- package/store/state-store.mjs +0 -106
package/README.ko.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
<a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
|
|
11
11
|
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
|
|
12
12
|
<img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
|
|
13
|
-
<img src="https://img.shields.io/badge/tests-
|
|
13
|
+
<img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
16
|
<p align="center">
|
|
@@ -60,8 +60,10 @@ AI 에이전트가 연속 루프에서 태스크를 수행합니다. 매 반복
|
|
|
60
60
|
│ 1. prd.json + progress 읽기 │
|
|
61
61
|
│ 2. 다음 스토리 선택 (passes=false)│
|
|
62
62
|
│ 3. 구현 + 검증 │
|
|
63
|
-
│ 4.
|
|
64
|
-
│ 5.
|
|
63
|
+
│ 4. 품질 측정 (score 0-100) │
|
|
64
|
+
│ 5. 개선 루프 (유지/폐기) │
|
|
65
|
+
│ 6. 커밋 + progress 업데이트 │
|
|
66
|
+
│ 7. 종료 시도 │
|
|
65
67
|
│ │ │
|
|
66
68
|
│ Stop Hook이 가로채기 │
|
|
67
69
|
│ 프롬프트 재주입 │
|
|
@@ -76,9 +78,12 @@ AI 에이전트가 연속 루프에서 태스크를 수행합니다. 매 반복
|
|
|
76
78
|
## 빠른 시작
|
|
77
79
|
|
|
78
80
|
```bash
|
|
79
|
-
|
|
81
|
+
npm install -g @graypark/loophaus
|
|
82
|
+
loophaus install
|
|
80
83
|
```
|
|
81
84
|
|
|
85
|
+
> **참고:** `npx @graypark/loophaus install`은 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 위의 글로벌 설치 방식을 권장합니다.
|
|
86
|
+
|
|
82
87
|
이후 AI 코딩 세션에서:
|
|
83
88
|
|
|
84
89
|
```
|
|
@@ -151,26 +156,33 @@ loophaus는 세 개의 주요 코딩 에이전트 플랫폼을 지원합니다:
|
|
|
151
156
|
| Stop hook | bash 기반 | Node.js 기반 | bash 기반 |
|
|
152
157
|
| 루프 실행 | Skill tool | 네이티브 커맨드 | 네이티브 커맨드 |
|
|
153
158
|
| 멀티 에이전트 | Agent tool | 서브에이전트 | 서브에이전트 |
|
|
154
|
-
| 상태 파일 | `.
|
|
159
|
+
| 상태 파일 | `.loophaus/state.json` | `.loophaus/state.json` | `.loophaus/state.json` |
|
|
155
160
|
|
|
156
161
|
## 설치
|
|
157
162
|
|
|
158
|
-
###
|
|
163
|
+
### 글로벌 설치 (권장)
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
npm install -g @graypark/loophaus
|
|
167
|
+
loophaus install
|
|
168
|
+
```
|
|
159
169
|
|
|
160
|
-
|
|
170
|
+
### npx로 설치
|
|
161
171
|
|
|
162
172
|
```bash
|
|
163
173
|
npx @graypark/loophaus install
|
|
164
174
|
```
|
|
165
175
|
|
|
176
|
+
> `npx`는 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 실패 시 위의 글로벌 설치를 사용하세요.
|
|
177
|
+
|
|
166
178
|
### 호스트별 설치
|
|
167
179
|
|
|
168
180
|
특정 호스트만 대상으로 설치:
|
|
169
181
|
|
|
170
182
|
```bash
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
183
|
+
loophaus install --claude # Claude Code만
|
|
184
|
+
loophaus install --host codex-cli # Codex CLI만
|
|
185
|
+
loophaus install --kiro # Kiro CLI만
|
|
174
186
|
```
|
|
175
187
|
|
|
176
188
|
| 플래그 | 설명 |
|
|
@@ -201,55 +213,110 @@ npx @graypark/loophaus install --kiro # Kiro CLI만
|
|
|
201
213
|
## CLI
|
|
202
214
|
|
|
203
215
|
```bash
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
216
|
+
loophaus install # 자동 감지 설치
|
|
217
|
+
loophaus status # 설치 상태 확인
|
|
218
|
+
loophaus stats # 루프 실행 통계
|
|
219
|
+
loophaus quality # 품질 점수 측정
|
|
220
|
+
loophaus uninstall # 제거
|
|
221
|
+
loophaus --version # 버전 확인
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## Quality Loop (v3.4.0+)
|
|
225
|
+
|
|
226
|
+
v3.4.0에서 도입된 **Quality Loop** — [karpathy/autoresearch](https://github.com/karpathy/autoresearch)의 실험→측정→유지/폐기 패턴을 코드 품질 개선에 적용.
|
|
227
|
+
|
|
228
|
+
테스트가 통과하면 "완료"로 처리하던 기존 방식 대신, `/loop-plan`이 이제 **품질을 측정**(0-100)하고 임계값을 충족할 때까지 **반복 개선**합니다.
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
Phase 4: 구현
|
|
232
|
+
↓
|
|
233
|
+
Phase 5: 측정 (score 0-100)
|
|
234
|
+
↓ ↑
|
|
235
|
+
Phase 6: 개선 루프
|
|
236
|
+
점수 향상? → 유지 (commit)
|
|
237
|
+
점수 하락? → 폐기 (git reset)
|
|
238
|
+
최대 시도 도달? → 다음으로
|
|
239
|
+
↓
|
|
240
|
+
Phase 7: 보고서 (품질 점수 포함)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
| autoresearch | loophaus |
|
|
244
|
+
|-------------|----------|
|
|
245
|
+
| `val_bpb` | quality score (가중치: tests, typecheck, lint, verify, diff, custom) |
|
|
246
|
+
| `results.tsv` | `.loophaus/results.tsv` |
|
|
247
|
+
| keep → advance | 점수 향상 → commit |
|
|
248
|
+
| discard → revert | 점수 하락 → `git reset --hard` |
|
|
249
|
+
| NEVER STOP | 스토리당 최대 3회 시도 (설정 가능) |
|
|
250
|
+
|
|
251
|
+
### 설정
|
|
252
|
+
|
|
253
|
+
```json
|
|
254
|
+
{
|
|
255
|
+
"qualityThreshold": 80,
|
|
256
|
+
"maxRefineAttempts": 3,
|
|
257
|
+
"qualityConfig": {
|
|
258
|
+
"weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### CLI
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
loophaus quality # 전체 스토리 품질 측정
|
|
267
|
+
loophaus quality --story US-001 # 특정 스토리 품질 측정
|
|
209
268
|
```
|
|
210
269
|
|
|
211
270
|
## 아키텍처
|
|
212
271
|
|
|
213
272
|
```
|
|
214
273
|
loophaus/
|
|
215
|
-
├── .claude-plugin/plugin.json # Claude Code 마켓플레이스 매니페스트
|
|
216
274
|
├── bin/
|
|
217
|
-
│ ├── loophaus.
|
|
218
|
-
│ ├── install.
|
|
219
|
-
│ └── uninstall.
|
|
220
|
-
├──
|
|
221
|
-
│
|
|
222
|
-
├──
|
|
223
|
-
│ ├──
|
|
224
|
-
│ ├──
|
|
225
|
-
│ ├── loop
|
|
226
|
-
│ ├──
|
|
227
|
-
│
|
|
228
|
-
├──
|
|
229
|
-
├──
|
|
230
|
-
├──
|
|
231
|
-
├──
|
|
232
|
-
│ ├──
|
|
233
|
-
│ ├──
|
|
234
|
-
│
|
|
235
|
-
|
|
236
|
-
│
|
|
237
|
-
│ └── ralph-claude-orchestrator/SKILL.md # Claude: Agent tool 패턴
|
|
275
|
+
│ ├── loophaus.ts # CLI 진입점
|
|
276
|
+
│ ├── install.ts # 크로스 플랫폼 설치기
|
|
277
|
+
│ └── uninstall.ts # 제거기
|
|
278
|
+
├── core/
|
|
279
|
+
│ ├── types.ts # 공유 TypeScript 인터페이스
|
|
280
|
+
│ ├── engine.ts # 핵심 루프 엔진
|
|
281
|
+
│ ├── event-logger.ts # 이벤트 추적
|
|
282
|
+
│ ├── quality-scorer.ts # 품질 측정 (점수, 평가, 로깅)
|
|
283
|
+
│ ├── refine-loop.ts # 유지/폐기 개선 로직
|
|
284
|
+
│ ├── validate.ts # PRD + 상태 스키마 검증
|
|
285
|
+
│ ├── policy.ts # 루프 정책 평가
|
|
286
|
+
│ ├── cost-tracker.ts # 토큰 비용 추정
|
|
287
|
+
│ ├── trace-analyzer.ts # 트레이스 분석 + 비교
|
|
288
|
+
│ ├── worktree.ts # Git 워크트리 관리
|
|
289
|
+
│ ├── merge-strategy.ts # 병렬 머지 전략
|
|
290
|
+
│ ├── parallel-runner.ts # 멀티 워크트리 오케스트레이션
|
|
291
|
+
│ ├── session.ts # 체크포인트 / 세션 관리
|
|
292
|
+
│ └── loop-registry.ts # 멀티 루프 레지스트리
|
|
293
|
+
├── store/
|
|
294
|
+
│ └── state-store.ts # 루프 상태 저장소
|
|
238
295
|
├── lib/
|
|
239
|
-
│ ├── paths.
|
|
240
|
-
│
|
|
241
|
-
|
|
242
|
-
|
|
296
|
+
│ ├── paths.ts # 크로스 플랫폼 경로
|
|
297
|
+
│ └── stop-hook-core.ts # 테스트 가능한 hook 로직
|
|
298
|
+
├── platforms/
|
|
299
|
+
│ ├── claude-code/installer.mjs # 플러그인 캐시 설치기
|
|
300
|
+
│ ├── codex-cli/installer.mjs # hooks.json 설치기
|
|
301
|
+
│ └── kiro-cli/installer.mjs # agents/ + steering/ 설치기
|
|
302
|
+
├── hooks/
|
|
303
|
+
│ └── stop-hook.mjs # 범용 Stop hook (Node.js)
|
|
304
|
+
├── commands/ # 슬래시 커맨드 정의
|
|
305
|
+
├── skills/ # 플랫폼별 스킬 정의
|
|
306
|
+
├── .claude-plugin/
|
|
307
|
+
│ └── plugin.json # Claude Code 마켓플레이스 매니페스트
|
|
308
|
+
├── dist/ # 컴파일 출력 (tsc)
|
|
309
|
+
└── tests/ # 296개 테스트 케이스 (vitest)
|
|
243
310
|
```
|
|
244
311
|
|
|
245
312
|
## PRD 포맷
|
|
246
313
|
|
|
247
|
-
loophaus는
|
|
314
|
+
loophaus는 `prd.json` 포맷을 사용합니다:
|
|
248
315
|
|
|
249
316
|
```json
|
|
250
317
|
{
|
|
251
318
|
"project": "MyApp",
|
|
252
|
-
"branchName": "
|
|
319
|
+
"branchName": "feature/auth-system",
|
|
253
320
|
"description": "JWT 인증 시스템과 로그인 UI",
|
|
254
321
|
"userStories": [
|
|
255
322
|
{
|
|
@@ -271,37 +338,6 @@ loophaus는 **ralph-skills 호환** `prd.json` 포맷을 사용합니다:
|
|
|
271
338
|
|
|
272
339
|
각 스토리는 **한 번의 반복**(하나의 컨텍스트 윈도우)에서 완료할 수 있는 크기입니다. 의존성은 priority 순으로 정렬됩니다.
|
|
273
340
|
|
|
274
|
-
## ralph-codex에서 마이그레이션
|
|
275
|
-
|
|
276
|
-
기존에 `ralph-codex`를 사용하고 있었다면, loophaus가 자동으로 마이그레이션을 처리합니다:
|
|
277
|
-
|
|
278
|
-
- **상태 파일 호환** — 기존 `prd.json`과 `progress.txt`를 그대로 사용 가능
|
|
279
|
-
- **자동 감지** — 설치 시 기존 ralph-codex 설정을 감지하고 loophaus 포맷으로 업그레이드
|
|
280
|
-
- **커맨드 매핑** — 기존 `/ralph-interview` → `/loop-plan`, `/ralph-loop` → `/loop`, `/cancel-ralph` → `/loop-stop`
|
|
281
|
-
|
|
282
|
-
마이그레이션 방법:
|
|
283
|
-
|
|
284
|
-
```bash
|
|
285
|
-
# 기존 ralph-codex 제거
|
|
286
|
-
npx @graypark/ralph-codex uninstall
|
|
287
|
-
|
|
288
|
-
# loophaus 설치 (기존 상태 파일 자동 인식)
|
|
289
|
-
npx @graypark/loophaus install
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
기존 PRD 파일은 수정 없이 그대로 동작합니다. `progress.txt`에 축적된 학습 내용도 보존됩니다.
|
|
293
|
-
|
|
294
|
-
## 생태계 호환성
|
|
295
|
-
|
|
296
|
-
loophaus는 기존 Ralph 도구들과 호환됩니다:
|
|
297
|
-
|
|
298
|
-
| 도구 | 호환성 |
|
|
299
|
-
| --- | --- |
|
|
300
|
-
| `ralph-skills:prd` | 동일한 `prd.json` 포맷 — 거기서 PRD를 생성하고 여기서 루프 실행 |
|
|
301
|
-
| `ralph-skills:ralph` | 동일한 `progress.txt`, `passes` 추적, `COMPLETE` promise |
|
|
302
|
-
| 공식 `ralph-loop` 플러그인 | PRD 파일이 양쪽 stop hook에서 동작 |
|
|
303
|
-
| `snarktank/ralph` | 호환되는 PRD 구조 및 반복 패턴 |
|
|
304
|
-
|
|
305
341
|
## 멀티 에이전트 오케스트레이션
|
|
306
342
|
|
|
307
343
|
여러 서비스에 걸치거나 광범위한 탐색이 필요한 태스크에 사용합니다:
|
|
@@ -331,19 +367,23 @@ Phase 2 — 순차 수정 (루프):
|
|
|
331
367
|
## 업데이트
|
|
332
368
|
|
|
333
369
|
```bash
|
|
334
|
-
|
|
370
|
+
npm install -g @graypark/loophaus@latest
|
|
371
|
+
loophaus install --force
|
|
335
372
|
```
|
|
336
373
|
|
|
337
374
|
## 제거
|
|
338
375
|
|
|
339
376
|
```bash
|
|
340
|
-
|
|
377
|
+
loophaus uninstall
|
|
378
|
+
npm uninstall -g @graypark/loophaus
|
|
341
379
|
```
|
|
342
380
|
|
|
343
381
|
## 개발
|
|
344
382
|
|
|
345
383
|
```bash
|
|
346
|
-
npm install && npm test
|
|
384
|
+
npm install && npm test # 296개 테스트
|
|
385
|
+
npm run typecheck # TypeScript strict 모드
|
|
386
|
+
npm run build # dist/로 컴파일
|
|
347
387
|
npx vitest # watch 모드
|
|
348
388
|
```
|
|
349
389
|
|
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
<a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
|
|
11
11
|
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
|
|
12
12
|
<img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
|
|
13
|
-
<img src="https://img.shields.io/badge/tests-
|
|
13
|
+
<img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
16
|
<h3 align="center">Control plane for coding agents — iterative dev loops across Claude Code, Codex CLI, and Kiro CLI.</h3>
|
|
@@ -62,8 +62,10 @@ An AI agent works on a task in a continuous loop. Each iteration starts with fre
|
|
|
62
62
|
│ 1. Read prd.json + progress │
|
|
63
63
|
│ 2. Pick next story (passes=false)│
|
|
64
64
|
│ 3. Implement + verify │
|
|
65
|
-
│ 4.
|
|
66
|
-
│ 5.
|
|
65
|
+
│ 4. Evaluate (score 0-100) │
|
|
66
|
+
│ 5. Refine loop (keep/discard) │
|
|
67
|
+
│ 6. Commit + update progress │
|
|
68
|
+
│ 7. Exit attempt │
|
|
67
69
|
│ │ │
|
|
68
70
|
│ Stop Hook intercepts │
|
|
69
71
|
│ Re-injects prompt │
|
|
@@ -81,9 +83,12 @@ An AI agent works on a task in a continuous loop. Each iteration starts with fre
|
|
|
81
83
|
## Quick Start
|
|
82
84
|
|
|
83
85
|
```bash
|
|
84
|
-
|
|
86
|
+
npm install -g @graypark/loophaus
|
|
87
|
+
loophaus install
|
|
85
88
|
```
|
|
86
89
|
|
|
90
|
+
> **Note:** `npx @graypark/loophaus install` may fail on some npm versions due to a bin resolution cache bug. Use the global install above for reliable setup.
|
|
91
|
+
|
|
87
92
|
The installer auto-detects your host (Claude Code, Codex CLI, or Kiro CLI) and sets up everything — stop hook, commands, and skills.
|
|
88
93
|
|
|
89
94
|
Then in your AI coding session:
|
|
@@ -112,22 +117,31 @@ That's it. The interview generates a PRD, activates the loop, and starts impleme
|
|
|
112
117
|
| **Commands** | `/reload-plugins` | native | steering manual mode |
|
|
113
118
|
| **Multi-agent** | Agent tool | subprocesses | steering agents |
|
|
114
119
|
|
|
115
|
-
All three platforms share the same core engine (`core/engine.
|
|
120
|
+
All three platforms share the same core engine (`core/engine.ts`) and state store (`store/state-store.ts`). Platform-specific adapters handle the differences.
|
|
116
121
|
|
|
117
122
|
## Installation
|
|
118
123
|
|
|
119
|
-
###
|
|
124
|
+
### Global install (recommended)
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
npm install -g @graypark/loophaus
|
|
128
|
+
loophaus install
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Via npx
|
|
120
132
|
|
|
121
133
|
```bash
|
|
122
134
|
npx @graypark/loophaus install
|
|
123
135
|
```
|
|
124
136
|
|
|
137
|
+
> `npx` may fail on some npm versions due to a bin resolution cache bug. If it does, use the global install above.
|
|
138
|
+
|
|
125
139
|
### Specify host
|
|
126
140
|
|
|
127
141
|
```bash
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
142
|
+
loophaus install --host claude-code
|
|
143
|
+
loophaus install --host codex-cli
|
|
144
|
+
loophaus install --host kiro-cli
|
|
131
145
|
```
|
|
132
146
|
|
|
133
147
|
### Flags
|
|
@@ -146,16 +160,54 @@ loophaus ships a standalone CLI for management tasks:
|
|
|
146
160
|
loophaus install # Install to detected host
|
|
147
161
|
loophaus status # Show current loop state and active host
|
|
148
162
|
loophaus stats # Iteration history and completion metrics
|
|
163
|
+
loophaus quality # Run quality scoring on current stories
|
|
149
164
|
loophaus uninstall # Clean removal from all hosts
|
|
150
165
|
```
|
|
151
166
|
|
|
152
|
-
|
|
167
|
+
## Quality Loop (v3.4.0+)
|
|
168
|
+
|
|
169
|
+
loophaus v3.4.0 introduces the **Quality Loop** — inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch)'s experiment→measure→keep/discard pattern.
|
|
170
|
+
|
|
171
|
+
Instead of simply marking a story as "done" when tests pass, `/loop-plan` now **measures quality** (0-100) and **iteratively refines** until the score meets the threshold.
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
Phase 4: Implement
|
|
175
|
+
↓
|
|
176
|
+
Phase 5: Evaluate (score 0-100)
|
|
177
|
+
↓ ↑
|
|
178
|
+
Phase 6: Refine Loop
|
|
179
|
+
score improved? → keep (commit)
|
|
180
|
+
score declined? → discard (git reset)
|
|
181
|
+
max attempts reached? → move on
|
|
182
|
+
↓
|
|
183
|
+
Phase 7: Report (with quality scores)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
| autoresearch | loophaus |
|
|
187
|
+
|-------------|----------|
|
|
188
|
+
| `val_bpb` | quality score (weighted: tests, typecheck, lint, verify, diff, custom) |
|
|
189
|
+
| `results.tsv` | `.loophaus/results.tsv` |
|
|
190
|
+
| keep → advance | score improved → commit |
|
|
191
|
+
| discard → revert | score declined → `git reset --hard` |
|
|
192
|
+
| NEVER STOP | max 3 attempts per story (configurable) |
|
|
193
|
+
|
|
194
|
+
### Configuration
|
|
195
|
+
|
|
196
|
+
```json
|
|
197
|
+
{
|
|
198
|
+
"qualityThreshold": 80,
|
|
199
|
+
"maxRefineAttempts": 3,
|
|
200
|
+
"qualityConfig": {
|
|
201
|
+
"weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### CLI
|
|
153
207
|
|
|
154
208
|
```bash
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
npx @graypark/loophaus stats
|
|
158
|
-
npx @graypark/loophaus uninstall
|
|
209
|
+
loophaus quality # Score all stories
|
|
210
|
+
loophaus quality --story US-001 # Score a specific story
|
|
159
211
|
```
|
|
160
212
|
|
|
161
213
|
## Architecture
|
|
@@ -163,58 +215,51 @@ npx @graypark/loophaus uninstall
|
|
|
163
215
|
```
|
|
164
216
|
loophaus/
|
|
165
217
|
├── bin/
|
|
166
|
-
│ ├── loophaus.
|
|
167
|
-
│ ├── install.
|
|
168
|
-
│ └── uninstall.
|
|
218
|
+
│ ├── loophaus.ts # CLI entry point
|
|
219
|
+
│ ├── install.ts # Cross-platform installer
|
|
220
|
+
│ └── uninstall.ts # Clean uninstaller
|
|
169
221
|
├── core/
|
|
170
|
-
│ ├──
|
|
171
|
-
│ ├──
|
|
172
|
-
│
|
|
222
|
+
│ ├── types.ts # Shared TypeScript interfaces
|
|
223
|
+
│ ├── engine.ts # Core loop engine (shared)
|
|
224
|
+
│ ├── event-logger.ts # Iteration event tracking
|
|
225
|
+
│ ├── quality-scorer.ts # Quality scoring (score, evaluate, log)
|
|
226
|
+
│ ├── refine-loop.ts # Keep/discard refinement logic
|
|
227
|
+
│ ├── validate.ts # PRD + state schema validation
|
|
228
|
+
│ ├── policy.ts # Loop policy evaluation
|
|
229
|
+
│ ├── cost-tracker.ts # Token cost estimation
|
|
230
|
+
│ ├── trace-analyzer.ts # Trace analysis + comparison
|
|
231
|
+
│ ├── worktree.ts # Git worktree lifecycle
|
|
232
|
+
│ ├── merge-strategy.ts # Parallel merge strategies
|
|
233
|
+
│ ├── parallel-runner.ts # Multi-worktree orchestration
|
|
234
|
+
│ ├── session.ts # Checkpoint / session management
|
|
235
|
+
│ └── loop-registry.ts # Multi-loop registry
|
|
173
236
|
├── store/
|
|
174
|
-
│ └── state-store.
|
|
237
|
+
│ └── state-store.ts # Loop state persistence
|
|
238
|
+
├── lib/
|
|
239
|
+
│ ├── paths.ts # Cross-platform path resolution
|
|
240
|
+
│ └── stop-hook-core.ts # Testable hook logic
|
|
175
241
|
├── platforms/
|
|
176
|
-
│ ├── claude-code/
|
|
177
|
-
│
|
|
178
|
-
│
|
|
179
|
-
│ ├── codex-cli/
|
|
180
|
-
│ │ ├── adapter.mjs # Codex CLI platform adapter
|
|
181
|
-
│ │ └── installer.mjs # hooks.json installer
|
|
182
|
-
│ └── kiro-cli/
|
|
183
|
-
│ ├── adapter.mjs # Kiro CLI platform adapter
|
|
184
|
-
│ └── installer.mjs # agents/ + steering/ installer
|
|
242
|
+
│ ├── claude-code/installer.mjs # Plugin cache installer
|
|
243
|
+
│ ├── codex-cli/installer.mjs # hooks.json installer
|
|
244
|
+
│ └── kiro-cli/installer.mjs # agents/ + steering/ installer
|
|
185
245
|
├── hooks/
|
|
186
|
-
│
|
|
187
|
-
|
|
188
|
-
├──
|
|
189
|
-
│ ├── loop-plan.md # /loop-plan command definition
|
|
190
|
-
│ ├── loop.md # /loop command definition
|
|
191
|
-
│ ├── loop-stop.md # /loop-stop command definition
|
|
192
|
-
│ ├── loop-pulse.md # /loop-pulse command definition
|
|
193
|
-
│ └── help.md # /help command definition
|
|
194
|
-
├── skills/
|
|
195
|
-
│ ├── ralph-interview/ # Interactive PRD generator
|
|
196
|
-
│ ├── ralph-orchestrator/ # Multi-agent patterns
|
|
197
|
-
│ ├── ralph-claude-interview/ # Claude Code interview + Skill tool
|
|
198
|
-
│ ├── ralph-claude-loop/ # Claude Code PRD-driven loop
|
|
199
|
-
│ ├── ralph-claude-cancel/ # Claude Code cancel
|
|
200
|
-
│ └── ralph-claude-orchestrator/# Claude Code Agent tool patterns
|
|
201
|
-
├── lib/
|
|
202
|
-
│ ├── paths.mjs # Cross-platform path resolution
|
|
203
|
-
│ ├── state.mjs # Legacy state management
|
|
204
|
-
│ └── stop-hook-core.mjs # Testable hook logic
|
|
246
|
+
│ └── stop-hook.mjs # Universal stop hook (Node.js)
|
|
247
|
+
├── commands/ # Slash command definitions
|
|
248
|
+
├── skills/ # Platform-specific skill definitions
|
|
205
249
|
├── .claude-plugin/
|
|
206
250
|
│ └── plugin.json # Claude Code marketplace manifest
|
|
207
|
-
|
|
251
|
+
├── dist/ # Compiled output (tsc)
|
|
252
|
+
└── tests/ # 296 test cases (vitest)
|
|
208
253
|
```
|
|
209
254
|
|
|
210
255
|
## PRD Format
|
|
211
256
|
|
|
212
|
-
loophaus uses a `prd.json` format
|
|
257
|
+
loophaus uses a `prd.json` format:
|
|
213
258
|
|
|
214
259
|
```json
|
|
215
260
|
{
|
|
216
261
|
"project": "MyApp",
|
|
217
|
-
"branchName": "
|
|
262
|
+
"branchName": "feature/auth-system",
|
|
218
263
|
"description": "JWT authentication with login UI",
|
|
219
264
|
"userStories": [
|
|
220
265
|
{
|
|
@@ -236,30 +281,19 @@ loophaus uses a `prd.json` format compatible with the ralph-skills ecosystem:
|
|
|
236
281
|
|
|
237
282
|
Each story is sized to complete in one iteration (one context window). Dependencies are ordered by priority. The loop engine picks the next story where `passes` is `false` and works on it until verification succeeds.
|
|
238
283
|
|
|
239
|
-
##
|
|
284
|
+
## Update
|
|
240
285
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
npx @graypark/loophaus install --force
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
2. **State files auto-migrate** — Existing `prd.json` and `progress.txt` files are fully compatible. No changes needed.
|
|
249
|
-
|
|
250
|
-
3. **Command mapping:**
|
|
286
|
+
```bash
|
|
287
|
+
npm install -g @graypark/loophaus@latest
|
|
288
|
+
loophaus install --force
|
|
289
|
+
```
|
|
251
290
|
|
|
252
|
-
|
|
253
|
-
|-------------|----------|
|
|
254
|
-
| `/ralph-interview` | `/loop-plan` |
|
|
255
|
-
| `/ralph-loop` | `/loop` |
|
|
256
|
-
| `/cancel-ralph` | `/loop-stop` |
|
|
257
|
-
| (none) | `/loop-pulse` |
|
|
291
|
+
## Uninstall
|
|
258
292
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
293
|
+
```bash
|
|
294
|
+
loophaus uninstall
|
|
295
|
+
npm uninstall -g @graypark/loophaus
|
|
296
|
+
```
|
|
263
297
|
|
|
264
298
|
## Development
|
|
265
299
|
|
|
@@ -267,7 +301,9 @@ Each story is sized to complete in one iteration (one context window). Dependenc
|
|
|
267
301
|
git clone https://github.com/vcz-Gray/loophaus.git
|
|
268
302
|
cd loophaus
|
|
269
303
|
npm install
|
|
270
|
-
npm test #
|
|
304
|
+
npm test # 296 test cases
|
|
305
|
+
npm run typecheck # TypeScript strict mode
|
|
306
|
+
npm run build # Compile to dist/
|
|
271
307
|
npx vitest # watch mode
|
|
272
308
|
```
|
|
273
309
|
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "loophaus",
|
|
3
|
+
"description": "loophaus — Control plane for coding agents",
|
|
4
|
+
"version": "2.0.1",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "graypark",
|
|
7
|
+
"email": "vcz.graypark@gmail.com"
|
|
8
|
+
},
|
|
9
|
+
"skills": "./skills/",
|
|
10
|
+
"keywords": ["loophaus", "loop", "control-plane", "agents"]
|
|
11
|
+
}
|
package/dist/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Viewcommz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|