timsquad 3.5.0 → 3.7.0

package/templates/base/timsquad/ssot/sdk-spec.template.md

@@ -0,0 +1,223 @@
+---
+title: "SDK 명세서 (SDK Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# SDK 명세서 (SDK Specification)
+
+> 외부 개발자가 사용하는 SDK/라이브러리의 공개 API, 사용법, 버전 정책을 정의합니다.
+> 플랫폼/프레임워크 프로젝트에서 사용자 경험의 핵심 문서입니다.
+
+---
+
+## 1. 개요
+
+### 1.1 SDK 정보
+
+| 항목 | 값 |
+|-----|-----|
+| 패키지명 | `@{{PROJECT_NAME}}/sdk` |
+| 버전 | 1.0.0 |
+| 지원 런타임 | Node.js 18+, Browser (ESM) |
+| 번들 크기 | < 50KB (gzip) |
+| 라이선스 | MIT |
+
+### 1.2 설치
+
+```bash
+npm install @{{PROJECT_NAME}}/sdk
+# or
+yarn add @{{PROJECT_NAME}}/sdk
+```
+
+### 1.3 빠른 시작
+
+```typescript
+import { Client } from '@{{PROJECT_NAME}}/sdk';
+
+const client = new Client({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com',
+});
+
+const result = await client.resource.list({ limit: 10 });
+console.log(result.data);
+```
+
+---
+
+## 2. 공개 API
+
+### 2.1 Client
+
+| 메서드 | 시그니처 | 설명 |
+|-------|---------|------|
+| `constructor` | `new Client(options: ClientOptions)` | 클라이언트 초기화 |
+
+```typescript
+interface ClientOptions {
+  apiKey: string;
+  baseUrl?: string;          // default: 프로덕션 URL
+  timeout?: number;          // default: 30000 (ms)
+  retries?: number;          // default: 3
+  onError?: (error: SDKError) => void;
+}
+```
+
+### 2.2 [Resource Name]
+
+| 메서드 | 시그니처 | 설명 |
+|-------|---------|------|
+| `list` | `list(params?: ListParams): Promise<PaginatedResponse<T>>` | 목록 조회 |
+| `get` | `get(id: string): Promise<T>` | 단건 조회 |
+| `create` | `create(data: CreateInput): Promise<T>` | 생성 |
+| `update` | `update(id: string, data: UpdateInput): Promise<T>` | 수정 |
+| `delete` | `delete(id: string): Promise<void>` | 삭제 |
+
+#### 사용 예시
+
+```typescript
+// 목록 조회 (페이지네이션)
+const items = await client.resource.list({
+  page: 1,
+  limit: 20,
+  sort: 'createdAt',
+  order: 'desc',
+});
+
+// 단건 조회
+const item = await client.resource.get('item_123');
+
+// 생성
+const newItem = await client.resource.create({
+  name: 'New Item',
+  description: 'Description',
+});
+
+// 수정
+const updated = await client.resource.update('item_123', {
+  name: 'Updated Name',
+});
+
+// 삭제
+await client.resource.delete('item_123');
+```
+
+---
+
+## 3. 타입 정의
+
+### 3.1 공통 타입
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+interface SDKError {
+  code: string;
+  message: string;
+  status: number;
+  details?: Record<string, unknown>;
+}
+```
+
+### 3.2 리소스 타입
+
+```typescript
+interface Resource {
+  id: string;
+  name: string;
+  description: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CreateResourceInput {
+  name: string;
+  description?: string;
+}
+
+interface UpdateResourceInput {
+  name?: string;
+  description?: string;
+}
+```
+
+---
+
+## 4. 에러 처리
+
+### 4.1 에러 코드
+
+| 코드 | HTTP | 설명 | 대응 |
+|-----|:----:|------|------|
+| `UNAUTHORIZED` | 401 | API 키 무효 | 키 확인 |
+| `FORBIDDEN` | 403 | 권한 없음 | 권한 확인 |
+| `NOT_FOUND` | 404 | 리소스 없음 | ID 확인 |
+| `RATE_LIMITED` | 429 | 요청 제한 초과 | 재시도 (자동) |
+| `SERVER_ERROR` | 500 | 서버 오류 | 재시도 (자동) |
+
+### 4.2 에러 핸들링
+
+```typescript
+import { SDKError } from '@{{PROJECT_NAME}}/sdk';
+
+try {
+  const item = await client.resource.get('invalid_id');
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.error(`[${error.code}] ${error.message}`);
+    // RATE_LIMITED인 경우 자동 재시도됨
+  }
+}
+```
+
+---
+
+## 5. 버전 정책
+
+### 5.1 Semantic Versioning
+
+| 변경 유형 | 버전 | 예시 |
+|---------|------|------|
+| Breaking change | Major (X.0.0) | 메서드 시그니처 변경 |
+| 새 기능 | Minor (0.X.0) | 새 리소스 추가 |
+| 버그 수정 | Patch (0.0.X) | 에러 수정 |
+
+### 5.2 지원 정책
+
+| 버전 | 상태 | 지원 종료 |
+|-----|:----:|----------|
+| v1.x | Active | - |
+| v0.x | Deprecated | v1 출시 후 6개월 |
+
+### 5.3 마이그레이션 가이드
+
+Breaking change 시 마이그레이션 가이드를 `MIGRATION.md`에 제공합니다.
+
+---
+
+## 6. 관련 문서
+
+- [서비스 명세](./service-spec.md) — 내부 API 상세
+- [연동 명세](./integration-spec.md) — 외부 서비스 연동
+- [에러 코드](./error-codes.md) — 전체 에러 코드
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot/service-spec.template.md

@@ -1,7 +1,7 @@
-# {PROJECT_NAME} 서비스 명세서
+# {{PROJECT_NAME}} 서비스 명세서
 
 **Version**: 1.0
-**Created**: {DATE}
+**Created**: {{DATE}}
 **Base URL**: `https://api.example.com/v1`
 
 ---
@@ -191,4 +191,4 @@
 
 | 버전 | 날짜 | 변경 내용 | 작성자 |
 |-----|-----|----------|-------|
-| 1.0 | {DATE} | 최초 작성 | |
+| 1.0 | {{DATE}} | 최초 작성 | |

package/templates/base/timsquad/ssot/state-machine.template.md

@@ -0,0 +1,127 @@
+---
+title: "상태 머신 명세서 (State Machine Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# 상태 머신 명세서 (State Machine Specification)
+
+> 시스템 내 주요 엔티티의 상태 전이(State Transition)를 정의합니다.
+> 상태 전이 규칙, 가드 조건, 부수 효과를 명확히 하여 일관된 비즈니스 로직을 보장합니다.
+
+---
+
+## 1. 개요
+
+### 1.1 적용 대상
+
+| 엔티티 | 상태 수 | 설명 |
+|-------|:------:|------|
+| Order | 6 | 주문 생명주기 |
+| Payment | 5 | 결제 처리 흐름 |
+| User | 4 | 사용자 계정 상태 |
+
+### 1.2 용어
+
+| 용어 | 설명 |
+|-----|------|
+| State | 엔티티가 가질 수 있는 상태 값 |
+| Transition | 한 상태에서 다른 상태로의 전이 |
+| Guard | 전이가 허용되는 조건 (사전 검증) |
+| Action | 전이 시 실행되는 부수 효과 |
+| Event | 전이를 트리거하는 외부/내부 이벤트 |
+
+---
+
+## 2. [Entity Name] 상태 머신
+
+### 2.1 상태 다이어그램
+
+```
+                    ┌──────────┐
+          ┌─────── │  CREATED  │ ───────┐
+          │        └──────────┘        │
+          │ cancel       │ confirm     │ expire
+          ▼              ▼             ▼
+   ┌──────────┐   ┌──────────┐  ┌──────────┐
+   │ CANCELLED│   │ CONFIRMED│  │ EXPIRED  │
+   └──────────┘   └─────┬────┘  └──────────┘
+                        │ process
+                        ▼
+                  ┌──────────┐
+                  │ COMPLETED│
+                  └──────────┘
+```
+
+### 2.2 상태 정의
+
+| 상태 | 코드 | 설명 | 진입 조건 |
+|-----|------|------|----------|
+| CREATED | `created` | 초기 생성 상태 | 생성 시 자동 |
+| CONFIRMED | `confirmed` | 확인됨 | 검증 통과 |
+| COMPLETED | `completed` | 처리 완료 | 모든 작업 완료 |
+| CANCELLED | `cancelled` | 취소됨 | 사용자/시스템 취소 |
+| EXPIRED | `expired` | 만료됨 | TTL 초과 |
+
+### 2.3 전이 규칙
+
+| From | Event | To | Guard | Action |
+|------|-------|----|-------|--------|
+| CREATED | `confirm` | CONFIRMED | 필수 필드 충족 | 알림 발송 |
+| CREATED | `cancel` | CANCELLED | - | 관련 리소스 해제 |
+| CREATED | `expire` | EXPIRED | TTL 초과 | 정리 작업 |
+| CONFIRMED | `process` | COMPLETED | 처리 조건 충족 | 완료 알림 |
+| CONFIRMED | `cancel` | CANCELLED | 취소 가능 기간 | 환불 처리 |
+
+### 2.4 가드 조건 상세
+
+| Guard | 로직 | 실패 시 |
+|-------|------|--------|
+| 필수 필드 충족 | `entity.requiredFields.every(f => !!f)` | 400 Bad Request |
+| TTL 초과 | `now - entity.createdAt > TTL` | 스케줄러가 자동 전이 |
+| 취소 가능 기간 | `now - entity.confirmedAt < CANCEL_WINDOW` | 409 Conflict |
+
+### 2.5 부수 효과
+
+| Action | 트리거 | 처리 | 실패 전략 |
+|--------|-------|------|----------|
+| 알림 발송 | confirm → CONFIRMED | 이메일/푸시 | 재시도 (3회) |
+| 환불 처리 | cancel → CANCELLED | 결제 API 호출 | 수동 처리 큐 |
+| 정리 작업 | expire → EXPIRED | 관련 데이터 정리 | 로그 + 재시도 |
+
+---
+
+## 3. 상태 전이 정합성
+
+### 3.1 불변 규칙 (Invariants)
+
+- [ ] 터미널 상태(COMPLETED, CANCELLED, EXPIRED)에서 다른 상태로 전이 불가
+- [ ] 모든 전이는 감사 로그에 기록
+- [ ] 동시 전이 충돌 시 낙관적 잠금(Optimistic Locking) 적용
+
+### 3.2 동시성 처리
+
+| 시나리오 | 해결 방법 |
+|---------|----------|
+| 동시 상태 변경 | 버전 기반 낙관적 잠금 |
+| 이벤트 순서 역전 | 타임스탬프 검증 |
+| 중복 이벤트 | 멱등성 키(idempotency key) |
+
+---
+
+## 4. 관련 문서
+
+- [서비스 명세](./service-spec.md) — API 엔드포인트별 상태 변경
+- [에러 코드](./error-codes.md) — 상태 전이 실패 에러 코드
+- [데이터 설계](./data-design.md) — 상태 필드 스키마
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot/test-spec.template.md

@@ -178,7 +178,17 @@ describe('UserService', () => {
 
 ---
 
-## 5. 테스트 자동화
+## 5. 테스트 게이트
+
+TimSquad 워크플로우에서 자동 실행되는 테스트 게이트 설정.
+
+### 5.0 게이트별 실행 명령
+
+| 게이트 | 실행 시점 | 명령 | 타임아웃 |
+|--------|----------|------|---------|
+| Task (Unit) | Task 완료 시 | `npm run test:unit` | 120s |
+| Sequence (Integration + Build) | Sequence 완료 시 | `npm run test:integration` + `tsc --noEmit` | 300s |
+| Phase (E2E) | Phase 완료 시 | `npm run test:e2e` | 300s |
 
 ### 5.1 CI 파이프라인
 

package/templates/base/timsquad/ssot/ui-ux-spec.template.md

@@ -2,7 +2,7 @@
 title: "UI/UX 명세서"
 version: 1.0.0
 last_updated: {{DATE}}
-author: tsq-planner
+author: tsq-architect
 status: draft
 project: {{PROJECT_NAME}}
 ---
@@ -151,7 +151,47 @@ project: {{PROJECT_NAME}}
 
 ### SCR-002: [화면명]
 
-(위와 동일한 형식으로 작성)
+#### 3.2.1 개요
+
+| 항목 | 내용 |
+|-----|------|
+| **ID** | SCR-002 |
+| **화면명** | |
+| **경로** | |
+| **관련 기능** | [FS-002](./functional-spec.md#FS-002) |
+
+#### 3.2.2 와이어프레임
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│              [와이어프레임 작성]                 │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+#### 3.2.3 UI 요소
+
+| 요소 | 타입 | 설명 | 필수 |
+|-----|------|------|:----:|
+| | | | |
+
+#### 3.2.4 상태별 UI
+
+| 상태 | 설명 | UI 변화 |
+|-----|------|--------|
+| 기본 | | |
+| 로딩 | | |
+| 에러 | | |
+| 성공 | | |
+
+#### 3.2.5 반응형
+
+| 브레이크포인트 | 레이아웃 변경 |
+|--------------|-------------|
+| Desktop (≥1024px) | |
+| Tablet (768-1023px) | |
+| Mobile (<768px) | |
 
 ---
 
@@ -259,4 +299,4 @@ graph LR
 
 | 버전 | 날짜 | 작성자 | 변경 내용 |
 |------|------|--------|----------|
-| 1.0.0 | {{DATE}} | tsq-planner | 초기 작성 |
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot-map.template.yaml

@@ -0,0 +1,69 @@
+# SSOT Map — 티어별 문서 주입 기준
+# Tier 0: 모든 작업에 항상 주입 (Hook → systemMessage)
+# Tier 1: Phase 시작 시 Controller가 주입
+# Tier 2: Sequence 범위 문서 (Controller가 선택 주입)
+# Tier 3: 개별 Task에 필요한 구체 spec (Controller가 선택 주입)
+# optional: true → 타입별 선택 배포 문서 (미존재 시 건너뜀)
+
+tier-0-always:
+  description: "모든 작업에 항상 주입되는 제약 문서"
+  inject_via: hook
+  documents:
+    - compiled: rules/security-constraints.md
+      source: security-spec.md
+    - compiled: rules/completion-criteria.md
+      source: requirements.md
+
+tier-1-phase:
+  description: "Phase 시작 시 controller가 주입하는 방향성 문서"
+  inject_via: controller
+  documents:
+    - compiled: references/prd-summary.spec.md
+      source: prd.md
+    - compiled: references/architecture.spec.md
+      source: planning.md
+    - compiled: references/compliance-matrix.spec.md
+      source: compliance-matrix.md
+      optional: true
+    - compiled: references/infra-topology.spec.md
+      source: infra-topology.md
+      optional: true
+
+tier-2-sequence:
+  description: "Sequence 범위의 기능별 문서"
+  inject_via: controller
+  documents:
+    - compiled: references/service.spec.md
+      source: service-spec.md
+    - compiled: references/data-design.spec.md
+      source: data-design.md
+    - compiled: references/state-machine.spec.md
+      source: state-machine.md
+      optional: true
+    - compiled: references/performance-budget.spec.md
+      source: performance-budget.md
+      optional: true
+    - compiled: references/component-map.spec.md
+      source: component-map.md
+      optional: true
+    - compiled: references/navigation-map.spec.md
+      source: navigation-map.md
+      optional: true
+    - compiled: references/monitoring-spec.spec.md
+      source: monitoring-spec.md
+      optional: true
+
+tier-3-task:
+  description: "개별 Task에 필요한 구체 spec"
+  inject_via: controller
+  documents:
+    - compiled: references/error-codes.spec.md
+      source: error-codes.md
+    - compiled: references/functional.spec.md
+      source: functional-spec.md
+    - compiled: references/sdk-spec.spec.md
+      source: sdk-spec.md
+      optional: true
+    - compiled: references/audit-trail-spec.spec.md
+      source: audit-trail-spec.md
+      optional: true

package/templates/base/timsquad/state/workspace.xml

@@ -9,7 +9,7 @@
 
   <!-- 현재 활성 에이전트 -->
   <active-session>
-    <agent>tsq-planner</agent>
+    <agent>tsq-architect</agent>
     <started-at>{{TIMESTAMP}}</started-at>
     <mode>planning</mode>
   </active-session>
@@ -21,7 +21,7 @@
     <id>TASK-001</id>
     <title>PRD 작성</title>
     <description>제품 요구사항 정의서 초안 작성</description>
-    <agent>tsq-planner</agent>
+    <agent>tsq-architect</agent>
     <phase>planning</phase>
     <started-at>{{TIMESTAMP}}</started-at>
     <status>in_progress</status>
@@ -44,7 +44,7 @@
     <task id="TASK-002" priority="1">
       <title>요구사항 정의</title>
       <description>기능/비기능 요건 작성</description>
-      <assigned-to>tsq-planner</assigned-to>
+      <assigned-to>tsq-architect</assigned-to>
       <phase>planning</phase>
       <depends-on>TASK-001</depends-on>
       <estimated-effort>medium</estimated-effort>
@@ -73,7 +73,7 @@
     <!--
     현재 에이전트가 다음 에이전트에게 전달할 내용
 
-    <from>tsq-planner</from>
+    <from>tsq-architect</from>
     <to>tsq-developer</to>
     <timestamp>{{TIMESTAMP}}</timestamp>
     <message>
@@ -124,7 +124,7 @@
     <approval id="APV-001" type="phase-transition">
       <from-phase>planning</from-phase>
       <to-phase>implementation</to-phase>
-      <requested-by>tsq-planner</requested-by>
+      <requested-by>tsq-architect</requested-by>
       <requested-at>{{TIMESTAMP}}</requested-at>
       <reason>SSOT 문서 작성 완료, 구현 단계 진입 요청</reason>
       <checklist>
@@ -174,27 +174,27 @@
   <next-steps>
     <step order="1">
       <action>PRD 작성 완료</action>
-      <agent>tsq-planner</agent>
+      <agent>tsq-architect</agent>
       <output>ssot/prd.md</output>
     </step>
     <step order="2">
       <action>요구사항 정의</action>
-      <agent>tsq-planner</agent>
+      <agent>tsq-architect</agent>
       <output>ssot/requirements.md</output>
     </step>
     <step order="3">
       <action>API 명세 작성</action>
-      <agent>tsq-planner</agent>
+      <agent>tsq-architect</agent>
       <output>ssot/service-spec.md</output>
     </step>
     <step order="4">
       <action>데이터 설계</action>
-      <agent>tsq-planner</agent>
+      <agent>tsq-architect</agent>
       <output>ssot/data-design.md</output>
     </step>
     <step order="5">
       <action>User 승인 요청</action>
-      <agent>tsq-planner</agent>
+      <agent>tsq-architect</agent>
       <requires-approval>true</requires-approval>
     </step>
     <step order="6">
@@ -209,7 +209,7 @@
        ============================================================ -->
   <session-notes>
     <!--
-    <note timestamp="{{TIMESTAMP}}" agent="tsq-planner">
+    <note timestamp="{{TIMESTAMP}}" agent="tsq-architect">
       사용자가 MVP 우선 요청. 소셜 로그인은 v2로 미룸.
     </note>
     -->

package/templates/platforms/claude-code/rules/adr-rules.md

@@ -1,6 +1,6 @@
 ---
 description: ADR (Architecture Decision Record) 작성 규칙.
-globs:
+paths:
   - ".timsquad/ssot/ADR-*"
 ---
 

package/templates/platforms/claude-code/rules/api-conventions.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "src/api/**/*.ts"
+  - "src/routes/**/*.ts"
+  - "src/controllers/**/*.ts"
+---
+
+- RESTful 네이밍 사용 (복수형 리소스, kebab-case)
+- 에러 응답 표준 형식: `{ code: string, message: string, details?: unknown }`
+- HTTP 상태 코드 정확히 매핑 (200/201/400/401/403/404/500)
+- 요청 validation은 엔드포인트 진입 시점에서 수행
+- 비즈니스 로직은 서비스 레이어에 위치 (컨트롤러에 직접 작성 금지)

package/templates/platforms/claude-code/rules/build-gate.md

@@ -1,6 +1,6 @@
 ---
 description: 빌드 게이트. 변경 파일의 TypeScript 에러를 자동 감지하여 완료 차단.
-globs:
+paths:
   - "src/**/*.ts"
   - "src/**/*.tsx"
 ---

package/templates/platforms/claude-code/rules/completion-verification.md

@@ -1,7 +1,5 @@
 ---
 description: 완료 검증 루프. 자기 보고 금지, exit code로 완료 판정.
-globs:
-  - "**/*"
 ---
 
 # 완료 검증 루프 (Completion Verification)

package/templates/platforms/claude-code/rules/context-monitor.md

@@ -1,6 +1,6 @@
 ---
 description: 컨텍스트 윈도우 모니터. 85% 임계값 도달 시 사전 대응.
-globs:
+paths:
   - ".timsquad/.daemon/**"
 ---
 

package/templates/platforms/claude-code/rules/feedback-routing.md

@@ -1,6 +1,6 @@
 ---
 description: 피드백 라우팅 규칙. Level 1/2/3 분류 기준과 라우팅.
-globs:
+paths:
   - ".timsquad/feedback/**"
 ---
 
@@ -15,4 +15,4 @@ globs:
 ## 규칙
 - User 승인 없이 Level 3 변경 금지
 - 모든 피드백에 Level 분류 필수
-- `tsq feedback "{설명}"` 으로 기록 (직접 파일 생성 금지)
+- 피드백은 `.timsquad/state/decisions.jsonl`에 기록

package/templates/platforms/claude-code/rules/librarian-constraints.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - ".timsquad/**"
+  - "docs/**"
+---
+
+Librarian 에이전트가 이 경로에서 작업할 때:
+- 문서 작성/갱신 허용
+- 소스 코드(src/, lib/, app/) 수정 절대 금지
+- 기록, 분석, 리포트 작성만 수행
+- 코드 변경이 필요한 사항은 피드백으로 라우팅

package/templates/platforms/claude-code/rules/phase-management.md

@@ -1,6 +1,6 @@
 ---
 description: Phase 관리 규칙. Phase 전환, 허용/금지 작업, 종료 조건.
-globs:
+paths:
   - ".timsquad/state/**"
   - ".timsquad/ssot/**"
 ---
@@ -19,5 +19,5 @@ globs:
 | deployment | 배포 | - | 배포 완료 |
 
 ## Phase 종료 시
-- `skills/retrospective/SKILL.md`를 활용하여 회고 실행
+- `/retro` (tsq-retro 스킬)를 활용하여 회고 실행
 - Phase 전환 조건 미충족 시 다음 Phase 진행 금지