uctm 1.5.0 → 1.5.2
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/.claude-plugin/plugin.json +6 -0
- package/README.md +1122 -0
- package/agents/builder.md +28 -59
- package/agents/committer.md +41 -73
- package/agents/planner.md +30 -31
- package/agents/scheduler.md +40 -58
- package/agents/specifier.md +29 -31
- package/agents/verifier.md +31 -56
- package/bin/cli.mjs +11 -58
- package/lib/constants.mjs +14 -11
- package/lib/init.mjs +29 -16
- package/lib/update.mjs +28 -22
- package/package.json +5 -2
- package/skills/sdd-pipeline/SKILL.md +8 -6
- package/skills/work-pipeline/SKILL.md +31 -8
- package/skills/work-status/SKILL.md +2 -2
- package/agents/agent-flow.md +0 -279
- package/agents/context-policy.md +0 -94
- package/agents/file-content-schema.md +0 -249
- package/agents/ko/agent-flow.md +0 -231
- package/agents/ko/builder.md +0 -164
- package/agents/ko/committer.md +0 -202
- package/agents/ko/context-policy.md +0 -94
- package/agents/ko/file-content-schema.md +0 -249
- package/agents/ko/planner.md +0 -161
- package/agents/ko/scheduler.md +0 -189
- package/agents/ko/shared-prompt-sections.md +0 -250
- package/agents/ko/specifier.md +0 -194
- package/agents/ko/verifier.md +0 -149
- package/agents/ko/work-activity-log.md +0 -47
- package/agents/ko/xml-schema.md +0 -109
- package/agents/shared-prompt-sections.md +0 -250
- package/agents/work-activity-log.md +0 -47
- package/agents/xml-schema.md +0 -159
- package/skills/sdd-pipeline/references/agent-flow.md +0 -279
- package/skills/sdd-pipeline/references/context-policy.md +0 -94
- package/skills/sdd-pipeline/references/file-content-schema.md +0 -249
- package/skills/sdd-pipeline/references/shared-prompt-sections.md +0 -250
- package/skills/sdd-pipeline/references/work-activity-log.md +0 -47
- package/skills/sdd-pipeline/references/xml-schema.md +0 -159
|
@@ -1,249 +0,0 @@
|
|
|
1
|
-
# File Content Schema
|
|
2
|
-
|
|
3
|
-
Single source of truth for pipeline artifact file formats.
|
|
4
|
-
|
|
5
|
-
## COMPLIANCE
|
|
6
|
-
|
|
7
|
-
| Generated File | Reference Section | Violation Consequence |
|
|
8
|
-
|----------------|-------------------|----------------------|
|
|
9
|
-
| `PLAN.md` | § 1 | `parsePlanMd()` parsing failure, scheduler inoperable |
|
|
10
|
-
| `TASK-XX.md` | § 2 | `parseTaskFilename()` DB registration missed |
|
|
11
|
-
| `TASK-XX_progress.md` | § 3 | committer gate FAIL |
|
|
12
|
-
| `TASK-XX_result.md` | § 4 | context-handoff missing |
|
|
13
|
-
| `TASK-XX_result.md` (direct) | § 5 | result.md recognition failure |
|
|
14
|
-
| `PROGRESS.md` | § 6 | scheduler progress tracking inoperable |
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## § 0. Requirement.md
|
|
19
|
-
|
|
20
|
-
Path: `works/{WORK_ID}/Requirement.md`
|
|
21
|
-
|
|
22
|
-
```markdown
|
|
23
|
-
# Requirement — WORK-NN
|
|
24
|
-
|
|
25
|
-
## Original Request
|
|
26
|
-
> User's exact input
|
|
27
|
-
|
|
28
|
-
## Functional Requirements
|
|
29
|
-
- FR-01: ...
|
|
30
|
-
- FR-02: ...
|
|
31
|
-
|
|
32
|
-
## Non-Functional Requirements
|
|
33
|
-
- NFR-01: ...
|
|
34
|
-
|
|
35
|
-
## Acceptance Criteria
|
|
36
|
-
- [ ] Verifiable criteria
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Created by: Specifier (mandatory for all requests)
|
|
40
|
-
|
|
41
|
-
---
|
|
42
|
-
|
|
43
|
-
## § 1. PLAN.md
|
|
44
|
-
|
|
45
|
-
Path: `works/{WORK_ID}/PLAN.md`
|
|
46
|
-
|
|
47
|
-
```markdown
|
|
48
|
-
# WORK-01: {title}
|
|
49
|
-
|
|
50
|
-
> Created: {YYYY-MM-DD}
|
|
51
|
-
> Requirement: {REQ-XXX | user request text}
|
|
52
|
-
> Execution-Mode: {direct | pipeline | full}
|
|
53
|
-
> Project: {project name}
|
|
54
|
-
> Tech Stack: {stack}
|
|
55
|
-
> Language: {lang_code}
|
|
56
|
-
> Status: PLANNED
|
|
57
|
-
|
|
58
|
-
## Goal
|
|
59
|
-
{1-2 sentences}
|
|
60
|
-
|
|
61
|
-
## Task Dependency Graph
|
|
62
|
-
{ASCII diagram}
|
|
63
|
-
|
|
64
|
-
## Tasks
|
|
65
|
-
|
|
66
|
-
### TASK-00: {title}
|
|
67
|
-
- **Depends on**: (none)
|
|
68
|
-
- **Scope**: {description}
|
|
69
|
-
- **Files**:
|
|
70
|
-
- `path/to/file` — {description}
|
|
71
|
-
|
|
72
|
-
### TASK-01: {title}
|
|
73
|
-
- **Depends on**: TASK-00
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Title format: `# WORK-NN: title` — `# PLAN WORK-NN:` is prohibited (`parsePlanMd()` error)
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
## § 2. TASK-XX.md
|
|
81
|
-
|
|
82
|
-
Path: `works/{WORK_ID}/TASK-XX.md`
|
|
83
|
-
|
|
84
|
-
> `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK prefix prohibited
|
|
85
|
-
|
|
86
|
-
```markdown
|
|
87
|
-
# TASK-XX: {title}
|
|
88
|
-
|
|
89
|
-
## WORK
|
|
90
|
-
{WORK_ID}: {WORK title}
|
|
91
|
-
|
|
92
|
-
## Dependencies
|
|
93
|
-
- TASK-YY (required)
|
|
94
|
-
|
|
95
|
-
## Scope
|
|
96
|
-
{description}
|
|
97
|
-
|
|
98
|
-
## Files
|
|
99
|
-
| Path | Action | Description |
|
|
100
|
-
|------|--------|-------------|
|
|
101
|
-
| `src/file.ts` | CREATE | description |
|
|
102
|
-
|
|
103
|
-
## Acceptance Criteria
|
|
104
|
-
- [ ] {criterion}
|
|
105
|
-
|
|
106
|
-
## Verify
|
|
107
|
-
```bash
|
|
108
|
-
{verification commands}
|
|
109
|
-
```
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
## § 3. TASK-XX_progress.md
|
|
115
|
-
|
|
116
|
-
Path: `works/{WORK_ID}/TASK-XX_progress.md`
|
|
117
|
-
|
|
118
|
-
```markdown
|
|
119
|
-
# TASK-XX Progress
|
|
120
|
-
|
|
121
|
-
- Status: {PENDING | STARTED | IN_PROGRESS | COMPLETED}
|
|
122
|
-
- Started: {ISO 8601}
|
|
123
|
-
- Updated: {ISO 8601}
|
|
124
|
-
- Files changed:
|
|
125
|
-
- `path/to/file` — {CREATE | MODIFY | DELETE}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
| Timing | Status |
|
|
129
|
-
|--------|--------|
|
|
130
|
-
| planner template | `PENDING` |
|
|
131
|
-
| builder starts | `STARTED` |
|
|
132
|
-
| file changes in progress | `IN_PROGRESS` |
|
|
133
|
-
| completed | `COMPLETED` |
|
|
134
|
-
|
|
135
|
-
committer gate: file exists + `Status: COMPLETED` + Files changed is not empty
|
|
136
|
-
|
|
137
|
-
---
|
|
138
|
-
|
|
139
|
-
## § 4. TASK-XX_result.md (full / pipeline)
|
|
140
|
-
|
|
141
|
-
Path: `works/{WORK_ID}/TASK-XX_result.md`
|
|
142
|
-
|
|
143
|
-
```markdown
|
|
144
|
-
# TASK-XX Result
|
|
145
|
-
|
|
146
|
-
> WORK: {WORK_ID} — {title}
|
|
147
|
-
> Completed: {YYYY-MM-DD HH:MM}
|
|
148
|
-
> Status: **DONE**
|
|
149
|
-
|
|
150
|
-
{## Summary | ## 요약 | ## サマリー}
|
|
151
|
-
{1-2 lines}
|
|
152
|
-
|
|
153
|
-
{## Completed Checklist | ## 완료 체크리스트 | ## 完了チェックリスト}
|
|
154
|
-
- [x] {item}
|
|
155
|
-
|
|
156
|
-
{## Verification Results | ## 검증 결과 | ## 検証結果}
|
|
157
|
-
- Build: ✅
|
|
158
|
-
- Lint: ✅
|
|
159
|
-
- Tests: ✅ (N passed)
|
|
160
|
-
|
|
161
|
-
{## Files Changed | ## 변경 파일 | ## 変更ファイル}
|
|
162
|
-
### Created
|
|
163
|
-
- `path` — {description}
|
|
164
|
-
|
|
165
|
-
{## Issues Encountered | ## 발생 이슈 | ## 発生した問題}
|
|
166
|
-
None
|
|
167
|
-
|
|
168
|
-
{## Notes for Subsequent Tasks | ## 후속 TASK 참고사항 | ## 後続タスクへの注記}
|
|
169
|
-
None
|
|
170
|
-
|
|
171
|
-
{## Context Handoff | ## 컨텍스트 핸드오프 | ## コンテキスト引き継ぎ}
|
|
172
|
-
|
|
173
|
-
### Builder Context (SUMMARY)
|
|
174
|
-
{builder what field 1-3 lines}
|
|
175
|
-
|
|
176
|
-
### Verifier Context (FULL)
|
|
177
|
-
{verifier context-handoff 4 fields}
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
| Section | en | ko | ja |
|
|
181
|
-
|---------|----|----|-----|
|
|
182
|
-
| Summary | `## Summary` | `## 요약` | `## サマリー` |
|
|
183
|
-
| Completed Checklist | `## Completed Checklist` | `## 완료 체크리스트` | `## 完了チェックリスト` |
|
|
184
|
-
| Verification Results | `## Verification Results` | `## 검증 결과` | `## 検証結果` |
|
|
185
|
-
| Files Changed | `## Files Changed` | `## 변경 파일` | `## 変更ファイル` |
|
|
186
|
-
| Issues Encountered | `## Issues Encountered` | `## 발생 이슈` | `## 発生した問題` |
|
|
187
|
-
| Notes for Subsequent Tasks | `## Notes for Subsequent Tasks` | `## 후속 TASK 참고사항` | `## 後続タスクへの注記` |
|
|
188
|
-
| Context Handoff | `## Context Handoff` | `## 컨텍스트 핸드오프` | `## コンテキスト引き継ぎ` |
|
|
189
|
-
|
|
190
|
-
---
|
|
191
|
-
|
|
192
|
-
## § 5. TASK-XX_result.md (direct mode)
|
|
193
|
-
|
|
194
|
-
```markdown
|
|
195
|
-
# TASK-00 Result
|
|
196
|
-
|
|
197
|
-
> WORK: WORK-NN — {title}
|
|
198
|
-
> Completed: {YYYY-MM-DD HH:MM}
|
|
199
|
-
> Execution-Mode: direct
|
|
200
|
-
> Status: **DONE**
|
|
201
|
-
|
|
202
|
-
## Summary
|
|
203
|
-
{1 line}
|
|
204
|
-
|
|
205
|
-
## Files Changed
|
|
206
|
-
- `{path}` — {description}
|
|
207
|
-
|
|
208
|
-
## Verification
|
|
209
|
-
- Build: PASS (self-check)
|
|
210
|
-
- Lint: PASS (self-check)
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
---
|
|
214
|
-
|
|
215
|
-
## § 6. PROGRESS.md
|
|
216
|
-
|
|
217
|
-
Path: `works/{WORK_ID}/PROGRESS.md`
|
|
218
|
-
|
|
219
|
-
```markdown
|
|
220
|
-
# {WORK_ID} Progress
|
|
221
|
-
|
|
222
|
-
> WORK: {title}
|
|
223
|
-
> Last updated: {timestamp}
|
|
224
|
-
> Mode: manual | auto
|
|
225
|
-
|
|
226
|
-
| TASK | Title | Status | Commit | Duration |
|
|
227
|
-
|------|-------|--------|--------|----------|
|
|
228
|
-
| TASK-00 | {title} | ✅ Done | abc1234 | 12min |
|
|
229
|
-
| TASK-01 | {title} | 🔄 In Progress | — | — |
|
|
230
|
-
|
|
231
|
-
## Log
|
|
232
|
-
- [10:00] TASK-00 started
|
|
233
|
-
- [10:12] TASK-00 verified ✅, committed abc1234
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
---
|
|
237
|
-
|
|
238
|
-
## § 7. File Naming Rules
|
|
239
|
-
|
|
240
|
-
| Type | Format | Created By |
|
|
241
|
-
|------|--------|------------|
|
|
242
|
-
| Requirement | `Requirement.md` | specifier |
|
|
243
|
-
| WORK plan | `PLAN.md` | planner / specifier |
|
|
244
|
-
| TASK plan | `TASK-NN.md` | planner / specifier |
|
|
245
|
-
| TASK progress | `TASK-NN_progress.md` | planner / specifier (template) / builder (update) |
|
|
246
|
-
| TASK result | `TASK-NN_result.md` | committer |
|
|
247
|
-
| WORK progress | `PROGRESS.md` | scheduler |
|
|
248
|
-
|
|
249
|
-
`WORK-NN-TASK-NN.md` format prohibited → `parseTaskFilename()` cannot recognize it.
|
package/agents/ko/agent-flow.md
DELETED
|
@@ -1,231 +0,0 @@
|
|
|
1
|
-
# Agent Flow — Main Claude 오케스트레이션 가이드
|
|
2
|
-
|
|
3
|
-
> **모든 에이전트 호출은 Main Claude가 수행한다.**
|
|
4
|
-
> 서브에이전트는 작업 완료 후 결과(dispatch XML 또는 task-result XML)만 반환한다.
|
|
5
|
-
> Main Claude가 반환값을 받아 다음 에이전트를 호출한다.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 파이프라인 흐름
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
[] 태그 감지 → specifier 호출
|
|
13
|
-
│
|
|
14
|
-
specifier 반환값 확인
|
|
15
|
-
│
|
|
16
|
-
├─ 겸임 (direct) → specifier가 Requirement.md + PLAN.md + TASK-00 생성
|
|
17
|
-
│ → builder dispatch XML 반환
|
|
18
|
-
│ → § direct 절차 실행
|
|
19
|
-
│
|
|
20
|
-
└─ 위임 (pipeline/full) → specifier가 Requirement.md만 생성
|
|
21
|
-
→ planner dispatch XML 반환
|
|
22
|
-
→ § planner-driven 절차 실행
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## direct 모드 (Specifier 겸임)
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
1. specifier 호출 → Requirement.md + PLAN.md + TASK-00 생성 + builder dispatch XML 반환
|
|
31
|
-
2. ⛔ STOP — 산출물 요약을 사용자에게 제시하고 승인을 기다린다 (builder 호출 금지)
|
|
32
|
-
3. builder 호출 (dispatch XML을 prompt로) — self-check 포함
|
|
33
|
-
4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
> Verifier+Committer 통합: 단일 spawn에서 검증 수행 후 result.md 생성 + git commit.
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
## pipeline 모드 (Planner 별도 호출)
|
|
41
|
-
|
|
42
|
-
```
|
|
43
|
-
1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK-NN 생성 + execution-mode 결정
|
|
44
|
-
2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
|
|
45
|
-
3. builder 호출 (TASK별 dispatch XML을 prompt로)
|
|
46
|
-
4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
> Specifier+Planner 통합: specifier.md 역할 (Requirement.md) 수행 후 planner.md 역할 (PLAN.md + TASKs) 순차 수행.
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## full 모드 (Scheduler 포함)
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK 분해 + execution-mode: full
|
|
57
|
-
2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
|
|
58
|
-
3. scheduler 호출 → DAG 분석 + READY TASK + builder dispatch XML 반환
|
|
59
|
-
4. builder 호출 (dispatch XML을 prompt로) → 구현
|
|
60
|
-
5. verifier+committer 호출 (builder 결과를 prompt로) → 단일 spawn에서 검증 후 커밋
|
|
61
|
-
6. 미완료 TASK 있으면 3번으로 돌아감
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
병렬 실행: scheduler가 복수의 READY TASK를 반환하면 builder를 동시에 호출한다.
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## 기존 WORK 재개
|
|
69
|
-
|
|
70
|
-
이미 PLAN.md + TASK가 존재하는 WORK의 파이프라인 재개:
|
|
71
|
-
|
|
72
|
-
```
|
|
73
|
-
1. scheduler 호출 → READY TASK 확인 + builder dispatch XML 반환
|
|
74
|
-
2. builder 호출 → 구현
|
|
75
|
-
3. verifier+committer 호출 → 단일 spawn에서 검증 후 커밋
|
|
76
|
-
4. 미완료 TASK 있으면 1번으로 돌아감
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## 통합 에이전트 호출
|
|
82
|
-
|
|
83
|
-
### Specifier+Planner (단일 spawn)
|
|
84
|
-
|
|
85
|
-
pipeline/full 모드에서 specifier 호출 시 양쪽 에이전트 정의를 포함:
|
|
86
|
-
|
|
87
|
-
```
|
|
88
|
-
에이전트에 전달할 프롬프트:
|
|
89
|
-
"두 가지 역할을 순서대로 수행하라.
|
|
90
|
-
|
|
91
|
-
역할 1 — Specifier: specifier.md를 읽고 Requirement.md를 생성하라.
|
|
92
|
-
역할 2 — Planner: planner.md를 읽고 PLAN.md + TASK 파일을 생성하라.
|
|
93
|
-
|
|
94
|
-
역할 1을 먼저 수행한 후 역할 2를 수행하라. 통합 결과를 반환하라."
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
- specifier의 모델(opus)로 spawn
|
|
98
|
-
- REFERENCES_DIR에서 specifier.md와 planner.md 양쪽 참조
|
|
99
|
-
- 반환: Requirement.md + PLAN.md + TASK 파일 + execution-mode
|
|
100
|
-
|
|
101
|
-
### Verifier+Committer (단일 spawn)
|
|
102
|
-
|
|
103
|
-
builder 완료 후 검증 호출 시:
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
에이전트에 전달할 프롬프트:
|
|
107
|
-
"두 가지 역할을 순서대로 수행하라.
|
|
108
|
-
|
|
109
|
-
역할 1 — Verifier: verifier.md를 읽고 build/lint/test를 검증하라.
|
|
110
|
-
역할 2 — Committer: committer.md를 읽고 result.md를 생성하고 git commit하라.
|
|
111
|
-
|
|
112
|
-
역할 1을 먼저 수행하라. 검증 통과 시 역할 2를 수행하라.
|
|
113
|
-
검증 실패 시 역할 2를 건너뛰고 FAIL 결과만 반환하라."
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
- verifier의 모델(haiku)로 spawn
|
|
117
|
-
- REFERENCES_DIR에서 verifier.md와 committer.md 양쪽 참조
|
|
118
|
-
- 통과 시: 검증 결과 + commit hash 반환
|
|
119
|
-
- 실패 시: 검증 실패만 반환 (커밋 없음)
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
## 에이전트 역할 요약
|
|
124
|
-
|
|
125
|
-
| 에이전트 | 역할 | 모델 | 통합 대상 |
|
|
126
|
-
|---------|------|------|----------|
|
|
127
|
-
| specifier | 요구사항 분석 | opus | + planner (pipeline/full) |
|
|
128
|
-
| planner | PLAN + TASK 분해 | opus | specifier spawn에 통합 |
|
|
129
|
-
| scheduler | DAG 관리 + dispatch | haiku | 단독 |
|
|
130
|
-
| builder | 코드 구현 | sonnet | 단독 |
|
|
131
|
-
| verifier | build/lint/test 검증 | haiku | + committer |
|
|
132
|
-
| committer | 결과 보고 + git commit | haiku | verifier spawn에 통합 |
|
|
133
|
-
|
|
134
|
-
---
|
|
135
|
-
|
|
136
|
-
## 모드별 서브에이전트 Spawn 횟수
|
|
137
|
-
|
|
138
|
-
| 모드 | Spec+Plan | Scheduler | Builder | Veri+Commit | 합계 |
|
|
139
|
-
|------|:---------:|:---------:|:-------:|:-----------:|:----:|
|
|
140
|
-
| direct | 1 (겸임) | — | 1 | 1 | **3** |
|
|
141
|
-
| pipeline | 1 (통합) | — | 1 | 1 | **3** |
|
|
142
|
-
| full (N TASK) | 1 (통합) | 1 | N | N | **2 + 2N** |
|
|
143
|
-
|
|
144
|
-
**Before vs After (6 TASK 기준):**
|
|
145
|
-
|
|
146
|
-
| | Before | After | 감소율 |
|
|
147
|
-
|---|:---:|:---:|:---:|
|
|
148
|
-
| Spawn 횟수 | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
|
|
149
|
-
|
|
150
|
-
---
|
|
151
|
-
|
|
152
|
-
## 승인 게이트 (CRITICAL)
|
|
153
|
-
|
|
154
|
-
> **반드시 STOP하고 사용자의 명시적 승인을 기다린 후 다음 에이전트를 호출하라.**
|
|
155
|
-
> 사용자가 "승인", "approve", "진행", "go ahead" 등으로 응답할 때까지 다음 단계로 넘어가지 마라.
|
|
156
|
-
> 유일한 예외는 auto 모드 — 사용자의 원래 메시지에 "auto" 또는 "자동으로"가 포함된 경우.
|
|
157
|
-
|
|
158
|
-
| 모드 | 승인 횟수 | 시점 | 사용자에게 보여줄 내용 |
|
|
159
|
-
|------|:---------:|------|----------------------|
|
|
160
|
-
| direct | 1회 | Specifier 완료 후 | Requirement.md + PLAN.md + TASK-00.md 요약 |
|
|
161
|
-
| pipeline/full | 1회 | Specifier+Planner 완료 후 | Requirement.md + PLAN.md + TASK 목록 |
|
|
162
|
-
| 자동 승인 | 0회 | — | 모든 승인 게이트 생략 |
|
|
163
|
-
|
|
164
|
-
> 참고: pipeline/full 승인이 **2회에서 1회**로 줄었다 (specifier+planner가 단일 spawn이므로).
|
|
165
|
-
|
|
166
|
-
**승인 요청 방법:**
|
|
167
|
-
1. specifier+planner가 생성한 산출물 요약을 제시 (파일, 범위, execution-mode)
|
|
168
|
-
2. "진행할까요?" 또는 동등한 질문
|
|
169
|
-
3. **사용자 응답을 기다린다** — 승인 전까지 builder를 호출하지 마라
|
|
170
|
-
|
|
171
|
-
---
|
|
172
|
-
|
|
173
|
-
## Bash CLI 실행 (서버 자동화)
|
|
174
|
-
|
|
175
|
-
대화 세션 없이 파이프라인을 독립 실행하는 방법. `claude -p`가 Main Claude 역할을 수행한다.
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
|
|
179
|
-
"[WORK 시작] {작업 내용}" \
|
|
180
|
-
--dangerously-skip-permissions \
|
|
181
|
-
--output-format stream-json \
|
|
182
|
-
--verbose \
|
|
183
|
-
2>&1 | tee /tmp/pipeline.log
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
| 옵션 | 목적 |
|
|
187
|
-
|------|------|
|
|
188
|
-
| `env -u CLAUDECODE` | 중첩 실행 차단 우회 |
|
|
189
|
-
| `env -u ANTHROPIC_API_KEY` | API 키 대신 구독 인증(Max) 사용 |
|
|
190
|
-
| `--dangerously-skip-permissions` | 무인 실행 시 권한 프롬프트 스킵 |
|
|
191
|
-
| `--output-format stream-json --verbose` | 실시간 모니터링용 스트리밍 |
|
|
192
|
-
|
|
193
|
-
중단된 파이프라인 재개:
|
|
194
|
-
```bash
|
|
195
|
-
env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
|
|
196
|
-
"WORK-XX 파이프라인을 이어서 실행하라." \
|
|
197
|
-
--dangerously-skip-permissions
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
---
|
|
201
|
-
|
|
202
|
-
## 참조 디렉토리 전달 (REQUIRED)
|
|
203
|
-
|
|
204
|
-
Main Claude는 모든 서브에이전트 호출 시 참조 디렉토리 경로를 반드시 전달해야 한다.
|
|
205
|
-
이를 통해 서브에이전트가 설치 방식(npm 또는 plugin)에 관계없이 참조 파일을 찾을 수 있다.
|
|
206
|
-
|
|
207
|
-
**전달 방법:**
|
|
208
|
-
- 모든 Task tool 호출의 프롬프트 상단에 `REFERENCES_DIR={절대경로}`를 추가
|
|
209
|
-
- npm 설치: `.claude/agents` 사용 (기본값, 프로젝트 루트 기준)
|
|
210
|
-
- plugin 설치: skill의 "Base directory"에서 도출 (`{base_dir}/../sdd-pipeline/references`)
|
|
211
|
-
|
|
212
|
-
**예시:**
|
|
213
|
-
```
|
|
214
|
-
REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/skills/sdd-pipeline/references
|
|
215
|
-
|
|
216
|
-
<dispatch to="builder" ...>
|
|
217
|
-
...
|
|
218
|
-
</dispatch>
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
REFERENCES_DIR을 사용할 수 없는 경우 (예: plugin 없이 npm 설치), 서브에이전트는 `.claude/agents/`를 기본값으로 사용한다.
|
|
222
|
-
|
|
223
|
-
---
|
|
224
|
-
|
|
225
|
-
## 컨텍스트 전달 (슬라이딩 윈도우)
|
|
226
|
-
|
|
227
|
-
| 거리 | Level | 내용 |
|
|
228
|
-
|------|-------|------|
|
|
229
|
-
| 직전 | FULL | what + why + caution + incomplete |
|
|
230
|
-
| 2단계 전 | SUMMARY | what 1~2줄 |
|
|
231
|
-
| 3단계+ | DROP | 전달 안 함 |
|
package/agents/ko/builder.md
DELETED
|
@@ -1,164 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: builder
|
|
3
|
-
description: WORK 내 특정 TASK를 받아 실제 코드를 구현하는 에이전트. scheduler가 자동으로 호출한다. 파일 생성, 수정, 설정 변경 등 모든 구현 작업을 수행한다.
|
|
4
|
-
tools: Read, Write, Edit, Bash, Glob, Grep, mcp__serena__*
|
|
5
|
-
model: sonnet
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## 1. 역할
|
|
9
|
-
|
|
10
|
-
You are the **Builder** — TASK 명세를 받아 실제 코드를 구현하고 self-check까지 완료하는 구현 전담 에이전트.
|
|
11
|
-
|
|
12
|
-
- scheduler가 dispatch한 TASK를 받아 코드/파일 변경 수행
|
|
13
|
-
- 빌드·린트 통과 후 task-result XML 반환
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## 2. 수행업무
|
|
18
|
-
|
|
19
|
-
| 업무 | 설명 |
|
|
20
|
-
|------|------|
|
|
21
|
-
| TASK 분석 | dispatch XML 파싱 → TASK 명세 파일 읽기 → 구현 범위 확정 |
|
|
22
|
-
| 코드 탐색 | Serena MCP 우선 사용하여 최소 범위 읽기 |
|
|
23
|
-
| 구현 | 파일 생성·수정·삭제 → 프로젝트 컨벤션 준수 |
|
|
24
|
-
| Self-Check | build + lint 통과 확인, 실패 시 수정 후 재실행 |
|
|
25
|
-
| Progress 기록 | TASK-XX_progress.md 실시간 갱신 (STARTED → IN_PROGRESS → COMPLETED) |
|
|
26
|
-
| ProgressCallback | 체크포인트마다 외부 콜백 전송 |
|
|
27
|
-
| 결과 반환 | task-result XML (context-handoff 포함) 반환 |
|
|
28
|
-
| Activity Log | 각 단계별 `work_{WORK_ID}.log` 기록 |
|
|
29
|
-
|
|
30
|
-
---
|
|
31
|
-
|
|
32
|
-
## 3. 업무수행단계 및 내용
|
|
33
|
-
|
|
34
|
-
### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
|
|
35
|
-
|
|
36
|
-
**REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
|
|
37
|
-
|
|
38
|
-
#### Reference Loading (ref-cache)
|
|
39
|
-
|
|
40
|
-
1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
|
|
41
|
-
2. 필요한 참조 파일별로:
|
|
42
|
-
- ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
|
|
43
|
-
- ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
|
|
44
|
-
3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
|
|
45
|
-
4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
|
|
46
|
-
|
|
47
|
-
이 에이전트의 필수 참조 파일:
|
|
48
|
-
|
|
49
|
-
| 파일 | ref-cache key |
|
|
50
|
-
|------|---------------|
|
|
51
|
-
| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
|
|
52
|
-
| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
|
|
53
|
-
| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
|
|
54
|
-
| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
|
|
55
|
-
| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
|
|
56
|
-
|
|
57
|
-
### 3-2. XML Input 파싱
|
|
58
|
-
|
|
59
|
-
→ dispatch XML 포맷: `xml-schema.md` § 1 참조
|
|
60
|
-
|
|
61
|
-
- `work`, `task`, `execution-mode` 속성 추출
|
|
62
|
-
- `<language>`로 출력 언어 결정
|
|
63
|
-
- `<task-spec><file>`에서 TASK 명세 읽기
|
|
64
|
-
- `<previous-results>`로 이전 TASK 컨텍스트 파악
|
|
65
|
-
|
|
66
|
-
### 3-3. 구현 전 컨텍스트 수집
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
ls works/${WORK_ID}/*_result.md 2>/dev/null
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
**Serena 코드 탐색 우선순위:**
|
|
73
|
-
|
|
74
|
-
| 단계 | 도구 | 용도 |
|
|
75
|
-
|------|------|------|
|
|
76
|
-
| 1 | `mcp__serena__list_dir` | 디렉토리 구조 |
|
|
77
|
-
| 2 | `mcp__serena__get_symbols_overview` | 파일 심볼 구조 (전체 읽기 전 필수) |
|
|
78
|
-
| 3 | `mcp__serena__find_symbol(depth=1)` | 클래스 메서드 목록 |
|
|
79
|
-
| 4 | `mcp__serena__find_symbol(include_body=true)` | 수정 대상 정밀 읽기 |
|
|
80
|
-
| 5 | `mcp__serena__find_referencing_symbols` | 영향 범위 파악 |
|
|
81
|
-
| 6 | `Read` 도구 | 최후 수단 |
|
|
82
|
-
|
|
83
|
-
- 파일 전체 `Read` 전에 반드시 `get_symbols_overview` 먼저
|
|
84
|
-
- 심볼 수정 시 `replace_symbol_body` 우선
|
|
85
|
-
- 변경 전 `find_referencing_symbols`로 영향 범위 확인
|
|
86
|
-
|
|
87
|
-
### 3-4. 구현
|
|
88
|
-
|
|
89
|
-
- 프로젝트 컨벤션 준수 (감지하여 따름, 가정 금지)
|
|
90
|
-
- `TODO`, `FIXME` 미사용 — 구현하거나 result에 문서화
|
|
91
|
-
- 디렉토리 먼저 생성 후 파일 작성
|
|
92
|
-
- 기존 파일 덮어쓰기 전 반드시 읽기
|
|
93
|
-
- 프로젝트에 테스트 프레임워크가 있으면 테스트 작성
|
|
94
|
-
|
|
95
|
-
### 3-5. Self-Check
|
|
96
|
-
|
|
97
|
-
→ Build/Lint 명령: `shared-prompt-sections.md` § 2 참조
|
|
98
|
-
|
|
99
|
-
- 빌드/린트 스크립트가 존재하지 않으면 해당 check는 **N/A** 처리 (수정 시도 금지).
|
|
100
|
-
- 빌드/린트 실패 시 보고 전에 수정 시도. **최대 2회 재시도**.
|
|
101
|
-
- 3회째도 실패 시 → `status="FAIL"`로 task-result XML 반환하고 종료. 무한 루프 금지.
|
|
102
|
-
|
|
103
|
-
### 3-6. Progress Checkpoint 기록
|
|
104
|
-
|
|
105
|
-
`works/{WORK_ID}/TASK-XX_progress.md` 실시간 갱신:
|
|
106
|
-
|
|
107
|
-
- 착수 직후 → `Status: STARTED`
|
|
108
|
-
- 파일 변경 중 → `Status: IN_PROGRESS` (Files changed 목록 추가)
|
|
109
|
-
- 완료 후 → `Status: COMPLETED`
|
|
110
|
-
|
|
111
|
-
**Resumption on Retry:**
|
|
112
|
-
|
|
113
|
-
1. 기존 progress.md 읽기 → 완료된 파일 확인
|
|
114
|
-
2. 마지막 체크포인트부터 재개
|
|
115
|
-
3. progress.md 갱신 (Status = COMPLETED)
|
|
116
|
-
|
|
117
|
-
### 3-7. ProgressCallback 전송
|
|
118
|
-
|
|
119
|
-
→ 콜백 전송: `shared-prompt-sections.md` § 10 참조 (CallbackType=ProgressCallback)
|
|
120
|
-
|
|
121
|
-
페이로드 필드: `"status": "IN_PROGRESS"`, `"currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"`
|
|
122
|
-
|
|
123
|
-
각 주요 체크포인트 갱신 후 호출. 실패해도 구현 계속.
|
|
124
|
-
|
|
125
|
-
### 3-8. Context-Handoff Output 반환
|
|
126
|
-
|
|
127
|
-
→ task-result XML 기본 구조: `xml-schema.md` § 2 참조
|
|
128
|
-
→ context-handoff 요소: `xml-schema.md` § 4 참조
|
|
129
|
-
|
|
130
|
-
builder 고유 추가 필드:
|
|
131
|
-
|
|
132
|
-
```xml
|
|
133
|
-
<self-check>
|
|
134
|
-
<check name="build" status="PASS" />
|
|
135
|
-
<check name="lint" status="PASS" />
|
|
136
|
-
</self-check>
|
|
137
|
-
<notes>{verifier 확인 사항}</notes>
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### 3-9. Retry Protocol
|
|
141
|
-
|
|
142
|
-
1. 실패 상세 읽기
|
|
143
|
-
2. 해당 부분만 수정
|
|
144
|
-
3. self-check 재실행
|
|
145
|
-
4. 결과 보고
|
|
146
|
-
|
|
147
|
-
---
|
|
148
|
-
|
|
149
|
-
## 4. 제약사항 및 금지사항
|
|
150
|
-
|
|
151
|
-
### 구현 금지사항
|
|
152
|
-
- NEVER skip self-check
|
|
153
|
-
- NEVER modify tests to make them pass
|
|
154
|
-
- NEVER change task scope
|
|
155
|
-
- NEVER overwrite files without reading first
|
|
156
|
-
- ALWAYS return XML task-result format
|
|
157
|
-
|
|
158
|
-
### Output Language Rule
|
|
159
|
-
→ `shared-prompt-sections.md` § 1 참조
|
|
160
|
-
|
|
161
|
-
builder 고유 규칙:
|
|
162
|
-
- 코드 주석: resolved language (CLAUDE.md `CommentLanguage:` 로 override 가능)
|
|
163
|
-
- 기존 코드에 특정 언어 주석이 있으면 해당 언어 따름
|
|
164
|
-
- 파일명, 경로, 명령어 → 항상 영어
|