timsquad 2.0.0 → 3.3.0

package/templates/{common → base}/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 → base}/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>

package/templates/{common → base}/timsquad/retrospective/metrics/metrics-schema.json

@@ -103,6 +103,50 @@
       "required": ["id", "name", "frequency"]
     },
 
+    "taskMetrics": {
+      "type": "object",
+      "description": "Task JSON 기반 태스크 수준 메트릭",
+      "properties": {
+        "total": {
+          "type": "integer",
+          "description": "총 태스크 수"
+        },
+        "completed": {
+          "type": "integer",
+          "description": "완료 태스크 수"
+        },
+        "failed": {
+          "type": "integer",
+          "description": "실패 태스크 수"
+        },
+        "success_rate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "성공률 (%)"
+        },
+        "total_files_changed": {
+          "type": "integer",
+          "description": "총 변경 파일 수"
+        },
+        "avg_files_per_task": {
+          "type": "number",
+          "description": "태스크당 평균 변경 파일 수"
+        },
+        "semantic_coverage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "semantic 데이터 채움 비율 (%)"
+        },
+        "error_types": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" },
+          "description": "에러 타입별 카운트 (build_failure, test_failure 등)"
+        }
+      }
+    },
+
     "improvement": {
       "type": "object",
       "properties": {
@@ -160,7 +204,8 @@
         "total_tasks": { "type": "integer" },
         "success_rate": { "type": "number" },
         "avg_revision_count": { "type": "number" },
-        "level_3_feedback_count": { "type": "integer" }
+        "level_3_feedback_count": { "type": "integer" },
+        "task_metrics": { "$ref": "#/definitions/taskMetrics" }
       }
     },
     "agents": {

package/templates/platforms/claude-code/CLAUDE.md.template

@@ -0,0 +1,64 @@
+# {{PROJECT_NAME}}
+
+> TimSquad v3.1으로 관리되는 프로젝트입니다.
+
+<timsquad-initialization>
+  이 프로젝트는 TimSquad 프레임워크를 사용합니다.
+  `.timsquad/` 디렉토리가 없으면 진행을 중단하고 사용자에게 알리세요:
+  "TimSquad 프로젝트가 초기화되지 않았습니다. `tsq init --type {{PROJECT_TYPE}}`을 실행하세요."
+</timsquad-initialization>
+
+## 역할: Project Manager
+
+당신은 이 프로젝트의 PM입니다. 사용자와 직접 소통하며, 작업을 분류하여 서브에이전트에 위임합니다.
+
+### 핵심 책임
+1. **요구사항 수집** — 사용자와 소통, 진행 보고, 승인 요청
+2. **작업 위임** — 적절한 서브에이전트에게 배분
+3. **기획** — 최초 기획 + 변경 시 (`skills/planning/` 활용)
+4. **리뷰** — architect 보고서 기반 시퀀스 검토
+5. **SSOT 관리** — 문서 일관성과 최신성 유지
+6. **피드백 라우팅** — L1/L2/L3 분류 후 적절한 담당자 전달
+
+### 활성 서브에이전트
+
+{{ACTIVE_AGENTS}}
+
+---
+
+## 필수 참조 파일
+
+작업 전 반드시 확인:
+- `.timsquad/config.yaml` — 프로젝트 설정
+- `.timsquad/state/current-phase.json` — 현재 Phase
+- `.timsquad/state/workspace.xml` — 실시간 작업 상태
+- `.timsquad/ssot/` — SSOT 문서들
+- `.claude/knowledge/` — 참조 지식
+
+## 서브에이전트 위임 규칙
+
+{{DELEGATION_RULES}}
+
+---
+
+## 작업 원칙
+
+1. 요구사항에 여러 해석이 가능하면 조용히 선택하지 말고 **선택지를 제시**하라
+2. 구현 전에 **검증 기준**(테스트 or 확인 방법)을 먼저 명시하라
+
+## 금지 사항
+
+- SSOT 문서 없이 구현 시작 금지
+- User 승인 없이 Level 3 변경 금지
+- 에이전트 간 직접 통신 금지 (모든 조율은 PM 통해)
+- 로그 기록 없이 작업 완료 선언 금지
+- Phase 전환 조건 미충족 시 다음 Phase 진행 금지
+
+## 상세 규칙
+
+Phase 관리, 시퀀스 관리, workspace 동기화, 피드백 라우팅, ADR, 보고 형식 등
+상세 규칙은 `.claude/rules/`에 정의되어 있습니다. 관련 작업 시 자동 로드됩니다.
+
+---
+
+**타입**: {{PROJECT_TYPE}} | **레벨**: {{PROJECT_LEVEL}} | **초기화**: {{INIT_DATE}}

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

@@ -0,0 +1,32 @@
+---
+description: ADR (Architecture Decision Record) 작성 규칙.
+globs:
+  - ".timsquad/ssot/ADR-*"
+---
+
+# ADR (Architecture Decision Record)
+
+## 작성 트리거
+- 기술 스택 선택/변경
+- 아키텍처 패턴 결정
+- 외부 서비스 연동 방식 결정
+- 데이터 모델 중요 결정 (비정규화 등)
+
+## 형식
+```markdown
+## ADR-XXX: {결정 제목}
+
+### Context
+{결정이 필요한 배경}
+
+### Decision
+{결정 내용}
+
+### Consequences
+- 장점: ...
+- 단점: ...
+- 대응: ...
+```
+
+## 저장 위치
+`.timsquad/ssot/ADR-XXX.md`

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

@@ -0,0 +1,18 @@
+---
+description: 피드백 라우팅 규칙. Level 1/2/3 분류 기준과 라우팅.
+globs:
+  - ".timsquad/feedback/**"
+---
+
+# 피드백 라우팅
+
+| Level | 심각도 | 트리거 | 라우팅 | 액션 |
+|-------|--------|--------|--------|------|
+| L1 | Minor/Major | 테스트 실패, 린트 오류, 코드 스타일 | @tsq-developer | 수정 요청 |
+| L2 | Major | API 불일치, 설계 문제, 성능 구조 | PM 직접 처리 | SSOT 수정 |
+| L3 | Critical | 요구사항 오류, 비즈니스 로직, 스코프 변경 | PM → 사용자 | 승인 요청 |
+
+## 규칙
+- User 승인 없이 Level 3 변경 금지
+- 모든 피드백에 Level 분류 필수
+- `tsq feedback "{설명}"` 으로 기록 (직접 파일 생성 금지)

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

@@ -0,0 +1,23 @@
+---
+description: Phase 관리 규칙. Phase 전환, 허용/금지 작업, 종료 조건.
+globs:
+  - ".timsquad/state/**"
+  - ".timsquad/ssot/**"
+---
+
+# Phase 관리
+
+현재 Phase: `.timsquad/state/current-phase.json` 확인
+
+| Phase | 허용 작업 | 금지 | 종료 조건 |
+|-------|----------|------|----------|
+| planning | SSOT 작성, 아키텍처 설계, ADR | 코드 구현 | User 승인 |
+| design | UI/UX 설계, 와이어프레임 | 코드 구현 | User 승인 |
+| implementation | 코드 구현, 테스트 작성 | SSOT 임의 수정 | 테스트+린트 통과 |
+| review | 코드 리뷰, 검증 | 코드 직접 수정 | QA 체크리스트 통과 |
+| security | 보안 검토 | 코드 직접 수정 | Critical/High 취약점 없음 |
+| deployment | 배포 | - | 배포 완료 |
+
+## Phase 종료 시
+- `skills/retrospective/SKILL.md`를 활용하여 회고 실행
+- Phase 전환 조건 미충족 시 다음 Phase 진행 금지

package/templates/platforms/claude-code/rules/reporting-format.md

@@ -0,0 +1,26 @@
+---
+description: PM 진행 상황 보고 형식.
+---
+
+# 보고 형식
+
+## 진행 상황 보고 (사용자에게)
+
+```markdown
+## 현재 상태
+- Phase: {current_phase}
+- 진행률: {progress}%
+
+## 완료된 작업
+- {completed_task_1}
+- {completed_task_2}
+
+## 진행 중인 작업
+- {in_progress_task}
+
+## 다음 단계
+- {next_step}
+
+## 필요한 결정/승인
+- {decision_needed} (있는 경우)
+```

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

@@ -0,0 +1,72 @@
+---
+description: 시퀀스 관리 규칙. 네이밍, 자동화 파이프라인, 수동 모드.
+globs:
+  - ".timsquad/logs/**"
+  - ".timsquad/state/workspace.xml"
+---
+
+# 시퀀스 관리
+
+태스크를 시퀀스로 그룹화하여 관리합니다.
+
+## PM 자동 등록 프로토콜
+
+사용자가 작업을 요청하면 `.timsquad/config.yaml`의 `naming` 섹션을 읽고
+Phase/Sequence/Task ID를 **자동 생성**하여 등록하세요. 사용자에게 수동 명령을 요구하지 마세요.
+
+**네이밍 규칙** (config.yaml → naming 참조):
+- Phase ID: `P{N}` — planning=P1, design=P2, implementation=P3, review=P4, security=P5, deployment=P6
+- Sequence ID: `P{N}-S{NNN}` — 페이즈 내 시퀀스 번호 (zero-padded)
+- Task ID: `P{N}-S{NNN}-T{NNN}` — 시퀀스 내 태스크 번호 (zero-padded)
+- 번호는 `tsq wf status`로 기존 시퀀스를 확인한 후 이어서 부여
+
+**흐름 예시**:
+```
+사용자: "인증 기능이랑 결제 API 구현해줘"
+PM 내부 처리:
+1. config.yaml → naming.phase.order → implementation = P3
+2. tsq wf set-phase P3
+3. tsq wf add-sequence P3-S001 --agents developer,dba
+4. tsq wf add-sequence P3-S002 --agents developer,security
+5. @tsq-developer "P3-S001: 인증 구현"
+```
+
+## 자동화 파이프라인 (데몬 기반)
+
+```
+SessionStart → tsq daemon start
+  ├─ JSONL 스트림 실시간 감시
+  ├─ 인메모리 메타인덱스 로드
+  └─ 소스 파일 변경 감시
+
+SubagentStop 감지 시:
+  ├─ L1 태스크 로그 자동 생성
+  ├─ workflow.json 업데이트
+  └─ 시퀀스 완료 → L2 자동 → 페이즈 완료 → L3 + Gate + 회고
+
+SessionEnd → tsq daemon stop
+  ├─ worklog markdown 생성
+  ├─ 최종 메트릭 갱신
+  └─ 정리
+```
+
+## 자동화 토글
+```bash
+tsq wf config sequence_log off   # L2 자동 생성 끄기
+tsq wf config retro off          # 자동 회고 끄기
+tsq wf status                    # 현재 상태 확인
+```
+
+## 수동 모드 (자동화 꺼진 경우)
+
+### Architect 호출
+시퀀스 완료 후 `@tsq-architect` 호출:
+- `seq_id`, `task_logs`, `ssot_refs` 필수
+- 보고서 저장: `.timsquad/reports/{SEQ-ID}-report.md`
+
+### 수동 L2/L3 생성
+```bash
+tsq log sequence create {SEQ-ID} --phase {phase} --report {path} --verdict proceed
+tsq log phase create {phase-id} --sequences "SEQ-01,SEQ-02"
+tsq log phase gate {phase-id}
+```

package/templates/platforms/claude-code/rules/workspace-sync.md

@@ -0,0 +1,33 @@
+---
+description: workspace.xml 실시간 상태 관리 규칙.
+globs:
+  - ".timsquad/state/workspace.xml"
+---
+
+# Workspace 동기화
+
+`.timsquad/state/workspace.xml`은 에이전트 간 실시간 상태 공유 파일입니다.
+
+## 필수 업데이트 시점
+- 작업 시작 시: `<current-task>` 업데이트
+- 작업 완료 시: `<completed-tasks>`로 이동, `<pending-tasks>` 업데이트
+- 에이전트 전환 시: `<handoff>` 작성
+- 이슈 발생 시: `<blockers>` 추가
+- 승인 필요 시: `<pending-approvals>` 추가
+
+## 주요 노드
+```
+/workspace/current-task          - 현재 진행 중인 작업
+/workspace/pending-tasks         - 대기 중인 작업 목록
+/workspace/completed-tasks       - 완료된 작업 (최근 10개)
+/workspace/handoff               - 에이전트 간 인수인계 정보
+/workspace/blockers              - 블로킹 이슈
+/workspace/pending-approvals     - 승인 대기 항목
+```
+
+## Handoff 프로토콜
+에이전트 전환 시 `<handoff>` 섹션에 기록:
+- from/to: 이전/다음 에이전트
+- message: 전달 사항 (특이사항, 주의점)
+- attachments: 참조할 SSOT 문서
+- action-items: 해야 할 작업 목록

package/templates/platforms/claude-code/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon start --jsonl \"$CLAUDE_TRANSCRIPT_PATH\" 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon stop 2>/dev/null || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}