timsquad 2.1.0 → 3.4.0

package/templates/base/skills/mobile/flutter/security/rules/ssl-pinning.md

@@ -0,0 +1,197 @@
+---
+title: SSL Pinning
+impact: HIGH
+impactDescription: "미적용 → MITM 공격에 API 통신 노출, 토큰/데이터 탈취"
+tags: ssl, tls, certificate-pinning, public-key-pinning, dio, mitm
+---
+
+## SSL Pinning
+
+**Impact: HIGH (미적용 → MITM 공격에 API 통신 노출, 토큰/데이터 탈취)**
+
+Dio SecurityContext 기반 인증서/공개키 pinning.
+프록시 도구(Charles, mitmproxy)를 통한 API 통신 감청 방지.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  dio: ^5.7.0
+```
+
+### 인증서 Pinning
+
+**Incorrect (pinning 없이 기본 HTTP 클라이언트 사용):**
+```dart
+final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));
+// → 루팅 기기 + Charles Proxy → 모든 API 통신 감청 가능
+// → 사용자 토큰, 개인정보 탈취
+```
+
+**Correct (인증서 pinning 적용):**
+```dart
+class PinnedHttpClient {
+  /// 인증서 pinning이 적용된 Dio 인스턴스 생성
+  static Dio create({required String baseUrl}) {
+    final securityContext = SecurityContext(withTrustedRoots: false);
+
+    // 서버 인증서를 앱에 번들
+    // assets/certificates/api_cert.pem
+    final certData = rootBundle.load('assets/certificates/api_cert.pem');
+
+    return Dio(BaseOptions(baseUrl: baseUrl))
+      ..httpClientAdapter = IOHttpClientAdapter(
+        createHttpClient: () {
+          final client = HttpClient(context: securityContext);
+
+          client.badCertificateCallback = (cert, host, port) {
+            // 핀 검증 실패 → 연결 거부
+            return false;
+          };
+
+          return client;
+        },
+      );
+  }
+}
+```
+
+### 공개키 Pinning (권장)
+
+```dart
+/// 공개키 pinning — 인증서 갱신 시에도 공개키가 동일하면 동작
+class PublicKeyPinnedClient {
+  // SHA-256 공개키 해시 (base64)
+  // openssl 명령어로 추출:
+  // openssl s_client -connect api.example.com:443 | \
+  //   openssl x509 -pubkey -noout | \
+  //   openssl pkey -pubin -outform der | \
+  //   openssl dgst -sha256 -binary | base64
+  static const _pinnedKeys = [
+    'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=', // 현재 키
+    'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=', // 백업 키
+  ];
+
+  static Dio create({required String baseUrl}) {
+    return Dio(BaseOptions(baseUrl: baseUrl))
+      ..httpClientAdapter = IOHttpClientAdapter(
+        createHttpClient: () {
+          final client = HttpClient();
+
+          client.badCertificateCallback = (X509Certificate cert, String host, int port) {
+            // 공개키 해시 비교
+            final certHash = sha256
+                .convert(cert.der)
+                .toString();
+
+            // 핀 목록에 포함되어 있으면 허용
+            return _pinnedKeys.contains(certHash);
+          };
+
+          return client;
+        },
+      );
+  }
+}
+```
+
+### 핀 업데이트 전략
+
+```dart
+/// 원격 핀 설정 — 인증서 만료 시 앱 업데이트 없이 핀 교체
+class RemotePinManager {
+  final SecureStorageService _storage;
+  final Dio _bootstrapDio; // pinning 없는 초기 요청용 (최초 1회)
+
+  RemotePinManager({
+    required SecureStorageService storage,
+    required Dio bootstrapDio,
+  })  : _storage = storage,
+        _bootstrapDio = bootstrapDio;
+
+  /// 앱 시작 시 핀 목록 갱신
+  Future<List<String>> fetchPins() async {
+    // 1. 로컬 캐시 확인
+    final cached = await _storage.getPinnedKeys();
+    if (cached != null && cached.isNotEmpty) {
+      return cached;
+    }
+
+    // 2. 서버에서 핀 목록 가져오기 (최초 또는 캐시 만료)
+    try {
+      final response = await _bootstrapDio.get('/security/pins');
+      final pins = (response.data['pins'] as List).cast<String>();
+      await _storage.savePinnedKeys(pins);
+      return pins;
+    } catch (e) {
+      // 3. 하드코딩 폴백 (앱 번들)
+      return PublicKeyPinnedClient._pinnedKeys;
+    }
+  }
+}
+```
+
+### 디버그/개발 환경 처리
+
+```dart
+/// 개발 환경에서만 pinning 비활성화
+Dio createApiClient({required String baseUrl}) {
+  if (kDebugMode) {
+    // 개발 환경: Charles Proxy 등 디버깅 도구 허용
+    return Dio(BaseOptions(baseUrl: baseUrl));
+  }
+
+  // 프로덕션: pinning 적용
+  return PublicKeyPinnedClient.create(baseUrl: baseUrl);
+}
+
+// 주의: kDebugMode가 아닌 커스텀 플래그 사용 시
+// Release 빌드에서 실수로 pinning 비활성화 위험
+// → kDebugMode (컴파일 타임 상수) 사용 권장
+```
+
+### 플랫폼별 고려사항
+
+```
+iOS:
+- App Transport Security (ATS) → TLS 1.2 이상 강제 (기본)
+- NSAllowsArbitraryLoads: false 유지 (HTTP 차단)
+- 개발 서버 예외: NSExceptionDomains에 로컬 서버만 추가
+
+Android:
+- Network Security Config (res/xml/network_security_config.xml)
+- 기본: 시스템 CA만 신뢰 (Android 7+)
+- 사용자 CA 차단: <trust-anchors><certificates src="system"/></trust-anchors>
+- 디버그 빌드 예외: <debug-overrides><trust-anchors><certificates src="user"/></trust-anchors></debug-overrides>
+```
+
+```xml
+<!-- android/app/src/main/res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+  <base-config cleartextTrafficPermitted="false">
+    <trust-anchors>
+      <certificates src="system"/>
+    </trust-anchors>
+  </base-config>
+  <debug-overrides>
+    <trust-anchors>
+      <certificates src="user"/>
+    </trust-anchors>
+  </debug-overrides>
+</network-security-config>
+```
+
+### 규칙
+
+- 프로덕션 → SSL pinning 필수 (인증서 또는 공개키)
+- 공개키 pinning 권장 → 인증서 갱신 시에도 동일 키면 동작
+- 백업 핀 최소 1개 → 키 롤오버 시 앱 업데이트 없이 전환
+- `badCertificateCallback` → 핀 불일치 시 `return false` (연결 거부)
+- 디버그 모드 → `kDebugMode`로 pinning 비활성화 (프록시 디버깅용)
+- `kDebugMode` 외 커스텀 플래그 → Release에서 실수로 비활성화 위험
+- Android → `network_security_config.xml` 에서 cleartext 차단 + 사용자 CA 차단
+- iOS → ATS 기본 유지, `NSAllowsArbitraryLoads: false`
+- 핀 만료 대비 → 원격 핀 업데이트 또는 하드코딩 백업 핀
+- 인증서 교체 주기 → 핀 업데이트 배포 일정과 동기화

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

@@ -0,0 +1,58 @@
+---
+name: planning
+description: |
+  기획 및 요건 정의 가이드라인.
+  PRD, 요구사항 정의, 문서 구조화, 대용량 문서 분할 전략을 다룸.
+  Use when: "기획, PRD, 요구사항, 요건 정의, 스코프, 마일스톤"
+version: "1.0.0"
+tags: [planning, prd, requirements]
+user-invocable: false
+---
+
+# Planning
+
+기획 문서 작성 및 요건 정의를 위한 가이드라인.
+
+## Philosophy
+
+- SSOT 구조 준수: PRD (Why) → Planning (Overview) → Requirements (What)
+- 각 문서는 다음 단계의 입력
+- 검증 가능한 요건만 작성
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | ref | [prd-guide](references/prd-guide.md) | PRD 작성 가이드 + 예시 |
+| HIGH | ref | [requirements-guide](references/requirements-guide.md) | 요건 분류 + SMART + MoSCoW |
+
+## Quick Rules
+
+### SSOT Documents
+| 문서 | 역할 |
+|------|------|
+| `prd.md` | 왜 만드는지, 목표, 성공 지표 |
+| `planning.md` | 전체 계획, 마일스톤, 일정 |
+| `requirements.md` | 기능/비기능 요건 목록 |
+| `functional-spec.md` | 기능 시나리오, 예외처리 |
+
+### Large Document Strategy
+800줄 이상 예상 문서는 반드시 분할:
+1. 목차 기반 규모 사전 추정
+2. 도메인별 분할
+3. 인덱스 파일에서 분할 문서 링크 유지
+4. 순차 append 방식으로 섹션별 작성
+
+### Context Verification
+SSOT 템플릿 작성 시 `config.yaml` 프로젝트 설정을 먼저 확인.
+프로젝트에서 실제 사용하는 서비스만 포함. 제너릭 외부 서비스를 무분별하게 채우지 않는다.
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 목표가 명확히 정의되었는가 |
+| CRITICAL | 스코프가 명확히 구분되었는가 (포함/제외) |
+| HIGH | 모든 요건에 우선순위가 있는가 |
+| HIGH | 요건이 검증 가능한가 (정량적 기준) |
+| MEDIUM | 이해관계자 승인을 받았는가 |

package/templates/base/skills/planning/references/prd-guide.md

@@ -0,0 +1,47 @@
+---
+title: PRD Writing Guide
+category: guide
+source: internal
+---
+
+# PRD (Product Requirements Document) Guide
+
+PRD 작성 시 필수 섹션과 예시.
+
+## Required Sections
+
+1. **배경 및 목적** — 왜 이 제품/기능이 필요한가
+2. **목표 사용자** — 누가 사용하는가
+3. **핵심 가치** — 어떤 문제를 해결하는가
+4. **성공 지표** — 어떻게 성공을 측정할 것인가
+5. **스코프** — 포함/제외 범위
+
+## Example
+
+```markdown
+## 1. 배경 및 목적
+현재 로그인 프로세스에서 이탈률이 30%에 달함.
+소셜 로그인 도입으로 가입/로그인 허들을 낮추고자 함.
+
+## 2. 목표 사용자
+- 처음 방문하는 신규 사용자
+- 비밀번호를 자주 잊어버리는 사용자
+
+## 3. 핵심 가치
+- 3초 내 로그인 완료
+- 비밀번호 기억 부담 제거
+
+## 4. 성공 지표
+- 로그인 이탈률 30% → 10%
+- 가입 전환율 20% 향상
+
+## 5. 스코프
+포함: Google, Apple 소셜 로그인
+제외: Facebook, Twitter (Phase 2)
+```
+
+## Common Pitfalls
+
+- 성공 지표가 정량적이지 않음 ("사용자 경험 개선" → 구체적 수치)
+- 스코프 경계가 모호 → 나중에 스코프 크리프 발생
+- 목표 사용자 미정의 → 모든 사람을 위해 만들다 아무도 만족 못함

package/templates/base/skills/planning/references/requirements-guide.md

@@ -0,0 +1,46 @@
+---
+title: Requirements Writing Guide
+category: guide
+source: internal
+---
+
+# Requirements Writing Guide
+
+기능/비기능 요건 정의 및 분류 가이드.
+
+## Classification
+
+| 유형 | 약어 | 설명 |
+|------|------|------|
+| 기능 요건 | FR | 시스템이 해야 하는 것 |
+| 비기능 요건 | NFR | 성능, 보안, 확장성 등 |
+
+## SMART Principles
+
+- **S**pecific — 구체적
+- **M**easurable — 측정 가능
+- **A**chievable — 달성 가능
+- **R**elevant — 관련성 있음
+- **T**ime-bound — 기한 있음
+
+## Priority System (MoSCoW)
+
+- **Must** — 반드시 포함
+- **Should** — 강력 권장
+- **Could** — 있으면 좋음
+- **Won't** — 이번에는 제외
+
+## Requirements Table Template
+
+```markdown
+| ID | 분류 | 요건 | 우선순위 | 검증 방법 |
+|----|-----|-----|---------|----------|
+| FR-001 | 인증 | 사용자는 이메일/비밀번호로 로그인할 수 있다 | Must | 테스트 |
+| NFR-001 | 성능 | 로그인 응답 시간 < 500ms | Must | 부하 테스트 |
+```
+
+## Common Pitfalls
+
+- 검증 불가능한 요건 ("빨라야 한다" → "응답 500ms 이하")
+- 우선순위 미지정 → 모든 것이 Must가 됨
+- 기능/비기능 미분류 → 비기능 요건 누락

package/templates/base/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: prompt-engineering
+description: 프롬프트 최적화, 템플릿 관리, 회고 기반 개선 가이드라인
+version: "1.0.0"
+tags: [prompt, optimization, retrospective]
+user-invocable: false
+---
+
+<skill name="prompt-engineering">
+  <purpose>에이전트/스킬 프롬프트 최적화 및 품질 개선</purpose>
+
+  <optimization-principles>
+    <principle name="구조화">
+      역할 → 페르소나 → 작업 전 필수 → 핵심 원칙 → 작업 프로세스 → 출력 형식 → 금지 사항 → 예시
+    </principle>
+    <principle name="명확성">
+      | Bad | Good |
+      |-----|------|
+      | "잘 작성해" | "3문장 이내로 요약해" |
+      | "좋은 코드" | "테스트 커버리지 80%" |
+      | 나열만 | "필수/권장/선택" 분류 |
+    </principle>
+    <principle name="컨텍스트">
+      프로젝트 정보, 참조 문서 경로, 제약 사항을 명시적으로 주입
+    </principle>
+    <principle name="예시 포함">
+      Good/Bad 예시를 함께 제공하여 기대 품질 수준 명확화
+    </principle>
+  </optimization-principles>
+
+  <template-format>
+    <![CDATA[
+---
+name: {template-name}
+version: 1.0.0
+agent: {target-agent}
+task_type: {implementation|review|analysis}
+---
+
+# {Title}
+
+## 컨텍스트 주입
+{{CONTEXT}}
+
+## 작업 정의
+{{TASK_DESCRIPTION}}
+
+## SSOT 참조
+{{SSOT_REFERENCES}}
+
+## 출력 요구사항
+{{OUTPUT_REQUIREMENTS}}
+
+## 검증 기준
+{{VALIDATION_CRITERIA}}
+    ]]>
+  </template-format>
+
+  <version-management>
+    | 변경 유형 | 버전 증가 | 예시 |
+    |---------|----------|------|
+    | 구조 변경 | Major (x.0.0) | 섹션 추가/삭제 |
+    | 내용 수정 | Minor (0.x.0) | 규칙 추가, 예시 수정 |
+    | 오타 수정 | Patch (0.0.x) | 단순 수정 |
+  </version-management>
+
+  <rollback-conditions>
+    | 조건 | 액션 |
+    |-----|------|
+    | 성공률 10% 하락 | 이전 버전 롤백 |
+    | Critical 피드백 발생 | 즉시 롤백 + 분석 |
+    | A/B 테스트 실패 | 기존 버전 유지 |
+  </rollback-conditions>
+
+  <improvement-mapping>
+    패턴 → 프롬프트 개선 매핑 프로세스:
+    1. 실패/성공 패턴 식별 (회고 스킬에서)
+    2. 대상 에이전트/스킬 .md 파일 특정
+    3. 변경 전/후 diff 작성
+    4. 기대 효과 및 검증 방법 명시
+    5. 사용자 승인 후 적용
+  </improvement-mapping>
+
+  <quality-checklist>
+    | 항목 | 검증 내용 |
+    |-----|----------|
+    | 명확성 | 모호한 표현이 없는가? |
+    | 완전성 | 필요한 정보가 모두 있는가? |
+    | 구조화 | 논리적 순서로 구성되었는가? |
+    | 예시 | Good/Bad 예시가 있는가? |
+    | 제약 | 금지 사항이 명시되었는가? |
+    | 출력 | 기대 출력 형식이 정의되었는가? |
+  </quality-checklist>
+
+  <effectiveness-metrics>
+    | 메트릭 | 측정 방법 | 목표 |
+    |-------|----------|:----:|
+    | 작업 성공률 | 성공 작업 / 전체 작업 | 90%+ |
+    | 수정 횟수 | 평균 수정 횟수 | 2 미만 |
+    | 피드백 레벨 | Level 2+ 피드백 비율 | 10% 미만 |
+    | SSOT 정합성 | SSOT 불일치 건수 | 0 |
+  </effectiveness-metrics>
+</skill>

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

@@ -0,0 +1,102 @@
+---
+name: retrospective
+description: 회고 분석, 패턴 식별, 개선 제안 가이드라인
+version: "1.0.0"
+tags: [retrospective, analysis, improvement]
+user-invocable: false
+---
+
+<skill name="retrospective">
+  <purpose>프로젝트 회고를 위한 분석 프레임워크와 개선 프로세스</purpose>
+
+  <tsq-cli priority="critical">
+    <instruction>
+      로그 기록, 피드백, 메트릭, 회고 등 TSQ CLI가 제공하는 기능은 반드시 CLI 커맨드를 사용하세요.
+      직접 파일을 조작하지 마세요. CLI를 사용해야 구조화된 데이터가 자동 저장됩니다.
+    </instruction>
+    <commands>
+      | 시점 | 커맨드 |
+      |-----|--------|
+      | 회고 시작 | `tsq retro start` |
+      | Phase별 회고 | `tsq retro phase {phase}` |
+      | 메트릭 수집 | `tsq retro collect` 또는 `tsq metrics collect` |
+      | 로그 확인 | `tsq log list` / `tsq log today` |
+      | 리포트 생성 | `tsq retro report` (GitHub Issue 포함) |
+      | 로컬 리포트만 | `tsq retro report --local` |
+      | 사이클 완료 | `tsq retro apply` |
+    </commands>
+  </tsq-cli>
+
+  <references>
+    <reference path=".timsquad/retrospective/metrics/">메트릭 데이터</reference>
+    <reference path=".timsquad/logs/">작업 로그</reference>
+    <reference path=".timsquad/retrospective/patterns/">기존 패턴</reference>
+    <reference path=".timsquad/state/workspace.xml">작업 이력</reference>
+  </references>
+
+  <kpt-framework>
+    <description>Keep-Problem-Try 회고 프레임워크</description>
+    <category name="Keep">무엇이 잘 되었나? 계속해야 할 것은?</category>
+    <category name="Problem">무엇이 문제였나? 장애물은?</category>
+    <category name="Try">다음에 시도해볼 것은?</category>
+  </kpt-framework>
+
+  <pattern-classification>
+    <failure-pattern id="FP-XXX">
+      <criteria>3회 이상 반복, 작업 지연 유발, 품질 저하 원인</criteria>
+    </failure-pattern>
+    <success-pattern id="SP-XXX">
+      <criteria>효과 검증됨, 효율성 향상, 품질 향상</criteria>
+    </success-pattern>
+  </pattern-classification>
+
+  <metrics>
+    | 메트릭 | 계산 방법 |
+    |-------|----------|
+    | 작업 수 | 완료된 작업 개수 |
+    | 성공률 | (성공 작업 / 전체 작업) x 100 |
+    | 평균 수정 횟수 | 총 수정 횟수 / 작업 수 |
+    | 점수 | 가중 평균 (성공률 x 0.4 + (1 - 수정률) x 0.3 + 기타 x 0.3) |
+  </metrics>
+
+  <improvement-format>
+    <![CDATA[
+## IMP-XXX: {개선 제목}
+
+**대상**: {에이전트/스킬}.md
+**관련 패턴**: FP-XXX / SP-XXX
+
+### 현재 문제
+{문제 설명}
+
+### 제안 변경
+```diff
+- 현재 내용
++ 개선된 내용
+```
+
+### 기대 효과
+{개선 효과}
+    ]]>
+  </improvement-format>
+
+  <report-sections>
+    1. 메트릭 요약
+    2. 에이전트별 성과
+    3. 피드백 분석
+    4. 발견된 패턴
+    5. 개선 조치
+    6. 다음 사이클 목표
+  </report-sections>
+
+  <principles>
+    <principle>객관적 데이터 우선 - 주관적 평가보다 수치 기반</principle>
+    <principle>구체적 예시 - 추상적 서술 지양</principle>
+    <principle>실행 가능한 개선안 - "더 잘하자" 대신 구체적 액션</principle>
+    <principle>균형 잡힌 시각 - 문제점만이 아닌 성공 사례도 포함</principle>
+  </principles>
+
+  <apply-process>
+    제안된 개선 → 사용자 검토/승인 → SKILL.md 업데이트 → 템플릿 업데이트 → lessons.md 기록 → 다음 사이클에서 효과 측정
+  </apply-process>
+</skill>

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

@@ -0,0 +1,55 @@
+---
+name: security
+description: 보안 검토 및 취약점 탐지 가이드라인
+version: "1.0.0"
+tags: [security, owasp, vulnerability]
+user-invocable: false
+---
+
+# Security Guidelines (OWASP Top 10)
+
+## OWASP Top 10 요약
+
+| # | 취약점 | 핵심 방어 |
+|---|--------|----------|
+| 1 | Injection | Parameterized Query, ORM 사용 |
+| 2 | Broken Authentication | 강력한 패스워드 정책, bcrypt(12+) |
+| 3 | Sensitive Data Exposure | DTO로 민감 정보 제외, 로그 마스킹 |
+| 5 | Broken Access Control | authenticate + authorize 미들웨어 |
+| 6 | Security Misconfiguration | helmet(), CORS 제한 |
+| 7 | XSS | textContent 사용, innerHTML 금지 |
+| 8 | Insecure Deserialization | Zod 스키마 검증 |
+| 9 | Known Vulnerabilities | npm audit, 정기 업데이트 |
+| 10 | Insufficient Logging | 로그인 실패, 브루트포스 로깅 |
+
+## 추가 보안 체크
+
+### 시크릿 관리
+- **금지**: 하드코딩 (`const apiKey = 'sk-...'`)
+- **필수**: 환경변수 (`process.env.API_KEY`)
+- **권장**: 시크릿 매니저
+
+### Rate Limiting
+- API 엔드포인트에 rate limiter 적용
+
+### CSRF 방지
+- csrf 토큰 사용
+
+## Checklist
+- [ ] SQL/NoSQL Injection 방지
+- [ ] 강력한 인증 구현
+- [ ] 민감 정보 보호
+- [ ] 접근 제어 구현
+- [ ] XSS 방지
+- [ ] 입력 검증 (Zod)
+- [ ] 의존성 취약점 확인
+- [ ] 보안 로깅 구현
+- [ ] 시크릿 안전하게 관리
+- [ ] Rate Limiting 적용
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [owasp-examples](rules/owasp-examples.md) | 취약점별 Bad/Good 코드 예시 |
+| HIGH | script | [check-secrets](scripts/check-secrets.sh) | 하드코딩된 시크릿 자동 스캔 |