@yuaone/core 0.3.3 → 0.4.0

package/plugins/git/skills/branch-strategy.md

@@ -0,0 +1,172 @@
+## Identity
+Git 브랜치 전략 전문가. 프로젝트 규모, 팀 크기, 배포 주기에 맞는 최적의 브랜치 전략을 분석하고 추천한다. Git Flow와 Trunk-based Development를 모두 이해하며 상황에 맞는 전략을 제시한다.
+
+## Git Flow 전략
+
+### 브랜치 구조
+```
+main (production)
+├── develop (integration)
+│   ├── feature/TICKET-123-user-auth
+│   ├── feature/TICKET-456-payment
+│   └── feature/TICKET-789-dashboard
+├── release/1.2.0 (release candidate)
+└── hotfix/critical-auth-bug
+```
+
+### 브랜치별 역할
+| 브랜치     | 수명     | 생성 원본   | 병합 대상           | 용도                     |
+|-----------|----------|------------|---------------------|--------------------------|
+| `main`    | 영구     | -          | -                   | 프로덕션 코드, 태그 기준   |
+| `develop` | 영구     | `main`     | -                   | 통합 브랜치, 다음 릴리스   |
+| `feature` | 임시     | `develop`  | `develop`           | 새 기능 개발              |
+| `release` | 임시     | `develop`  | `main` + `develop`  | 릴리스 준비, 버그 수정     |
+| `hotfix`  | 임시     | `main`     | `main` + `develop`  | 긴급 프로덕션 버그 수정    |
+
+### Git Flow 워크플로우
+1. `develop`에서 `feature/TICKET-xxx` 분기
+2. 기능 개발 완료 → `develop`으로 PR
+3. 릴리스 준비 → `develop`에서 `release/x.y.z` 분기
+4. release 브랜치에서 최종 버그 수정
+5. `release` → `main` 병합 + 태그
+6. `release` → `develop` 병합 (수정 사항 반영)
+7. 긴급 수정: `main`에서 `hotfix/xxx` → `main` + `develop` 병합
+
+### Git Flow 적합 상황
+- 정기 릴리스 주기 (2주~1개월)
+- 여러 버전을 동시에 유지보수하는 프로젝트
+- QA 단계가 별도로 존재하는 팀
+- 엔터프라이즈/모바일 앱 (앱스토어 릴리스)
+
+## Trunk-based Development 전략
+
+### 브랜치 구조
+```
+main (production, always deployable)
+├── feature/short-lived-1  (1-2일)
+├── feature/short-lived-2  (1-2일)
+└── feature/short-lived-3  (1-2일)
+```
+
+### 핵심 원칙
+- `main`은 항상 배포 가능 상태
+- feature 브랜치는 1~2일 이내 병합
+- 큰 기능은 feature flag로 숨김
+- CI/CD가 모든 커밋에서 자동 실행
+- `develop` 브랜치 없음
+
+### Trunk-based 워크플로우
+1. `main`에서 짧은 feature 브랜치 분기
+2. 작은 단위로 커밋 (1일 이내 목표)
+3. CI 통과 확인 후 main으로 PR
+4. Squash merge 또는 rebase merge
+5. main에서 자동 배포 (CD)
+
+### Trunk-based 적합 상황
+- 지속적 배포 (CD) 환경
+- 소규모 팀 (2~8명)
+- 웹 서비스 (즉시 배포 가능)
+- 높은 자동화 수준 (CI/CD, 자동 테스트)
+- SaaS 프로덕트
+
+## 전략 선택 가이드
+
+### 의사결정 기준
+| 기준              | Git Flow         | Trunk-based      |
+|-------------------|-----------------|------------------|
+| 팀 크기           | 중~대 (8+)      | 소~중 (2~8)      |
+| 배포 주기         | 정기 (2주+)     | 지속적 (매일+)    |
+| 릴리스 관리       | 다중 버전       | 단일 버전         |
+| QA 프로세스       | 별도 QA 단계    | 자동화 테스트      |
+| 롤백 전략         | 이전 버전 배포   | feature flag off   |
+| CI/CD 성숙도      | 중간            | 높음              |
+
+## 브랜치 네이밍 컨벤션
+
+### Feature 브랜치
+```
+feature/TICKET-123-add-user-auth
+feature/JIRA-456-payment-integration
+feat/add-oauth2-google
+```
+
+### Fix 브랜치
+```
+fix/issue-789-login-crash
+fix/null-pointer-in-session
+bugfix/TICKET-101-memory-leak
+```
+
+### Release 브랜치
+```
+release/1.2.0
+release/2024.03
+release/v3.0.0-rc1
+```
+
+### Hotfix 브랜치
+```
+hotfix/critical-auth-bypass
+hotfix/1.2.1
+```
+
+### 기타
+```
+chore/bump-dependencies
+docs/update-api-reference
+refactor/extract-auth-module
+ci/add-github-actions
+```
+
+### 네이밍 규칙
+- 소문자 + 하이픈 (kebab-case)
+- type prefix 필수: `feature/`, `fix/`, `release/`, `hotfix/`
+- 티켓 번호 포함 권장: `feature/TICKET-123-description`
+- description은 간결하게 (3~5단어)
+- 슬래시 1단계만: `feature/xxx` (O), `feature/sub/xxx` (X)
+
+## PR 워크플로우 권장사항
+
+### PR 생성 시
+1. 제목: Conventional Commits 형식 (`feat(scope): description`)
+2. 본문: 변경 이유, 영향 범위, 테스트 방법
+3. 레이블: `feature`, `bugfix`, `breaking`, `docs`
+4. 리뷰어: 최소 1명 (CODEOWNERS 활용)
+
+### PR 크기
+- 이상적: 200~400줄 변경
+- 최대: 800줄 (넘으면 분리)
+- 큰 변경: stacked PRs 활용
+
+### Merge 전략
+| 전략             | 용도                    | 히스토리        |
+|-----------------|------------------------|----------------|
+| Squash merge    | feature 브랜치          | 깔끔한 1커밋    |
+| Rebase merge    | 커밋 히스토리 보존 필요   | 선형 히스토리    |
+| Merge commit    | release/hotfix 병합      | 분기점 보존     |
+
+## Known Error Patterns
+- **장기 feature 브랜치**: 3일+ 미병합 → 충돌 위험 증가, 브랜치 분리 또는 중간 병합 권장
+- **develop 스킵**: feature → main 직접 병합 시도 → Git Flow면 develop 거쳐야 함
+- **삭제 안 된 브랜치**: 병합 후 브랜치 미삭제 → `git branch -d` 또는 자동 삭제 설정
+- **rebase vs merge 혼용**: 팀 내 일관된 전략 필요 → 하나를 정하고 문서화
+- **hotfix develop 미반영**: hotfix → main만 병합하고 develop 누락 → 양쪽 병합 필수
+- **main 직접 push**: 보호 규칙 없이 main에 직접 push → branch protection rule 설정
+
+## Tool Sequence
+1. `shell_exec` — `git branch -a` 전체 브랜치 목록 조회
+2. `shell_exec` — `git log --oneline --graph -30` 최근 히스토리 구조 파악
+3. `shell_exec` — `git remote -v` 원격 저장소 확인
+4. 분석 — 현재 브랜치 구조에서 전략 유형 판별 (develop 존재 여부 등)
+5. `file_read` — package.json, CI 설정 등으로 프로젝트 성격 파악
+6. 추천 — 프로젝트에 맞는 전략 및 브랜치 네이밍 가이드 제시
+
+## Validation Checklist
+- [ ] 브랜치 전략이 팀 규모와 배포 주기에 적합
+- [ ] 브랜치 네이밍 컨벤션이 일관됨
+- [ ] main/develop 브랜치 보호 규칙 설정됨
+- [ ] feature 브랜치 수명이 적절함 (1~3일 권장)
+- [ ] 병합 전략이 팀 내 통일됨 (squash/rebase/merge)
+- [ ] 병합 후 브랜치 자동 삭제 설정됨
+- [ ] hotfix가 main과 develop 양쪽에 병합됨 (Git Flow 시)
+- [ ] CI가 모든 PR에서 실행됨

package/plugins/git/skills/commit-conv.md

@@ -0,0 +1,178 @@
+## Identity
+Conventional Commits 전문가. 커밋 메시지를 Conventional Commits 1.0.0 스펙에 맞게 작성하고, 기존 커밋 메시지를 검증하며, 프로젝트 히스토리 품질을 보장한다.
+
+## Conventional Commits 스펙
+
+### 기본 형식
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Type 목록
+| Type       | 용도                                | SemVer 영향 |
+|------------|-------------------------------------|-------------|
+| `feat`     | 새 기능 추가                        | MINOR       |
+| `fix`      | 버그 수정                           | PATCH       |
+| `chore`    | 빌드/도구/의존성 등 부수 작업        | -           |
+| `docs`     | 문서 변경                           | -           |
+| `style`    | 코드 포맷팅 (동작 변경 없음)         | -           |
+| `refactor` | 기능 변경 없는 코드 구조 개선        | -           |
+| `perf`     | 성능 개선                           | PATCH       |
+| `test`     | 테스트 추가/수정                    | -           |
+| `build`    | 빌드 시스템/외부 의존성 변경         | -           |
+| `ci`       | CI 설정 변경                        | -           |
+
+### Scope 규칙
+- 모노레포: 패키지명을 scope로 사용 — `feat(core):`, `fix(web):`, `chore(shared):`
+- 파일 기반: 영향받는 주요 모듈/디렉토리 — `fix(auth):`, `feat(api):`
+- 다중 scope: 슬래시로 구분 — `feat(core/tools):`
+- scope 생략 가능: 프로젝트 전체 변경 시 — `chore: bump dependencies`
+
+### Breaking Change 표기
+1. type/scope 뒤에 `!` 추가: `feat(api)!: change response format`
+2. footer에 `BREAKING CHANGE:` 명시:
+```
+feat(api): change response format
+
+BREAKING CHANGE: response.data is now wrapped in { result: data }
+Migration: change all `response.data.x` to `response.data.result.x`
+```
+3. `!`와 footer 동시 사용 권장 (최대 명확성)
+
+### Multi-line Body 규칙
+- subject와 body 사이 빈 줄 필수
+- body는 변경의 "왜"를 설명 (what은 diff가 보여줌)
+- 72자 줄바꿈 권장
+- 불릿 리스트 사용 가능 (`-` 또는 `*`)
+- 관련 이슈 참조: `Refs: #123, #456`
+
+### Footer 규칙
+- `BREAKING CHANGE: <description>` — 호환성 깨지는 변경
+- `Closes #123` / `Fixes #456` — 이슈 자동 종료
+- `Reviewed-by: Name <email>` — 리뷰어
+- `Co-Authored-By: Name <email>` — 공동 작성자
+- `Refs: #789` — 관련 이슈 (종료하지 않음)
+
+## 커밋 메시지 예시
+
+### feat
+```
+feat(auth): add OAuth2 Google login
+
+Implement Google OAuth2 flow with PKCE for enhanced security.
+Tokens are stored in httpOnly cookies with 7-day expiry.
+
+Closes #234
+```
+
+### fix
+```
+fix(api): prevent race condition in session refresh
+
+Multiple concurrent requests could trigger parallel token refreshes,
+causing 401 errors. Add mutex lock around refresh logic.
+
+Fixes #567
+```
+
+### chore
+```
+chore: bump typescript to 5.7.0
+
+Also updates related @types packages for compatibility.
+```
+
+### docs
+```
+docs(readme): add deployment instructions for Docker
+```
+
+### style
+```
+style(web): apply prettier formatting to components/
+```
+
+### refactor
+```
+refactor(core): extract tool dispatch into separate module
+
+Split the monolithic agent-loop.ts into focused modules:
+- tool-dispatcher.ts: tool routing and execution
+- result-aggregator.ts: response collection and formatting
+
+No behavior changes. All existing tests pass.
+```
+
+### perf
+```
+perf(search): add bloom filter for file-exists checks
+
+Reduces filesystem calls by ~60% during project scanning.
+Benchmark: 2.3s → 0.9s for 10k file projects.
+```
+
+### test
+```
+test(tools): add integration tests for shell-exec sandboxing
+```
+
+### build
+```
+build: migrate from webpack to esbuild
+
+3x faster build times. Output bundle size reduced by 15%.
+```
+
+### ci
+```
+ci: add GitHub Actions workflow for automated releases
+```
+
+### Breaking Change
+```
+feat(api)!: require authentication for all endpoints
+
+All API endpoints now require a valid Bearer token.
+Previously, /health and /version were public.
+
+BREAKING CHANGE: unauthenticated requests to any endpoint
+will receive 401. Update clients to include auth headers.
+
+Migration guide: https://docs.example.com/auth-migration
+```
+
+## Known Error Patterns
+- **누락된 type**: `added new feature` → `feat: add new feature`
+- **잘못된 type**: `feature(api): ...` → `feat(api): ...` (feature는 유효하지 않음)
+- **type 대문자**: `Feat: ...` → `feat: ...` (소문자 필수)
+- **subject 너무 김**: 50자 초과 subject → 핵심만 subject에, 나머지는 body로
+- **subject 마침표**: `feat: add login.` → `feat: add login` (마침표 제거)
+- **body 없는 breaking change**: `feat!: remove API` → body에 마이그레이션 가이드 필수
+- **scope 불일치**: 모노레포에서 패키지명과 다른 scope 사용 → 패키지명 확인
+- **명령형 아닌 subject**: `feat: added login` → `feat: add login` (현재형 명령형)
+- **WIP 커밋**: `WIP: stuff` → 커밋 전에 메시지 정리 또는 fixup으로 정리
+
+## Tool Sequence
+1. `shell_exec` — `git log --oneline -20` 최근 커밋 스타일 파악
+2. `shell_exec` — `git diff --cached --stat` 스테이징된 변경 확인
+3. `shell_exec` — `git diff --cached` 상세 diff 분석
+4. 분석 — 변경 내용 기반으로 type, scope, description 결정
+5. `shell_exec` — `git commit -m "<message>"` 커밋 실행
+6. `shell_exec` — `git log -1 --format="%H %s"` 커밋 결과 확인
+
+## Validation Checklist
+- [ ] type이 유효한 목록에 포함됨 (feat, fix, chore, docs, style, refactor, perf, test, build, ci)
+- [ ] type은 소문자
+- [ ] scope가 있다면 프로젝트 패키지명/모듈명과 일치
+- [ ] subject는 50자 이하
+- [ ] subject는 명령형 현재시제
+- [ ] subject 끝에 마침표 없음
+- [ ] subject와 body 사이 빈 줄 있음 (body가 있을 때)
+- [ ] body 줄바꿈 72자 이내
+- [ ] breaking change에 BREAKING CHANGE footer 또는 ! 표기 있음
+- [ ] breaking change에 마이그레이션 가이드 포함
+- [ ] 관련 이슈 번호 참조됨 (해당 시)

package/plugins/git/skills/conflict-resolve.md

@@ -0,0 +1,159 @@
+## Identity
+Git merge conflict 해결 전문가. 3-way merge를 이해하고, conflict 마커를 분석하며, 양측의 의도를 파악하여 안전하게 충돌을 해결한다. 해결 후 빌드와 테스트 검증까지 수행한다.
+
+## 3-Way Merge 이해
+
+### 세 가지 버전
+```
+BASE (공통 조상)
+├── OURS  (현재 브랜치, HEAD)
+└── THEIRS (병합 대상 브랜치)
+```
+
+- **BASE**: 두 브랜치가 갈라진 시점의 원본 코드
+- **OURS**: 현재 체크아웃된 브랜치의 변경 (`<<<<<<< HEAD` 위)
+- **THEIRS**: 병합하려는 브랜치의 변경 (`>>>>>>> branch-name` 아래)
+
+### Conflict 마커 구조
+```
+<<<<<<< HEAD
+// OURS: 현재 브랜치의 코드
+const timeout = 5000;
+=======
+// THEIRS: 병합 대상의 코드
+const timeout = 10000;
+>>>>>>> feature/update-timeout
+```
+
+### 해결 옵션
+1. **Accept Ours**: HEAD 쪽만 유지
+2. **Accept Theirs**: 병합 대상만 유지
+3. **Accept Both**: 양쪽 모두 유지 (순서 주의)
+4. **Manual Merge**: 양쪽을 이해하고 새로운 코드 작성
+
+## 일반 Conflict 패턴
+
+### 1. 같은 줄 수정 (Most Common)
+```
+<<<<<<< HEAD
+const API_URL = "https://api.prod.example.com";
+=======
+const API_URL = "https://api.staging.example.com";
+>>>>>>> feature/staging
+```
+**해결**: 의도 파악 — 환경별 분기라면 환경변수로 추출. 단순 값 변경이면 최신 의도 채택.
+
+### 2. Import 순서 변경
+```
+<<<<<<< HEAD
+import { Button } from './Button';
+import { Modal } from './Modal';
+import { Toast } from './Toast';
+=======
+import { Button } from './Button';
+import { Dialog } from './Dialog';
+import { Modal } from './Modal';
+>>>>>>> feature/add-dialog
+```
+**해결**: 양쪽의 추가된 import를 모두 포함하고 알파벳 정렬. 삭제된 import는 실제 사용 여부 확인.
+
+### 3. 인접 줄 변경 (Adjacent Line Conflict)
+두 브랜치가 같은 영역의 인접한 줄을 수정한 경우.
+**해결**: 양쪽 변경이 독립적이면 둘 다 적용. 연관된 변경이면 통합 로직 작성.
+
+### 4. 파일 이름 변경 + 내용 수정
+한 브랜치에서 파일 rename, 다른 브랜치에서 내용 수정.
+**해결**: renamed 파일에 내용 수정을 적용. `git log --follow` 로 이력 확인.
+
+### 5. 삭제 vs 수정 (Delete/Modify Conflict)
+한 브랜치에서 파일 삭제, 다른 브랜치에서 수정.
+**해결**: 삭제 의도 확인 — 리팩토링으로 다른 파일로 이동했다면 해당 파일에 수정 적용. 불필요해서 삭제했다면 삭제 유지.
+
+### 6. package.json / lock file Conflict
+```
+<<<<<<< HEAD
+"react": "^18.2.0",
+"react-dom": "^18.2.0",
+=======
+"react": "^18.3.0",
+"react-dom": "^18.3.0",
+>>>>>>> feature/upgrade-react
+```
+**해결**: 최신 버전 채택 후 `pnpm install` 재실행으로 lock file 재생성. lock file은 수동 편집하지 않음.
+
+### 7. 동시 함수 추가
+같은 파일에 서로 다른 함수를 추가한 경우.
+**해결**: 양쪽 함수 모두 유지. 이름 충돌 확인, export 정리.
+
+### 8. 타입 정의 충돌 (TypeScript)
+```
+<<<<<<< HEAD
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+=======
+interface User {
+  id: string;
+  name: string;
+  role: UserRole;
+}
+>>>>>>> feature/add-roles
+```
+**해결**: 양쪽 필드를 모두 포함한 통합 인터페이스 생성.
+
+## 해결 전략 의사결정
+
+### 자동 해결 가능
+- Import 순서 충돌 (알파벳 정렬)
+- 독립적인 함수/메서드 추가
+- 주석 변경
+- 빈 줄/포맷팅 차이
+
+### 수동 판단 필요
+- 로직 변경 충돌 (양쪽 다 비즈니스 로직 수정)
+- 동일 변수의 다른 값 설정
+- API 계약 변경
+- 타입 시스템 변경
+
+### 위험 — 반드시 확인 필요
+- 보안 관련 코드 (인증, 권한)
+- 데이터베이스 마이그레이션
+- 환경 설정 파일
+- 암호화/해싱 로직
+
+## Known Error Patterns
+- **마커 잔존**: 해결 후 `<<<<<<<`, `=======`, `>>>>>>>` 마커가 코드에 남아있음 → grep으로 확인
+- **절반만 해결**: 여러 충돌 중 일부만 해결하고 커밋 → `git diff --check` 로 미해결 충돌 확인
+- **lock file 수동 편집**: package-lock.json이나 pnpm-lock.yaml 수동 편집 → 삭제 후 재설치
+- **테스트 미실행**: 충돌 해결 후 빌드/테스트 미확인 → 반드시 빌드 + 테스트 실행
+- **의도 미파악**: 양쪽 변경의 목적을 모른 채 하나만 채택 → PR 설명/커밋 메시지 먼저 확인
+- **rebase 중 반복 충돌**: 같은 충돌이 커밋마다 반복 → `git rerere` 활성화 고려
+
+## Tool Sequence
+1. `shell_exec` — `git status` 현재 merge 상태 및 충돌 파일 목록 확인
+2. `shell_exec` — `git diff --name-only --diff-filter=U` 충돌 파일만 추출
+3. `file_read` — 충돌 파일 읽기 (conflict 마커 포함 전체 내용)
+4. `shell_exec` — `git log --oneline --left-right HEAD...MERGE_HEAD -20` 양쪽 변경 이력 파악
+5. `shell_exec` — `git show :1:<file>` BASE 버전 확인 (필요 시)
+6. `shell_exec` — `git show :2:<file>` OURS 버전 확인 (필요 시)
+7. `shell_exec` — `git show :3:<file>` THEIRS 버전 확인 (필요 시)
+8. 분석 — 양쪽 변경 의도 파악 및 해결 전략 결정
+9. `file_edit` — conflict 마커 제거 및 최종 코드 작성
+10. `shell_exec` — `git add <resolved_files>` 해결 완료 표시
+11. `shell_exec` — `git diff --check` 미해결 충돌 마커 잔존 확인
+12. `shell_exec` — 빌드 확인 (`tsc --noEmit` 또는 `pnpm build`)
+13. `shell_exec` — 테스트 실행 (있다면)
+14. `shell_exec` — `git commit` (merge commit 또는 rebase continue)
+
+## Validation Checklist
+- [ ] 모든 충돌 파일이 해결됨 (`git diff --check` 통과)
+- [ ] conflict 마커가 코드에 남아있지 않음 (grep 확인)
+- [ ] 양쪽 변경의 의도가 모두 반영됨
+- [ ] TypeScript 컴파일 통과 (`tsc --noEmit`)
+- [ ] 빌드 성공 (`pnpm build`)
+- [ ] 테스트 통과 (해당 시)
+- [ ] import 문이 정리됨 (중복 없음, 미사용 없음)
+- [ ] 새로 추가된 의존성이 package.json에 반영됨
+- [ ] lock file이 재생성됨 (package.json 충돌 시)