@decencia/ch-cli 1.3.4 → 1.4.0

package/skill/2t-decencia-channel-orchestrator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: 2t-decencia-channel-orchestrator
+description: 소통채널 작업의 단일 진입점(디스패처). 사용자 요청을 듣고 6종(bootstrap·terraformer·change-manager·github-issue·issue-coder·pr-merger) 중 적절한 곳으로 라우팅하고, 필요하면 여러 단계를 순차 오케스트레이션한다. 대화형 스킬은 메인 세션에서 Skill로, 자율 에이전트는 Agent로 위임. "소통채널 작업 해줘"·"이거 어떻게 처리하지?"처럼 무엇부터 할지 모를 때, 또는 신규기획/코드편입/기획변경/이슈/구현/머지 어디로든 시작할 때.
+allowed-tools: Skill Agent Read Bash(ch:*) Bash(gh:*) Bash(git:*)
+version: 1.4.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# 2t-decencia-channel-orchestrator — 소통채널 작업 디스패처
+
+소통채널 관련 요청의 **단일 진입점**. 사용자 의도를 분류해 아래 6종 중 알맞은 것으로 보내고, 여러 단계가 필요하면 **순차 오케스트레이션**한다.
+이 스킬은 라우터다 — 실제 작업 디테일은 각 스킬/에이전트가 가지고 있으니 **중복 서술하지 않고 위임만** 한다.
+
+## 핵심 규칙
+- **대화형 = `Skill`로 메인 세션 실행** / **자율 = `Agent`로 위임**. (대화형을 서브에이전트로 던지면 turn-by-turn 대화가 안 됨)
+- **모호하면 1개 질문으로 확정** 후 라우팅 — 잘못 보내면 비싸다.
+- 연쇄 작업(예: "코드 편입하고 스프린트까지")이면 **한 단계 끝나면 다음으로** 순차 진행.
+
+## 라우팅 표
+
+| # | 사용자 의도 (신호) | 대상 | 종류 | 호출 |
+|---|---|---|---|---|
+| 1 | **새 아이디어/기획을 처음부터** ("새 프로젝트", 코드·문서 둘 다 없음) | `2t-decencia-channel-project-bootstrap` | 스킬(대화형) | `Skill` |
+| 2 | **기존 코드는 있는데 소통채널 문서 0** ("이 레포 편입/온보딩", 코드 O·`.ch-project` X) | `2t-decencia-channel-terraformer` | 에이전트(자율) | `Agent` |
+| 3 | **기존 기획을 변경/추가/수정** (문서 전파 + 새 할일 이슈까지) | `2t-decencia-channel-change-manager` | 스킬(대화형) | `Skill` |
+| 4 | **이슈만 발행** ("이거 이슈로 등록") | `2t-decencia-channel-github-issue` | 스킬 | `Skill` |
+| 5 | **이슈를 구현** ("이슈 #N 작업해줘") | `2t-decencia-channel-issue-coder` | 에이전트(자율) | `Agent` |
+| 6 | **PR을 머지** ("PR #N 머지", "쌓인 PR 정리") | `2t-decencia-channel-pr-merger` | 에이전트(자율) | `Agent` |
+
+## 판별 신호 (먼저 확인)
+- cwd(또는 상위)의 **`.ch-project` 존재 여부** → 이미 온보딩된 repo인지.
+  - 없음 + 코드 없음/아이디어 → **1 bootstrap**
+  - 없음 + 코드 있음 → **2 terraformer**
+  - 있음 → 변경/이슈/구현/머지(3~6)는 의도로 구분
+- `gh auth status` / `ch auth status` — 5·6(또는 이슈 발행)이면 미인증 시 먼저 안내.
+
+## 병렬/직렬 (에이전트 위임 시)
+- **issue-coder 다수 = 병렬** `Agent`(각자 worktree 격리, 독립 이슈).
+- **pr-merger 다수 = 직렬** `Agent`(한 번에 하나 — main 바뀌면 다음 PR mergeability 재평가, 레이스 방지).
+- terraformer는 보통 단건(repo 1개).
+
+## 순차 오케스트레이션 예시
+- "이 레포 소통채널에 올리고 스프린트도 짜줘" → 2 terraformer(Agent) → 끝나면 `2t-decencia-channel-sprint-builder-v2`(Skill).
+- "로그인에 SNS 추가하고 개발까지" → 3 change-manager(Skill, 전파+이슈 발행) → 발행된 이슈로 5 issue-coder(Agent, 병렬) → PR 나오면 6 pr-merger(Agent, 직렬).
+- 한 단계의 산출물(projectId·이슈번호·PR번호)을 다음 단계 입력으로 넘긴다.
+
+## 경계/주의
+- 라우터는 **분류·위임·순차 진행만** 한다. 문서/코드 작성 디테일은 각 대상이 책임.
+- 어디로 보낼지 끝내 모호하면 **추측하지 말고 사용자에게 한 번 더 물어** 확정.
+- 공통 함정(전 대상 공유): ch CLI content는 마크다운+CRLF 정제, spec 필드 단수+복수 동시, `--json`/`specs get` 윈도우 빈출력 시 PowerShell `Out-File` 우회 — 이는 각 스킬/에이전트가 이미 준수.

package/skill/2t-decencia-channel-prd-v2/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: 2t-decencia-channel-prd-v2
+description: |
+  [2t][v2] 소통채널 PRD 작성/수정 가이드.
+  Epic-Story-Task 체계와의 연결성에 초점 (PRD의 Epic 절 → spec의 --epic).
+  Use when:
+  (1) PRD를 작성하거나 갱신할 때,
+  (2) PRD 구성에서 Epic/스토리/태스크 구조를 후속 spec 작성에 매핑할 때,
+  (3) Read-before-Write 규칙으로 PRD content를 안전하게 수정해야 할 때.
+version: 1.4.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# PRD — Epic-Story-Task 매핑 가이드
+
+## 0. Read-before-Write
+
+PRD content는 마크다운 한 덩어리. 일부만 바꿔도 `--content`는 통째 덮어쓰므로:
+
+```bash
+ch prd get --json > /tmp/prd.json                  # 1) 현재 본문 추출
+# 본문 편집
+ch prd set --content /tmp/prd-edited.md            # 2) 통째 교체 (버전 기록됨)
+```
+
+## 1. 권장 목차 (Epic-Story-Task 추적성)
+
+```markdown
+# 프로젝트명 PRD
+
+## 1. 개요
+## 2. 사용자 페르소나 / 시나리오
+
+## 3. Epic 목록
+### 3.1 [Epic: 인증]
+- 목적, KPI
+- 포함 Story: 로그인, 회원가입, 비밀번호 재설정
+### 3.2 [Epic: 결제]
+- ...
+
+## 4. 비기능 요구사항
+## 5. 마일스톤 / 일정
+## 6. 데이터 모델 개요 (테이블 목록 — 자세한 건 db-tables 문서 참조)
+```
+
+PRD의 각 Epic 절 → spec 작성 시 `--epic` 값으로 그대로 사용.
+PRD의 각 Story 항목 → 1개 spec(=Story)으로 생성.
+
+## 2. 마크다운 작성 규칙
+
+- 본문은 **마크다운** (CLI --help에 "HTML"이라 표기되어 있어도 HTML 태그는 텍스트로 표시됨)
+- CRLF는 CLI가 자동 정제하지만 가능하면 LF로 작성
+- 표/이미지 링크 가능, 외부 링크 자유
+
+## 3. 운영 팁
+
+- PRD 큰 개정 시 버전 기록 활용: `ch prd versions` 로 이전 본문 비교
+- spec 작성 직전이라면 PRD의 Epic/Story 매핑 표를 만들어두면 일괄 등록 시 누락 방지
+- workStatus(=spec별 작업 현황)는 PRD와 분리. 진행 상태 메모는 spec.workStatus에.

package/skill/2t-decencia-channel-project-bootstrap/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: 2t-decencia-channel-project-bootstrap
+description: 신규 기획을 사용자와 대화하며 step-by-step으로 소통채널 프로젝트로 만드는 오케스트레이터 스킬. (1)대화로 PRD 완성 → 승인 → (2)페이지명세(spec)+DB스키마 → 승인 → (3)SQA 시트. 각 단계 사용자 승인 게이트, 작성 디테일은 기존 2t-decencia-channel-*-v2 스킬을 적극 재사용. "새 기획 만들어줘"·"프로젝트 처음부터 세팅" 류 요청 시.
+allowed-tools: Bash(ch:*) Bash(git:*) Read Write
+version: 1.4.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# 2t-decencia-channel-project-bootstrap — 신규 기획 → 프로젝트
+
+신규 기획을 **사용자와 대화하며 step-by-step**으로 소통채널 프로젝트로 만든다.
+이 스킬은 **오케스트레이터**다 — PRD/spec/DB/SQA의 실제 작성법은 기존 v2 스킬을 **적극 재사용**하고(중복 작성 금지), 흐름·승인 게이트만 책임진다.
+
+## 핵심 원칙
+- **각 단계마다 사용자 승인 게이트.** "괜찮다"는 확인 없이는 절대 다음 단계로 넘어가지 않는다. 수정 요청이면 그 단계를 반복.
+- 작성 디테일은 호출: PRD→`2t-decencia-channel-prd-v2`, 페이지명세→`2t-decencia-channel-spec-v2`, DB→`2t-decencia-channel-db-schema-v2`, SQA→`2t-decencia-channel-sqa-v2`, 업로드→`2t-decencia-channel-cli-v2`.
+
+## Use when
+- "새 기획 만들어줘", "프로젝트 처음부터 세팅해줘", 아이디어/요구사항을 소통채널 프로젝트로 구조화하고 싶을 때.
+
+---
+
+## 0. 프로젝트 준비
+- **이미 프로젝트가 있으면 생략**: cwd의 `.ch-project`가 있거나 사용자가 기존 프로젝트를 지정하면 그걸 사용.
+- 없으면 새로 생성:
+  - `ch projects create` 로 생성.
+  - **schema 설정**(⚠️ 빠지면 웹 UI가 빈 칼럼으로 보임) + **specVersion=2**(Epic-Story-Task).
+  - cwd에 `.ch-project`(`{"projectId":"..."}`) 기록 → 이후 issue-coder/머저가 사용.
+
+## 1. PRD (대화형)
+- 사용자와 **Q&A로 요구사항 수집**(목적/사용자/핵심 기능/범위/제약). 한 번에 다 묻지 말고 대화로 좁혀간다.
+- `2t-decencia-channel-prd-v2` 규칙대로 PRD 작성·업로드. 견적/유지보수성 항목은 제외.
+- → **[게이트] 사용자에게 PRD 확인 요청.** "괜찮다" 하면 2단계, 수정 요청이면 반영 후 재확인.
+
+## 2. 페이지명세(spec) + DB 스키마
+*(PRD 승인 후에만)*
+- **페이지명세 = spec**(ui 메타 포함): `2t-decencia-channel-spec-v2`로 PRD의 Epic/Story → spec 작성(ui: route/file/figmaNodeId·logic·dbTableRefs·tasks).
+- **DB 스키마**: `2t-decencia-channel-db-schema-v2`로 db-schema(ERD/정책) + db-tables(컬럼·인덱스·보안규칙). `spec.dbTableRefs` ↔ `dbTable.relatedSpecIds` 양방향.
+- → **[게이트] 사용자 확인.** OK면 3단계.
+
+## 3. SQA 시트
+*(spec/DB 승인 후에만)*
+- `2t-decencia-channel-sqa-v2`로 SQA 작성: **A축**(명세별 기능 TC — 영역별 번들에서 도출) + **B축**(비기능 표준 40).
+
+---
+
+## 업로드 주의 (전 단계 공통)
+- 모든 업로드는 `2t-decencia-channel-cli-v2`(=`ch` CLI) 경유.
+- ⚠️ content는 **마크다운**(HTML 아님) + **CRLF 정제**(`tr -d '\r'`). PowerShell 인자 분리 실패 시 Bash 도구로 우회.
+- spec 필드는 **단수+복수 동시 저장**(device/devices 등) 규칙 유지(미준수 시 웹 빈 칼럼).
+- `--json` 조회가 Windows에서 깨지면 파일 저장 + forward-slash 경로로 우회.
+
+## 후속 (자동 X — 안내만)
+- 완료 후 "스프린트 구성"(`2t-decencia-channel-sprint-builder-v2`) 또는 "이슈 발행 → issue-coder"로 자연스럽게 이어진다고 사용자에게 안내.

package/skill/2t-decencia-channel-spec-v2/SKILL.md

@@ -0,0 +1,463 @@
+---
+name: 2t-decencia-channel-spec-v2
+description: |
+  [2t][v2] 소통채널 기능명세(=Story) 작성/수정 표준.
+  Epic-Story-Task 구조에서 UI/Logic/DB/Task 필드 각각의 작성 패턴, JSON 템플릿, 입자 기준을 다룬다.
+  Spec ID는 JIRA 스타일 사용자 지정(`LOGIN-001`) 또는 자동 생성 선택 가능 — §1.5.
+  작업 일지(workStatus)는 라이프사이클이 달라 [[2t-decencia-channel-work-status-v2]]로 분리.
+  Use when:
+  (1) spec(=Story)을 작성·수정할 때,
+  (2) UI 메타데이터·비즈니스 로직·DB 참조를 함께 다룰 때,
+  (3) Task를 JIRA 스타일(points·assignee·description·completedAt)로 잘게 쪼갤 때,
+  (4) 신규 spec ID를 `LOGIN-001` 같은 JIRA 스타일로 부여하고 싶을 때 (`ch specs create --id`).
+version: 1.4.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# 기능명세 — Story / Epic / Task 작성 표준
+
+CLI 명령은 [[2t-decencia-channel-cli-v2]], DB 테이블 작성은 [[2t-decencia-channel-db-schema-v2]] 참조.
+
+---
+
+## 0. 핵심 개념
+
+| 계층 | 매핑 | 역할 |
+|---|---|---|
+| **Spec ID** | `spec.id` (string) | 식별자. **JIRA 스타일 사용자 지정 가능** (예: `LOGIN-001`). §1.5 |
+| **Epic** | `spec.epic` (string) | 분류 라벨. 같은 에픽 spec끼리 자동 그룹핑 |
+| **Story** | spec 자체 (1 spec = 1 story) | 명세 1건. CLI 명칭은 `specs` 그대로 |
+| **Task** | `spec.tasks[]` | Story 완료를 위한 체크리스트 (points/assignee/description/completedAt) |
+| **UI**   | `spec.ui` (object) | Figma·route·file·access·interactionMap |
+| **Logic** | `spec.logic` (object) | dataFlow·stateTransitions·businessRules |
+| **DB**   | `spec.dbTableRefs` (string[]) | db-tables 컬렉션의 테이블 ID 배열. 양방향 동기화 |
+
+`spec.workStatus`(작업 일지)는 개발 진행 중에 누적되는 별개 라이프사이클 — [[2t-decencia-channel-work-status-v2]] 참조.
+
+**완료 조건**: 별도 acceptanceCriteria 없음. **연관 SQA 통과 = 완료**.
+
+---
+
+## 🚨 BLOCKING: Read-before-Write
+
+```bash
+ch specs get <specId> --json > /tmp/spec.json     # 1) 현재 상태 백업
+# 편집 (tasks/ui/logic JSON 통째 교체 위험)
+ch specs update <specId> --tasks /tmp/tasks.json --no-version
+ch specs get <specId> --json | jq '.tasks'        # 3) 검증
+```
+
+`--tasks` / `--ui` / `--logic` / `--work-status`는 **각 필드 자체를 통째로 교체**. 일부만 바꾸려면 반드시 전체 가져와서 편집 후 전송.
+
+---
+
+## 1. 필드 분담
+
+| 위치 | 들어가는 것 |
+|---|---|
+| `content` | 개요 1~3줄 + 권한 요약. 짧게 유지 |
+| `ui.*` | 화면 메타 (figma/route/file/access) + 인터랙션 맵 |
+| `logic.dataFlow` | 데이터 READ/WRITE 흐름 |
+| `logic.stateTransitions` | 상태 머신 |
+| `logic.businessRules` | 도메인 규칙 |
+| `dbTableRefs[]` | 참조 테이블 ID (스키마 본문은 db-tables 문서에) |
+| `tasks[]` | 작업 단위 체크리스트 |
+
+---
+
+## 1.5 Spec ID — 식별자 명명 규칙 (ch-cli 1.3.5+, ch-api `b029f88`+)
+
+### 1.5-1. 두 가지 모드
+
+| 모드 | 사용법 | 결과 ID 예 |
+|---|---|---|
+| **자동 (기본)** | `ch specs create --name ...` (`--id` 생략) | `g3pWKfTpO0uSRU2KEiqh` (Firestore auto-id) |
+| **사용자 지정** | `ch specs create --id LOGIN-001 --name ...` | `LOGIN-001` |
+
+기존 spec(랜덤 ID)은 그대로 유지된다. 신규 생성 시에만 패턴 선택 가능.
+
+### 1.5-2. 허용 패턴
+
+서버 검증 정규식: `^[A-Za-z][A-Za-z0-9_]*-[A-Za-z0-9]+$` (MaxLength 60)
+
+| 형태 | 허용 | 예 |
+|---|---|---|
+| JIRA 표준 | ✅ | `LOGIN-001`, `AUTH-12`, `USER-A1` |
+| 언더스코어 prefix | ✅ | `USER_ADMIN-007` |
+| 소문자 prefix | ✅ | `login-001` (단, 팀 컨벤션상 대문자 권장) |
+| 숫자 prefix 시작 | ❌ | `1LOGIN-001` |
+| 하이픈 없음 | ❌ | `LOGIN001` |
+| 끝부분 특수문자 | ❌ | `LOGIN-001@v2` |
+
+### 1.5-3. 네이밍 권장
+
+- **prefix = Epic 또는 도메인 약어 (대문자)**, **`-` + 3자리 0패딩 숫자**가 가장 가독성 좋음.
+  - 예: `AUTH-001`, `AUTH-002`, `DASHBOARD-001` …
+- prefix는 Epic과 1:1로 묶으면 검색·정렬 모두 편함. (예: Epic "인증" → `AUTH-*`)
+- 숫자 폭은 프로젝트 규모로 결정 (소형 3자리, 대형 4~5자리).
+- 너무 긴 prefix는 피한다 (Firestore 키 길이·URL 가독성).
+
+### 1.5-4. 충돌 시 동작
+
+- 이미 같은 ID의 spec이 존재하면 서버가 **409 Conflict** 반환.
+  - 메시지: `Spec ID "LOGIN-001"가 이미 존재합니다. 다른 ID를 사용하세요.`
+- 패턴 위반 시 **400 Bad Request** (`Spec ID는 "PREFIX-숫자" 형식이어야 합니다 ...`).
+
+### 1.5-5. 사용 예
+
+```bash
+# 단일 spec — JIRA 스타일
+ch specs create --id LOGIN-001 --name "로그인 화면" \
+  --device web --domain user --type 인증 --epic 인증
+
+# Epic의 다음 번호 자동 산정 (간단 스크립트)
+NEXT=$(ch specs list --json --per-page 200 \
+  | jq -r '[.data[].id | select(test("^AUTH-[0-9]+$"))] | map(split("-")[1] | tonumber) | (max // 0) + 1' \
+  | xargs printf '%03d')
+ch specs create --id "AUTH-$NEXT" --name "비밀번호 재설정" ... --epic 인증
+
+# 기존 자동 ID 그대로 (--id 생략)
+ch specs create --name "임시 화면" --device web --domain admin --type 관리
+# → id: g3pWKfTpO0uSRU2KEiqh (자동)
+```
+
+### 1.5-6. 마이그레이션 주의
+
+- 기존 spec의 ID는 **변경 불가** (Firestore 문서 키 = ID). 바꾸려면 새 ID로 재생성 + 기존 삭제 + 모든 참조(dbTable.relatedSpecIds, SQA.relatedSpec) 일괄 갱신 — [[2t-decencia-channel-change-propagation-v2]] 참조.
+- 같은 프로젝트 안에 자동 ID와 사용자 지정 ID가 **공존 허용**. 일관성을 원하면 새 ID는 모두 사용자 지정으로 통일.
+
+---
+
+## 2. 작성 전 절차
+
+```bash
+# 0) 신규 프로젝트라면 schema 등록 (UI 컬럼 노출에 필수)
+ch projects set-schema --devices "웹,모바일" --domains "본사관리,회원관리" \
+  --types "조회,관리" --permissions "관리자,일반"
+
+# 1) 스키마 옵션 확인
+ch specs meta --json
+
+# 2) 기존 spec/db-tables 목록 확인 (중복·연결 대상 파악)
+ch specs list --json --per-page 100
+ch db-tables list --json
+```
+
+---
+
+## 3. Task — JIRA 스타일 체크리스트
+
+### 3-1. tasks.json 구조
+
+```json
+[
+  {
+    "id": "",
+    "title": "로그인 폼 UI 구현",
+    "done": false,
+    "assignee": "박준하",
+    "points": 5,
+    "description": "## 세부\n- React Hook Form + Yup\n- error UI 별도 컴포넌트\n- 참고: [Figma](https://...)"
+  },
+  {
+    "id": "",
+    "title": "Firebase Auth 연결",
+    "done": false,
+    "points": 3,
+    "description": "- signInWithEmailAndPassword 사용\n- 5회 실패 시 잠금 로직은 별도 spec"
+  },
+  {
+    "id": "a1b2c3d4",
+    "title": "유효성 검증",
+    "done": true,
+    "points": 1,
+    "completedAt": "2026-05-29T08:00:00.000Z"
+  }
+]
+```
+
+서버가 자동 처리:
+- `id` 비어있으면 UUID 부여
+- `done: true && completedAt 없음` → 현재 ISO 부여
+- `done: false` → completedAt 제거
+- 전체 progress(%) 자동 재계산 (`Math.round(doneCount / total * 100)`)
+
+### 3-2. 입자 기준
+
+| 너무 크다 | 적정 | 너무 작다 |
+|---|---|---|
+| "로그인 기능 구현" (points 13+) | "로그인 폼 UI 구현" (3~5p) | "input 태그 추가" (0p) |
+
+- **1 Task = 반나절~2일 작업**. points 1~8 (피보나치).
+- 13 이상이면 쪼개라.
+- 1 이하면 description bullet으로 합쳐라.
+
+### 3-3. points 부여 가이드 (피보나치)
+
+| points | 의미 | 예 |
+|---|---|---|
+| 1 | 거의 자명. 30분~2시간 | 단순 텍스트 변경, 색상 토큰 적용 |
+| 2 | 1일 이내. 구현 + 단순 검증 | 기존 폼에 필드 추가 |
+| 3 | 1~2일. 신규 컴포넌트/엔드포인트 | 로그인 폼 UI 구현 |
+| 5 | 2~3일. 통합 작업 (API + UI + state) | Firebase Auth 통합 |
+| 8 | 1주~. 큰 모듈, 모르는 영역 포함 | 결제 모듈 통합 |
+| 13 | 너무 큼 — **쪼개라** | — |
+
+### 3-4. description 작성 권장
+
+- 마크다운 사용 가능 (목록·표·코드블록·링크)
+- 들어가야 할 것: 구체 산출물, 의존성, 참고 자료(Figma/문서 링크), 엣지케이스
+- 들어가지 말 것: 작업 일지(→ [[work-status-v2]] 참조), 완료 보고(→ done + completedAt)
+
+### 3-5. assignee 표기
+
+자유 문자열. 한글 이름 또는 GitHub 핸들. 팀 컨벤션 통일 권장.
+
+---
+
+## 4. UI — Figma · Route · Interaction Map
+
+### 4-1. ui.json 구조
+
+```json
+{
+  "figmaNodeId": "12345:67890",
+  "route": "/login",
+  "file": "src/app/login/page.tsx",
+  "access": "public",
+  "interactionMap": "## 인터랙션\n\n| 요소 | 타입 | 액션 | 동작 |\n|---|---|---|---|\n| 이메일 input | input | onBlur | 형식 검증 |\n| 비밀번호 input | input + 토글 | 클릭 | 숨김/표시 |\n| 로그인 버튼 | 버튼 | 클릭 | 비동기 인증 |\n| 회원가입 링크 | 링크 | 클릭 | → /register |\n\n### 다이얼로그/바텀시트\n- 잠금 안내: 5회 실패 시 표시\n"
+}
+```
+
+### 4-2. 필드 작성 가이드
+
+| 필드 | 작성 규칙 |
+|---|---|
+| `figmaNodeId` | Figma URL의 `?node-id=` 값. `-` → `:` 치환. 예: `12345:67890` |
+| `route` | 화면 경로. SPA면 `/login`, 동적 세그먼트는 `/users/[id]` |
+| `file` | 진입 컴포넌트 파일 경로(저장소 기준). 예: `src/app/login/page.tsx` |
+| `access` | `public`, `auth`, `admin`, `role:센터장` 등 자유 문자열. 권한 체크 진입점 표기 |
+| `interactionMap` | **모든 인터랙티브 요소**를 마크다운 표로. 다이얼로그/바텀시트/키보드 단축키는 별도 절 |
+
+### 4-3. interactionMap 표 권장 컬럼
+
+```markdown
+| 요소 | 타입 | 액션 | 동작/이동경로 |
+|---|---|---|---|
+| 뒤로가기 | 아이콘 | 탭 | Navigator.pop() |
+| 폴더 만들기 | 버튼 | 탭 | → /folders/create |
+| 이미지 카드 | 카드 | 탭 | → /images/:id |
+| 이미지 카드 | 카드 | 롱프레스 | 선택 모드 진입 |
+| 공유 토글 | 스위치 | ON/OFF | is_shared 변경 + 참여자 UI 표시 |
+| ⋮ 메뉴 | 아이콘 | 탭 | 바텀시트(관리/삭제) |
+```
+
+규칙:
+- 같은 요소에 여러 액션 → **행 분리** (탭/롱프레스/스와이프 등)
+- 모달·바텀시트가 열리면 그 안의 요소도 별도 행
+- 이동 경로는 `/path` 또는 동작 설명
+
+### 4-4. 비화면 명세
+
+화면이 없는 기능 명세(Cron, 배치, 외부 연동)는 `ui` 통째 생략. 대신 `logic`에 집중.
+
+---
+
+## 5. Logic — 데이터 흐름 · 상태 전이 · 비즈니스 규칙
+
+### 5-1. logic.json 구조
+
+```json
+{
+  "dataFlow": "...",
+  "stateTransitions": "...",
+  "businessRules": "..."
+}
+```
+
+세 필드 모두 마크다운. 필요한 것만 채워도 됨.
+
+### 5-2. dataFlow — READ/WRITE 매핑 표
+
+이 spec이 다루는 데이터의 출처/목적지를 명시.
+
+```markdown
+| 데이터 | 소스/대상 | 방향 | 조건/비고 |
+|---|---|---|---|
+| 이메일·비밀번호 | 사용자 입력 | IN | 클라이언트 검증 |
+| Firebase Auth credential | Firebase | WRITE | signInWithEmailAndPassword |
+| ID Token | Firebase | READ | 쿠키에 httpOnly 저장 |
+| users/{uid} 문서 | Firestore | READ | 최초 로그인 시 lastLoginAt 갱신 |
+| users/{uid}.lastLoginAt | Firestore | WRITE | serverTimestamp() |
+```
+
+규칙:
+- READ: 화면/기능이 읽는 데이터
+- WRITE: 기능 결과로 쓰이는 데이터
+- 조건/비고: 필터·정렬·트랜잭션 여부·인덱스 활용 등
+- 외부 API 호출도 동일 형식 (소스/대상 = "Firebase Auth", "Toss Payments API" 등)
+
+### 5-3. stateTransitions — 상태 머신 표
+
+상태가 있는 기능(주문/배포/인증 등)은 머신 다이어그램 대신 표로.
+
+```markdown
+| 현재 상태 | 이벤트 | 다음 상태 | 사이드이펙트 |
+|---|---|---|---|
+| idle | submit | loading | spinner 표시 |
+| loading | success | authenticated | 토큰 저장 + /dashboard 이동 |
+| loading | error | error | 에러 메시지 + lockCount++ |
+| error | retry | loading | spinner |
+| authenticated | logout | idle | 토큰 제거 |
+| error | (lockCount >= 5) | locked | 1시간 잠금 타이머 |
+```
+
+규칙:
+- 컬럼: 현재 / 이벤트 / 다음 / 사이드이펙트 (이펙트 컬럼은 옵션)
+- 가드 조건은 이벤트 컬럼에 `(조건)` 또는 별도 컬럼
+- 진입 시점 = idle (또는 init)을 명시
+
+### 5-4. businessRules — 도메인 규칙 목록
+
+번호/불릿 마크다운.
+
+```markdown
+- 비밀번호 5회 연속 실패 시 해당 계정 1시간 잠금 (lockedUntil 필드)
+- 휴면 계정(마지막 로그인 후 30일 경과)은 이메일 재인증 후 로그인 허용
+- 동일 계정 동시 세션 3개 초과 시 가장 오래된 세션 강제 만료
+- 비밀번호 정책: 영문 + 숫자 + 특수문자 포함 8자 이상
+- 어드민 권한 계정은 IP 화이트리스트 통과 시에만 로그인
+```
+
+규칙:
+- 1 규칙 = 1 불릿
+- 임계값·기간·조건을 구체 수치로
+- 큰 규칙은 별도 spec 분리 가능
+
+---
+
+## 6. DB — dbTableRefs로 테이블 연결
+
+### 6-1. 흐름
+
+1. 먼저 `db-tables` 컬렉션에 테이블 문서를 만든다 (CLI: `ch db-tables create`).
+2. spec 생성/수정 시 `--db-tables tbl_users,tbl_sessions` 로 ID를 연결한다.
+3. 서버가 `spec.dbTableRefs` ↔ `table.relatedSpecIds` **양방향 동기화**.
+
+### 6-2. spec vs db-tables 분담
+
+| 위치 | 내용 |
+|---|---|
+| **spec** | "이 화면/기능이 어느 테이블의 어떤 컬럼을 R/W하는가" — `logic.dataFlow` 표에 기술 |
+| **db-tables** | 컬럼 정의, 인덱스, 보안 규칙, 역할 매트릭스 |
+
+spec.dbTableRefs는 **포인터만**. 스키마 본문은 [[2t-decencia-channel-db-schema-v2]] 참조.
+
+### 6-3. 신규 spec에서 신규 테이블이 필요한 경우 순서
+
+```bash
+# 1) 테이블 먼저 생성
+ch db-tables create --name users \
+  --description "회원 기본정보" \
+  --columns ./users-columns.json \
+  --indexes ./users-indexes.json \
+  --security ./users-security.json
+# → {"id": "tbl_xyz123"}
+
+# 2) spec 생성/연결
+ch specs create --name "로그인" ... --db-tables tbl_xyz123
+```
+
+### 6-4. 기존 테이블 추가 연결
+
+```bash
+# 현재 dbTableRefs 가져와 새 ID 합치기
+ch specs get <specId> --json | jq -r '.dbTableRefs | join(",")'
+# 결과에 새 ID를 쉼표로 이어서:
+ch specs update <specId> --db-tables tbl_xyz,tbl_new --no-version
+```
+
+---
+
+## 7. 작업 일지 — 별도 스킬 참조
+
+spec 작성 시점이 아니라 **개발 진행 중에 누적**되는 일지(`spec.workStatus`)는 라이프사이클이 달라 [[2t-decencia-channel-work-status-v2]]에서 따로 다룬다. spec을 처음 만드는 시점에는 비워둔다.
+
+---
+
+## 8. 명세 유형별 패턴
+
+### 8-A. 화면 명세 (가장 흔함)
+
+- `ui` 모든 필드 채움 (figmaNodeId/route/file/access/interactionMap)
+- `logic.dataFlow` 필수
+- `tasks[]` 5~10개 (UI/로직/테스트 분리)
+- `dbTableRefs` 화면이 R/W하는 테이블 전부
+
+### 8-B. 기능 명세 (Cron · 배치 · 외부 연동)
+
+- `ui` 통째 생략
+- `logic.dataFlow` + `logic.businessRules` 필수
+- `logic.stateTransitions` 작업 상태 머신
+- `tasks[]` 트리거·처리·에러처리·로깅
+
+### 8-C. 공통 명세 (인증 · 알림 · 업로드)
+
+- `ui` 생략 (모듈이라 화면 없음)
+- `logic.businessRules` 중심 (정책·제약)
+- `tasks[]` 인터페이스 구현·통합 테스트
+- 다른 spec이 이걸 import한다는 점을 `note`에 명시
+
+---
+
+## 9. 분해 크기 검증
+
+너무 큰 spec은 분리.
+
+| 지표 | 한계 | 조치 |
+|---|---|---|
+| `tasks` 개수 | 12+ | spec 분리 검토 |
+| Task points 합 | 30+ | sprint 1회로 못 끝남 → 분리 |
+| `logic.dataFlow` 표 행 수 | 15+ | 화면/기능이 다중일 가능성 → 분리 |
+| `ui.interactionMap` 줄 수 | 80+ | 화면이 너무 큼 → 분리 |
+| 같은 spec에 화면 2개 이상 | 항상 분리 | 1 화면 = 1 spec |
+
+---
+
+## 10. 흔한 함정
+
+- `--tasks/--ui/--logic` JSON 통째 교체 → 일부 수정도 **반드시 get 후 편집**.
+- `dbTableRefs`를 손으로 JSON에 넣어도 서버가 무시 (CLI `--db-tables` 또는 웹 picker만 사용).
+- 항구적 작업 정의는 `tasks[].description`. 시간축 진행 메모는 workStatus(별도 스킬).
+- estimate(시간)는 사용하지 않음. points만 사용.
+
+---
+
+## 11. 작업 순서 체크리스트
+
+신규 화면 spec 1건을 만들 때:
+
+1. `ch specs meta --json` → 스키마 옵션 확인
+2. 화면이 사용하는 테이블 정리 → 없으면 `ch db-tables create` 먼저
+3. **Spec ID 결정** (§1.5) — JIRA 스타일(`EPIC-NNN`) 사용 시 다음 번호 결정. 자동 ID로 가도 됨
+4. `tasks.json` 작성 (5~10개, points 부여)
+5. `ui.json` 작성 (figmaNodeId/route/file/access/interactionMap)
+6. `logic.json` 작성 (dataFlow 필수, 나머지 해당 시)
+7. `ch specs create [--id LOGIN-001] --name ... --epic ... --tasks ... --ui ... --logic ... --db-tables tbl_a,tbl_b`
+8. `ch specs get <id> --json`으로 결과 검증
+9. SQA 항목은 [[2t-decencia-channel-sqa-v2]]에 따라 별도 등록
+10. 개발 착수 후의 진행 일지는 [[2t-decencia-channel-work-status-v2]]에서 관리