@angar2/taskery 0.1.1 → 0.1.3

package/template/.claude/skills/add-backlog/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: add-backlog
+description: 사용자 발화로 *버전별* tasks/<vX.X>/BACKLOG.md에 task 후보 1건 추가 — 얕은 분석(개요/대상 영역) + BL-NNN 채번 + withMetaLock 직렬화 (0.1.2+)
+---
+
+# /add-backlog
+
+## 개요
+
+`/add-backlog`는 사용자 발화를 받아 *버전별 백로그* `.project/tasks/<vX.X>/BACKLOG.md`에 task 후보를 1건씩 누적한다. 멀티세션 환경에서 `withMetaLock`으로 동시 쓰기 직렬화. **얕은 분석**만 — 코드 직접 탐색 X, 추정 수준. 본격 분석은 다음 단계 `/task-plan`에서.
+
+글로벌 `.project/BACKLOG.md` (plan 기획 후보 카탈로그) 는 `/plan-init` 영역으로 본 스킬 무관.
+
+## 호출 시점
+
+- 사용자 명시 호출: `/add-backlog 로그인 빈 화면 떠`
+- 발화 캐치: *"~ 백로그에 추가해 줘"* / *"백로그에 ~"* 등 백로그 추가 의도 발화 description 매칭으로 메인이 자동 발동
+
+## 입력 처리
+
+- 무인자 호출: 사용자가 *"백로그 추가"*만 말한 경우 — 어떤 항목인지 한 줄 인터뷰
+- 인자 호출: 인자에 백로그 후보 주제. 1건 기본. 다건 명시 시 순차 처리
+
+## 단계 (Step 1~6)
+
+### Step 1 — 사전 검증
+
+- 메인 워크트리 검출:
+  ```sh
+  MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+  ```
+- 메인 워크트리 dev 체크아웃 검증 — 위배 시 사용자 호출 + 중단
+- 활성 버전 검출 — `$MAIN_WT/.project/AGENT-GUIDE.md` `## 활성 plan 버전` 섹션 다음 비어 있지 않은 첫 줄에서 `vX.X` 패턴 추출
+- BACKLOG.md 경로 = `$MAIN_WT/.project/tasks/<vX.X>/BACKLOG.md`. 부재 시 사용자 호출: *"`/plan-init` 먼저 호출해 활성 버전 디렉토리 + 빈 BACKLOG.md 생성 필요"* + 중단
+
+### Step 2 — 백로그 항목 후보 추출
+
+- 사용자 발화에서 1건 추출. 다건 명시 시 순차 처리 (각 1건씩 본 흐름 반복)
+- 입력이 비어 있으면 사용자에게 *"어떤 항목? 한 줄로 알려줘"* 인터뷰
+
+### Step 3 — 얕은 분석 (LLM, 코드 탐색 X)
+
+추정 수준의 메타 산출:
+- **유형** (`feature` / `bug` / `improve` / `refactor` / `docs` / `chore`) — 자동 추정, 모호 시 사용자 confirm
+- **제목** — 한 줄, 간결, 한국어
+- **개요** — 한 줄. bug → 원인 추정 / feature → 구상 / improve → 개선 방향
+- **대상 영역** — 한 줄. 이 파일 / 모듈일 거다 — 추정 수준
+
+> *코드 직접 탐색 금지*. 본격 분석은 다음 단계 `/task-plan`에서. 본 스킬은 *메모지 누적*만.
+
+### Step 4 — 결정적 슬러그 산출
+
+- 한국어 제목 → 영어 *의미 변환* → kebab-case (3 단어 이내, 음역 X)
+- 예: *"로그인 페이지 빈 화면"* → `login-empty-page` / *"다크모드 토글"* → `dark-mode-toggle`
+
+### Step 5 — BL-NNN 채번 + append (withMetaLock 직렬화)
+
+`bin/lib.js`의 `appendBacklogItem(mainWtPath, meta)` 호출.
+
+```js
+const lib = require('@angar2/taskery/bin/lib'); // 또는 패키지 내부 경로
+const blNum = await lib.appendBacklogItem(MAIN_WT, {
+  type: '<유형>',
+  title: '<제목>',
+  slug: '<슬러그>',
+  summary: '<개요>',
+  target: '<대상 영역>',
+});
+```
+
+내부 흐름:
+1. `withMetaLock(backlogPath)` 안에서:
+   - BACKLOG.md 전체에서 `BL-(\d+)` 패턴 grep → 최대값 + 1. 빈 파일 → BL-001 시작
+   - 항목 블록 포맷팅:
+     ```
+     - [ ] **BL-NNN** [유형] 제목 `slug`
+       - 개요: ...
+       - 대상 영역: ...
+     ```
+   - plan-init 빈 골격의 placeholder 라인 (`(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)`) 발견 시 → 그 자리에 치환. 미발견 시 → 파일 끝 빈 줄 + 블록 append
+
+### Step 6 — 결과 보고
+
+```
+✅ BL-<NNN> [<유형>] <제목> — <vX.X> 백로그 추가됐어.
+   - 개요: <개요>
+   - 대상 영역: <대상 영역>
+   - 슬러그: <slug>
+다음: 진행 의향이면 *"BL-<NNN> 진행"*이라고 말해. `/task-init`이 메타 그대로 받아 워크트리를 분기하고 항목을 `[x]` 확인 마킹할게.
+```
+
+## 도구 가이드
+
+- **Bash**: 메인 워크트리 검출 / dev 체크아웃 검증
+- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` (활성 버전 검출) / 기존 BACKLOG.md 정독 (중복 / 유사 항목 사전 확인)
+- **bin/lib.js**: `getActiveVersion` / `getBacklogPath` / `appendBacklogItem` 호출
+- **AskUserQuestion**: 유형 모호 시 confirm — 한 번에 한 질문
+
+## 주의사항
+
+- **얕은 분석만** — 본 스킬에서 도메인 코드 Read · Grep 금지. 본격 분석은 `/task-plan`
+- **유형 자동 추정 + 모호 시 confirm** — *"메뉴 검색 개선"* 같이 feature/improve 모호 시 사용자 결정 받기
+- **메인 워크트리 dev 검증 누락 X** — 위배 시 즉시 중단. 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md에 쓰기
+- **활성 버전 부재 시 즉시 중단** — `AGENT-GUIDE.md` 부재 / `## 활성 plan 버전` 섹션 부재 / vX.X 패턴 추출 실패 모두 명확한 에러 메시지 후 사용자 호출
+- **결정적 슬러그 best-effort** — LLM 비결정성 수용. race 차단 본체는 SSoT 2층(`/task-init` §4.4)이 담당. 슬러그 변형 발생 시 사용자 confirm
+- **글로벌 BACKLOG.md (plan 기획 후보)** 와 혼동 X — 본 스킬은 *버전별*만 다룸. 글로벌은 `/plan-init` 영역
+- **자동 추정 진행 X** — 유형 / 제목 / 개요 / 대상 영역 모두 사용자 OK 또는 명백한 발화 매칭 후에만 BACKLOG.md 쓰기
+
+## 상태 전이
+
+해당 없음 (백로그 메모지 누적 — task 상태 X).
+
+## 멀티세션 정합
+
+- **위치 = 메인 워크트리 절대 경로** — 워크트리 안에서 호출돼도 메인 절대 경로의 BACKLOG.md를 단일 소스로 사용
+- **`withMetaLock` 직렬화** — 두 메인 세션이 동시 `/add-backlog` 호출 시 락으로 직렬화 (proper-lockfile, stale=30s, retries=5). 한 세션 `/add-backlog` + 다른 세션 `/task-init` (BL 마킹) 동시 시도 시 락 정합
+- **체크박스 의미** — `[ ]` = 미확인 (task로 옮기지 않은 메모) / `[x]` = 확인 완료 (task로 옮김). **dev 머지 완료 의미 X** — 완료 추적은 `git log dev --grep 'BL-NNN'` + 브랜치명 + `taskery status`

package/template/.claude/skills/plan-init/SKILL.md

@@ -66,7 +66,11 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
    - **ARCHITECTURE.md**: 시스템 구조 (멀티 리포 / 레이어드 / 마이크로서비스 등)
    - **DATA-MODEL.md** (해당 시): 주요 엔티티 + 관계
    - **API-SPEC.md**: 엔드포인트 목록 + 인증 방식
-   - **ROADMAP.md**: 마일스톤 + 시기 + 우선순위
+   - **ROADMAP.md**: 마일스톤 + 시기 + 우선순위. *ROADMAP 작성 4룰* (stash FRICTION_LOG #1 반영):
+     1. ROADMAP은 *현재 버전 한정* — 미래 버전 후보는 별도 `BACKLOG.md` (글로벌) 분리
+     2. 진행 순서에 task 번호(TASK-NNN) 강제 금지 — *Stage(영역) 단위*로만 명시 (예측 불가 task 합류 시 번호 어긋남 방지)
+     3. Stage 안 *작업 단위 명시* 필요 (한 task 분량 권장 — 다음 task 진행 시 메인 세션이 ROADMAP 보고 작업 범위 판단 가능)
+     4. 작업 단위에 task 번호 컬럼 추가 X / *상태 컬럼만* (⏳ 대기 / 🔧 진행 중 / ✅ 완료 / ❌ 폐기) — Living document
 4. 받은 답 기반으로 각 문서 작성.
 5. 마지막에 **PLAN.md** 작성 — 9 문서 인덱스 + 체크리스트.
 6. **`.project/AGENT-GUIDE.md`의 활성 plan 버전 vX.X로 갱신** (신규도 동일 — 분기 2와 일관).
@@ -84,7 +88,26 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
 ### Step 5 — `tasks/<vX.X>/` 디렉토리 준비
 
 1. `.project/tasks/<vX.X>/` 디렉토리 생성 (빈 폴더).
-2. `.project/tasks/<vX.X>/spec-diffs/`, `.project/tasks/<vX.X>/screenshots/` 빈 폴더 미리 생성.
+2. `.project/tasks/<vX.X>/spec-diffs/`, `.project/tasks/<vX.X>/screenshots/`, `.project/tasks/<vX.X>/mockup/` 빈 폴더 미리 생성.
+3. `.project/tasks/<vX.X>/BACKLOG.md` 빈 골격 Write (stash FRICTION_LOG #17 반영) — *버전별 task 후보 누적용*, 글로벌 `.project/BACKLOG.md`와 별개:
+
+```markdown
+# BACKLOG — <vX.X>
+
+> 본 파일은 *<vX.X> plan 진행 중 누적되는 후속 task 후보* 추적용.
+> 글로벌 `.project/BACKLOG.md` (plan 기획 후보 카탈로그) 와 별개.
+
+| 위치 | 영역 | 역할 |
+|------|------|------|
+| `.project/BACKLOG.md` (글로벌) | plan 기획 후보 카탈로그 (다음 plan 버전에서 검토) | Living document |
+| `.project/tasks/<vX.X>/BACKLOG.md` (본 파일) | 현재 plan 진행 중 누적된 후속 task 후보 | 한 버전 내 task close 직후 후보 누적 |
+
+## 후속 task 후보
+
+(사용자 발화 또는 task-close 직후 메인 감지로 한 행씩 추가. 빈 상태 default.)
+```
+
+빈 골격만 작성. 본문은 task 진행하면서 사용자 발화 또는 메인 감지로 누적.
 
 ### Step 6 — `PLAN.md` 작성/갱신
 
@@ -119,12 +142,12 @@ plan 버전(vX.X)마다 호출. `.project/plans/<vX.X>/` 안에 9 기획 문서
 **결과 commit 흐름** (GIT_RULE 정합):
 - dev 직접 commit *금지* (git-guard.sh 차단). 두 가지 default 흐름:
   1. **첫 task에 묶기 (권장)**: 분기 1(신규)에서 `/project-init` 직후 본 스킬 호출이면 `/project-init` 산출물과 같은 작업 브랜치(보통 TASK-001 부트스트랩 chore)에 함께 commit. 분기 2(이어가기)면 새 task 브랜치 또는 임시 docs 브랜치에서.
-  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_plan-{vX.X}` 후 commit → dev에 `--no-ff` 머지. 다음 task 생성 *전*에 plan 산출물을 깔끔히 박고 싶을 때.
+  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_plan-{vX.X}` 후 commit → dev에 `--no-ff` 머지. 다음 task 생성 *전*에 plan 산출물을 깔끔히 기록하고 싶을 때.
 
 ## 도구 가이드
 
 - **Read**: PROJECT.md / 기존 plans/vY.Y/ 정독
-- **Bash**: `ls .project/plans/`, `cp -r plans/vY.Y plans/vX.X`, `mkdir -p plans/<vX.X> tasks/<vX.X>/{spec-diffs,screenshots}`
+- **Bash**: `ls .project/plans/`, `cp -r plans/vY.Y plans/vX.X`, `mkdir -p plans/<vX.X> tasks/<vX.X>/{spec-diffs,screenshots,mockup}`
 - **Write/Edit**: 9 기획 문서 작성/갱신
 - **AskUserQuestion**: 9 문서별 핵심 질문 + 변경 인터뷰
 

package/template/.claude/skills/project-init/SKILL.md

@@ -92,7 +92,9 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 1. `CLAUDE.md` — 프로젝트 메타 + 검증 명령 + 룰 참조
 2. `.project/PROJECT.md` — 프로젝트 개요
 3. `.project/plans/<활성버전>/PLAN.md` — 활성 plan 진입 (이게 9 기획 문서 인덱스)
-4. `.project/AGENT-GUIDE.md` — 본 파일 (그대로)
+4. `.project/GLOSSARY.md` — 도메인 용어집 (영문/한글 표기 일관성 단일 진실 소스)
+5. `.project/tasks/<활성버전>/BACKLOG.md` — 현재 plan 진행 중 누적된 후속 task 후보 (사용자 발화 *"이건 다음 task로"* / task-close 직후 메인 감지로 추가)
+6. `.project/AGENT-GUIDE.md` — 본 파일 (그대로)
 
 ## 작업 흐름
 - task 시작: `/task-init` 또는 `/task-plan`
@@ -100,7 +102,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 - 불편 등록: `/log-friction` (사용자 호출 / 발화 캐치 / task-close 자체 감지)
 
 ## 폴더 구조
-- `.project/rules/` — 코어 룰 (TASK_DOC_RULE / GIT_RULE)
+- `.project/rules/` — 코어 룰 (TASK_DOC_RULE / GIT_RULE / CHANGELOG_RULE / MOCKUP_RULE)
 - `.project/plans/<vX.X>/` — 9 기획 문서
 - `.project/tasks/<vX.X>/` — task 문서
 - `.project/flows/` — 도메인 흐름
@@ -113,8 +115,33 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 멀티 리포면 "LINKED-REPOS.md 참조">
 ```
 
+### Step 4.5 — `.project/GLOSSARY.md` 작성 (도메인 용어집)
+
+stash FRICTION_LOG #3 반영 — 프로젝트 도메인 용어를 *영문/한글 표기 일관성* 단일 진실 소스로 모음. 코드 메서드명·변수명 / 대화·문서 한글 표기 통일.
+
+```markdown
+# GLOSSARY — <프로젝트명>
+
+> 본 프로젝트에서 사용하는 도메인 용어집. 코드 식별자 / 문서 / 대화 모두 본 표 기준.
+> 새 용어 추가 시 영문 알파벳 순 정렬 유지.
+
+| 영문 | 한글 | 정의 | 출처 |
+|------|------|------|------|
+| | | | |
+
+## 운용 룰
+
+- 영문 알파벳 순 정렬
+- 출처: 본 용어가 도입된 task/plan 문서 경로 (예: `plans/v1.0/FEATURES.md`)
+- 동의어 / 변형 표기 발견 시 본 표 기준으로 정합
+```
+
+빈 표만 작성. 본문은 plan/task 진행하면서 사용자가 채움.
+
 ### Step 5 — `.project/LINKED-REPOS.md` 작성
 
+멀티리포 구성 명세. 단일 리포면 빈 템플릿만, 멀티 리포면 연결 리포 목록까지.
+
 ```markdown
 # LINKED-REPOS.md
 
@@ -153,7 +180,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 - `.project/tasks/` (`.gitkeep` — `/task-init`이 `vX.X/<NNN>_<slug>.md` 작성)
 - `.project/shared/{sent,received}/completed/` (`.gitkeep`)
 - `.project/FRICTION_LOG.md` (빈 템플릿)
-- `.project/rules/{TASK_DOC_RULE,GIT_RULE}.md` (코어 룰)
+- `.project/rules/{TASK_DOC_RULE,GIT_RULE,CHANGELOG_RULE,MOCKUP_RULE}.md` (코어 룰)
 
 → `/project-init`은 폴더 생성 X. 누락 시(`init` 안 거치고 수동 셋업한 경우)에만 `mkdir -p` 실행.
 
@@ -193,12 +220,12 @@ git branch -a                                        # main(또는 master) + dev
 ### Step 8 — 결과 보고
 
 작성된 파일 목록 + 다음 단계 안내:
-- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). **빈 폴더 케이스라 git init + dev 분기까지 완료** (이미 git 리포면 건너뜀). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
+- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / GLOSSARY.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). **빈 폴더 케이스라 git init + dev 분기까지 완료** (이미 git 리포면 건너뜀). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
 
 **결과 commit 흐름** (GIT_RULE 정합):
 - dev 직접 commit *금지* (git-guard.sh 차단). 두 가지 default 흐름:
   1. **첫 task에 묶기 (권장)**: `/plan-init` 끝나고 첫 `/task-init` (보통 TASK-001 부트스트랩 chore)으로 만든 작업 브랜치에서 init 산출물(PROJECT/AGENT-GUIDE/LINKED-REPOS/.env)도 함께 commit. task-close 단계의 "태스크 문서 커밋"에 자연스럽게 묶임.
-  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_init-bootstrap` 후 commit → dev에 `--no-ff` 머지. 첫 task 생성 *전*에 init 결과를 깔끔히 박고 싶을 때.
+  2. **임시 docs 브랜치**: `git checkout -b docs/{개발자}_init-bootstrap` 후 commit → dev에 `--no-ff` 머지. 첫 task 생성 *전*에 init 결과를 깔끔히 기록하고 싶을 때.
 
 ## 도구 가이드