[RELEASE] v0.0.1

.agents/skills/api/timo-api-integration/SKILL.md

@@ -0,0 +1,77 @@
+# timo-api-integration
+
+## 트리거
+
+- "API 연동해줘 / 연동 세팅하자"
+- "orval / 제너레이터 나온 거 붙여줘"
+- mock 데이터를 실제 API 호출로 교체하는 작업
+
+## 참조
+
+- `docs/architecture/state.md` → 서버 상태는 React Query가 단일 출처
+- `docs/architecture/structure.md` → `_queries/` 위치 규칙
+- `apps/timo-web/api/generated/` → orval이 생성한 훅·zod 스키마·모델 (직접 수정 금지)
+- `apps/timo-web/api/client/custom-instance.ts`, `apps/timo-web/api/client/axios.ts` → axios 인스턴스, 에러 인터셉터
+- `apps/timo-web/api/error/api-error.ts` → `ApiError`, `parseApiError`
+
+## 배경
+
+- `api/generated/endpoints/{domain}/{domain}.ts` — orval이 생성한 react-query 훅(`useGetXxx`)과 순수 fetcher 함수, `queryKey` 헬퍼, `getXxxQueryOptions` 팩토리
+- `logout`/`withdraw`/`deleteTodo`/`deleteTag`/`completeOnboarding`처럼 실제로 반환 데이터가 없는 엔드포인트는 백엔드가 `data`를 Java `Object`(빈 스키마)로 선언해서 여전히 `data: zod.unknown().optional()`로 생성된다 — 이건 버그가 아니라 정상이다(정말로 shape이 없는 값이므로).
+- `api/generated/models/*.ts` — 응답 DTO 타입. 실제로 항상 오는 필드는 이제 `?` 없이 생성된다. 다만 gen 스키마는 백엔드가 스펙을 바꿀 때마다 사람 리뷰 없이 재생성되므로 100% 맹신하지는 않는다.
+- 그래도 도메인 로컬 zod 스키마(`app/(domain)/_types/*.ts`)로 한 번 더 검증한다 — 로컬 스키마의 `.parse()`가 "백엔드가 계약을 조용히 느슨하게 바꿨는지"를 잡아내는 방어선 역할을 한다. 로컬 스키마 작성 시 gen 응답 스키마를 기반 초안으로 그대로 가져다 쓰고, UI가 추가로 좁혀야 하는 부분(더 좁은 enum, 파생 필드 등)만 수정한다.
+
+## 워크플로우
+
+### Phase 1 — 대상 엔드포인트 확인
+
+- `/v3/api-docs`에서 대상 성공 응답의 `application/json` content type과 필드별 `required`를 확인한다.
+- 확인 결과를 반영하도록 `pnpm gen:api`를 실행한 뒤 생성된 모델·Zod 스키마를 검토한다.
+- `api/generated/endpoints/{domain}/{domain}.ts`에서 필요한 fetcher 함수(예: `getHome`)와 `getGetXxxQueryKey` 헬퍼를 찾는다.
+- 응답이 `BaseResponseXxx { status, message, data }` 형태로 감싸져 있는지 `api/generated/models/`에서 확인한다 — 실제 필요한 값은 `.data`에 있다.
+
+### Phase 2 — 로컬 zod 스키마로 응답 검증
+
+- 도메인 `_types/*.ts`에 이미 손으로 작성한 zod 스키마가 있는지 확인한다. 없으면 생성된 응답 zod 스키마(`api/generated/endpoints/{domain}/{domain}.zod.ts`)를 기반 초안으로 가져와 작성한다 — 이제 실제 shape을 담고 있으므로 신뢰할 수 있다.
+- gen 스키마와 UI가 실제로 필요로 하는 shape이 다르면(더 좁은 enum, 파생 필드 등) 로컬 스키마에서 추가로 좁힌다.
+- `select`에서 로컬 스키마의 `.parse()`/`.safeParse()`로 최종 검증한다 — gen 스키마를 UI까지 직접 노출하지 않고 반드시 로컬 스키마를 한 번 거친다. 백엔드가 스펙을 다시 느슨하게 바꿔도 이 단계가 조용히 깨지지 않고 파싱 실패로 드러나게 하는 방어선이다.
+
+### Phase 3 — `_queries/` 훅 작성
+
+- 위치: `app/(domain)/_queries/use-xxx.ts`
+- `useSuspenseQuery`를 쓸지 `useQuery`를 쓸지는 컴포넌트가 `AsyncBoundary`(Suspense) 안에 있는지로 결정한다. `AsyncBoundary`로 감싸져 있으면 `useSuspenseQuery`를 쓴다.
+- **주의**: 생성된 `getGetXxxQueryOptions()` 팩토리를 그대로 `useSuspenseQuery`에 스프레드하면 `UseQueryOptions`가 허용하는 `skipToken`과 `UseSuspenseQueryOptions`가 타입 충돌을 일으킨다. `queryKey`/`queryFn`은 생성된 `getGetXxxQueryKey` + 원본 fetcher 함수로 직접 조립한다.
+- `select`에서 `BaseResponse.data`를 언랩하고 로컬 zod 스키마로 `.parse()`해서 반환한다.
+
+```ts
+"use client";
+
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import {
+  getGetHomeQueryKey,
+  getHome,
+} from "@/api/generated/endpoints/home/home";
+import { homeViewDataSchema } from "@/app/[locale]/(main)/(with-time-sidebar)/home/_types/home-view-type";
+
+export const useHomeView = ({ filter, baseDate }: GetHomeViewParams) =>
+  useSuspenseQuery({
+    queryKey: getGetHomeQueryKey({ filter, baseDate }),
+    queryFn: ({ signal }) => getHome({ filter, baseDate }, undefined, signal),
+    select: ({ data }) => homeViewDataSchema.parse(data),
+  });
+```
+
+### Phase 4 — 컨테이너 연결
+
+- mock 함수 import를 제거하고 새 훅으로 교체한다.
+- 다른 도메인이 같은 mock을 참조하고 있는지 확인(`Grep`)하고, 참조 중이면 mock 파일 자체는 지우지 않는다.
+- 로그인 연동 전이라 요청이 401/네트워크 에러로 실패할 수 있다 — `useSuspenseQuery`가 던지는 에러는 상위 `error.tsx`(라우트 레벨) 또는 `AsyncBoundary`의 `errorFallback`이 잡는지 확인한다. 둘 다 없으면 최소한 라우트 레벨 `error.tsx` 존재 여부를 확인해 화면이 완전히 깨지지 않게 한다.
+
+### Phase 5 — 자가 검토
+
+- [ ] `api/generated/` 내부 파일을 직접 수정하지 않았는가 (재생성 시 사라짐)
+- [ ] 응답을 로컬 zod 스키마로 `.parse()`해서 검증했는가 (gen 응답 스키마를 그대로 UI까지 노출하지 않았는가)
+- [ ] `useSuspenseQuery` 사용 시 `queryKey`/`queryFn`을 직접 조립해 타입 충돌을 피했는가
+- [ ] `tsc --noEmit`, `eslint` 통과
+- [ ] 다른 도메인이 참조하는 mock을 실수로 지우지 않았는가

.agents/skills/git/timo-commit/SKILL.md

@@ -1 +1,81 @@
-<!-- diff를 읽어 기능 단위로 커밋을 분해하고 메시지를 작성한다 -->
+# timo-commit
+
+## 트리거
+
+- "커밋해줘", "커밋 만들어줘", "commit"
+- "staged 변경 정리해줘", "변경사항 나눠줘"
+
+## 참조
+
+- `docs/conventions/commit.md` → 커밋 타입·스코프·형식·규칙
+
+## 핵심 원칙
+
+1. **secret guard 먼저**: `.env`, 비밀번호, API 키, 토큰이 스테이징되어 있으면 즉시 멈추고 알린다.
+2. **atomic 단위 분리**: 논리적으로 무관한 변경은 별도 커밋으로 나눈다.
+3. **2단계 진행**: Phase 1(계획표 출력 → 승인) → Phase 2(실행). 승인 없이 커밋하지 않는다.
+4. **push는 명시적 요청 시에만**: 커밋까지만 하고, push는 사용자가 동의하면 수행한다.
+
+---
+
+## Phase 1 — 분석 및 계획 수립
+
+1. `git status`와 `git diff --cached`로 스테이징된 변경 확인.
+2. **secret guard**: `.env`, `password`, `api_key`, `secret`, `token` 패턴 검색 — 발견 시 즉시 중단.
+3. 변경된 파일들을 도메인/기능/계층 단위로 커밋 그룹 분류.
+4. 아래 형식의 계획표를 출력하고 **사용자 승인 대기**.
+
+### 계획표 출력 형식
+
+```
+## 커밋 계획
+
+### 커밋 1: feat(web): 소셜 로그인 컴포넌트 추가 (#5)
+- apps/timo-web/src/components/SocialLogin/index.tsx
+- 소셜 로그인 UI 컴포넌트를 추가했습니다
+
+### 커밋 2: chore(root): turbo filter 스크립트 추가
+- package.json
+- dev:web, build:web 등 필터 스크립트를 추가했습니다
+
+계속 진행할까요?
+```
+
+---
+
+## Phase 2 — 커밋 실행
+
+승인 후 각 그룹별 `git add <파일>` → `git commit -m` 순으로 실행한다.  
+완료 후 `git log --oneline -n <커밋 수>`로 결과 요약 출력.
+
+---
+
+## 계층별 분리 원칙
+
+같은 기능이라도 계층이 다르면 **별도 커밋**으로 분리한다:
+
+1. **의존성 변경**: `package.json`, `pnpm-lock.yaml` → `chore`
+2. **핵심 구현**: 컴포넌트, 훅, 유틸리티 → `feat` / `fix` / `refactor`
+3. **설정/라우팅**: 라우트 등록, 설정 파일 → `chore` / `feat`
+
+---
+
+## 커밋 메시지 형식
+
+→ `docs/conventions/commit.md` 참조 (타입 목록·스코프 기준·형식·규칙)
+
+핵심 요약:
+
+- 형식: `타입(스코프): 한국어 제목 (#이슈번호)`
+- 본문: 반드시 `~했습니다` 체로 종결
+- 대괄호 스코프 금지: `feat: [web] …` ❌
+- 이슈 번호 모르면 사용자에게 확인
+
+---
+
+## 금지
+
+- `--no-verify` 플래그 사용 금지 (사용자가 요청해도 이유를 먼저 묻는다)
+- 스테이징되지 않은 파일을 임의로 `git add` 하지 않는다
+- `.env`, 인증서, 토큰 파일을 커밋에 포함하지 않는다
+- 승인 없이 커밋을 실행하지 않는다

.agents/skills/git/timo-issue/SKILL.md

@@ -1 +1,165 @@
-<!-- 요청을 받아 재현 조건·수용 기준이 포함된 GitHub 이슈를 작성한다 -->
+# timo-issue
+
+## 트리거
+
+다음 요청이 오면 이 스킬을 사용한다:
+
+- "이슈 만들어줘", "이슈 올려줘", "이슈 써줘"
+- 새 기능 개발 또는 버그 수정 시작 전
+
+인자 없이 실행하면 현재 대화 컨텍스트에서 작업 내용을 자동으로 추론한다.
+
+---
+
+## 이슈 타입
+
+→ `docs/conventions/issue-pr.md` 참조 (TYPE 목록·형식·규칙)
+
+PREFIX는 `[FEAT]`, `[FIX]`, `[CI]` 등 작업 성격에 따라 대문자로 자유롭게 지정한다.
+
+---
+
+## 이슈 본문 템플릿
+
+### Feature Request — feat / refactor / ui / style / docs / chore / ci / perf / init
+
+`.github/ISSUE_TEMPLATE/feature_request.md` 기반:
+
+```markdown
+### 🛠️ 만들고자 한 기능 설명
+
+{작업 목적과 내용을 2-3문장으로 서술}
+
+### ✅ TODO LIST
+
+- [ ] {세부 작업 1}
+- [ ] {세부 작업 2}
+
+### ⏰ 예상 작업 기간
+
+{컨텍스트 기반 예상 기간, 모르면 "-"}
+
+### 📝 참고 링크(선택)
+
+### 🗣️ ETC(선택)
+
+### 📸 피그마 스크린샷
+```
+
+### Bug Report — fix
+
+`.github/ISSUE_TEMPLATE/bug_report.md` 기반:
+
+```markdown
+## 어떤 버그인가요?
+
+{버그를 간결하게 설명}
+
+<br><br>
+
+## 어떤 상황에서 발생한 버그인가요?
+
+- **Given**: {사전 조건}
+- **When**: {어떤 행동을 했을 때}
+- **Then**: {어떤 문제가 발생했는지}
+
+<br><br>
+
+## 예상 결과
+
+{정상적으로 동작했어야 할 결과}
+
+<br><br>
+
+## 참고자료
+
+{관련 스크린샷, 에러 로그 등 — 없으면 생략}
+```
+
+---
+
+## 브랜치 네이밍 컨벤션
+
+→ `docs/conventions/branch.md` 참조 (구조·타입·형식·규칙)
+
+```
+{type}/{scope}/{이슈번호}-{kebab-case-영어설명}
+
+feat/web/5-social-login
+fix/web/7-redirect-error
+refactor/ui/12-button-cleanup
+chore/root/15-turbo-filter-scripts
+```
+
+---
+
+## 워크플로우
+
+### Phase 1 — 분석 및 계획 수립
+
+1. 인자에서 타입과 설명 파싱. 없으면 현재 대화 컨텍스트에서 추론.
+2. 타입에 맞는 템플릿 선택 후 내용 채우기.
+3. `git config user.name`으로 작성자 확인.
+4. 계획표 출력 후 **사용자 승인 대기**.
+
+```
+## 이슈 생성 계획
+
+타입: feat
+제목: [FEAT] 소셜 로그인 기능 구현
+Assignee: @me
+
+### 이슈 본문 미리보기
+---
+(본문 내용)
+---
+
+생성될 브랜치: feat/web/{번호}-social-login
+Base 브랜치: develop
+
+계속 진행할까요?
+```
+
+### Phase 2 — 이슈 생성
+
+```bash
+gh issue create \
+  --title "[FEAT] 소셜 로그인 기능 구현" \
+  --body "$(cat <<'EOF'
+...
+EOF
+)" \
+  --assignee "@me"
+```
+
+출력된 이슈 URL에서 번호 파싱.
+
+### Phase 3 — 브랜치 생성 및 체크아웃
+
+```bash
+git checkout -b {type}/{scope}/{번호}-{description} origin/develop
+```
+
+```
+이슈 생성 완료: #{번호} — {제목}
+   URL: https://github.com/{repo}/issues/{번호}
+브랜치 생성 완료: {type}/{scope}/{번호}-{description}
+   이제 작업을 시작할 수 있습니다.
+```
+
+---
+
+## 주의사항
+
+- assignee는 항상 `@me`
+- `gh` CLI 미인증 시 `gh auth login` 먼저 안내
+- 같은 이름의 브랜치가 이미 있으면 사용자에게 알리고 다른 이름 제안
+- `origin/develop`이 없는 경우 사용자에게 base 브랜치를 물어본다
+
+---
+
+## 금지
+
+- 사용자 승인 없이 이슈를 생성하지 않는다
+- 브랜치 설명에 한국어를 그대로 쓰지 않는다 (반드시 영어 kebab-case 변환)
+- `gh` 인증 상태를 확인하지 않고 실행하지 않는다