@angar2/taskery 0.1.0 → 0.1.1

package/README.md

@@ -1,117 +1,222 @@
 # taskery
 
-> Claude Code 메인 세션을 위한 *가벼운 task 시스템*.
-> **1 메인 세션 + 스킬 8종 + catastrophic hook 3종 + npx 배포**.
+AI 코딩 에이전트의 자율 개발을 위한 Task 기반의 가드레일 시스템.
 
 ---
 
-## 한 줄 정신
+## 해결하는 문제
 
-practice 영역(SW 개발)을 process로 강제하지 않는다.
+- Task 단위 라이프사이클의 가이드를 제시한다.
+- 메인 세션을 단독으로 운영할 때 자주 발생하는 사고를 사전 차단한다.
 
-- **Process는 자동화 OK, Practice는 자유롭게 + 사용자 판단 신뢰** — 결정적 영역(린트/타입/빌드)만 강제, 휴리스틱은 강제 X
-- **Catastrophic만 hook 차단, 형식 위반은 instruction + 대화** — 합리적 변형 차단 사고 회피
-- **Top-down 선제적 작성 금지, bottoms-up** — 진짜 데이터 모이면 그때 추가 (PLAYBOOK 카탈로그 + FRICTION_LOG 패턴 ≥ 3회 트리거)
+| 문제 | taskery 대응 |
+|------|------------|
+| AI 협업 작업이 매번 즉흥적이라 일관된 체계가 없음 | task 단위 라이프사이클로 작업 흐름 구조화 — 단계별 자동화 가능 |
+| 작업 컨텍스트가 휘발되어 이전 결정·사유를 추적하기 어려움 | task 문서로 컨텍스트와 히스토리 기록 — 작업 중 참조 가능 |
+| 에이전트가 catastrophic 사고를 일으킬 수 있음 | 필수 hook으로 차단 — 정상 흐름에는 무간섭 |
+| 에이전트가 작성한 코드의 자가검증으로 인해 문제를 놓침 (confirmation bias) | 테스트 시 별도 격리 세션 호출(`/task-test`) — 메인 세션의 가정 없이 독립 검증 |
+
+> catastrophic 사고 예시 — git 운영 정책 위반, 검증 우회, 완료된 task 문서 재수정 등
+
+---
+
+## 워크플로우
+
+task 단위 라이프사이클은 7 상태로 구성된다.
+
+**task 상태**
+
+```
+draft → planned → developing → developed → testing → tested → closed
+```
+
+| 상태 | 의미 |
+|------|------|
+| `draft` | 새 task 생성 직후 |
+| `planned` | 작업 기획 완료 |
+| `developing` | 구현 진행 중 |
+| `developed` | 구현 완료 (자가 검증 통과) |
+| `testing` | 독립 검증 진행 중 |
+| `tested` | 독립 검증 완료 |
+| `closed` | git 커밋 + dev 병합 완료 |
+
+> 상태별 전이 조건과 task 문서 양식은 [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md)에서 확인 가능
 
 ---
 
 ## 빠른 시작
 
+> **요구 사항**: Node.js ≥ 18.
+
+### npx
+
+특정 프로젝트에 일회성 다운로드 방식.
+
 ```bash
 # 새 프로젝트
 npx -p @angar2/taskery create-taskery <project-name>
 
-# 기존 프로젝트에 설치
-cd <your-project>
+# 기존 프로젝트에 도입
+cd <project-name>
 npx @angar2/taskery init
 
-# 최신 버전 동기화
+# 최신 버전 머지 갱신
 npx @angar2/taskery update
 ```
 
-> 글로벌 install (`npm install -g @angar2/taskery`) 후엔 `taskery init` / `create-taskery <name>` 단축 명령 사용 가능.
+### 글로벌 npm install
 
-요구 사항: Node.js >=18, Claude Code (CLI / VS Code / JetBrains).
+
+```bash
+# 글로벌 설치
+npm install -g @angar2/taskery
+
+# 새 프로젝트
+create-taskery <project-name>
+
+# 기존 프로젝트에 도입
+cd <project-name>
+taskery init
+
+# 최신 버전 머지 갱신
+taskery update
+```
 
 ---
 
-## 스킬 8종 — project > plan > task 위계 + 회고
+## 패키지 디렉토리 구조
+
+`taskery init` 직후 골격:
+
+```
+my-app/
+├─ CLAUDE.md                              # AI 에이전트 진입 문서
+├─ .taskery-manifest.json                 # 패키지 업데이트 추적
+├─ .gitignore
+├─ .claude/
+│   ├─ settings.json                      # hook 등록 (PreToolUse 매칭)
+│   ├─ skills/<skil-name>/SKILL.md        # 8 skill
+│   └─ hooks/<hook-name>.sh               # 3 hook
+└─ .project/
+    ├─ PROJECT.md                         # 프로젝트 개요
+    ├─ AGENT-GUIDE.md                     # AI 에이전트 가이드
+    ├─ LINKED-REPOS.md                    # 관계 리포지토리 정보
+    ├─ .env                               # 사용자 설정 환경변수 (관계 리포지토리 환경변수 등)
+    ├─ rules/
+    │   ├─ TASK_DOC_RULE.md               # task 문서 작성 규칙
+    │   ├─ GIT_RULE.md                    # 로컬 깃 운영 규칙
+    │   └─ *.local.md                     # 사용자 오버라이드 규칙 (패키지 업데이트 대상 제외)
+    ├─ plans/                             # plan 문서
+    ├─ tasks/                             # task 문서
+    ├─ flows/                             # 서비스 로직 플로우 정보
+    ├─ changelog/                         # 수정사항 정보
+    ├─ shared/                            # 관계 리포지토리 소통 메세지함
+    │   ├─ sent/completed/
+    │   └─ received/completed/
+    └─ FRICTION_LOG.md                    # taskery 불편사항 누적 로그
+```
+
+---
+
+## Skills
+
+스킬은 호출 시점에 따라 4 카테고리(`project` / `plan` / `task` / `meta`)로 분류된다.
+
+- `project` — 프로젝트 첫 도입 시 1회만 호출
+- `plan` — 새 기획 버전 시작 시 호출
+- `task` — 새 task 작업 진행 단계에서 호출
+- `meta` — 그 외 taskery 관리
 
 | 스킬 | 레벨 | 역할 |
 |------|------|------|
-| `/project-init` | project | PROJECT/AGENT-GUIDE/LINKED-REPOS/.env 골격 생성 (1회성) |
-| `/plan-init` | plan | `.project/plans/<vX.X>/` 안 기획 문서 작성 |
-| `/task-init` | task | task.md 빈 골격 + status=draft |
-| `/task-plan` | task | Requirements/Scope/Dev Plan/Test Plan 작성 |
-| `/task-dev` | task | Phase 순서 구현 + self-check |
-| `/task-test` | task | 격리 세션 검증 (confirmation bias 회피) |
-| `/task-close` | task | 검증 명령 게이트 + 커밋 + dev 병합 |
-| `/refine` | meta | FRICTION_LOG 정독 + 패턴 감지 + bottoms-up 보강 제안 |
+| `/project-init` | project | 프로젝트 첫 도입 시 메타 문서와 디렉토리 골격 생성 (1회성) |
+| `/plan-init` | plan | 새 기획 버전의 기획 문서 작성 |
+| `/task-init` | task | 새 task의 빈 문서 생성 |
+| `/task-plan` | task | task의 요구사항·범위·개발 계획·테스트 계획 작성 |
+| `/task-dev` | task | 계획에 따른 단계별 구현 + 자가 검증 |
+| `/task-test` | task | 별도 격리 세션에서 독립 검증 (메인 가정 차단) |
+| `/task-close` | task | 최종 검증 후 git 커밋 + dev 브랜치 `--no-ff` 병합 |
+| `/log-friction` | meta | 사용자 불편을 `.project/FRICTION_LOG.md`에 한 행 기록 |
 
-명령어 직접 호출(`/task-init` 등) 또는 메인 세션이 frontmatter description 매칭으로 자동 발동.
+각 스킬은 슬래시로 직접 호출하거나, 사용자 발화의 의미가 스킬의 frontmatter description과 매칭되면 메인 세션이 자동으로 발동시킨다.
+
+`/project-init`, `/plan-init`, `/task-init` 세 스킬은 호출 시 다음 문서를 생성한다.
+
+| 스킬 | 생성 위치 | 생성 문서 |
+|------|---------|---------|
+| `/project-init` | `.project/` | PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env |
+| `/plan-init` | `.project/plans/<plan-name>/` | 9 기획 문서 — PLAN.md / SERVICE-POLICY.md / FEATURES.md / UX-UI.md / TECH-STACK.md / ARCHITECTURE.md / DATA-MODEL.md / API-SPEC.md / ROADMAP.md (프로젝트 타입에 따라 일부 제외) |
+| `/task-init` | `.project/tasks/<plan-name>/` | `<NNN>_<slug>.md` (단일 파일) 또는 `TASK-<NNN>_<slug>/task.md` (규모 `large` 시 폴더 승격) |
+
+> 각 스킬의 호출 시점, 입력 처리 방식, 단계별 절차, 주의사항은 [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md)에서 확인 가능
 
 ---
 
-## Catastrophic Hook 3종
+## Hooks
 
-| Hook | 영역 | 잡는 것 |
-|------|------|--------|
-| `git-guard.sh` | PreToolUse(Bash) | main/dev 직접 커밋 / `--force` / `--no-verify` / `branch -D` / `reset --hard` |
-| `pre-commit-verify.sh` | PreToolUse(Bash) | `git commit` 시 검증 명령(린트/타입/빌드/테스트) 모두 PASS 게이트 |
-| `closed-immutable.sh` | PreToolUse(Write\|Edit) | `closed` 상태 task.md 본 파일 재수정 차단 |
+| Hook | 작동 시점 | 차단 대상 |
+|------|---------|---------|
+| `git-guard.sh` | git 명령 실행 직전 | 주력 브랜치 직접 커밋 / `--force` / `--no-verify` / 강제 브랜치 삭제 / `reset --hard` / `clean -fd` |
+| `pre-commit-verify.sh` | `git commit` 실행 직전 | 검증 명령(린트·타입체크·빌드·테스트) 통과 실패 commit |
+| `closed-immutable.sh` | 파일 수정 직전 | 완료(`closed`)된 task.md 본 파일 재수정 (관련 spec-diff·스크린샷은 자유) |
 
-**잘 지키면 hook 작동 0회 (무해). catastrophic만 차단.**
+hook은 catastrophic 사고만 차단한다. 정상 흐름에는 간섭하지 않는다.
+
+> 각 hook의 영역 분리 정신, 등록 매칭, 차단 정책, 예외 처리 절차는 [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md)에서 확인 가능
 
 ---
 
-## 디렉토리 구조 (사용자 프로젝트 — `npx @angar2/taskery init` 후)
+## 워크플로우 예시
+
+```bash
+# 사용자 프로젝트 첫 셋업
+cd <project-name>
+npx @angar2/taskery init
+```
+
+이후 메인 세션에 진입(`CLAUDE.md` 자동 정독)하여 다음 시퀀스로 호출한다. task 5 스킬은 호출과 동시에 상태를 전이시킨다.
 
 ```
-my-app/
-├─ CLAUDE.md                     # 메인 세션 진입점
-├─ .taskery-manifest.json        # 자산 manifest (npx 자동 갱신)
-├─ .claude/
-│   ├─ settings.json             # hook 등록
-│   ├─ skills/                   # 8 스킬
-│   └─ hooks/                    # 3 catastrophic 안전망
-└─ .project/
-    ├─ PROJECT.md                # /project-init 생성
-    ├─ AGENT-GUIDE.md            # /project-init 생성
-    ├─ rules/
-    │   ├─ TASK_DOC_RULE.md      # task 양식
-    │   └─ GIT_RULE.md           # git 정책
-    ├─ plans/                    # /plan-init 생성
-    ├─ tasks/                    # /task-init 생성
-    ├─ flows/                    # /task-dev 갱신
-    ├─ changelog/                # /task-close 갱신
-    ├─ shared/                   # 멀티리포 메시지
-    └─ FRICTION_LOG.md           # 짜증 누적
+/project-init                  # 진입 메타 문서와 디렉토리 골격 생성
+/plan-init v1.0                # v1.0 기획 문서 작성
+/task-init                     # draft : 첫 task의 빈 문서 생성
+/task-plan TASK-001            # draft → planned : 요구사항·범위·개발 계획·테스트 계획 작성
+/task-dev TASK-001             # planned → developed : 단계별 구현과 자체 검증
+/task-test TASK-001            # developed → tested : 별도 격리 세션으로 독립 검증
+/task-close TASK-001           # tested → closed : 최종 검증 후 git 커밋과 dev 병합
+
+# 불편 발생 시 등록
+/log-friction                  # 사용자 불편 한 행 기록
 ```
 
----
+**자동 발동 예시** — 사용자 발화 의미가 스킬 description과 매칭되면 메인이 슬래시 직접 호출 없이 다음 스킬을 자동 발동한다.
 
-## 상세 문서
+- *"로그인 기능 추가해줘"* / *"이 버그 고쳐줘"* → `/task-init` 자동 발동 (새 task 시작 의도)
+- *"기획 다 됐으니 이제 구현 시작해"* → `/task-dev` 자동 발동 (planned task의 다음 단계)
+- *"이거 진짜 불편하다"* / *"이 부분 답답하네"* → `/log-friction` 자동 발동 (불만 발화 캐치)
 
-> 본 리포 spec 문서는 npm 패키지에 포함되지 않으므로 GitHub에서 정독.
+**실패·불확정 분기** — `/task-test`가 FAIL 또는 UNCERTAIN을 반환하면 메인 세션이 사용자에게 판단을 묻고, 사용자의 자연어 답변에서 의도를 해석해 다음 흐름을 *자동 발동*한다(별도 슬래시 호출 없이 진행됨).
 
-- [plan/OVERVIEW.md](https://github.com/angar2/taskery/blob/main/plan/OVERVIEW.md) — 진입 + 큰 그림 + 단일 진실 소스
-- [plan/SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md) — 스킬 8종 명세 + 흐름
-- [plan/TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md) — 태스크 양식 + 7 상태
-- [plan/HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md) — 3 catastrophic hook 정책
-- [plan/DISTRIBUTION.md](https://github.com/angar2/taskery/blob/main/plan/DISTRIBUTION.md) — npx 배포 + manifest
-- [plan/DECISIONS.md](https://github.com/angar2/taskery/blob/main/plan/DECISIONS.md) — 핵심 의사결정
-- [plan/PLAYBOOK.md](https://github.com/angar2/taskery/blob/main/plan/PLAYBOOK.md) — 미래 옵션 카탈로그
+- 사용자가 재구현을 요청하면 → `testing` → `developing`으로 회귀해 `/task-dev`가 자동 발동된다.
+- 사용자가 결함을 인지한 채 종결을 지시하면 → `testing` → `tested`로 진행하고 결함을 명시한 후 `/task-close`로 이행된다.
+- UNCERTAIN(자동 검증이 불가능한 시나리오)은 사용자가 직접 검수한 결과를 답하면 메인 세션이 PASS/FAIL로 해석해 위 두 흐름 중 하나로 합류시킨다.
 
 ---
 
-## 라이선스
+## 상세 문서
+
+spec 문서는 GitHub에서 참고할 수 있다.
 
-[MIT](LICENSE)
+- [OVERVIEW.md](https://github.com/angar2/taskery/blob/main/plan/OVERVIEW.md) — 시스템 진입 가이드와 전체 구조 개요.
+- [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md) — 스킬 8종의 상세 명세와 호출 흐름.
+- [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md) — task 문서의 작성 양식과 7 상태 머신의 동작 정의.
+- [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md) — catastrophic hook 3종의 정책과 예외 처리 절차.
+- [DISTRIBUTION.md](https://github.com/angar2/taskery/blob/main/plan/DISTRIBUTION.md) — npx 배포 메커니즘과 자산 갱신 로직.
+- [DECISIONS.md](https://github.com/angar2/taskery/blob/main/plan/DECISIONS.md) — 시스템 설계의 핵심 의사결정과 변경 이력.
+- [PLAYBOOK.md](https://github.com/angar2/taskery/blob/main/plan/PLAYBOOK.md) — 향후 도입 가능한 기능 후보 목록.
 
 ---
 
-## 수정 이력
+## 라이센스
 
-| 날짜 | 변경 사항 |
-|------|----------|
-| 2026-05-09 | 신규 작성 — npm 페이지 진입 문서 |
+[MIT](LICENSE)

package/bin/lib.js

@@ -37,7 +37,7 @@ function sha256(filePath) {
 
 function walkTemplate(templateDir) {
   // template/ 안 모든 파일 상대경로 + 해시 맵 리턴
-  // 결과: { 'CLAUDE.md': 'sha256:...', '.claude/skills/task-init.md': 'sha256:...', ... }
+  // 결과: { 'CLAUDE.md': 'sha256:...', '.claude/skills/task-init/SKILL.md': 'sha256:...', ... }
   const result = {};
   function walk(dir, relBase) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angar2/taskery",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight task system for Claude Code — 1 메인 세션 + 스킬 8종 + catastrophic hook 안전망 3종",
   "bin": {
     "taskery": "bin/taskery.js",

package/template/.claude/skills/log-friction/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: log-friction
+description: 사용자가 작업 흐름 중 겪은 불편(friction)을 .project/FRICTION_LOG.md에 한 행 기록한다. 사용자가 짜증·불만·답답함을 표현하면 자동 발동(등록 제안). 명시 호출(`/log-friction`) 또는 `/task-close` 직후 마찰 신호 자체 감지 시에도 발동한다.
+---
+
+# /log-friction
+
+## 개요
+
+사용자가 작업 흐름 중 겪은 불편을 `.project/FRICTION_LOG.md`에 한 행 기록한다.
+후속 조치 X — 분석 / 패턴 감지 / 룰 제안 자체를 본 스킬이 수행하지 않는다. 사용자가 직접 검토 후 판단한다.
+
+## 호출 시점 (3가지 트리거)
+
+1. **사용자 명시 호출** — `/log-friction "<불편 내용>"` 또는 인자 없이 호출
+2. **사용자 불만 발화 캐치** — 메인 세션이 사용자 발화에서 불편·짜증·답답함 신호를 감지하면 *"이거 FRICTION_LOG에 등록할까?"* 제안한 후 사용자 OK 시 자동 발동
+3. **task-close 직후 메인 자체 감지** — 작업 중 마찰 신호(동일 단계 재호출 / 실패 반복 / 사용자 부정 반응 누적 등)가 감지된 경우에만 *"이번 task에서 X 부분이 마찰이었어 보여 — 등록할까?"* 제안한 후 사용자 OK 시 발동. 감지 신호 없으면 호출 X
+
+## 입력 처리
+
+- 인자 형태 (사용자 명시 호출):
+  - `/log-friction "<불편 내용>"` — 큰따옴표 인자에 본문 직접 전달
+  - `/log-friction` — 인자 없이 호출 시 메인이 사용자에게 *"어떤 점이 불편했는지?"* 묻고 답변을 받음
+- 자동 발동 시: 메인이 캐치한 발화 또는 감지한 마찰 신호를 사용자에게 *확인 차원*으로 보여주고 등록 본문에 대해 합의를 받음
+
+## 단계
+
+### Step 1 — 호출 경로 확인
+
+호출 형태에 따라 분기한다.
+
+- 직접 호출 (인자 있음) → 인자 본문을 등록 후보로 사용
+- 직접 호출 (인자 없음) → 사용자에게 불편 내용을 질문
+- 자동 발동 (불만 발화 캐치) → 캐치한 발화를 등록 후보로 보여주고 사용자 합의
+- 자동 발동 (task-close 자체 감지) → 감지한 마찰 신호를 보여주고 사용자 합의
+
+### Step 2 — 등록 본문 확정
+
+사용자가 합의한 내용을 한 행(1~3 문장 이내)으로 정리한다.
+
+포맷:
+
+```
+- YYYY-MM-DD | <맥락 — TASK 번호 또는 호출 시점> | <불편 내용 요약>
+```
+
+### Step 3 — FRICTION_LOG.md 한 행 추가
+
+`.project/FRICTION_LOG.md`를 Read한 후 마지막 행 다음에 신규 행을 Append(Edit)한다.
+파일이 없거나 비어 있으면 안내 후 첫 행을 작성한다.
+
+### Step 4 — 결과 보고
+
+```
+✅ /log-friction 완료
+- 추가된 행: <등록 본문>
+- 누적 행 수: <N>건
+- 다음 호출: 사용자 명시 / 불만 발화 캐치 / task-close 자체 감지 중 하나
+```
+
+## 도구 가이드
+
+- **Read**: `.project/FRICTION_LOG.md` 정독
+- **Edit**: 마지막 행 다음에 신규 행 Append
+- **AskUserQuestion**: Step 1·2 사용자 합의
+
+## 주의사항
+
+- 본 스킬은 *기록 행위*만 수행한다. 패턴 분석 / PLAYBOOK 매핑 / 룰 제안 X.
+- task-close 자체 감지 트리거는 *마찰 신호 감지* 시에만 발동한다. 감지 없는 task-close에서 prompt 강제 X.
+- 사용자 합의 없이 자동 등록 X. 자동 발동 경로도 반드시 사용자 OK 후 기록한다.
+- 메인 자체 판단으로 등록 본문을 임의 가공·확장 X. 사용자 발화 또는 감지한 신호를 *그대로 인용* 원칙.
+
+## 상태 전이
+
+해당 없음 (meta 레벨 — task 상태 전이 X).

package/template/.claude/skills/{plan-init.md → plan-init/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: plan-init
 description: plan 버전 단위 9 기획 문서 작성 — 신규 vX.X/ 또는 기존 카피 후 변경 인터뷰
 ---
 

package/template/.claude/skills/{project-init.md → project-init/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: project-init
 description: taskery 도입 직후 1회성 — PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env 빈 골격 생성
 ---
 
@@ -96,7 +97,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 ## 작업 흐름
 - task 시작: `/task-init` 또는 `/task-plan`
 - task 진행: `/task-dev` → `/task-test` → `/task-close`
-- 회고: `/refine` (5 task마다 또는 사용자 호출)
+- 불편 등록: `/log-friction` (사용자 호출 / 발화 캐치 / task-close 자체 감지)
 
 ## 폴더 구조
 - `.project/rules/` — 코어 룰 (TASK_DOC_RULE / GIT_RULE)
@@ -105,7 +106,7 @@ taskery 도입 직후 **1회성**으로 호출. 사용자 또는 동료가 새
 - `.project/flows/` — 도메인 흐름
 - `.project/shared/` — 멀티리포 메시지
 - `.project/changelog/` — 월별 변경 이력
-- `.project/FRICTION_LOG.md` — 짜증 데이터
+- `.project/FRICTION_LOG.md` — 불편 데이터
 
 ## 멀티리포
 <단일 리포면 "단일 리포. LINKED-REPOS.md 빈 템플릿."
@@ -164,10 +165,35 @@ mkdir -p .project/shared/sent/completed .project/shared/received/completed
 
 `.project/FRICTION_LOG.md`도 `init`이 카피한 빈 템플릿 그대로 사용. **이미 있으면 덮어쓰기 X** — 사용자 데이터 보호.
 
+### Step 7.5 — git 초기화 + 첫 ref 분기 (빈 폴더 케이스)
+
+`git status`가 *fatal: not a git repository* 에러면 빈 폴더 진입 케이스. 다음 4단계 실행:
+
+```bash
+git status 2>&1 | head -1
+# "fatal: not a git repository" 면 미초기화
+```
+
+미초기화 시:
+
+```bash
+git init
+git commit --allow-empty -m "chore: root commit"   # ref 생성용 (commit 0 상태에선 branch 만들어도 ref 안 박힘)
+git symbolic-ref --short HEAD                       # 현재 default branch 확인 (예: main 또는 master)
+git branch dev                                       # 같은 sha에 dev 분기
+git branch -a                                        # main(또는 master) + dev 둘 다 떠야 함
+```
+
+이렇게 하지 않으면 첫 task `git checkout -b feature/...`까지는 동작하지만 **dev 브랜치 ref 자체가 없어서** `--no-ff` 머지 시점에 막힘. 사용자가 수동 `git branch dev <root-sha>` 매핑 필요.
+
+이미 git 초기화된 리포면 (status 정상) 이 step 건너뜀.
+
+> root commit이 빈 commit으로 박히는 게 싫으면 생략 가능. 단 그러면 첫 task chore commit이 박히기 *전엔* dev/main ref 못 만듦 → 첫 머지 직전에 사용자/메인이 명시 매핑 필요.
+
 ### Step 8 — 결과 보고
 
 작성된 파일 목록 + 다음 단계 안내:
-- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
+- *"PROJECT.md / AGENT-GUIDE.md / LINKED-REPOS.md / .env 생성. (FRICTION_LOG.md / 빈 골격 폴더는 npx init이 이미 카피한 것 그대로). **빈 폴더 케이스라 git init + dev 분기까지 완료** (이미 git 리포면 건너뜀). 다음은 `/plan-init <버전명>`으로 9 기획 문서 작성."*
 
 **결과 commit 흐름** (GIT_RULE 정합):
 - dev 직접 commit *금지* (git-guard.sh 차단). 두 가지 default 흐름:

package/template/.claude/skills/{task-close.md → task-close/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-close
 description: task git 마무리 — 검증 명령 재실행 게이트 + 커밋 순서 준수 + dev --no-ff 병합, tested → closed
 ---
 
@@ -137,8 +138,23 @@ PASS 시 Step 3으로.
 4. Step 4-3: 태스크 문서 커밋 (status=closed 적용된 채로)
 5. Step 4-4: CHANGELOG 커밋
 6. Step 5: dev 병합
+7. Step 7: 마찰 신호 자체 감지 (`/log-friction` 발동 후보)
+8. Step 8: 결과 보고
 
-### Step 7 — 결과 보고
+### Step 7 — 마찰 신호 자체 감지 (`/log-friction` 발동 후보)
+
+본 task 진행 중 *마찰 신호* 누적 여부를 검사한다. 감지 시 `/log-friction` 등록을 사용자에게 제안.
+
+검사 항목:
+- 동일 단계 재호출 ≥ 2회 (예: `/task-dev` Phase 동일 단계 반복 진입)
+- 실패 반복 (검증 명령 FAIL 2회 이상 / 격리 세션 FAIL 후 재구현 반복)
+- 사용자 부정 반응 발화 누적 (불편·짜증·답답함 신호)
+
+분기:
+- **감지 신호 있음** → *"이번 task에서 X 부분이 마찰이었어 보여 — `/log-friction`으로 등록할까?"* 사용자 합의 받음. OK 시 `/log-friction` 자동 발동.
+- **감지 신호 없음** → prompt X (정상 close 진행).
+
+### Step 8 — 결과 보고
 
 ```
 ✅ TASK-<NNN> closed
@@ -147,7 +163,7 @@ PASS 시 Step 3으로.
 - dev 병합: --no-ff 완료
 - 상태: tested → closed
 - 작업 브랜치 보존 (삭제하려면 "브랜치 삭제해" 명시)
-- 다음: 새 task 시작은 /task-init, 5 task 누적 시 /refine으로 회고
+- 다음: 새 task 시작은 /task-init. 본 task에서 마찰 신호 감지된 경우 /log-friction 등록 제안
 ```
 
 ## 도구 가이드

package/template/.claude/skills/{task-dev.md → task-dev/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-dev
 description: task 구현 — Dev Plan Phase 순서대로 코드 작성 + self-check 게이트, planned → developing → developed
 ---
 

package/template/.claude/skills/{task-init.md → task-init/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-init
 description: task 시작 — 6 섹션 빈 골격 + 헤더 5컬럼 (status=draft) task.md 생성
 ---
 

package/template/.claude/skills/{task-plan.md → task-plan/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-plan
 description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Plan 4 섹션 작성, draft → planned
 ---
 

package/template/.claude/skills/{task-test.md → task-test/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-test
 description: task 격리 세션 검증 — Task tool 격리 호출 + Test Plan 그대로 수행, developed → testing → tested
 ---
 

package/template/.project/FRICTION_LOG.md

@@ -1,23 +1,16 @@
 # FRICTION_LOG
 
-> 짜증 / 한계 / 짚이는 부분 누적.
-> 메인이 사용자 발화에서 *"이거 짜증나"* 감지하거나 사용자 명시 요청 시 한 줄씩 추가.
-> `/refine` 스킬이 정독 + 반복 패턴 감지 + bottoms-up 보강 제안.
+> 사용자가 작업 흐름 중 겪은 불편 / 한계 / 짚이는 부분의 누적.
+> `/log-friction` 스킬이 사용자 합의 후 한 행씩 추가한다.
 
 **사용 규칙**:
-- 한 행에 한 짜증
+- 한 행에 한 불편
 - 손수 편집 X — 메인이 대화로 적음
-- *"이거 짜증나, 적어줘"* 발화 또는 메인 자체 감지 시 추가
+- 사용자 명시 호출 / 사용자 불만 발화 캐치 / task-close 직후 마찰 신호 자체 감지 시 추가
 
 ---
 
-## 짜증 누적
+## 불편 누적
 
-| 날짜 | 짜증 | 맥락 (어느 task / 스킬 / 카테고리) |
+| 날짜 | 불편 | 맥락 (어느 task / 스킬 / 카테고리) |
 |------|------|-----------------------------------|
-
----
-
-## /refine 회고 메타 행
-
-(매 `/refine` 호출 결과를 메타 행으로 추가 — 다음 회고가 *이전 결과 참조*용)

package/template/CLAUDE.md

@@ -52,9 +52,9 @@
 | `/task-dev` | task | Phase 순서 구현 + self-check (planned → developed) |
 | `/task-test` | task | Task tool 격리 검증 (developed → tested) |
 | `/task-close` | task | 검증 명령 게이트 + 커밋 + dev 병합 (tested → closed) |
-| `/refine` | meta | FRICTION_LOG 정독 + 패턴 감지 + bottoms-up 보강 제안 |
+| `/log-friction` | meta | FRICTION_LOG.md에 사용자 불편 한 행 기록 |
 
-본문은 `.claude/skills/<스킬>.md` 참조.
+본문은 `.claude/skills/<스킬>/SKILL.md` 참조.
 
 ---
 
@@ -70,10 +70,10 @@
 
 ---
 
-## 짜증 데이터
+## 불편 데이터
 
-- **누적**: `.project/FRICTION_LOG.md` — 메인이 한 줄씩 추가 (사용자 발화 *"이거 짜증나"* 또는 자동 감지)
-- **회고**: `/refine` 스킬 — 5 task마다 또는 사용자 호출. 반복 패턴 감지 + PLAYBOOK 부활/새 룰 제안
+- **누적**: `.project/FRICTION_LOG.md` — 메인이 한 줄씩 추가 (사용자 불만 발화 캐치 또는 사용자 명시)
+- **등록**: `/log-friction` 스킬 — 사용자 명시 호출 / 불만 발화 캐치 / task-close 직후 마찰 신호 자체 감지 시 한 행 기록
 
 ---
 

package/template/.claude/skills/refine.md

@@ -1,177 +0,0 @@
----
-description: 회고 메타 — FRICTION_LOG 정독 + 반복 패턴 감지 + bottoms-up 보강 제안 (PLAYBOOK 부활 / 새 룰)
----
-
-# /refine
-
-## 개요
-
-5 task마다 또는 사용자 호출 시 메인이 `.project/FRICTION_LOG.md`를 정독해 *반복 패턴 감지* + *bottoms-up 보강 제안*. PLAYBOOK 미래 옵션 항목 부활 검토 또는 새 룰 추가 제안. 사용자 OK 시 적용.
-
-**핵심 정신**: *"선제적 작성 금지, 진짜 데이터 모이면 그때 추가"* — top-down 선제적 작성 함정 회피.
-
-## 호출 시점
-
-- 5 task 닫고 나서 (`/task-close` 5회 후 메인이 사용자에게 *"`/refine` 돌릴까요?"* 제안 OK).
-- 사용자가 *"짜증 정리 좀"* / *"`/refine`"* 명시 호출.
-- 짜증 패턴이 단기 폭증할 때 (메인 자체 판단으로 사용자에게 제안).
-
-## 입력 처리
-
-인자 없음. 기본 흐름.
-
-옵션 인자 = `--scope last-N` (예: `--scope last-10` — 최근 10개 짜증만). 미명시 시 *전체* 정독.
-
-## 단계
-
-### Step 1 — FRICTION_LOG.md 정독
-
-1. `.project/FRICTION_LOG.md` Read.
-2. 파일 없거나 비어 있으면 종료 + 안내:
-   *"FRICTION_LOG가 비어 있어. 짜증 데이터 누적되면 다시 호출. 평소 *'이거 짜증나'* 발화해주면 메인이 한 줄씩 추가."*
-3. 인자 `--scope last-N` 있으면 마지막 N개 행만 추출.
-
-### Step 2 — 패턴 분류 + 빈도 카운트
-
-짜증 항목을 카테고리로 분류:
-
-| 카테고리 | 예시 |
-|---------|------|
-| 형식 위반 | task 헤더 누락 / 섹션 빠짐 / status 잘못 작성 |
-| 컨텍스트 부담 | 메인 세션이 무거워짐 / 답변 느림 / 압축 발생 |
-| 스킬 미스매치 | `/task-init` 인터뷰 짜증 / `/task-plan` 질문 너무 많음 / 등 |
-| Test Plan 가정 | 격리 세션이 메인 가정 못 풀어 헤맴 |
-| git/커밋 흐름 | 브랜치 이름 충돌 / 커밋 순서 헛갈림 |
-| 멀티리포 통신 | shared/ 메시지 못 잡음 / .env 빠짐 |
-| 자동화 부족 | 같은 작업 반복 / 자동화 가능한데 수동 |
-| 기타 | 위 카테고리 외 |
-
-각 카테고리 *빈도 카운트* + 짜증 행 인용.
-
-### Step 3 — 반복 패턴 감지
-
-빈도 ≥ 3회 카테고리는 *반복 패턴*으로 간주. 빈도 < 3회는 *단발성*으로 분류.
-
-```markdown
-## 반복 패턴 (≥ 3회)
-
-1. <카테고리>: <N회>
-   - 짜증 1: "<원문 인용>" (<날짜 / TASK 맥락>)
-   - 짜증 2: ...
-   - ...
-
-2. <카테고리>: <N회>
-   ...
-```
-
-### Step 4 — PLAYBOOK 항목 매핑
-
-`plan/PLAYBOOK.md` Read. 반복 패턴마다 *부활 후보 항목* 매핑:
-
-| 반복 패턴 카테고리 | PLAYBOOK 후보 항목 |
-|------------------|--------------------|
-| 형식 위반 | §4 minimal form hook |
-| 컨텍스트 부담 | §1 컨텍스트 격리 강화 / §2 압축 평가 subagent |
-| 스킬 미스매치 | (PLAYBOOK 외 — 스킬 instruction 보강 검토) |
-| Test Plan 가정 | (PLAYBOOK 외 — TASK_DOC_RULE.md §3.3 보강 검토) |
-| git/커밋 흐름 | (PLAYBOOK 외 — GIT_RULE.md 보강 검토) |
-| 멀티리포 통신 | (PLAYBOOK 외 — LINKED-REPOS.md 보강 검토) |
-| 자동화 부족 | §3 Python orchestrator (큰 그림) / §7 자동 PR 리뷰 |
-| 큰 묶음 작업 부담 | §5 `/plan-roadmap` 스킬 |
-| task 누적 우선순위 | §8 우선순위 컬럼 부활 |
-| npx update 충돌 | §9 머지 로직 엣지 케이스 보강 |
-
-### Step 5 — bottoms-up 제안서 작성
-
-```markdown
-## /refine 제안서 — <YYYY-MM-DD>
-
-### 반복 패턴 (≥ 3회)
-- <카테고리 1>: <N회>
-- <카테고리 2>: <N회>
-
-### PLAYBOOK 부활 검토
-1. **§<N> <항목명>** 부활 검토
-   - 사유: <패턴 N회 누적 — PLAYBOOK §<N> 매핑>
-   - 도입 방법: <PLAYBOOK §<N> 본문 §방법 그대로 인용 + 적용 영역>
-   - 얻는 것: <효용>
-   - 주의: <함정 — PLAYBOOK §<N> §주의 인용>
-
-2. ...
-
-### PLAYBOOK 외 보강 제안
-1. **<문서 / 스킬>** 보강
-   - 사유: <패턴 N회>
-   - 보강 방향: <구체 수정 제안>
-   - 영향 범위: <수정 대상 파일>
-
-### 단발성 짜증 (< 3회 — 데이터 더 모이기 대기)
-- <짜증 인용 N>회
-
-### 추천 다음 행동
-- <사용자 OK 시 적용 순서>
-```
-
-### Step 6 — 사용자 합의
-
-제안서 보여주기 + *"어느 항목 적용할까?"* 묻기.
-
-분기:
-- **사용자 OK한 항목 → 즉시 적용 (또는 별도 task로 분리)**:
-  - PLAYBOOK 부활: 해당 PLAYBOOK 항목 *방법* 그대로 따라 새 task 생성 — `/task-init` 호출 권장 (큰 변경이면).
-  - 스킬 instruction 보강: 해당 `template/.claude/skills/<스킬>.md` 직접 Edit + 사유 기록.
-  - TASK_DOC_RULE / GIT_RULE 보강: 해당 룰 파일 Edit + 수정 이력 행 추가.
-- **거부한 항목 → 보류** (FRICTION_LOG에 *"보류 — `/refine` <YYYY-MM-DD>"* 메모).
-- **단발성 → 그대로 누적** (반복되면 다음 `/refine`에서 다시 검토).
-
-### Step 7 — FRICTION_LOG 갱신
-
-본 `/refine` 호출 결과를 FRICTION_LOG에 메타 행 추가:
-
-```markdown
-## /refine — <YYYY-MM-DD>
-
-- 반복 패턴: <카테고리> N회 / <카테고리> N회
-- 부활 적용: §<N> <항목명> (TASK-<NNN>으로 분리)
-- 보강 적용: <문서명> §<N> Edit
-- 보류: <항목>
-- 단발성 누적: N건
-```
-
-이 메타 행은 다음 `/refine`이 *이전 회고 결과 참조*용.
-
-### Step 8 — 결과 보고
-
-```
-✅ /refine 완료
-- 정독한 짜증 행: <N>건
-- 반복 패턴: <카테고리> N개
-- 적용한 보강: <목록>
-- 보류: <목록>
-- 단발성 누적: <N>건 (다음 회고 대기)
-
-다음 일정: <5 task 후 / 사용자 호출 시>
-```
-
-## 도구 가이드
-
-- **Read**: `.project/FRICTION_LOG.md` / `plan/PLAYBOOK.md` / 보강 대상 룰/스킬 파일 정독
-- **Edit**: 보강 적용 (TASK_DOC_RULE / GIT_RULE / 스킬 instruction Edit) + FRICTION_LOG 메타 행 추가
-- **AskUserQuestion**: Step 6 합의 — 어느 항목 적용할지 사용자 답
-- **Write**: 신규 룰/문서 추가 (드뭄 — 보통 PLAYBOOK 부활 항목이 새 hook 등 신규 파일 생성 요청 시)
-
-## 주의사항
-
-- **선제적 작성 금지** — *진짜 데이터(반복 패턴) 없이* PLAYBOOK 부활 절대 X. 합리적 변형 차단 함정 회피의 핵심.
-- **단발성 짜증 = 데이터 부족** — < 3회 패턴은 *부활 검토 X*. 누적 대기.
-- **자체 판단으로 룰 작성 금지** — 보강 제안은 *사용자 합의 후* 적용. *"이거 좋아 보여"* 자체 판단으로 즉시 Edit X.
-- **합리적 변형 차단 함정** — minimal form hook 부활 시 *섹션 존재* 검사만. *내용 검증 X* — 25행 화이트리스트 함정 회피 (PLAYBOOK §4 §주의 참조).
-- **PLAYBOOK 본문 인용 그대로** — *방법* 인용 시 자체 추측 작성 금지. PLAYBOOK 본문 한 줄씩 따라가며 적용.
-- **`/refine` 호출 빈도** — 매 task마다 호출 X. 5 task 또는 짜증 누적 폭증 시. 너무 잦으면 *회고 자체가 짜증*.
-- **회고 → 보강 → 다음 task** 흐름 — 보강 적용은 *별도 task로 분리* 권장 (큰 변경이면). `/task-init` 호출하고 plan에 부활 사유 기록.
-
-## 상태 전이
-
-해당 없음 (meta 레벨 — task 상태 전이 X).
-
-단 보강 적용이 *별도 task*로 분리되면 그 task는 일반 흐름 (draft → planned → ... → closed) 따라감.