sync-docs

name	sync-docs
description	Synchronizes harness documentation (CLAUDE.md, harness.md) and install script (harness.sh) with the actual state of .claude/ subdirectories (skills, agents, hooks). Detects mismatches between source files and docs, then auto-updates affected sections. Triggers on: "문서 동기화", "docs sync", "sync-docs", or after harness file changes.
argument-hint	[--check-only] [변경 설명 (선택)]
user-invocable	true
context	fork
agent	coder

Sync Docs Skill

입력

$ARGUMENTS: (선택) --check-only 플래그 또는 변경 설명.

• --check-only: 실제 수정 없이 불일치만 보고
• 변경 설명이 있으면 해당 변경에 영향받는 섹션만 타겟팅

프로세스

1. 현재 상태 수집

.claude/ 하위를 스캔하여 현재 상태를 파악한다:

스킬 목록 수집:

• Glob으로 .claude/skills/*/SKILL.md 검색
• 각 SKILL.md의 frontmatter에서 name, description, agent, user-invocable 추출
• 결과: 스킬 이름, 에이전트, 용도 요약 목록

에이전트 목록 수집:

• Glob으로 .claude/agents/*.md 검색
• 각 에이전트 파일의 frontmatter에서 name, description, model, tools 추출
• 결과: 에이전트 이름, 역할, 호출 방식 목록

훅 목록 수집:

• .claude/settings.json을 읽어 등록된 훅 이벤트와 matcher 파악
• Glob으로 .claude/hooks/*.sh 검색 (test-*.sh 제외)
• 각 훅 스크립트의 상단 주석에서 용도 추출
• 결과: 훅 이름, 이벤트, 용도 목록

2. 문서 현재 상태 파싱

대상 문서들을 읽고 관련 섹션을 파싱한다:

CLAUDE.md 파싱 대상:

• ## 디렉토리 구조 - 스킬/에이전트 개수
• ## 주요 스킬 (N개) - 스킬 목록 전체
• ## 훅 - 훅 테이블

harness.md 파싱 대상:

• ### 워커 스킬 (N개) - 스킬 테이블
• ### 에이전트 (N개) - 에이전트 테이블
• ## 훅 하위 섹션들

orchestrator.md 파싱 대상:

• ## Skill Catalog - 스킬 카탈로그 테이블들

3. 불일치 감지

수집한 현재 상태와 문서 상태를 비교:

• 누락된 스킬 (소스에 있지만 문서에 없음)
• 삭제된 스킬 (문서에 있지만 소스에 없음)
• 개수 불일치 (헤더의 "(N개)"와 실제 개수)
• 누락된 에이전트
• 삭제된 에이전트
• 누락/삭제된 훅
• 훅 이벤트/matcher 불일치

--check-only이면 불일치 목록만 보고하고 종료.

4. 문서 업데이트

불일치가 있는 섹션을 업데이트한다:

CLAUDE.md 업데이트:

• ## 주요 스킬 (N개) 헤더의 N을 실제 개수로 수정
• 누락된 스킬의 설명 섹션을 추가 (기존 스킬 형식 참조)
• 삭제된 스킬의 섹션 제거
• ## 훅 테이블에 누락된 훅 추가/삭제된 훅 제거
• ## 디렉토리 구조의 개수 업데이트

harness.md 업데이트:

• ### 워커 스킬 (N개) 헤더와 테이블 동기화
• ### 에이전트 (N개) 헤더와 테이블 동기화
• 훅 관련 섹션 동기화

orchestrator.md 업데이트:

• ## Skill Catalog의 테이블에 누락된 스킬 추가
• 삭제된 스킬 행 제거

5. harness.sh 검증

harness.sh의 TEMPLATE_DIRS 배열을 확인:

• 현재: (agents skills rules hooks)
• .claude/ 하위에 새 디렉토리가 있지만 TEMPLATE_DIRS에 없으면 경고
• 직접 수정하지 않고 "harness.sh의 TEMPLATE_DIRS에 X를 추가해야 합니다" 형태로 보고

출력

## 문서 동기화 완료

### 감지된 불일치
- [불일치 항목 목록]

### 업데이트된 파일
- `CLAUDE.md` — [수정 내용 요약]
- `.claude/harness.md` — [수정 내용 요약]
- `.claude/agents/orchestrator.md` — [수정 내용 요약]

### harness.sh 주의사항
- [TEMPLATE_DIRS 관련 경고 (있는 경우)]

### 검증
- 스킬 목록: N개 (문서 = 소스)
- 에이전트 목록: N개 (문서 = 소스)
- 훅 목록: N개 (문서 = 소스)

REVIEW 연동

sync-docs는 문서 파일만 수정하므로 자체 리뷰는 불필요. Orchestrator가 전체 작업 흐름에서 리뷰 필요성을 판단한다.