timsquad 2.0.0 → 2.1.0

package/templates/common/claude/settings.json

@@ -0,0 +1,86 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/event-logger.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/common/config.template.yaml

@@ -6,8 +6,9 @@
 # ============================================================
 project:
   name: my-project
-  type: web-service      # web-service | api-backend | platform | fintech | infra
+  type: web-service      # web-service | web-app | api-backend | platform | fintech | infra
   level: 2               # 1=MVP | 2=Standard | 3=Enterprise
+  architecture: traditional  # traditional | baas | microservices
   description: ""
 
 # ============================================================

package/templates/common/timsquad/process/phase-checklist.yaml

@@ -0,0 +1,174 @@
+# TimSquad Phase 전환 체크리스트
+# 각 Phase 전환 시 반드시 확인해야 할 항목
+# 에이전트는 이 체크리스트를 모두 통과해야 다음 Phase로 진행 가능
+
+version: "1.0"
+
+# ============================================================
+# Planning → Implementation
+# ============================================================
+planning_to_implementation:
+  description: "기획/설계 완료 → 구현 시작"
+  checklist:
+    # SSOT 문서 완성 확인
+    - id: ssot-complete
+      check: "필수 SSOT 문서가 모두 작성되었는가?"
+      required: true
+      validation:
+        - "prd.md 존재 및 내용 작성됨"
+        - "requirements.md 존재 및 내용 작성됨"
+        - "service-spec.md 존재 및 내용 작성됨"
+        - "프로젝트 타입별 필수 문서 확인 (REQUIRED_SSOT_BY_TYPE)"
+        - "프로젝트 레벨별 필수 문서 확인 (REQUIRED_SSOT_BY_LEVEL)"
+
+    # workspace.xml 동기화 확인
+    - id: workspace-synced
+      check: "workspace.xml이 최신 상태인가?"
+      required: true
+      validation:
+        - "모든 Planning TASK가 completed-tasks에 존재"
+        - "pending-tasks에 미완료 Planning 작업 없음"
+        - "current-task가 비어있거나 Implementation 첫 TASK"
+
+    # Handoff 작성 확인
+    - id: handoff-written
+      check: "workspace.xml의 handoff 섹션이 작성되었는가?"
+      required: true
+      validation:
+        - "from: tsq-planner"
+        - "to: tsq-developer"
+        - "message: 인수인계 내용 작성됨"
+        - "attachments: 참조할 SSOT 문서 목록"
+        - "action-items: 구현 우선순위 목록"
+
+    # 사용자 승인
+    - id: user-approval
+      check: "사용자가 구현 진행을 승인했는가?"
+      required: true
+      validation:
+        - "pending-approvals에 승인 요청 기록"
+        - "사용자 승인 응답 수신"
+
+  on_failure:
+    - "미완료 항목 목록 표시"
+    - "Phase 전환 차단"
+    - "누락된 문서 작성 안내"
+
+# ============================================================
+# Implementation → Review
+# ============================================================
+implementation_to_review:
+  description: "구현 완료 → 검증 시작"
+  checklist:
+    - id: tests-pass
+      check: "모든 테스트가 통과하는가?"
+      required: true
+      validation:
+        - "npm run test 성공"
+        - "커버리지 최소 기준 충족 (L1: 60%, L2: 80%, L3: 90%)"
+
+    - id: no-lint-errors
+      check: "린트 에러가 없는가?"
+      required: true
+      validation:
+        - "npm run lint 성공"
+
+    - id: no-type-errors
+      check: "타입 에러가 없는가?"
+      required: true
+      validation:
+        - "npm run type-check 성공"
+
+    - id: work-log
+      check: "작업 로그가 기록되었는가?"
+      required: true
+      validation:
+        - ".timsquad/logs/ 에 최신 로그 존재"
+
+    - id: workspace-synced
+      check: "workspace.xml이 최신 상태인가?"
+      required: true
+      validation:
+        - "모든 Implementation TASK가 completed-tasks에 존재"
+        - "구현 결과 output 기록됨"
+
+  on_failure:
+    - "실패 항목 상세 표시"
+    - "Phase 전환 차단"
+    - "수정 필요 항목 안내"
+
+# ============================================================
+# Review → Security (Level 3 / fintech 필수)
+# ============================================================
+review_to_security:
+  description: "검증 완료 → 보안 검토"
+  required_for: ["level-3", "fintech"]
+  optional_for: ["level-1", "level-2"]
+  checklist:
+    - id: no-critical-issues
+      check: "Critical/Major 이슈가 모두 해결되었는가?"
+      required: true
+
+    - id: qa-checklist
+      check: "QA 체크리스트를 모두 통과했는가?"
+      required: true
+
+    - id: feedback-resolved
+      check: "미해결 피드백이 없는가?"
+      required: true
+      validation:
+        - "feedback-queue에 pending 항목 없음"
+
+# ============================================================
+# Review → Complete (보안 생략 시, Level 1/2만)
+# ============================================================
+review_to_complete:
+  description: "검증 완료 → 완료 (보안 생략)"
+  allowed_for: ["level-1", "level-2"]
+  forbidden_for: ["level-3", "fintech"]
+  checklist:
+    - id: no-critical-issues
+      check: "Critical/Major 이슈가 모두 해결되었는가?"
+      required: true
+
+    - id: qa-checklist
+      check: "QA 체크리스트를 모두 통과했는가?"
+      required: true
+
+# ============================================================
+# Security → Complete
+# ============================================================
+security_to_complete:
+  description: "보안 검토 완료 → 완료"
+  checklist:
+    - id: no-critical-vuln
+      check: "Critical 취약점이 없는가?"
+      required: true
+
+    - id: high-vuln-resolved
+      check: "High 취약점이 모두 해결되었는가?"
+      required: true
+
+    - id: user-approval
+      check: "사용자 승인을 받았는가? (Level 3 / fintech)"
+      required_for: ["level-3", "fintech"]
+
+# ============================================================
+# 공통 규칙
+# ============================================================
+common_rules:
+  # 체크리스트 미통과 시 행동
+  on_checklist_failure:
+    action: block_transition
+    message: "Phase 전환 조건이 충족되지 않았습니다."
+    show: "미충족 항목 목록"
+
+  # workspace.xml 업데이트는 모든 전환의 공통 조건
+  workspace_sync:
+    required: true
+    description: "모든 Phase 전환 시 workspace.xml이 최신 상태여야 합니다."
+
+  # 로그 기록은 모든 전환의 공통 조건
+  logging:
+    required: true
+    description: "Phase 전환 시 전환 사유와 결과를 로그에 기록합니다."

package/templates/common/timsquad/process/state-machine.xml

@@ -109,6 +109,12 @@
         <condition type="required">
           <check>service-spec.md 존재</check>
         </condition>
+        <condition type="required">
+          <check>workspace.xml 동기화 완료 (모든 Planning TASK가 completed-tasks에 존재)</check>
+        </condition>
+        <condition type="required">
+          <check>workspace.xml handoff 섹션 작성 완료</check>
+        </condition>
         <condition type="required">
           <check>User 승인 완료</check>
         </condition>
@@ -116,6 +122,7 @@
 
       <on-transition>
         <action>상태 파일 업데이트</action>
+        <action>workspace.xml active-session을 tsq-developer로 변경</action>
         <action>Planning Phase 완료 로그 기록</action>
         <notification>User에게 구현 시작 알림</notification>
       </on-transition>
@@ -123,6 +130,7 @@
       <on-failure>
         <action>차단 사유 표시</action>
         <suggestion>누락된 SSOT 문서 작성 필요</suggestion>
+        <suggestion>workspace.xml 동기화 필요</suggestion>
       </on-failure>
     </transition>
 
@@ -149,10 +157,14 @@
         <condition type="required">
           <check>작업 로그 기록 완료</check>
         </condition>
+        <condition type="required">
+          <check>workspace.xml 동기화 완료 (모든 Implementation TASK가 completed-tasks에 존재)</check>
+        </condition>
       </conditions>
 
       <on-transition>
         <action>상태 파일 업데이트</action>
+        <action>workspace.xml active-session을 tsq-qa로 변경</action>
         <action>QA 에이전트에게 리뷰 요청 전달</action>
       </on-transition>
     </transition>

package/templates/common/timsquad/process/workflow-base.xml

@@ -165,8 +165,132 @@
     <rule id="mandatory-logging">
       모든 작업은 로그 기록 필수. 미기록 시 작업 미완료로 간주.
     </rule>
+    <rule id="mandatory-workspace-sync">
+      모든 TASK 완료 시 workspace.xml 업데이트 필수. 미동기화 시 작업 미완료로 간주.
+    </rule>
+    <rule id="phase-checklist">
+      Phase 전환 시 phase-checklist.yaml의 해당 체크리스트를 모두 통과해야 함.
+    </rule>
   </global-rules>
 
+  <!-- 에이전트 위임 실패 폴백 전략 -->
+  <agent-fallback-strategy>
+    <description>
+      서브에이전트 실행 실패 시 (Bash 권한 거부, 환경 미설정 등) 자동 폴백 전략.
+      역할 분리 원칙을 최대한 유지하되, 프로세스 중단을 방지.
+    </description>
+
+    <fallback-chain>
+      <step id="1" action="retry">
+        <description>동일 에이전트로 1회 재시도</description>
+        <max-retries>1</max-retries>
+        <wait>5s</wait>
+      </step>
+      <step id="2" action="fallback-agent">
+        <description>폴백 에이전트로 위임 (workflow에 정의된 fallback)</description>
+        <example>tsq-frontend 실패 → tsq-developer로 폴백</example>
+        <example>tsq-dba 실패 → tsq-planner(architect)로 폴백</example>
+      </step>
+      <step id="3" action="pm-direct">
+        <description>PM(현재 에이전트)이 직접 처리</description>
+        <conditions>
+          <condition>폴백 에이전트도 실패한 경우</condition>
+          <condition>환경 자체 문제 (권한, 의존성 미설치)</condition>
+        </conditions>
+        <logging>
+          역할 분리 원칙 위반 사유를 로그에 기록.
+          회고 시 개선 대상으로 플래그.
+        </logging>
+      </step>
+      <step id="4" action="user-notify">
+        <description>모든 폴백 실패 시 사용자에게 알림</description>
+        <message>에이전트 실행 환경 문제 보고. 수동 개입 요청.</message>
+      </step>
+    </fallback-chain>
+
+    <!-- 환경 사전 요구사항 -->
+    <environment-prerequisites>
+      <instruction>
+        .timsquad/knowledge/setup.md에 프로젝트 환경 요구사항을 문서화하세요.
+        에이전트 실행 전 이 파일을 확인하여 누락된 의존성을 사전 설치합니다.
+      </instruction>
+      <common-requirements>
+        <requirement>Node.js 18+</requirement>
+        <requirement>패키지 매니저 (npm/pnpm/bun)</requirement>
+        <requirement>corepack enable (pnpm 사용 시)</requirement>
+      </common-requirements>
+    </environment-prerequisites>
+  </agent-fallback-strategy>
+
+  <!-- 대용량 문서 분할 가이드 -->
+  <large-document-guide>
+    <description>
+      1,000 lines 이상 예상되는 SSOT 문서는 토큰 초과를 방지하기 위해 분할 작성합니다.
+    </description>
+    <rules>
+      <rule id="split-threshold">
+        단일 문서가 800 lines 이상 예상되면 섹션별 분할 작성
+      </rule>
+      <rule id="domain-split">
+        도메인별 분리: 예) functional-spec.md → FS-AUTH.md, FS-MATCH.md, FS-PAYMENT.md
+      </rule>
+      <rule id="sequential-append">
+        분할 문서는 순차 append 방식으로 작성 (한 번에 전체 작성 금지)
+      </rule>
+      <rule id="index-file">
+        분할된 문서들의 인덱스 파일 유지 (예: functional-spec.md에 각 분할 파일 링크)
+      </rule>
+    </rules>
+    <split-patterns>
+      <pattern document="functional-spec.md">
+        <split-by>도메인 (인증, 매칭, 결제 등)</split-by>
+        <naming>FS-{DOMAIN}.md (예: FS-AUTH.md)</naming>
+      </pattern>
+      <pattern document="service-spec.md">
+        <split-by>API 그룹 (auth, users, resources 등)</split-by>
+        <naming>API-{GROUP}.md (예: API-AUTH.md)</naming>
+      </pattern>
+      <pattern document="data-design.md">
+        <split-by>도메인 (사용자, 매칭, 트랜잭션 등)</split-by>
+        <naming>DD-{DOMAIN}.md (예: DD-USERS.md)</naming>
+      </pattern>
+    </split-patterns>
+  </large-document-guide>
+
+  <!-- SSOT 교차 검증 규칙 -->
+  <ssot-cross-validation>
+    <description>
+      SSOT 문서 간 일관성을 검증하는 규칙.
+      에이전트(특히 tsq-qa)가 검증 시 적용.
+    </description>
+    <rules>
+      <rule id="fr-id-consistency">
+        <check>requirements.md의 FR-XXX ID가 functional-spec.md에서 참조됨</check>
+        <severity>Major</severity>
+      </rule>
+      <rule id="api-endpoint-match">
+        <check>service-spec.md의 API 엔드포인트가 구현 코드와 일치</check>
+        <severity>Critical</severity>
+      </rule>
+      <rule id="error-code-match">
+        <check>error-codes.md의 에러 코드가 구현 코드에서 올바르게 사용됨</check>
+        <severity>Major</severity>
+      </rule>
+      <rule id="data-model-match">
+        <check>data-design.md의 테이블/필드가 실제 스키마(마이그레이션)와 일치</check>
+        <severity>Critical</severity>
+      </rule>
+      <rule id="glossary-consistency">
+        <check>glossary.md의 용어가 모든 SSOT 문서에서 일관되게 사용됨</check>
+        <severity>Minor</severity>
+      </rule>
+      <rule id="req-to-test-traceability">
+        <check>requirements.md의 각 FR이 test-spec.md에서 테스트 케이스로 매핑됨</check>
+        <severity>Major</severity>
+      </rule>
+    </rules>
+  </ssot-cross-validation>
+
   <!-- User 승인 필요 지점 -->
   <user-checkpoints>
     <checkpoint phase="planning" event="SSOT 완료">User 승인 필요</checkpoint>