timsquad 2.1.0 → 3.4.0

package/templates/base/knowledge/templates/task-result.md

@@ -0,0 +1,105 @@
+# Task Result Template
+
+모든 에이전트가 태스크 완료 시 사용하는 공통 리턴 형식.
+
+## TASK-{id} Result
+
+### Summary
+{1줄 요약}
+
+### Changes
+| File | Lines | Action | Description |
+|------|-------|--------|-------------|
+
+### Techniques Applied
+- {패턴/기법}: {적용 이유}
+
+### SSOT Alignment
+- {ssot-문서}#{섹션}: {구현 상태}
+
+### Decisions
+- {결정}: {근거}
+
+### Issues / Handoff Notes
+- {전달 사항} 또는 "없음"
+
+### UI Meta Index Updates (컴포넌트 작업 시, 선택)
+| component | layout | colorScheme | spacing | states | responsive |
+|-----------|--------|-------------|---------|--------|------------|
+
+### TSQ Log Enrich (필수)
+위 내용을 기반으로 반드시 tsq log enrich를 호출하세요:
+```bash
+tsq log enrich {agent} --json '{"summary":"...", "techniques":[...], "ssot_refs":[...], "decisions":[...], "issues":[...]}'
+```
+
+---
+
+## Few-shot 예제
+
+### 예제 1: Developer — API 엔드포인트 구현
+
+```
+## P3-S001-T001 Result
+
+### Summary
+POST /auth/login 엔드포인트 구현 + 단위 테스트 3개 작성
+
+### Changes
+| File | Lines | Action | Description |
+|------|-------|--------|-------------|
+| src/routes/auth/login.ts | 1-45 | created | 로그인 핸들러 (Zod 검증 + Supabase Auth) |
+| src/routes/auth/login.test.ts | 1-62 | created | 성공/실패/입력검증 3 케이스 |
+| src/types/auth.ts | 12-18 | modified | LoginRequest/Response 타입 추가 |
+
+### Techniques Applied
+- Zod validation: 런타임 입력 검증으로 타입 안전성 확보
+- Repository pattern: Supabase 직접 호출 대신 AuthRepository 추상화
+
+### SSOT Alignment
+- service-spec.md#POST-auth-login: aligned (명세대로 구현)
+- data-design.md#users-table: aligned (email + hashed_password 컬럼 활용)
+- error-codes.md#AUTH-001: aligned (잘못된 자격증명 에러 코드 적용)
+
+### Decisions
+- session-based auth 선택: Supabase RLS와의 호환성 (JWT는 RLS 정책과 충돌)
+
+### Issues / Handoff Notes
+- 없음
+
+### TSQ Log Enrich
+```
+
+```bash
+tsq log enrich developer --json '{"summary":"POST /auth/login 엔드포인트 구현 + 단위 테스트 3개","techniques":[{"name":"Zod validation","reason":"런타임 입력 검증"},{"name":"Repository pattern","reason":"Supabase 추상화"}],"ssot_refs":[{"doc":"service-spec.md","section":"POST-auth-login","status":"aligned"},{"doc":"data-design.md","section":"users-table","status":"aligned"}],"decisions":[{"decision":"session-based auth","rationale":"Supabase RLS 호환성"}],"issues":[]}'
+```
+
+### 예제 2: QA — 리뷰 결과
+
+```
+## P3-S001-T003 Result
+
+### Summary
+인증 시퀀스 코드 리뷰 — Level 1 이슈 2건, Level 2 이슈 1건 발견
+
+### Changes
+| File | Lines | Action | Description |
+|------|-------|--------|-------------|
+| (리뷰 대상) src/routes/auth/ | - | reviewed | 3개 파일 검토 |
+
+### Techniques Applied
+- SSOT 교차 검증: service-spec.md vs 실제 응답 형식 대조
+- 경계값 분석: 비밀번호 길이 제한 미검증 발견
+
+### SSOT Alignment
+- service-spec.md#POST-auth-login: partial (응답의 token 필드명이 access_token으로 불일치)
+- error-codes.md#AUTH-002: misaligned (계정 잠금 에러코드 미구현)
+
+### Decisions
+- 없음 (리뷰 역할)
+
+### Issues / Handoff Notes
+- Level 1: 비밀번호 최소 길이 검증 누락 (src/routes/auth/login.ts:23) → @developer 수정 요청
+- Level 1: 로그인 실패 시 응답에 email 노출 (src/routes/auth/login.ts:38) → @developer 수정 요청
+- Level 2: token → access_token 필드명 SSOT 불일치 → PM 보고 (명세 vs 구현 어느 쪽이 정확한지 확인 필요)
+```

package/templates/base/skills/_template/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: {skill-name}
+description: |
+  {무엇을 하는지 + 언제 사용하는지, 1024자 이하.}
+  {에이전트가 이 description만 보고 스킬 필요 여부를 판단함.}
+version: "1.0.0"
+tags: [{tag1}, {tag2}]
+user-invocable: false
+---
+
+# {Skill Title}
+
+{1~2줄 목적 설명}
+
+## Philosophy
+
+- {핵심 원칙 1}
+- {핵심 원칙 2}
+- {핵심 원칙 3}
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [{rule-name}](rules/{rule-name}.md) | {1줄 설명} |
+| HIGH | rule | [{rule-name}](rules/{rule-name}.md) | {1줄 설명} |
+| HIGH | ref | [{topic}](references/{topic}.md) | {1줄 설명} |
+| MEDIUM | script | [{script}](scripts/{script}.sh) | {1줄 설명} |
+
+## Quick Rules
+
+### {카테고리 1}
+- {규칙}
+- {규칙}
+
+### {카테고리 2}
+- {규칙}
+- {규칙}
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | {필수 확인 항목} |
+| HIGH | {중요 확인 항목} |
+| MEDIUM | {권장 확인 항목} |
+
+<!--
+스킬 작성 가이드:
+- SKILL.md는 120줄 이하 인덱스 (항상 로드됨 → 컨텍스트 절약)
+- 하위 디렉토리 3종:
+  - rules/   → "이렇게 해라/하지 마라" (Incorrect/Correct 패턴, impact 레벨)
+  - references/ → "이것을 알아라" (심층 가이드, 외부 문서)
+  - scripts/   → "이것을 실행해라" (자동화, 검증, 생성)
+- rules/는 Read로 온디맨드 로드, scripts/는 Bash로 실행 (토큰 0)
+- "Claude가 이미 아는 것"은 넣지 말 것 → 프로젝트 컨벤션만
+- description은 PRIMARY trigger — 1024자 이하
+- 참조 모델: vercel-react-best-practices (SKILL.md 인덱스 + 45 rules 파일)
+-->

package/templates/base/skills/_template/references/_template.md

@@ -0,0 +1,35 @@
+---
+title: {Reference Title}
+category: guide                 # guide | api | migration | external
+source: internal                # URL (외부) 또는 "internal" (자체 작성)
+---
+
+# {Reference Title}
+
+{이 레퍼런스가 다루는 주제 1~2줄 설명}
+
+## Key Concepts
+
+{에이전트가 알아야 할 핵심 개념}
+
+## Detailed Guide
+
+{상세 가이드 내용}
+
+## Common Pitfalls
+
+{에이전트가 흔히 하는 실수}
+
+## Examples
+
+{구체적인 코드/설정 예시}
+
+<!--
+레퍼런스 파일 작성 가이드:
+- 50~200줄 (심층 가이드)
+- frontmatter 필수: title, category
+- source 권장: 외부 자료 기반이면 URL 기록
+- rules/와 차이: 규칙이 아닌 "알아야 할 지식"
+- 에이전트가 Read로 필요할 때만 로드 (온디맨드)
+- 파일명: kebab-case.md (예: nextjs-migration.md)
+-->

package/templates/base/skills/_template/rules/_sections.md

@@ -0,0 +1,34 @@
+---
+title: Rule Categories
+---
+
+# Rule Categories
+
+규칙 파일을 카테고리별로 그룹화하는 인덱스.
+SKILL.md의 Resources 테이블과 함께 에이전트의 규칙 탐색을 돕습니다.
+
+## {Category 1} ({prefix-})
+
+**Impact:** CRITICAL
+**Description:** {이 카테고리의 규칙이 왜 중요한지}
+
+| Rule | Description |
+|------|-------------|
+| [{prefix}-{name}]({prefix}-{name}.md) | {1줄 설명} |
+
+## {Category 2} ({prefix-})
+
+**Impact:** HIGH
+**Description:** {이 카테고리의 규칙이 왜 중요한지}
+
+| Rule | Description |
+|------|-------------|
+| [{prefix}-{name}]({prefix}-{name}.md) | {1줄 설명} |
+
+<!--
+_sections.md 작성 가이드:
+- 5개 이상 규칙이 있는 스킬에서 사용
+- Impact 순으로 카테고리 정렬 (CRITICAL → LOW)
+- 파일명 prefix로 규칙 자동 분류 (예: async-, bundle-, server-)
+- 참조: vercel-react-best-practices/rules/_sections.md
+-->

package/templates/base/skills/_template/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: {Rule Title}
+impact: HIGH                    # CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: {영향도 수치}  # 예: "2-10× improvement", "200-800ms 감소"
+tags: {tag1}, {tag2}
+---
+
+## {Rule Title}
+
+**Impact: {LEVEL} ({영향도 수치})**
+
+{왜 이 규칙이 필요한지 1~2줄 설명}
+
+**Incorrect ({무엇이 잘못됐는지}):**
+```{lang}
+// 잘못된 패턴
+```
+
+**Correct ({무엇이 올바른지}):**
+```{lang}
+// 올바른 패턴
+```
+
+<!--
+규칙 파일 작성 가이드:
+- 20~80줄 (간결하게)
+- frontmatter 필수: title, impact, tags
+- impactDescription 권장: 수치화된 영향도
+- Incorrect/Correct 코드 예시 필수
+- "Claude가 이미 아는 것"은 생략, 프로젝트 고유 패턴만
+- 파일명: kebab-case.md (예: async-parallel.md)
+-->

package/templates/base/skills/_template/scripts/_template.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# @name {script-name}
+# @description {이 스크립트가 하는 일 1줄}
+# @args {필요한 인자 설명}
+# @output {출력 형식 (text | json | exit-code)}
+
+set -euo pipefail
+
+# ─────────────────────────────────────
+# 설정
+# ─────────────────────────────────────
+PROJECT_ROOT="${1:-.}"
+
+# ─────────────────────────────────────
+# 실행
+# ─────────────────────────────────────
+
+echo "Running {script-name}..."
+
+# TODO: 스크립트 로직 작성
+
+echo "Done."
+
+# ─────────────────────────────────────
+# 스크립트 작성 가이드:
+# - set -euo pipefail 필수 (안전 실행)
+# - 외부 URL 호출 금지 (보안)
+# - 헤더 메타데이터 필수: @name, @description, @args, @output
+# - 에이전트가 Bash로 실행 (컨텍스트에 로드하지 않음 → 토큰 0)
+# - 파일명: {verb}-{noun}.sh (예: check-secrets.sh, validate-schema.sh)
+# ─────────────────────────────────────

package/templates/base/skills/architecture/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: architecture
+description: |
+  아키텍처 설계 및 API 명세 가이드라인.
+  Clean Architecture, RESTful API 설계, ADR, 데이터 모델링을 다룸.
+  Use when: "아키텍처 설계, API 설계, ADR, 레이어 구조, 데이터 모델"
+version: "1.0.0"
+tags: [architecture, api, design]
+user-invocable: false
+---
+
+# Architecture
+
+시스템 아키텍처 설계 및 API 명세를 위한 가이드라인.
+
+## Philosophy
+
+- 의존성 규칙: 안쪽 레이어는 바깥쪽을 모름
+- 추상화: 인터페이스를 통한 의존성 역전
+- 단일 책임: 각 컴포넌트는 하나의 역할
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | ref | [api-design](references/api-design.md) | RESTful API URL 패턴, 응답 형식 |
+| HIGH | ref | [adr-template](references/adr-template.md) | ADR 작성 가이드 + 템플릿 |
+
+## Quick Rules
+
+### Clean Architecture Layers
+| Layer | Level | 역할 |
+|-------|-------|------|
+| Entities | core | 핵심 비즈니스 로직 |
+| Use Cases | application | 애플리케이션 로직 |
+| Interface Adapters | adapter | 컨트롤러, 프레젠터 |
+| Frameworks & Drivers | external | DB, Web, 외부 시스템 |
+
+### Data Design
+- 정규화: 1NF(원자값) → 2NF(부분 함수 종속 제거) → 3NF(이행 함수 종속 제거)
+- 인덱스: 자주 조회되는 컬럼, WHERE/JOIN/ORDER BY 대상, 카디널리티 고려
+
+### ADR
+트레이드오프가 있는 기술 결정 시 반드시 ADR 작성. 상세 템플릿은 references/adr-template.md 참조.
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 레이어 간 의존성이 올바른가 (안→밖만 허용) |
+| CRITICAL | API 응답 형식이 일관적인가 |
+| HIGH | 에러 코드가 문서화되었는가 |
+| HIGH | 주요 결정에 ADR이 있는가 |
+| MEDIUM | 데이터 모델이 정규화되었는가 |

package/templates/base/skills/architecture/references/adr-template.md

@@ -0,0 +1,50 @@
+---
+title: Architecture Decision Record Template
+category: guide
+source: internal
+---
+
+# Architecture Decision Record (ADR)
+
+아키텍처 결정을 문서화하는 ADR 작성 가이드.
+
+## When to Write ADR
+
+- 기술 스택 선정
+- 아키텍처 패턴 결정
+- 트레이드오프가 있는 결정
+
+## Template
+
+```markdown
+# ADR-XXX: {제목}
+
+## Status
+Proposed / Accepted / Deprecated / Superseded
+
+## Context
+결정이 필요한 배경과 상황
+
+## Decision
+내린 결정과 선택한 옵션
+
+## Consequences
+### Positive
+- 장점 1
+- 장점 2
+
+### Negative
+- 단점 1 (완화 방안)
+
+## Alternatives Considered
+| 옵션 | 장점 | 단점 |
+|-----|-----|-----|
+| A | ... | ... |
+| B | ... | ... |
+```
+
+## Common Pitfalls
+
+- Status를 업데이트하지 않아 현재 유효한지 모호
+- Context 없이 Decision만 기록 → 나중에 "왜 이렇게 했지?" 불명확
+- Alternatives를 기록하지 않으면 나중에 같은 논의 반복

package/templates/base/skills/architecture/references/api-design.md

@@ -0,0 +1,64 @@
+---
+title: RESTful API Design Guide
+category: guide
+source: internal
+---
+
+# RESTful API Design Guide
+
+REST API URL 패턴, 응답 형식, 에러 코드 설계 가이드.
+
+## URL Patterns
+
+| Method | Path | 용도 |
+|--------|------|------|
+| GET | `/api/v1/{resource}` | 목록 조회 |
+| GET | `/api/v1/{resource}/:id` | 단일 조회 |
+| POST | `/api/v1/{resource}` | 생성 |
+| PUT | `/api/v1/{resource}/:id` | 전체 수정 |
+| PATCH | `/api/v1/{resource}/:id` | 부분 수정 |
+| DELETE | `/api/v1/{resource}/:id` | 삭제 |
+
+## Response Format
+
+### Success
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null,
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100
+  }
+}
+```
+
+### Error
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "AUTH_001",
+    "message": "Invalid credentials",
+    "details": { ... }
+  }
+}
+```
+
+## Key Principles
+
+- 리소스 중심 URL 설계 (동사 X, 명사 O)
+- HTTP 메서드로 동작 표현 (GET=조회, POST=생성, PUT/PATCH=수정, DELETE=삭제)
+- 일관된 응답 형식 (success/data/error 구조)
+- 버전 관리 (`/api/v1/`)
+- 적절한 HTTP 상태 코드 사용
+
+## Common Pitfalls
+
+- URL에 동사 사용 (`/api/getUsers` → `/api/v1/users`)
+- 일관성 없는 에러 응답 형식
+- 페이지네이션 미구현 (대량 데이터 성능 이슈)
+- 버전 없는 API → 하위 호환성 깨짐

package/templates/base/skills/backend/node/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: node
+description: Node.js 백엔드 개발 가이드라인 (Hono Framework). 비동기 우선, Zod 타입 안전, Clean Architecture 레이어 분리.
+version: "1.0.0"
+tags: [nodejs, hono, backend]
+user-invocable: false
+---
+
+# Node.js Backend Guidelines (Hono)
+
+Node.js 기반 백엔드 서비스 개발 가이드라인 (Hono 프레임워크 중심).
+
+## Philosophy
+
+- 비동기 우선 - 블로킹 작업 피하기
+- 에러는 명시적으로 처리
+- 환경 분리 - 설정은 환경변수로
+- 타입 안전한 API - Zod로 검증
+- 레이어 분리 - Clean Architecture
+
+## Project Structure
+
+아키텍처 설정에 따라 결정:
+- Clean Architecture: `architectures/clean/backend.xml`
+- Hexagonal Architecture: `architectures/hexagonal/backend.xml`
+
+## Rules
+
+| Priority | Rule | Description |
+|----------|------|-------------|
+| CRITICAL | [hono-app-setup](rules/hono-app-setup.md) | Hono 앱 설정, 미들웨어, 라우트, Zod 검증 |
+| CRITICAL | [error-handling](rules/error-handling.md) | AppError 계층 + 글로벌 에러 핸들러 |
+| CRITICAL | [async-patterns](rules/async-patterns.md) | Promise.all, waterfall 방지, 트랜잭션 |
+| HIGH | [jwt-auth](rules/jwt-auth.md) | JWT 미들웨어, RBAC, 토큰 생성/갱신 |
+| HIGH | [env-config](rules/env-config.md) | Zod 환경변수 검증 |
+| MEDIUM | [middleware](rules/middleware.md) | Rate Limiting, Request Logging |
+| MEDIUM | [testing](rules/testing.md) | Hono API 테스트 + Service 유닛 테스트 |
+| LOW | [deployment](rules/deployment.md) | Graceful Shutdown |
+
+## Quick Rules
+
+### 비동기
+- async/await 사용, 콜백 금지
+- 독립 작업은 Promise.all로 병렬
+- Waterfall 방지 (Promise 먼저 시작, 나중에 await)
+- 동기 파일 I/O 금지 (fs.readFileSync)
+
+### 보안
+- 환경변수 Zod 검증 (앱 시작 시 실패)
+- 입력 검증 (zValidator)
+- JWT HttpOnly 쿠키로 Refresh Token 관리
+- Rate Limiting 적용
+- 에러 메시지에 민감 정보 제외
+- 하드코딩된 시크릿 금지
+
+### 구조
+- Clean Architecture 레이어 분리
+- Repository 패턴 (DI)
+- 글로벌 에러 핸들러
+- 커스텀 에러 클래스 계층
+
+### Hono
+- 타입 안전한 라우트 정의
+- zValidator로 요청 검증
+- 미들웨어로 공통 로직 처리
+- 일관된 응답 형식 `{ success, data, error }`
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | Zod 입력 검증 (zValidator) |
+| CRITICAL | 글로벌 에러 핸들러 |
+| CRITICAL | 환경변수 Zod 검증 |
+| CRITICAL | Waterfall 제거 (Promise.all) |
+| HIGH | Clean Architecture 레이어 분리 |
+| HIGH | 커스텀 에러 클래스 |
+| HIGH | JWT 인증 (HttpOnly Refresh Token) |
+| HIGH | Rate Limiting |
+| MEDIUM | Request Logging (구조화 로그) |
+| MEDIUM | Graceful Shutdown |

package/templates/base/skills/backend/node/rules/async-patterns.md

@@ -0,0 +1,81 @@
+---
+title: Async Patterns
+impact: CRITICAL
+tags: async, promise, waterfall, transaction
+---
+
+## Async Patterns
+
+### Promise.all for Independent Operations
+
+**Incorrect:**
+```typescript
+// Sequential - 3 round trips
+const user = await userService.findById(userId);
+const orders = await orderService.findByUserId(userId);
+const notifications = await notificationService.getUnread(userId);
+```
+
+**Correct:**
+```typescript
+// Parallel - 1 round trip
+const [user, orders, notifications] = await Promise.all([
+  userService.findById(userId),
+  orderService.findByUserId(userId),
+  notificationService.getUnread(userId),
+]);
+```
+
+### API Route Waterfall Prevention
+
+**Incorrect:**
+```typescript
+app.get('/dashboard', async (c) => {
+  const session = await auth();
+  const config = await fetchConfig(); // config는 session 불필요
+  const data = await fetchData(session.user.id);
+  return c.json({ data, config });
+});
+```
+
+**Correct:**
+```typescript
+app.get('/dashboard', async (c) => {
+  const sessionPromise = auth();
+  const configPromise = fetchConfig(); // 즉시 시작
+
+  const session = await sessionPromise;
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id), // session에 의존
+  ]);
+  return c.json({ data, config });
+});
+```
+
+### Prisma Transaction
+
+```typescript
+export async function createOrder(input: CreateOrderInput) {
+  return prisma.$transaction(async (tx) => {
+    const user = await tx.user.findUnique({ where: { id: input.userId } });
+    if (!user) throw new AppError('USER_NOT_FOUND', 'User not found', 404);
+
+    let totalAmount = 0;
+    for (const item of input.items) {
+      const product = await tx.product.findUnique({ where: { id: item.productId } });
+      if (!product || product.stock < item.quantity) {
+        throw new AppError('INSUFFICIENT_STOCK', `Insufficient stock for ${item.productId}`, 400);
+      }
+      await tx.product.update({ where: { id: item.productId }, data: { stock: { decrement: item.quantity } } });
+      totalAmount += product.price * item.quantity;
+    }
+
+    return tx.order.create({
+      data: { userId: input.userId, totalAmount, status: 'PENDING',
+        items: { create: input.items.map(i => ({ productId: i.productId, quantity: i.quantity })) } },
+      include: { items: true },
+    });
+  });
+}
+```

package/templates/base/skills/backend/node/rules/deployment.md

@@ -0,0 +1,33 @@
+---
+title: Deployment
+impact: LOW
+tags: deployment, graceful-shutdown
+---
+
+## Graceful Shutdown
+
+```typescript
+// src/index.ts
+import { serve } from '@hono/node-server';
+import app from './app';
+import { config } from './config';
+import { prisma } from './infrastructure/database/prisma';
+
+const server = serve({
+  fetch: app.fetch,
+  port: config.PORT,
+  hostname: config.HOST,
+}, (info) => {
+  console.log(`Server running at http://${info.address}:${info.port}`);
+});
+
+async function shutdown(signal: string) {
+  console.log(`${signal} received. Shutting down...`);
+  server.close(() => console.log('HTTP server closed'));
+  await prisma.$disconnect();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```