timsquad 2.1.0 → 3.3.0

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) | 하드코딩된 시크릿 자동 스캔 |

package/templates/base/skills/security/rules/owasp-examples.md

@@ -0,0 +1,119 @@
+---
+title: OWASP Top 10 Security Patterns
+impact: CRITICAL
+tags: security, owasp, vulnerability
+---
+
+# OWASP Top 10 — 코드 예시
+
+## 1. Injection
+```typescript
+// Bad
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// Good: Parameterized Query
+const query = 'SELECT * FROM users WHERE email = $1';
+await db.query(query, [email]);
+// Good: ORM 사용
+await userRepository.findOne({ where: { email } });
+```
+
+## 2. Broken Authentication
+```typescript
+// Bad
+if (password.length >= 4) { ... }
+
+// Good
+const passwordPolicy = {
+  minLength: 12, requireUppercase: true, requireLowercase: true,
+  requireNumber: true, requireSpecialChar: true,
+};
+const hash = await bcrypt.hash(password, 12);
+```
+
+## 3. Sensitive Data Exposure
+```typescript
+// Bad
+logger.info('User login', { email, password });
+return { ...user }; // passwordHash 포함
+
+// Good
+logger.info('User login', { email, password: '***' });
+return userToDto(user); // passwordHash 제외
+```
+
+## 5. Broken Access Control
+```typescript
+// Bad
+app.get('/api/users/:id', async (req, res) => {
+  const user = await userService.getUser(req.params.id);
+  return res.json(user);
+});
+
+// Good
+app.get('/api/users/:id', authenticate, authorize('user:read'), async (req, res) => {
+  if (req.user.id !== req.params.id && !req.user.isAdmin) throw new ForbiddenError();
+  const user = await userService.getUser(req.params.id);
+  return res.json(user);
+});
+```
+
+## 6. Security Misconfiguration
+```typescript
+app.use(helmet());
+app.use(helmet.contentSecurityPolicy({
+  directives: { defaultSrc: ["'self'"], scriptSrc: ["'self'"] },
+}));
+app.use(cors({ origin: ['https://allowed-domain.com'], credentials: true }));
+```
+
+## 7. XSS
+```typescript
+// Bad
+element.innerHTML = userInput;
+// Good
+element.textContent = userInput;
+```
+
+## 8. Insecure Deserialization
+```typescript
+// Bad
+const data = JSON.parse(userInput);
+// Good
+const schema = z.object({ name: z.string().max(100), age: z.number().min(0) });
+const data = schema.parse(JSON.parse(userInput));
+```
+
+## 9. Known Vulnerabilities
+```bash
+npm audit && npm audit fix
+npm outdated && npm update
+```
+
+## 10. Insufficient Logging
+```typescript
+logger.warn('Login failed', { email, ip: req.ip, timestamp: new Date().toISOString() });
+if (failedAttempts >= 5) {
+  logger.error('Possible brute force attack', { email, ip: req.ip });
+  await lockAccount(email);
+}
+```
+
+## Additional Checks
+
+### Rate Limiting
+```typescript
+import rateLimit from 'express-rate-limit';
+app.use('/api/', rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+```
+
+### CSRF 방지
+```typescript
+import csrf from 'csurf';
+app.use(csrf({ cookie: true }));
+```
+
+### 시크릿 관리
+- **금지**: `const apiKey = 'sk-1234567890';`
+- **필수**: `const apiKey = process.env.API_KEY;`
+- **권장**: `await secretManager.getSecret('api-key');`

package/templates/base/skills/security/scripts/check-secrets.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# @name check-secrets
+# @description 하드코딩된 시크릿/토큰/비밀번호를 소스코드에서 스캔
+# @args [PROJECT_ROOT] (기본: 현재 디렉토리)
+# @output text (발견된 파일:라인 목록 또는 "No secrets found")
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-.}"
+FOUND=0
+
+echo "Scanning for hardcoded secrets in: $PROJECT_ROOT"
+echo "================================================"
+
+# Pattern 1: API keys, tokens, secrets in assignments
+echo ""
+echo "## Hardcoded API Keys / Tokens"
+if grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.go" \
+  -E "(api_key|apiKey|API_KEY|secret|SECRET|token|TOKEN|password|PASSWORD)\s*[:=]\s*['\"][^'\"]{8,}" \
+  "$PROJECT_ROOT/src" "$PROJECT_ROOT/app" "$PROJECT_ROOT/lib" 2>/dev/null | \
+  grep -v "node_modules" | grep -v ".test." | grep -v "__mock__" | grep -v "example" | grep -v "placeholder"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+# Pattern 2: .env files committed
+echo ""
+echo "## Committed .env Files"
+if find "$PROJECT_ROOT" -name ".env" -o -name ".env.local" -o -name ".env.production" 2>/dev/null | \
+  grep -v "node_modules" | grep -v ".example"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+# Pattern 3: Private keys
+echo ""
+echo "## Private Keys"
+if grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.pem" --include="*.key" \
+  -l "PRIVATE KEY" "$PROJECT_ROOT" 2>/dev/null | grep -v "node_modules"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+echo ""
+echo "================================================"
+if [ "$FOUND" -eq 1 ]; then
+  echo "WARNING: Potential secrets found. Review above results."
+  exit 1
+else
+  echo "No secrets found."
+  exit 0
+fi

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

@@ -0,0 +1,63 @@
+---
+name: testing
+description: |
+  테스트 작성 규칙 및 패턴 가이드라인.
+  TDD 사이클, 테스트 피라미드, Given-When-Then 패턴, 커버리지 기준을 다룸.
+  Use when: "테스트 작성, TDD, 단위 테스트, 통합 테스트, E2E, 커버리지"
+version: "1.0.0"
+tags: [testing, tdd, quality]
+user-invocable: false
+---
+
+# Testing
+
+품질 보장을 위한 테스트 작성 가이드라인.
+
+## Philosophy
+
+- Red-Green-Refactor (TDD 사이클) 준수
+- 테스트 피라미드: Unit(다수) > Integration(중간) > E2E(소수)
+- 행동(behavior) 테스트 — 구현 디테일이 아닌 결과 검증
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | ref | [testing-patterns](references/testing-patterns.md) | Given-When-Then, Mock 가이드, 카테고리별 예시 |
+
+## Quick Rules
+
+### TDD Cycle
+1. **Red** — 실패하는 테스트 작성
+2. **Green** — 테스트를 통과하는 최소 코드 작성
+3. **Refactor** — 코드 정리 (테스트는 계속 통과)
+
+### Test Naming
+- 형식: `should {expected behavior} when {condition}`
+- Good: `should return null when user is not found`
+- Bad: `test getUser`, `works correctly`
+
+### Test Categories
+모든 테스트는 3가지 카테고리 커버:
+- **Happy Path** — 정상 흐름
+- **Edge Cases** — 경계 조건 (빈 문자열, 0, null, 최대값)
+- **Error Cases** — 오류 상황
+
+### Coverage Standards
+
+| Metric | Minimum | Recommended |
+|--------|---------|-------------|
+| Line Coverage | 80% | 90% |
+| Branch Coverage | 70% | 80% |
+| Function Coverage | 80% | 90% |
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | Given-When-Then 패턴을 따르는가 |
+| CRITICAL | Happy path, Edge case, Error case 커버하는가 |
+| HIGH | 테스트 이름이 `should...when...` 형식인가 |
+| HIGH | 커버리지 기준을 충족하는가 |
+| MEDIUM | Mock이 적절히 사용되었는가 (외부 서비스만) |
+| MEDIUM | 테스트가 독립적인가 (순서 무관) |