template-sync

Template Sync

upstream brain-in-a-vat 템플릿의 새 변경사항을 확인하고, 사용자가 선택한 항목을 적용하는 워크플로우.

WHY

brain-in-a-vat는 계속 진화하는 템플릿이다. 새로운 규칙, 스킬, 스쿼드, 도구가 추가되지만, clone한 사용자는 이를 감지할 방법이 없다. 이 스킬이 그 간극을 메운다.

Input

Required

• .biv-sync.yml — baseline_sha + upstream_repo 기록 파일

Optional

• --dry-run — 변경사항만 보여주고 적용하지 않음

Output

• 카테고리별 변경사항 목록 (사용자 선택 UX)
• 선택 항목에 대한 initiative 생성 (또는 즉시 적용)
• .biv-sync.yml baseline_sha 갱신

Execution Order

Step 1: Read sync config

cat .biv-sync.yml

.biv-sync.yml이 없으면:

1. 사용자에게 안내: ".biv-sync.yml이 없습니다. 초기 설정을 진행합니다."
2. upstream repo URL 확인 (기본값: https://github.com/nomoory/brain-in-a-vat)
3. 현재 HEAD SHA를 baseline으로 .biv-sync.yml 생성
4. "다음 /template:sync 실행 시 이 시점 이후의 변경사항을 확인합니다." 안내 후 종료

Step 2: Setup upstream remote

git remote get-url biv-upstream 2>/dev/null || git remote add biv-upstream <upstream_repo>
git fetch biv-upstream main

• remote가 이미 있으면 fetch만 실행
• fetch 실패 시 (네트워크, 인증 등) 에러 안내 후 종료

Step 3: Check for new commits

git log <baseline_sha>..biv-upstream/main --oneline --no-merges

새 커밋이 없으면:

✅ Up to date! baseline과 upstream/main이 동일합니다.

→ 종료

Step 4: Categorize changes

각 커밋에 대해 변경된 파일 경로를 분석하여 카테고리 분류:

git diff --name-only <baseline_sha>..biv-upstream/main

카테고리 매핑:

Step 5: Present changes to user

카테고리별로 정리하여 제시. 각 카테고리에 관련 커밋과 변경 파일 목록 포함.

출력 형식:

## 🔄 Upstream Updates Available

baseline: <baseline_sha_short> → upstream: <upstream_sha_short>
신규 커밋: N건

### [1] System Rules (M files changed)
- <commit_sha_short> <commit_message>
  - .claude/rules/new-rule.md (added)
  - .claude/rules/existing-rule.md (modified)

### [2] Skills (M files changed)
- <commit_sha_short> <commit_message>
  ...

### [3] Squads (M files changed)
...

---
적용할 카테고리 번호를 선택하세요 (예: 1,2,3 또는 all 또는 none):

--dry-run이면 여기서 종료.

Step 6: Process user selection

사용자 선택에 따라 분기:

6a. "none" — 스킵

• baseline_sha만 upstream HEAD로 갱신 (확인은 했으므로)
• 사용자에게 확인: "baseline을 갱신하면 다음 sync에서 이 변경들이 표시되지 않습니다. 갱신할까요?"

6b. 소규모 (3카테고리 이하, 10파일 이하) — 즉시 적용

1. 카테고리별로 변경 내용을 상세 표시 (diff)
2. 사용자에게 적용 방법 안내:
   • 파일 단위로 upstream 버전을 가져오기: git show biv-upstream/main:<path> > <path>
   • 또는 수동 편집 (커스터마이징이 있는 파일)
3. 충돌 가능성 안내: "커스터마이징한 파일은 수동 병합이 필요할 수 있습니다"
4. 적용 완료 후 baseline_sha 갱신

6c. 대규모 (4카테고리 이상 또는 10파일 초과) — initiative 생성

1. 선택된 카테고리를 ST로 매핑하여 initiative 생성
2. /initiative:start 패턴을 따라 workspace/initiatives/active/template-sync-<date>/ 생성
3. 각 카테고리 = 1 ST (type: implementation)
4. initiative index.yml에 relation으로 이 sync의 baseline..upstream 범위 기록
5. baseline_sha 갱신

initiative 생성 시 index.yml 구조:

topic: template-sync-YYYY-MM-DD
title: "Template Sync — upstream <sha_short> 적용"
stage: executing
goal: "upstream <baseline_short>..<upstream_short> 범위의 선택된 변경사항을 적용한다"
subtopics:
  - id: ST-01
    title: "System Rules 업데이트 — N files"
    type: implementation
    status: pending
    # ...

Step 7: Update baseline

# .biv-sync.yml 갱신
upstream_repo: <unchanged>
baseline_sha: <biv-upstream/main HEAD SHA>

git rev-parse biv-upstream/main

갱신 후 안내:

✅ baseline 갱신: <old_short> → <new_short>
다음 /template:sync 실행 시 이 시점 이후의 변경만 표시됩니다.

JUDGMENT

즉시 적용 vs initiative 생성

• 3카테고리 이하 + 10파일 이하 → 즉시 적용 제안 (사용자가 initiative 원하면 전환)
• 그 외 → initiative 생성 제안 (사용자가 즉시 적용 원하면 전환)
• 사용자 선택 우선

충돌 처리

• 사용자가 커스터마이징한 파일은 덮어쓰지 않음
• diff를 보여주고 수동 병합 안내
• 새로 추가된 파일은 안전하게 복사 가능

baseline 갱신 시점

• 변경 확인만 하고 적용하지 않아도 baseline 갱신 가능 (사용자 확인 후)
• 스킵한 변경은 의식적 선택으로 간주

KNOWLEDGE REFS

• .biv-sync.yml — baseline 추적 파일
• workspace/squads/initiative/ — initiative 생성 시 참조