specthread 0.2.0 → 0.2.3

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.md CHANGED
@@ -1,217 +1,138 @@
1
1
  # specthread
2
2
 
3
- Spec-Driven Development (SDD) 도구. 문서가 단일 진실 원천이고, 검사/생성 도구가 문서 체계를 유지한다.
3
+ [![npm](https://img.shields.io/npm/v/specthread)](https://www.npmjs.com/package/specthread) [![license](https://img.shields.io/npm/l/specthread)](https://github.com/dingPie/specthread/blob/main/LICENSE)
4
4
 
5
- ## 시작하기
6
-
7
- ```bash
8
- npm install -g specthread
9
- specthread init
10
- specthread check
11
- ```
12
-
13
- 프로젝트 로컬로 쓰려면 `npm install -D specthread` 후 `npx specthread`로 실행한다.
14
-
15
- `init`이 프로젝트에 SDD 체계를 세팅한다:
16
-
17
- ```
18
- specthread/ ← 문서 규칙·설정·미확정 사항
19
- config.jsonc
20
- rules.md
21
- project.md
22
- pending.md
23
- templates/ ← 문서 골격 (check 대상 아님)
24
- spec.md
25
- plan.md
26
- AGENTS.md ← AI 도구 진입점
27
- CLAUDE.md ← Claude Code용 (@AGENTS.md)
28
- .claude/skills/ ← Claude Code 스킬
29
- ```
30
-
31
- 기존 `AGENTS.md`가 있으면 `<!-- specthread:start/end -->` 마커로 섹션만 삽입한다. 기존 `CLAUDE.md`가 있으면 `@AGENTS.md` 줄만 추가한다.
5
+ 스펙 문서에 현재 상태만 남기고, 그 규칙을 코드로 검사하는 Spec-Driven Development(SDD) 도구입니다.
32
6
 
33
- | 종류 | 파일 | `init` | `init --force` |
34
- | ---- | ---- | ------ | -------------- |
35
- | 패키지 파일 | `rules.md`, `templates/`, `.claude/skills/` | 없을 때만 생성 | 새 버전으로 덮어씀 |
36
- | 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 | 없을 때만 생성 |
37
- | 병합 | `AGENTS.md` (마커 사이), `CLAUDE.md`, `.gitignore` | 병합 | 병합 |
7
+ - **현재 상태만 담는 스펙**: 정하지 못한 것은 `pending.md` 로, 지난 이력은 변경 이력과 git 으로 분리. 이 원칙을 14개 규칙으로 검사
8
+ - **코드로 하는 검사**: 목차·참조 절은 자동 생성하고, 링크·절 참조를 포함한 30개 규칙을 검사. CI 에서 종료 코드로 판정
9
+ - **기본 작업 흐름**: spec·plan 템플릿과 AI 에이전트용 `AGENTS.md`·스킬로 계획 → 구현 → spec 반영
38
10
 
39
- 설정을 처음 상태로 되돌리려면 `config.jsonc`를 지우고 `init`을 다시 실행한다.
11
+ <br />
40
12
 
41
- ## 명령어
13
+ ## 시작하기
42
14
 
43
15
  ```bash
44
- npx specthread init [--tools claude,cursor] # 프로젝트 초기화
45
- npx specthread init --force # 패키지 파일을 새 버전으로 갱신 (사용자 파일은 유지)
46
- npx specthread check # 문서 정합성 검사
47
- npx specthread gen # 참조 절·목차·요약 표 미리보기
48
- npx specthread gen --write # 실제 적용
16
+ npm install -D specthread
17
+ npx specthread init
18
+ npx specthread check
49
19
  ```
50
20
 
51
- ### check
52
-
53
- 30개 규칙으로 문서 형식을 검사한다. 목차, 헤딩, 링크, 참조 절, 변경 이력, 미확정 마커 등.
21
+ `init` 이 규칙 문서, 설정, AI 도구용 파일을 만들고 `check` 가 문서를 검사합니다. 지적은 파일과 줄 번호, 규칙 ID 와 함께 출력됩니다.
54
22
 
55
- ### gen
23
+ ```
24
+ 지적 4 건
56
25
 
57
- 본문 링크와 헤딩을 기반으로 목차·참조 절·미확정 사항 요약을 생성한다. `--write` 없이 실행하면 변경 대상만 보여준다.
26
+ docs/spec/auth.md
27
+ 3 toc/stale 목차가 헤딩과 어긋난다 - 항목 2 / 헤딩 3
28
+ 10 link/target 대상이 없다 - ./session.md
29
+ 14 section-ref/unknown-doc §3 없는 문서를 가리킨다 - api.md
30
+ 20 reference/missing 참조 절이 없다 - 본문 링크 1 대상
31
+ ```
58
32
 
59
- ## 설정
33
+ 목차와 참조 절처럼 본문에서 만들 수 있는 부분은 `npx specthread gen --write` 로 고칩니다.
60
34
 
61
- `specthread/config.jsonc`로 프로젝트별 동작을 제어한다. 개인 오버라이드는 `specthread/config.local.jsonc` (gitignore 대상).
35
+ <details>
36
+ <summary>init 이 만드는 파일</summary>
62
37
 
63
38
  ```
64
- Core defaults (도구 내부 기본값)
65
- ↓ deep merge
66
- specthread/config.jsonc (프로젝트 공유)
67
- ↓ deep merge
68
- specthread/config.local.jsonc (개인)
39
+ specthread/
40
+ config.jsonc 설정
41
+ rules.md 문서 형식 규칙
42
+ project.md 설정값의 맥락과 근거
43
+ pending.md 미확정 사항 정본
44
+ templates/ spec·plan 문서 골격
45
+ AGENTS.md AI 도구 진입점
46
+ CLAUDE.md @AGENTS.md
47
+ .claude/skills/ Claude Code 스킬
69
48
  ```
70
49
 
71
- 배열과 `path` 는 통째로 교체되고, 나머지 객체는 키 단위로 합쳐진다. 잘못된 값이 있으면 파일과 키를 출력하고 종료 코드 2 로 끝난다. init이 생성하는 `config.jsonc`에 모든 옵션이 주석으로 설명되어 있고, `fileKinds`는 기본 확장자 목록이 실제 값으로 기록되므로 필요한 확장자를 그 자리에서 더하거나 뺄 수 있다.
72
-
73
- | 키 | 역할 |
74
- | ----------- | ------------------------------------------ |
75
- | `path` | 스캔 대상 경로 (자유 KV) |
76
- | `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`) |
77
- | `features` | 기능 플래그 (`markers`, `references`) |
78
- | `markers` | 마커 종류·시점 라벨 |
79
- | `skipCheck` | 검사·생성을 건너뛸 경로 |
80
- | `skipRefs` | 참조 절 생성을 건너뛸 경로 |
81
- | `work` | 작업 문서 폴더 (기본 `docs/work/`) |
50
+ 기존 `AGENTS.md`, `CLAUDE.md` 가 있으면 specthread 내용만 추가합니다.
82
51
 
83
- `specthread/` 아래 규칙·미확정·프로젝트 문서의 위치는 고정이다. 템플릿과 설정 파일은 항상 검사에서 제외된다.
52
+ </details>
84
53
 
85
- ## SDD 작업 흐름
54
+ 새 버전으로 올릴 때는 패키지를 갱신하고 `init --force` 를 실행합니다. 규칙·템플릿·스킬만 새 버전으로 바뀌고, 남은 정리를 위한 프롬프트가 출력됩니다. 이 프롬프트를 AI 에게 그대로 전달하면 됩니다.
86
55
 
56
+ ```bash
57
+ npm install -D specthread@latest
58
+ npx specthread init --force
87
59
  ```
88
- 스펙 확인 → 현황 점검(check) → 계획 수립 → 구현 → 검증(check) → 문서 갱신
89
- ```
90
-
91
- 구현 전에 spec을 읽고, 구현 후에 spec을 갱신한다. 진행 중 모호함을 발견하면 `PENDING` 마커를 남기고 작업을 계속한다.
92
60
 
93
- ### 예시: 기존 인증 spec에 소셜 로그인 추가
61
+ <br />
94
62
 
95
- `docs/spec/auth.md`가 이미 있는 프로젝트에서 소셜 로그인을 추가한다:
63
+ ## 명령어
96
64
 
97
- ```
98
- You: 소셜 로그인 기능 계획 세워줘
99
- AI: docs/spec/auth.md 를 읽고, plan 템플릿 기반으로
100
- docs/work/social-login.md 생성.
101
- 목표, 작업 단계, 영향 파일을 함께 채운다.
102
- 문서 정합성 검사 통과.
65
+ ```bash
66
+ npx specthread init # 프로젝트 초기화
67
+ npx specthread init --force # 새 버전으로 갱신
68
+ npx specthread check # 문서 검사
69
+ npx specthread gen # 생성 결과 미리보기
70
+ npx specthread gen --write # 생성 결과 적용
103
71
  ```
104
72
 
105
- ```
106
- You: 진행해줘
107
- AI: 작업 단계 1 "OAuth 프로바이더 연동" 구현.
108
- 세션 관리 방식이 미확정이라
109
- PENDING::design::oauth-session 마커를 남긴다.
110
- 단계 상태를 "완료"로 갱신.
111
- ```
73
+ - `check`: 지적이 있으면 종료 코드 1, 설정을 읽지 못하면 2
74
+ - `gen`: 목차, 참조 절, 미확정 사항 목록 생성. `--write` 없이는 바뀔 파일 목록만 출력
75
+ - `init --force`: `config.jsonc`, `project.md`, `pending.md` 는 덮어쓰지 않음
112
76
 
113
- ```
114
- You: 전부 끝났어, 정리해줘
115
- AI: 종료 게이트 점검 후,
116
- 작업 내용을 docs/spec/auth.md §3 에 흡수.
117
- docs/work/social-login.md 삭제.
118
- 문서 정합성 검사 통과.
119
- ```
77
+ 규칙 전체와 규칙 ID 는 [`rules.md`](https://github.com/dingPie/specthread/blob/main/scaffold/rules.md) 에 있습니다. `init` 이 같은 파일을 `specthread/rules.md` 로 설치합니다.
120
78
 
121
- 결과: `docs/spec/auth.md`에 소셜 로그인 절이 추가되고, work 문서는 사라진다. spec이 항상 현재 시스템의 정본으로 남는다.
79
+ <br />
122
80
 
123
- AI는 작업 중에 `check`와 `gen`을 자동으로 호출한다. `AGENTS.md`가 이 워크플로우를 AI에게 전달하고, `check`가 문서와 코드의 어긋남을 잡는다.
81
+ ## 작업 흐름
124
82
 
125
- ## AI 도구 지원
83
+ 구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신합니다. 진행 중 정하지 못한 것은 `PENDING::<종류>::<slug>` 마커로 남기고 작업을 계속합니다.
126
84
 
127
- `AGENTS.md`가 본체. 대부분의 AI 코딩 도구가 이 파일을 읽는다.
85
+ ```
86
+ You: 소셜 로그인 계획 세워줘
87
+ AI: docs/spec/auth.md 확인 후
88
+ docs/work/social-login.md 작성
128
89
 
129
- | 도구 | 동작 |
130
- | --------------------------------- | -------------------------------------- |
131
- | Claude Code | `CLAUDE.md`의 `@AGENTS.md`가 자동 확장 |
132
- | Cursor / Copilot / Codex / Gemini | `AGENTS.md`를 네이티브로 읽음 |
90
+ You: 진행해줘
91
+ AI: OAuth 연동 구현, 세션 방식은 미정이라
92
+ PENDING::design::oauth-session 마커 추가
133
93
 
134
- `--tools claude` (기본값)로 init하면 Claude Code 스킬이 함께 설치된다:
94
+ You: 정리해줘
95
+ AI: 작업 내용을 docs/spec/auth.md 에 반영,
96
+ 계획 문서 삭제, check 통과
97
+ ```
135
98
 
136
- | 스킬 | 역할 |
137
- | ------------- | ----------------------------- |
138
- | `/check` | 문서 검사 실행 + 결과 해석 |
139
- | `/gen` | 참조 절·목차 생성 + 적용 안내 |
140
- | `/plan-open` | 작업 계획 문서 작성·검수·확정 |
141
- | `/plan-run` | 계획에 따라 실행·기록 |
142
- | `/plan-close` | 완료된 작업을 spec에 흡수 |
99
+ Claude Code 에서는 아래 스킬로 같은 흐름을 실행합니다. 스킬 없이 자연어로 요청해도 `AGENTS.md` 에 적힌 흐름대로 진행합니다.
143
100
 
144
- 스킬 없이 자연어로 같은 작업을 요청해도 된다. `AGENTS.md`가 AI에게 워크플로우를 알려주기 때문이다. 스킬은 자주 쓰는 흐름의 단축키다.
101
+ - `/plan-open`: 작업 계획 문서 작성·확정
102
+ - `/plan-run`: 계획에 따른 구현과 기록
103
+ - `/plan-close`: 완료된 작업을 spec 에 반영
104
+ - `/check`, `/gen`: 검사·생성 실행과 결과 안내
145
105
 
146
- ## 0.1.x 에서 올리기
106
+ Cursor, Copilot, Codex, Gemini 는 `AGENTS.md` 를 직접 읽습니다. 스킬이 필요 없으면 `init --tools cursor` 처럼 `claude` 를 빼고 실행합니다.
147
107
 
148
- 0.2.0 은 설정 키 일부를 정리하고 규칙 3개를 더했다. 패키지를 올린 뒤 아래를 실행한다.
108
+ <br />
149
109
 
150
- ```bash
151
- npm install -D specthread@latest
152
- npx specthread init --force
153
- ```
110
+ ## 설정
154
111
 
155
- `init --force` 는 `rules.md`·템플릿·스킬만 새 버전으로 바꾼다. 사용자 파일과, 0.1.x 가 마커 없이 만든 `AGENTS.md` 는 건드리지 않는다. 남은 정리는 AI 에게 아래 프롬프트로 맡긴다.
112
+ `specthread/config.jsonc` 에서 스캔 경로, 파일 종류, 마커 종류 등을 정합니다. `init` 이 만든 파일에 모든 옵션이 주석으로 설명되어 있습니다.
156
113
 
157
- ```
158
- specthread 를 0.2.0 으로 올렸다. 아래를 순서대로 처리해줘.
159
- 내가 직접 쓴 내용은 지우지 말고, 판단이 필요하면 멈추고 물어봐.
160
-
161
- 0. specthread/rules.md 와 specthread/templates/ 를 고쳐 쓴 적이 있으면,
162
- 다음 단계에서 덮어써지므로 먼저 커밋되어 있는지 확인한다.
163
-
164
- 1. AGENTS.md
165
- - `<!-- specthread:start -->` 표식이 없으면, specthread 가 만든 부분
166
- (`# specthread` 제목부터 그 섹션 끝까지)을 `<!-- specthread:start -->` 와
167
- `<!-- specthread:end -->` 로 감싼다. 그 밖의 내용은 그대로 둔다.
168
- - specthread 섹션이 두 번 들어가 있으면 뒤의 것을 지운다.
169
-
170
- 2. `npx specthread init --force` 를 실행한다.
171
- rules.md, 템플릿, 스킬, AGENTS.md 의 specthread 섹션이 새 버전으로 바뀐다.
172
-
173
- 3. specthread/config.jsonc
174
- - `"emDash"` 키와 그 주석을 지운다.
175
- - 주석으로만 남은 `locale`, `rules`, `pending`, `project` 블록을 지운다.
176
- - `rules`·`pending`·`project` 에 실제 값을 적어 쓰고 있었다면 지우지 말고 알려줘.
177
- 이제 경로가 specthread/ 아래로 고정이라 파일을 옮겨야 한다.
178
- - `path` 에 일부 키만 적어 두었다면 알려줘. 이제 path 는 기본값과 합치지 않고
179
- 통째로 교체되므로, docs/ 와 specthread/ 스캔이 빠질 수 있다.
180
-
181
- 4. specthread/project.md 의 "`config.jsonc` 에서 경로를 override 할 수 있다" 를
182
- "경로는 `specthread/pending.md` 고정이다" 로 바꾼다.
183
-
184
- 5. specthread/pending.md 의 "종류마다 `##` 섹션이 하나씩 생긴다. 종류 값은
185
- `config.markers.types` 가 정의하며" 를 "종류마다 `##` 섹션을 하나씩 둔다.
186
- 섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다." 로 바꾼다.
187
-
188
- 6. `.claude/skills/` 바로 아래에 check.md, gen.md, plan-open.md, plan-run.md,
189
- plan-close.md 가 남아 있으면 같은 이름의 `<이름>/SKILL.md` 와 비교한다.
190
- 내가 고친 부분이 없으면 지우고, 있으면 알려줘.
191
-
192
- 7. `npx specthread check` 를 실행한다.
193
- - `marker/unknown-type` 이 나오면 쓰고 있는 종류를 `config.markers.types` 에
194
- 추가할지 물어봐.
195
- - `heading/tail-order` 가 나오면 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴다.
196
-
197
- 8. `npx specthread gen --write` 후 `npx specthread check` 가 0 건인지 확인한다.
114
+ ```jsonc
115
+ {
116
+ "path": {
117
+ "docs": ["docs/"],
118
+ "source": ["src/"]
119
+ },
120
+ "markers": {
121
+ "types": ["system", "design"]
122
+ }
123
+ }
198
124
  ```
199
125
 
200
- 바뀐 동작:
126
+ `path` 는 기본값과 합치지 않고 교체되므로 `docs/` 도 함께 적습니다. 개인 설정은 `specthread/config.local.jsonc` 에 둡니다.
201
127
 
202
- | 변경 | 영향 |
203
- | ---- | ---- |
204
- | `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만 내고 동작한다 |
205
- | `path` 통째 교체 | 일부 키만 적었다면 기본 `docs/`, `specthread/` 스캔이 빠진다 |
206
- | 종료 코드 2 | 설정 파일이 없거나 설정을 읽지 못하면, 또는 모르는 명령이면 2 로 끝난다 |
207
- | 규칙 추가 | `heading/tail-order`, `marker/unknown-type`, `pending/unknown-timepoint` |
208
- | em dash 검사 제거 | `style/em-dash` 가 없어졌다 |
209
- | 스킬 경로 | `.claude/skills/<이름>/SKILL.md` 로 바뀌었다. 옛 파일은 지우지 않고 알린다 |
128
+ <br />
210
129
 
211
130
  ## 요구 사항
212
131
 
213
- - Node.js >= 18.0.0
214
- - 외부 의존성 없음 (zero-dependency)
132
+ - Node.js 18 이상
133
+ - 외부 의존성 없음
134
+
135
+ <br />
215
136
 
216
137
  ## 라이선스
217
138
 
package/dist/bin/cli.js CHANGED
@@ -7,7 +7,8 @@ const usage = `specthread - Spec-Driven Development (SDD) 도구
7
7
 
8
8
  commands:
9
9
  init [--tools claude,cursor] 프로젝트에 SDD 체계 초기화
10
- init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로 갱신
10
+ init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로 갱신하고
11
+ 남은 정리를 위한 업데이트 프롬프트 출력
11
12
  check 문서 정합성 검사 (30개 규칙)
12
13
  gen [--write] 참조 절·목차·미확정 사항 요약 생성
13
14
  help 이 도움말 표시
@@ -4,8 +4,8 @@ import { RULE } from '../constants/rules.js';
4
4
  * 헤딩 구조 - 제목이 하나인가, 꼬리 절 이름을 본문에서 재사용하지 않는가,
5
5
  * 꼬리 절에 번호가 붙지 않았는가, 꼬리 절이 정해진 순서인가.
6
6
  *
7
- * 둘 다 생성기가 자리를 잘못 짚게 만드는 원인이다. 꼬리 절은 이름으로 찾으므로
8
- * 이름이 겹치면 어느 쪽이 꼬리인지 가릴 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
7
+ * 하나라도 어긋나면 생성기가 목차와 꼬리 절을 넣을 위치를 정할 수 없다. 꼬리 절은 이름으로 찾으므로
8
+ * 이름이 겹치면 어느 쪽이 꼬리 절인지 구분할 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
9
9
  */
10
10
  import { isDoc, tailOrderOk, titleHeadings } from "../utils/scope.js";
11
11
  export const checkHeadings = (index) => {
@@ -11,6 +11,7 @@ import { ITEM_AS_LI, ITEM_HEADING, timepointGlobal } from '../constants/patterns
11
11
  import { RULE } from '../constants/rules.js';
12
12
  import { summaryBlocks } from '../gen/summary.js';
13
13
  import { invertByTarget, pendingSectionBlock } from '../gen/pending-section.js';
14
+ import { eachContentLine } from '../utils/parse.js';
14
15
  import { underPath } from '../utils/path-match.js';
15
16
  import { inChangeLog, isWorkDoc } from '../utils/scope.js';
16
17
  /**
@@ -216,7 +217,8 @@ export const checkPending = (index) => {
216
217
  if (file === undefined)
217
218
  return [];
218
219
  const findings = [];
219
- file.lines.forEach((raw, i) => {
220
+ // 코드블록 안은 항목 형식을 보여주는 예시다
221
+ eachContentLine(file.lines, (raw, i) => {
220
222
  const line = i + 1;
221
223
  if (inChangeLog(file, line))
222
224
  return;
@@ -7,7 +7,6 @@ import { RULE } from '../constants/rules.js';
7
7
  */
8
8
  import { basename, dirname, relative } from "node:path";
9
9
  import { inChangeLog, inPendingSection, inRefSection, inToc, isHeadingLine, } from "../utils/scope.js";
10
- /** 미해소 사유별 메시지 */
11
10
  /**
12
11
  * 해소 실패 사유마다 규칙 id 와 메시지.
13
12
  *
@@ -28,7 +28,7 @@ export const checkTimestamps = (index) => {
28
28
  return;
29
29
  }
30
30
  const line = i + 1;
31
- // 펜스는 예시, 변경 이력은 날짜가 있어야 하는 곳, 목차·미확정 사항 절은 생성물이다
31
+ // 코드블록은 예시, 변경 이력은 날짜가 있어야 하는 곳, 목차·미확정 사항 절은 생성물이다
32
32
  if (fence || inChangeLog(file, line) || inToc(file, line) || inPendingSection(file, line))
33
33
  return;
34
34
  const mask = codeSpanMask(text);
@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
4
4
  import { DEFAULT_CONFIG } from "../config.schema.js";
5
5
  import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, RULES_PATH, SPECTHREAD_DIR, TEMPLATES_DIR, } from "../constants/paths.js";
6
6
  import { renderConfig } from "./config-template.js";
7
+ import { renderUpgradePrompt } from "./upgrade-prompt.js";
7
8
  const SPECTHREAD_START = "<!-- specthread:start -->";
8
9
  const SPECTHREAD_END = "<!-- specthread:end -->";
9
10
  const scaffoldDir = () => {
@@ -26,6 +27,8 @@ const putFile = (dest, content, force, owner) => {
26
27
  return force ? "kept" : "skipped";
27
28
  if (existed && !force)
28
29
  return "skipped";
30
+ if (existed && readFileSync(dest, "utf8") === content)
31
+ return "unchanged";
29
32
  const dir = dirname(dest);
30
33
  if (!existsSync(dir))
31
34
  mkdirSync(dir, { recursive: true });
@@ -42,30 +45,36 @@ const wrapSection = (section) => `${SPECTHREAD_START}\n${section}\n${SPECTHREAD_
42
45
  * 사라질 수 있다. 그래서 건드리지 않고 알린다.
43
46
  */
44
47
  const isLegacyAgents = (content) => /^# specthread\s*$/m.test(content) && /^## 2\. SDD 작업 흐름\s*$/m.test(content);
45
- /** AGENTS.md 의 specthread 섹션을 맞춘다. 이전 버전 파일이라 손대지 않았으면 false */
48
+ /** AGENTS.md 의 specthread 섹션을 맞춘다 */
46
49
  const ensureAgentsMd = (cwd, scaffold) => {
47
50
  const dest = join(cwd, "AGENTS.md");
48
51
  const section = readFileSync(join(scaffold, "AGENTS.md"), "utf8");
49
52
  if (!existsSync(dest)) {
50
53
  writeFileSync(dest, `${wrapSection(section)}\n`, "utf8");
51
54
  console.log(" AGENTS.md 생성");
52
- return true;
55
+ return "written";
53
56
  }
54
57
  const content = readFileSync(dest, "utf8");
55
- if (content.includes(SPECTHREAD_START)) {
56
- const before = content.slice(0, content.indexOf(SPECTHREAD_START));
57
- const after = content.slice(content.indexOf(SPECTHREAD_END) + SPECTHREAD_END.length);
58
- writeFileSync(dest, `${before}${wrapSection(section)}${after}`, "utf8");
58
+ const start = content.indexOf(SPECTHREAD_START);
59
+ if (start >= 0) {
60
+ const end = content.indexOf(SPECTHREAD_END, start);
61
+ // 끝 표식이 없으면 섹션이 어디서 끝나는지 알 수 없다. 추측해서 바꾸면 사용자 내용을 지운다
62
+ if (end < 0) {
63
+ console.log(` AGENTS.md ${SPECTHREAD_END} 표식 없음. 건드리지 않음`);
64
+ return "broken";
65
+ }
66
+ const after = content.slice(end + SPECTHREAD_END.length);
67
+ writeFileSync(dest, `${content.slice(0, start)}${wrapSection(section)}${after}`, "utf8");
59
68
  console.log(" AGENTS.md specthread 섹션 갱신");
60
- return true;
69
+ return "written";
61
70
  }
62
71
  if (isLegacyAgents(content)) {
63
72
  console.log(" AGENTS.md 이전 버전 형식 (구분 표식 없음). 건드리지 않음");
64
- return false;
73
+ return "legacy";
65
74
  }
66
75
  writeFileSync(dest, `${content.trimEnd()}\n\n${wrapSection(section)}\n`, "utf8");
67
76
  console.log(" AGENTS.md specthread 섹션 삽입");
68
- return true;
77
+ return "written";
69
78
  };
70
79
  const ensureClaudeMd = (cwd) => {
71
80
  const dest = join(cwd, "CLAUDE.md");
@@ -99,6 +108,9 @@ const ensureGitignore = (cwd) => {
99
108
  console.log(` .gitignore ${LOCAL_CONFIG_PATH} 추가`);
100
109
  };
101
110
  const SKILLS = ["check", "gen", "plan-open", "plan-run", "plan-close"];
111
+ /** 업데이트 프롬프트 구분선. 사용자가 이 사이를 복사해 AI 에 전달한다 */
112
+ const PROMPT_START = "── 업데이트 프롬프트: 아래를 AI 에게 그대로 전달한다 ──────────────";
113
+ const PROMPT_END = "──────────────────────────────────────────────────────────────";
102
114
  const parseTools = (args) => {
103
115
  const idx = args.indexOf("--tools");
104
116
  if (idx === -1 || idx + 1 >= args.length)
@@ -108,10 +120,10 @@ const parseTools = (args) => {
108
120
  const STATUS_LABEL = {
109
121
  created: "생성",
110
122
  overwritten: "덮어씀",
123
+ unchanged: "변경 없음",
111
124
  skipped: "이미 존재. 건너뜀",
112
125
  kept: "사용자 파일. 건너뜀",
113
126
  };
114
- const UPGRADE_GUIDE = "README 의 '0.1.x 에서 올리기'";
115
127
  export const init = (args) => {
116
128
  const cwd = process.cwd();
117
129
  const scaffold = scaffoldDir();
@@ -131,37 +143,42 @@ export const init = (args) => {
131
143
  }
132
144
  const configStatus = putFile(join(cwd, CONFIG_PATH), renderConfig(DEFAULT_CONFIG), force, "user");
133
145
  console.log(` ${CONFIG_PATH} ${STATUS_LABEL[configStatus]}`);
146
+ // 내용이 바뀐 패키지 파일. 업데이트 프롬프트가 사용자 수정분 확인을 요청한다
147
+ const overwritten = [];
148
+ const put = ({ src, dest, owner }) => {
149
+ const status = copyFile(src, join(cwd, dest), force, owner);
150
+ if (status === "overwritten")
151
+ overwritten.push(dest);
152
+ console.log(` ${dest} ${STATUS_LABEL[status]}`);
153
+ };
134
154
  // scaffold 원본은 고정 경로와 같은 파일 이름을 쓴다
135
155
  const docs = [
136
156
  [RULES_PATH, "package"],
137
157
  [PROJECT_PATH, "user"],
138
158
  [PENDING_PATH, "user"],
139
159
  ];
140
- for (const [dest, owner] of docs) {
141
- const status = copyFile(join(scaffold, basename(dest)), join(cwd, dest), force, owner);
142
- console.log(` ${dest} ${STATUS_LABEL[status]}`);
143
- }
160
+ for (const [dest, owner] of docs)
161
+ put({ src: join(scaffold, basename(dest)), dest, owner });
144
162
  for (const file of ["spec.md", "plan.md"]) {
145
- const dest = `${TEMPLATES_DIR}/${file}`;
146
- const status = copyFile(join(scaffold, "templates", file), join(cwd, dest), force, "package");
147
- console.log(` ${dest} ${STATUS_LABEL[status]}`);
163
+ put({ src: join(scaffold, "templates", file), dest: `${TEMPLATES_DIR}/${file}`, owner: "package" });
148
164
  }
149
- let legacy = !ensureAgentsMd(cwd, scaffold);
165
+ const agents = ensureAgentsMd(cwd, scaffold);
150
166
  ensureGitignore(cwd);
167
+ const oldSkills = [];
151
168
  if (tools.has("claude")) {
152
169
  ensureClaudeMd(cwd);
153
- // Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다. 0.1.x 는 `<이름>.md` 로 깔았다
154
- const skillsDir = join(cwd, ".claude", "skills");
155
- const oldSkills = [];
170
+ // Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다. `<이름>.md` 는 이전 버전의 경로다
156
171
  for (const name of SKILLS) {
157
- const status = copyFile(join(scaffold, "claude", "skills", name, "SKILL.md"), join(skillsDir, name, "SKILL.md"), force, "package");
158
- console.log(` .claude/skills/${name}/SKILL.md ${STATUS_LABEL[status]}`);
159
- if (existsSync(join(skillsDir, `${name}.md`)))
172
+ put({
173
+ src: join(scaffold, "claude", "skills", name, "SKILL.md"),
174
+ dest: `.claude/skills/${name}/SKILL.md`,
175
+ owner: "package",
176
+ });
177
+ if (existsSync(join(cwd, ".claude", "skills", `${name}.md`)))
160
178
  oldSkills.push(`.claude/skills/${name}.md`);
161
179
  }
162
180
  // 사용자가 고쳤을 수 있으므로 지우지 않고 알리기만 한다
163
181
  if (oldSkills.length > 0) {
164
- legacy = true;
165
182
  console.log("\n 이전 형식의 스킬 파일이 남아 있다. Claude Code 가 읽지 않으므로 지워도 된다:");
166
183
  for (const path of oldSkills)
167
184
  console.log(` ${path}`);
@@ -169,9 +186,16 @@ export const init = (args) => {
169
186
  }
170
187
  if (force) {
171
188
  console.log(`\n--force 는 패키지 파일만 갱신한다. ${CONFIG_PATH}, ${PROJECT_PATH}, ${PENDING_PATH} 는 그대로 둔다.`);
189
+ console.log(`\n${PROMPT_START}`);
190
+ console.log(renderUpgradePrompt({ root: cwd, agents, overwritten, oldSkills }));
191
+ console.log(PROMPT_END);
192
+ return;
193
+ }
194
+ if (agents === "broken") {
195
+ console.log(`\nAGENTS.md 의 specthread 섹션 끝에 ${SPECTHREAD_END} 를 넣고 다시 실행한다.`);
172
196
  }
173
- if (legacy) {
174
- console.log(`\n이전 버전에서 올린 프로젝트로 보인다. 남은 정리는 ${UPGRADE_GUIDE} 를 따른다.`);
197
+ if (agents === "legacy" || oldSkills.length > 0) {
198
+ console.log("\n이전 버전에서 올린 프로젝트로 보인다. `npx specthread init --force` 로 패키지 파일을 갱신하면 남은 정리를 위한 프롬프트를 출력한다.");
175
199
  }
176
200
  console.log("\n완료. npx specthread check 로 문서 정합성을 확인할 수 있다.");
177
201
  };
@@ -0,0 +1,12 @@
1
+ /** AGENTS.md 처리 결과. `legacy`·`broken` 은 파일을 고치지 않은 경우다 */
2
+ export type AgentsStatus = "written" | "legacy" | "broken";
3
+ /** init 이 넘겨주는 상태 */
4
+ export interface UpgradeInput {
5
+ root: string;
6
+ agents: AgentsStatus;
7
+ /** 내용이 바뀐 패키지 파일 */
8
+ overwritten: string[];
9
+ /** `<이름>/SKILL.md` 가 아닌 이전 경로에 남은 스킬 파일 */
10
+ oldSkills: string[];
11
+ }
12
+ export declare const renderUpgradePrompt: (input: UpgradeInput) => string;