timsquad 3.5.0 → 3.7.0

package/templates/base/skills/{database → tsq-database}/SKILL.md

@@ -1,16 +1,22 @@
 ---
-name: database
+name: tsq-database
 description: |
   데이터베이스 설계 및 운영 방법론.
   정규화/비정규화 결정, 쿼리 최적화 프로세스, 마이그레이션 안전 규칙.
   Use when: DB 설계, 스키마 변경, 쿼리 최적화, 마이그레이션
 version: "1.0.0"
-tags: [database, sql, migration]
+tags: [tsq, database, sql, migration]
 user-invocable: false
 ---
 
 # Database Methodology
 
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | rule | [supabase-patterns](rules/supabase-patterns.md) | JSONB, RLS, Edge Runtime, USE_MOCK, 커넥션 풀링 |
+
 ## 정규화 기준
 
 | 정규형 | 적용 기준 | 예외 허용 조건 |
@@ -39,32 +45,9 @@ user-invocable: false
 - 대응: [트리거/애플리케이션 로직]
 ```
 
-## 쿼리 최적화 프로세스
-
-### 1. 분석
-
-```sql
-EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
-```
-
-### 2. 체크리스트
-
-| 항목 | 확인 내용 |
-|-----|----------|
-| Seq Scan | 대용량 테이블에 순차 스캔? |
-| Index 사용 | 적절한 인덱스 사용 중? |
-| Join 순서 | 작은 테이블 먼저 조인? |
-| N+1 | 루프 내 쿼리 실행? |
-| 불필요 컬럼 | SELECT * 사용? |
+## 쿼리 최적화
 
-### 3. 최적화 기법
-
-| 문제 | 해결책 |
-|-----|-------|
-| 느린 조인 | 인덱스 추가, 조인 순서 변경 |
-| N+1 | Eager Loading, JOIN |
-| 대용량 스캔 | 파티셔닝, 커버링 인덱스 |
-| 동시성 | 적절한 격리 수준 |
+상세 프로세스(EXPLAIN 분석, 체크리스트, 기법)는 `rules/query-optimization.md` 참조.
 
 ## 마이그레이션 규칙
 
@@ -96,3 +79,6 @@ ALTER TABLE users ADD COLUMN phone VARCHAR(20);
 -- Down
 ALTER TABLE users DROP COLUMN phone;
 ```
+
+## 관련 스킬
+- **tsq-prisma** — Prisma ORM 사용 시 스키마·쿼리·마이그레이션은 tsq-prisma 참조

package/templates/base/skills/tsq-database/rules/query-optimization.md

@@ -0,0 +1,32 @@
+---
+title: Query Optimization Process
+impact: MEDIUM
+tags: database, query, optimization, explain
+---
+
+# Query Optimization Process
+
+## 1. 분석
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
+```
+
+## 2. 체크리스트
+
+| 항목 | 확인 내용 |
+|-----|----------|
+| Seq Scan | 대용량 테이블에 순차 스캔? |
+| Index 사용 | 적절한 인덱스 사용 중? |
+| Join 순서 | 작은 테이블 먼저 조인? |
+| N+1 | 루프 내 쿼리 실행? |
+| 불필요 컬럼 | SELECT * 사용? |
+
+## 3. 최적화 기법
+
+| 문제 | 해결책 |
+|-----|-------|
+| 느린 조인 | 인덱스 추가, 조인 순서 변경 |
+| N+1 | Eager Loading, JOIN |
+| 대용량 스캔 | 파티셔닝, 커버링 인덱스 |
+| 동시성 | 적절한 격리 수준 |

package/templates/base/skills/tsq-database/rules/supabase-patterns.md

@@ -0,0 +1,94 @@
+---
+title: Supabase Patterns
+impact: HIGH
+tags: supabase, database, edge-runtime, rls
+---
+
+# Supabase Patterns
+
+## JSONB 쿼리
+
+```sql
+-- .contains() 사용 시 주의: GIN 인덱스 필수
+CREATE INDEX idx_data_gin ON records USING GIN (data);
+
+-- 올바른 사용
+SELECT * FROM records WHERE data @> '{"status": "active"}'::jsonb;
+
+-- 피해야 할 패턴: 중첩 키 직접 접근 (인덱스 미사용)
+-- SELECT * FROM records WHERE data->'nested'->'key' = '"value"';
+-- 대안: jsonb_path_query 또는 표현식 인덱스
+```
+
+## RLS (Row Level Security)
+
+```sql
+-- 항상 RLS 활성화
+ALTER TABLE user_data ENABLE ROW LEVEL SECURITY;
+
+-- 서비스 키와 anon 키 구분
+-- anon: 클라이언트 사이드, RLS 적용
+-- service_role: 서버 사이드, RLS 바이패스
+
+-- 정책 패턴
+CREATE POLICY "Users can view own data"
+  ON user_data FOR SELECT
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own data"
+  ON user_data FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+```
+
+## Edge Runtime 초기화
+
+```typescript
+// Edge Runtime에서 Supabase 클라이언트 초기화
+// 반드시 함수 내부에서 생성 (모듈 레벨 싱글톤 금지)
+import { createClient } from '@supabase/supabase-js';
+
+export function getSupabase() {
+  return createClient(
+    process.env.SUPABASE_URL!,
+    process.env.SUPABASE_ANON_KEY!
+  );
+}
+```
+
+## USE_MOCK 패턴
+
+```typescript
+// 테스트/개발 환경에서 Supabase Mock
+const USE_MOCK = process.env.USE_MOCK_DB === 'true';
+
+function getClient() {
+  if (USE_MOCK) {
+    return createMockClient(); // 인메모리 구현
+  }
+  return createClient(SUPABASE_URL, SUPABASE_KEY);
+}
+```
+
+## Edge Runtime 커넥션 풀링
+
+- Supabase는 PgBouncer 내장 (포트 6543)
+- Edge Functions에서는 항상 풀링 URL 사용
+- `connection_limit=1` 설정 권장 (Edge 인스턴스별)
+- 장기 트랜잭션 피하기 (풀 고갈 방지)
+
+```
+# 직접 연결 (마이그레이션용)
+DATABASE_URL=postgres://...@db.xxx.supabase.co:5432/postgres
+
+# 풀링 연결 (애플리케이션용)
+DATABASE_URL=postgres://...@db.xxx.supabase.co:6543/postgres?pgbouncer=true
+```
+
+## 소유권 경계
+
+| 영역 | 담당 | 설명 |
+|------|------|------|
+| 스키마 설계 | Database 스킬 | 테이블, 인덱스, RLS |
+| Prisma 스키마 | Prisma 스킬 | schema.prisma, 마이그레이션 |
+| 쿼리 로직 | Coding 스킬 | 비즈니스 로직 내 DB 호출 |
+| 성능 튜닝 | Database 스킬 | EXPLAIN, 인덱스 최적화 |

package/templates/base/skills/{methodology/ddd → tsq-ddd}/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: ddd
-description: Domain-Driven Design 전략적 설계 가이드라인
+name: tsq-ddd
+description: |
+  Domain-Driven Design 전략적 설계 가이드라인. Bounded Context, Ubiquitous Language, Context Map.
+  Use when: 도메인 모델링, Bounded Context 설계, 유비쿼터스 언어 정의, 컨텍스트 맵 작성 시.
 version: "1.0.0"
-tags: [ddd, methodology, architecture]
+tags: [tsq, ddd, methodology, architecture]
 user-invocable: false
-compatible-with: [tdd, bdd]
+compatible-with: [tsq-tdd, tsq-bdd]
 ---
 
 # DDD (Domain-Driven Design) — Strategic
@@ -63,12 +65,15 @@ Bounded Context 간 관계: Partnership, Shared Kernel, Customer-Supplier, Confo
 - 기술 용어를 도메인 모델에 사용
 
 ## Checklist
-- [ ] 용어 사전 존재 및 최신화
-- [ ] Bounded Context 경계 정의됨
-- [ ] 코드가 유비쿼터스 언어 사용
-- [ ] Context Map 문서화
-- [ ] 외부 연동에 ACL 적용
-- [ ] Subdomain 분류 (Core/Supporting/Generic)
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 용어 사전 존재 및 최신화 |
+| CRITICAL | Bounded Context 경계 정의됨 |
+| HIGH | 코드가 유비쿼터스 언어 사용 |
+| HIGH | Context Map 문서화 |
+| MEDIUM | 외부 연동에 ACL 적용 |
+| MEDIUM | Subdomain 분류 (Core/Supporting/Generic) |
 
 ## 참조
 - `rules/strategic-patterns.md` — Context Map, ACL 예시, Event Storming, 디렉토리 구조

package/templates/base/skills/{methodology/debugging → tsq-debugging}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: debugging
+name: tsq-debugging
 description: |
   체계적 디버깅 방법론.
   근본 원인 추적, defense-in-depth, 가설-실험 루프, 로그 기반 진단.
   Use when: "버그 수정, 디버깅, 에러 추적, 원인 분석, 트러블슈팅"
 version: "1.0.0"
-tags: [debugging, troubleshooting, methodology]
+tags: [tsq, debugging, troubleshooting, methodology]
 user-invocable: false
 ---
 

package/templates/base/skills/tsq-decompose/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: tsq-decompose
+description: |
+  Sub-PRD에서 Phase-Sequence-Task 계획을 자동 생성하는 스킬.
+  기능 요구사항을 의존성 분석하여 DAG 기반 실행 계획으로 분해.
+  Use when: "태스크 분해", "계획 생성", "decompose", "분해", "플래닝",
+  "실행 계획", "Phase 계획", 또는 Sub-PRD가 작성된 후 실행 계획이 필요할 때.
+version: "1.0.0"
+tags: [tsq, planning, decompose, task, dag]
+user-invocable: true
+---
+
+# /tsq-decompose — 자동 태스크 분해
+
+Sub-PRD의 요구사항을 분석하여 Phase-Sequence-Task 구조의 실행 계획을 자동 생성한다.
+
+## Concepts
+
+```
+Phase   = Topological Layer (순차 실행, 이전 Phase 완료 필요)
+Sequence = Parallel Batch (동일 Phase 내 병렬 실행 가능 단위)
+Task     = Atomic Work Unit (단일 에이전트가 수행하는 최소 작업)
+```
+
+- Phase ID: `P{N}` (P1, P2, ...)
+- Sequence ID: `P{N}-S{NNN}` (P1-S001, P1-S002, ...)
+- Task ID: `P{N}-S{NNN}-T{NNN}` (P1-S001-T001, ...)
+
+## Process
+
+### Step 1: Sub-PRD 스캔
+
+1. `.timsquad/ssot/prd/` 하위 Sub-PRD 파일 전체 읽기
+2. 각 Sub-PRD에서 Must-Have(P0) 요구사항 추출
+3. Should-Have(P1)는 별도 Phase 후순위 배치
+
+### Step 2: 의존성 분석
+
+요구사항 간 의존성 그래프 구성:
+
+```
+데이터 모델 → API 구현 → UI 구현
+인증 → 권한 기반 기능
+공통 컴포넌트 → 화면별 구현
+```
+
+의존성 판단 기준:
+- **데이터 의존**: 테이블/스키마가 필요한 기능은 DB 설계 후
+- **API 의존**: API가 필요한 UI는 API 구현 후
+- **기능 의존**: Sub-PRD 간 명시적 참조
+
+### Step 3: DAG 정렬 → Phase 배치
+
+1. Topological sort로 의존성 레이어 계산
+2. 같은 레이어 = 같은 Phase
+3. Phase 내에서 독립적인 작업 그룹 = Sequence
+4. Sequence 내 개별 작업 = Task
+
+Phase 배치 관례:
+| Phase | 일반적 내용 |
+|:---:|------|
+| P1 | 인프라/DB 스키마/공통 설정 |
+| P2 | 핵심 API + 비즈니스 로직 |
+| P3 | UI/UX 구현 |
+| P4 | 통합 + E2E 테스트 |
+| P5+ | 보안 감사, 성능 최적화, 배포 |
+
+### Step 4: Task 상세화
+
+각 Task에 포함할 정보: Task ID, 설명, 담당 에이전트, 입력(SSOT refs, 선행 산출물), 출력(코드, 테스트, 문서), 완료 기준.
+
+### Step 5: Traceability 매핑 (Layer A)
+
+각 Sub-PRD의 Mapped Artifacts 테이블에 생성된 Task ID를 역링크:
+
+```markdown
+| Type | ID | Link |
+|------|----|------|
+| Tasks | P1-S001-T001~T003 | [planning.md](../planning.md#P1-S001) |
+```
+
+### Step 6: planning.md 생성
+
+`.timsquad/ssot/planning.md`에 Phase-Sequence-Task 전체 계획 작성.
+각 Sequence에 PRD 역방향 링크 포함 (Layer B):
+
+```markdown
+### Sequence S001: Authentication (PRD: [prd/auth](./prd/auth.md))
+| Task ID | Description | Agent | PRD Ref | FR Ref |
+|---------|-------------|-------|---------|--------|
+| P1-S001-T001 | DB schema | dba | prd/auth | FR-AUTH-001 |
+```
+
+### Step 6.5: Plan Review (자동)
+
+planning.md 생성 후 Controller에 Plan Reviewer 위임 요청. Reviewer(fork 컨텍스트)가 Sub-PRD 커버리지 100%, DAG 무결성, Task 크기(1에이전트 1세션), Phase 배치 순서를 검증. 결과를 Step 7에서 함께 제시.
+
+### Step 7: Human Checkpoint
+
+생성된 계획을 사용자에게 제시하고 컨펌을 받는다:
+- Phase별 요약 (목표, 예상 Task 수, 핵심 산출물)
+- 의존성 그래프 (mermaid)
+- 수정/추가/삭제 요청 반영 후 확정
+
+## Output
+
+- `.timsquad/ssot/planning.md` — 확정된 실행 계획
+- Sub-PRD Mapped Artifacts 업데이트 (Layer A 링크)
+- 의존성 그래프 (mermaid diagram in planning.md)
+
+## Rules
+
+- Sub-PRD가 없으면 실행 불가 → `/tsq-grill` 먼저 안내
+- 사용자 컨펌 없이 실행 계획 확정 금지
+- Task 1개 = 에이전트 1명이 1회 세션에 완료 가능한 크기
+- 순환 의존성 발견 시 사용자에게 알리고 해결책 제시
+- planning.md 이외 SSOT 문서는 Mapped Artifacts 테이블만 수정

package/templates/base/skills/tsq-delete/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: tsq-delete
+description: |
+  TimSquad 프레임워크를 프로젝트에서 완전 제거. 모든 에이전트, 스킬, 훅, 룰 정리.
+  Use when: /tsq-delete, "timsquad 제거", "tsq 삭제", "프레임워크 제거"
+version: "1.0.0"
+tags: [tsq, delete, remove, cleanup]
+user-invocable: true
+---
+
+# /tsq-delete — Remove TimSquad
+
+## Protocol
+
+1. **사용자 확인**: 반드시 삭제 전 확인 요청
+   ```
+   TimSquad 프레임워크를 이 프로젝트에서 완전히 제거합니다.
+   제거 대상:
+   - .timsquad/ (설정, 로그, SSOT, 상태 전부)
+   - .claude/skills/tsq-* (TimSquad 스킬)
+   - .claude/agents/tsq-* (TimSquad 에이전트)
+   - .claude/rules/ (TimSquad 룰)
+   - .claude/scripts/ (TimSquad 훅 스크립트)
+   - .claude/settings.json 내 TimSquad 훅
+   - CLAUDE.md 내 TimSquad 블록
+
+   보존됨:
+   - CLAUDE.md (tsq 블록만 제거, 나머지 유지)
+   - .claude/settings.json (tsq 훅만 제거, 나머지 유지)
+   - 소스코드 (절대 변경 안 됨)
+
+   계속하시겠습니까?
+   ```
+
+2. **제거 실행** (사용자 승인 후):
+
+   a. **데몬 중지**:
+      ```bash
+      tsq daemon stop 2>/dev/null || true
+      ```
+
+   b. **스킬 제거**: `.claude/skills/tsq-*` 디렉토리 전부 삭제
+
+   c. **에이전트 제거**: `.claude/agents/tsq-*` 파일 전부 삭제
+
+   d. **룰 제거**: `.claude/rules/` 디렉토리 삭제
+
+   e. **스크립트 제거**: `.claude/scripts/` 디렉토리 삭제
+
+   f. **CLAUDE.md 정리**: `<!-- tsq:start -->` ~ `<!-- tsq:end -->` 블록 제거
+      - 블록 제거 후 빈 줄 정리
+      - 나머지 사용자 콘텐츠 보존
+
+   g. **settings.json 정리**: hooks 내 tsq 관련 항목 제거
+      - `.claude/scripts/` 경로 참조하는 훅 제거
+      - 나머지 사용자 훅 보존
+
+   h. **.timsquad 제거**: 전체 디렉토리 삭제 (마지막 단계)
+
+3. **완료 보고**:
+   ```
+   TimSquad가 프로젝트에서 제거되었습니다.
+   - 소스코드는 변경되지 않았습니다.
+   - 재설치: npx timsquad init
+   ```
+
+## Safety
+
+- 소스코드 (`src/`, `app/`, `lib/` 등)는 절대 변경하지 않음
+- CLAUDE.md에서 tsq 블록만 제거, 나머지 보존
+- settings.json에서 tsq 훅만 제거, 나머지 보존
+- 반드시 사용자 확인 후 실행

package/templates/base/skills/{mobile/flutter → tsq-flutter}/SKILL.md

@@ -1,8 +1,10 @@
 ---
-name: flutter
-description: Flutter 개발 가이드라인. Feature-first 아키텍처, Riverpod 상태관리, 위젯 합성, 성능 최적화, 크로스플랫폼 적응형 UI.
+name: tsq-flutter
+description: |
+  Flutter 개발 가이드라인. Feature-first 아키텍처, Riverpod 상태관리, 위젯 합성, 성능 최적화, 크로스플랫폼 적응형 UI.
+  Use when: Flutter 위젯 작성·수정, 상태관리 설계, 크로스플랫폼 UI 구현, pubspec.yaml 설정 시.
 version: "1.0.0"
-tags: [flutter, mobile, cross-platform, riverpod]
+tags: [tsq, flutter, mobile, cross-platform, riverpod]
 user-invocable: false
 ---
 
@@ -10,6 +12,7 @@ user-invocable: false
 
 Flutter 3.x 기반 크로스플랫폼 앱 개발 가이드라인.
 Flutter 공식 아키텍처 가이드 + VGV + Riverpod 커뮤니티 베스트 프랙티스 종합.
+기본 스택: Riverpod, go_router, freezed. 프로젝트 설정(`memory/conventions.md`)으로 재정의 가능.
 
 ## Philosophy
 

package/templates/base/skills/tsq-grill/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: tsq-grill
+description: |
+  Sub-PRD 작성/보강을 위한 소크라틱 심층 인터뷰 스킬.
+  기능별 Why/What/How를 체계적으로 파고들어 모호한 요구사항을 구체화.
+  Use when: "기능 상세화", "요구사항 인터뷰", "PRD 보강", "grill", "기능 정의",
+  "Sub-PRD 작성", "기능 스펙 잡기", 또는 PRD 기능 인덱스에 빈 항목이 있을 때.
+version: "1.0.0"
+tags: [tsq, prd, interview, grill, requirements]
+user-invocable: true
+---
+
+# /tsq-grill — 소크라틱 심층 인터뷰
+
+PRD의 기능을 하나씩 깊이 파고들어 Sub-PRD를 작성하거나 보강하는 스킬.
+"질문을 통해 답을 끌어낸다"는 소크라틱 방법론을 따른다.
+
+## When to Use
+
+- 새 기능의 Sub-PRD를 처음 작성할 때
+- 기존 Sub-PRD의 빈 섹션을 채울 때
+- 모호한 요구사항을 구체화해야 할 때
+- PRD 기능 인덱스에 Link가 비어있을 때
+
+## Process
+
+### Phase 1: 대상 선정
+
+1. `.timsquad/ssot/prd.md`의 기능 인덱스 테이블 읽기
+2. Sub-PRD가 없거나 빈 기능 식별
+3. 사용자에게 인터뷰 대상 기능 확인 (복수 선택 가능)
+
+### Phase 2: 디자인 트리 인터뷰
+
+기능마다 3단계 깊이로 질문한다. 한 번에 2-3개 질문, 답변 받으면 다음 깊이로.
+
+```
+Why (목적)
+├── 이 기능이 없으면 사용자에게 어떤 문제가 생기나?
+├── 핵심 사용자 시나리오는?
+└── 성공을 어떻게 측정하나?
+
+What (범위)
+├── Must-Have vs Nice-to-Have 경계는?
+├── 이 기능이 다루지 않는 것은?
+├── 어떤 데이터가 필요하고 어디서 오나?
+└── 기존 시스템과 연동 포인트는?
+
+How (설계)
+├── 사용자 흐름 (Happy Path → Exception Path)?
+├── 상태 전환이 있다면?
+├── 에러 케이스와 처리 방식은?
+└── 성능/보안 고려사항은?
+```
+
+질문 방식 원칙:
+- 한 번에 질문 2-3개만 (과부하 방지)
+- 사용자 답변을 요약해서 확인받기 ("~라는 뜻이 맞나요?")
+- 모호한 답변에는 구체적 예시로 재질문
+- "모르겠다"는 답변도 유효 — 결정 보류로 기록
+
+### Phase 3: Sub-PRD 생성
+
+인터뷰 결과를 `.timsquad/ssot/prd/[feature].md`로 구조화:
+
+1. `ssot/prd/_template.md` 복사
+2. 인터뷰 답변으로 각 섹션 채우기
+3. Mapped Artifacts는 빈 링크로 두되 구조 유지
+4. 설계 결정 테이블에 인터뷰 중 나온 선택지/결정 기록
+
+### Phase 4: PRD 인덱스 업데이트
+
+`prd.md`의 기능 인덱스 테이블에 새 Sub-PRD 링크 추가.
+
+## Output
+
+- `.timsquad/ssot/prd/[feature].md` — Sub-PRD 파일
+- `prd.md` 기능 인덱스 업데이트
+- 인터뷰 로그: `.timsquad/logs/grill-[feature]-[date].md`
+
+## Rules
+
+- 사용자 답변을 임의로 해석하지 않는다 — 확인 후 기록
+- "아직 모르겠다"는 TBD로 표시하되, 결정이 필요한 시점을 명시
+- SSOT 외 파일 수정 금지
+- Sub-PRD 생성 후 사용자에게 리뷰 요청 (Human Checkpoint)

package/templates/base/skills/{backend/node → tsq-hono}/SKILL.md

@@ -1,8 +1,10 @@
 ---
-name: node
-description: Node.js 백엔드 개발 가이드라인 (Hono Framework). 비동기 우선, Zod 타입 안전, Clean Architecture 레이어 분리.
-version: "1.0.0"
-tags: [nodejs, hono, backend]
+name: tsq-hono
+description: |
+  Hono Framework 백엔드 개발 가이드라인. 비동기 우선, Zod 타입 안전, Clean Architecture 레이어 분리.
+  Use when: Hono 라우트 작성, Node.js 백엔드 구현, 미들웨어 설계, API 엔드포인트 개발, zValidator 사용 시.
+version: "1.1.0"
+tags: [tsq, hono, nodejs, backend]
 user-invocable: false
 ---
 

package/templates/base/skills/tsq-librarian/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: tsq-librarian
+description: |
+  Phase 종합 기록, Phase Memory 생성, SSOT 상태 갱신, 문서 작성 전담 스킬.
+  Phase 완료 시 controller가 호출하여 Trail 추출 + Memory 생성 + 종합 리포트를 생성한다.
+  Use when: Phase 완료 후 기록, 리포트 작성, SSOT 상태 점검, 문서 갱신, 로그 정리 시.
+version: "2.0.0"
+tags: [tsq, librarian, recording, documentation, phase-report, phase-memory]
+user-invocable: false
+context: fork
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Librarian (Phase 기록 + Memory 전담)
+
+Phase 종합 기록 전담. 문서 작성/갱신만 수행하고 소스 코드를 수정하지 않는다.
+Phase Trail을 아카이브하고, 다음 Phase를 위한 Phase Memory를 생성한다.
+
+## Contract
+
+- **Trigger**: Phase 완료 시 controller의 phase-complete 트리거가 호출
+- **Input**: L1/L2/L3 로그 + Decision Log + SSOT 현재 상태 + Phase 정보
+- **Output**: Phase Trail + Phase Memory + 종합 리포트 + context note
+- **Error**: 기록 실패 시 에러 리포트만 생성 (프로세스 차단 안 함)
+- **Dependencies**: tsq-protocol
+
+## Protocol
+
+1. **L1/L2 로그 수집**: `.timsquad/logs/` 하위 해당 Phase 로그 전체 읽기
+2. **Decision Log 수집**: `.timsquad/state/decisions.jsonl` 읽기
+3. **SSOT 상태 확인 + Carry-over**:
+   - `.compile-manifest.json` hash 비교 → stale 목록 식별
+   - `.timsquad/.daemon/drift-warnings.json` 존재 시 drift 항목도 carry-over에 포함
+   - Stale + Drift 항목은 carry-over로 기록 (다음 Phase의 Architect가 갱신)
+   - SSOT 내용 직접 수정 금지 (메타데이터 last_reviewed, status만 갱신 허용)
+4. **Phase Trail 작성**: `.timsquad/trails/phase-{id}.md` 생성
+   - 작업 요약 (L1/L2/L3에서 뭘 했는지)
+   - 주요 의사결정 (decisions.jsonl에서 추출, 이유 포함)
+   - 막혔던 점과 해결 방법
+   - 보류/carry-over 항목 (carry_over: true인 결정들)
+5. **Phase Memory 아카이브 + 새 HEAD 생성**:
+   a. 현재 `phase-memory.md` → `trails/phase-{id}-memory.md` 복사 (아카이브)
+   b. 새 `phase-memory.md` 생성 (~50줄 엄수):
+      ```yaml
+      ---
+      phase: {new-phase-id}
+      prev: trails/phase-{id}-memory.md
+      created: {ISO8601}
+      ---
+      ```
+   c. 본문: 이전 Phase 한 줄 요약 + 핵심 결정 (최대 5개, carry_over 우선) + 주의사항 + carry-over
+   d. 에이전트 참조 규칙: HEAD만 기본 읽기. 필요시 prev 링크 따라 최대 3단계 추적
+6. **Decision Log 아카이브**:
+   - decisions.jsonl → trails/phase-{id}-decisions.jsonl 복사
+   - decisions.jsonl 초기화 (빈 파일)
+7. **Trails 정리**: trails/ 내 memory 아카이브가 10개 초과 시 가장 오래된 것부터 삭제
+8. **종합 리포트 + Context Note 작성**
+   - `.timsquad/reports/{phase}-report.md` 생성
+   - `docs/sprint/` 하위에 다음 Phase 맥락 문서
+
+## Constraints
+
+- **소스 코드(src/, lib/, app/) 수정 절대 금지**
+- `.timsquad/` 및 `docs/` 내 문서 작성·갱신만 허용
+- 기록, 분석, 리포트 작성만 수행
+
+## Verification
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Trail 생성 | `ls .timsquad/trails/phase-*.md` | 파일 존재 |
+| Memory HEAD | `head -5 .timsquad/state/phase-memory.md` | prev 링크 포함, ~50줄 |
+| Memory 아카이브 | `ls .timsquad/trails/phase-*-memory.md` | 이전 memory 아카이브 존재 |
+| 리포트 생성 | `ls .timsquad/reports/{phase}-report.md` | 파일 존재 |
+| Decision 아카이브 | `ls .timsquad/trails/phase-*-decisions.jsonl` | 파일 존재 |
+| SSOT stale carry-over | phase-memory.md 내 carry-over 확인 | stale 항목 기록됨 |
+| Trails GC | `ls .timsquad/trails/phase-*-memory.md \| wc -l` | 10개 이하 |
+| 소스 무변경 | `git diff --name-only src/ lib/ app/` | 변경 없음 |

package/templates/base/skills/tsq-log/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: tsq-log
+description: |
+  작업 로그 관리. 로그 추가, 조회, 시퀀스/Phase 로그 생성.
+  Use when: /tsq-log, "로그 추가", "작업 기록", "로그 확인", "L1 로그", "L2 로그"
+version: "1.0.0"
+tags: [tsq, log, recording]
+user-invocable: true
+---
+
+# /tsq-log — Work Log Management
+
+## Protocol
+
+### 로그 추가 (`/tsq-log add <message>`)
+1. 현재 날짜/시간 + 에이전트명 + 메시지로 로그 엔트리 생성
+2. `.timsquad/logs/{date}-{agent}.md`에 append
+3. 타입 자동 분류: work, decision, issue
+
+### 로그 조회 (`/tsq-log` or `/tsq-log list`)
+1. `.timsquad/logs/` 최근 로그 파일 목록 출력
+2. 오늘 날짜 로그가 있으면 내용 요약
+
+### 시퀀스 로그 (`/tsq-log sequence <id>`)
+1. 해당 시퀀스의 L1 로그를 수집
+2. L2 시퀀스 로그 생성 (`.timsquad/logs/sequences/`)
+
+### Phase 로그 (`/tsq-log phase <id>`)
+1. 해당 Phase의 L2 로그를 수집
+2. L3 Phase 로그 생성 (`.timsquad/logs/phases/`)