Release Setup v5.4.0 · SukbeomH/HExoskeleton

Quick Start

에이전트에게 아래 프롬프트를 복사하여 전달하면 프로젝트에 HXSK를 자동 구성합니다.
모든 에이전트(Claude Code, Gemini, Copilot, Cursor, Windsurf)를 하나의 프롬프트로 지원합니다.

Changes in v5.4.0

신규 — Git Forge 통합 작업 관리 (PR #131)

GATES.md — SPEC→PLAN(P1-P5)→EXECUTE→VERIFY→DONE 단일 진실 원천
gate-check.sh — PreToolUse/Stop 훅으로 게이트 조건 자동 집행
forge-detect.sh — remote URL로 플랫폼 감지(GitHub/GitLab/Gitea/Forgejo) → gh/glab/tea CLI 추상화
AGENTS.md에 게이트 규칙 섹션 추가 — opencode/Copilot/Antigravity 호환

신규 — lessons-learned 체계 (PR #127)

lessons-learned 메모리 타입 추가 — A/B/C/D/E 5개 카테고리로 분류 저장
planner 스킬 — 계획 수립 전 lessons recall + cross_phase_invariants 체크리스트
executor 스킬 — invariants 로드 + deviation A-E 분류 자동 저장
create-pr 스킬 — Pre-PR Self-Check A-E 품질 점검
pr-review 스킬 — 리뷰 후 lessons-learned A-E 분류 저장
dispatcher 스킬 — 서브에이전트에 lessons recall + ambiguity log 전달
PLAN.md 템플릿 — cross_phase_invariants frontmatter 필드 추가

개선 — 메모리 티어 최적화 (PR #132)

Write-gating — 훅 자체 변경(.hxsk/CURRENT.md, STATE.md, 내부 로그)만 있는 세션은 session-summary 저장 생략
Cap 기반 prune — prune-memories.sh --max-count N [--tier T] FIFO 모드 추가. stop-context-save / compact-context가 TTL 대신 최신 20개 유지로 교체
가치 기반 승격 — frontmatter tags: [decision|root-cause|incident|security|pattern|lesson] 매칭 파일은 삭제 직전 shared-tier 해당 폴더로 자동 mv. git이 장기 보존 시스템 역할
prune-memories.sh — --dry-run / --help / --max-count / --tier 옵션 (PR #125, #132)
RETENTION_DAYS=0 전체 삭제 분기, rm 실패 시 exit 2 + failed 카운터 분리
memory-cleanup.sh 삭제 (30일 아카이브 구정책과 충돌) — compact-context.sh가 prune-memories.sh 직접 호출

신규 — doc-lint 검증 체계 (PR #123, #126)

doc-lint 훅 — PR 전 문서 정합성 6개 항목 검증 (LINK, INDEX, COUNT, REF, ORPHAN)
LINK-02 — 마크다운 앵커(#) 링크 유효성 검사
메모리 2-tier 분리 정착 — local(gitignored) vs shared(git-tracked)

수정

setup.md

아래 코드 블럭을 복사하여 에이전트에게 전달하세요.

setup.md 전체 내용 (클릭하여 펼치기)

# HXSK Setup

아래 지침에 따라 현재 프로젝트에 HExoskeleton(HXSK) 개발 방법론을 구성하세요.

## Step 0: 상태 감지

```bash
test -f .hxsk/.bootstrap-version && echo "UPDATE" || echo "FRESH"
```

- **FRESH** → 아래 "초기 설치" (Step 1~8)
- **UPDATE** → 아래 "업데이트"

---

## 초기 설치

### Step 1: 진입점 읽기

이 레포의 `llms.txt`를 읽어 사용 가능한 리소스 목록을 파악하세요.

### Step 2: 에이전트 지침 설정

당신의 에이전트 유형에 맞는 지침 파일을 프로젝트 루트에 저장하세요:

| 에이전트 | 파일 |
|----------|------|
| Claude Code | `CLAUDE.md` |
| Gemini CLI | `GEMINI.md` |
| 기타 (Copilot, Cursor, Windsurf 등) | `AGENTS.md` |

### Step 3: HXSK 문서 구조 생성

`.hxsk/` 디렉토리를 만들고 working docs를 생성하세요:

```
.hxsk/
├── SPEC.md       ← 프로젝트 명세 (필수)
├── STATE.md      ← 현재 상태 (필수)
├── PATTERNS.md   ← 학습된 패턴 (필수)
├── DECISIONS.md  ← 아키텍처 결정 기록
├── templates/    ← 문서 템플릿 (llms.txt에서 fetch)
└── examples/     ← 사용 예시
```

### Step 4: 스킬 및 에이전트 설치

`.hxsk/skills/INDEX.md`를 참조하여 스킬을, `.hxsk/agents/INDEX.md`를 참조하여 에이전트를 가져오세요.

**필수 스킬** (반드시 설치):

| 스킬 | 용도 |
|------|------|
| `bootstrap` | 프로젝트 초기화 + 업데이트 감지 |
| `planner` | SPEC 기반 실행 계획 수립 |
| `executor` | 계획 실행 (atomic commits) |
| `verifier` | 경험적 증거 기반 검증 |
| `memory-protocol` | 메모리 저장/검색 프로토콜 |

**Claude Code 설치 방법:**
```bash
# 스킬: .hxsk/skills/ → .claude/skills/ (심볼릭 링크 — 원본 수정 시 자동 반영)
mkdir -p .claude/skills
for skill_dir in .hxsk/skills/*/; do
    skill_name=$(basename "$skill_dir")
    ln -sfn "../../.hxsk/skills/$skill_name" ".claude/skills/$skill_name"
done

# 에이전트: .hxsk/agents/*.md → .claude/agents/ (INDEX.md 제외)
mkdir -p .claude/agents
for agent in .hxsk/agents/*.md; do
    [[ "$(basename "$agent")" == "INDEX.md" ]] && continue
    ln -sf "../../.hxsk/agents/$(basename "$agent")" ".claude/agents/$(basename "$agent")"
done
```

> 심볼릭 링크를 사용하므로 `.hxsk/`의 스킬/에이전트 수정이 `.claude/`에 즉시 반영됩니다.
> 모든 스킬이 `/skill-name` 슬래시 커맨드로 자동 등록됩니다.

**Gemini CLI** → `.agent/skills/{name}/SKILL.md`, `.agent/agents/{name}.md`에 배치
**기타** → 에이전트 문서에 따라 배치

> **주의**: `.hxsk/.bootstrap-version` 파일을 직접 생성하지 마세요. `bootstrap.sh`가 자동 생성합니다.

### Step 5: 에이전트별 자동 로드 경로 연결

`AGENTS.md`를 각 에이전트의 자동 로드 경로에 심볼릭 링크로 연결하세요:

```bash
# GitHub Copilot
mkdir -p .github
ln -sf ../AGENTS.md .github/copilot-instructions.md

# Cursor
ln -sf AGENTS.md .cursorrules

# Windsurf
ln -sf AGENTS.md .windsurfrules
```

### Step 6: 훅 설치 (Claude Code만)

> Claude Code가 아닌 에이전트는 이 단계를 건너뛰세요. AGENTS.md의 Agent Boundaries 규칙으로 대체됩니다.

`.hxsk/hooks/INDEX.md`에서 훅 스크립트를 가져와 `.claude/settings.json`에 등록:

```json
{
  "hooks": {
    "SessionStart": [
      {"matcher": "startup|resume", "hooks": [{"type": "command", "command": ".hxsk/hooks/session-start.sh", "timeout": 10}]}
    ],
    "PreToolUse": [
      {"matcher": "Edit|Write|Read", "hooks": [{"type": "command", "command": ".hxsk/hooks/file-protect.py", "timeout": 5}]},
      {"matcher": "Bash", "hooks": [{"type": "command", "command": ".hxsk/hooks/bash-guard.py", "timeout": 5}]}
    ],
    "PostToolUse": [
      {"matcher": "Edit|Write", "hooks": [
        {"type": "command", "command": ".hxsk/hooks/auto-format.sh", "timeout": 30},
        {"type": "command", "command": ".hxsk/hooks/track-modifications.sh", "timeout": 2}
      ]},
      {"matcher": "Bash", "hooks": [{"type": "command", "command": ".hxsk/hooks/track-modifications.sh", "timeout": 2}]}
    ],
    "PreCompact": [
      {"matcher": "auto|manual", "hooks": [{"type": "command", "command": ".hxsk/hooks/pre-compact-save.sh", "timeout": 10}]}
    ],
    "Stop": [
      {"hooks": [
        {"type": "command", "command": ".hxsk/hooks/post-turn-verify.sh", "timeout": 15},
        {"type": "command", "command": ".hxsk/hooks/stop-context-save.sh", "timeout": 10}
      ]}
    ],
    "SubagentStop": [
      {"hooks": [{"type": "prompt", "prompt": "## SubagentStop\n- 핵심 결과 2-3문장 요약\n- 코드 변경 시: `touch .hxsk/.modified-this-session`\n- 재사용 패턴 발견 시: PATTERNS.md에 추가 검토\n- 스킬 본문을 결과에 복제하지 말 것"}]}
    ],
    "SessionEnd": [
      {"hooks": [
        {"type": "command", "command": ".hxsk/hooks/save-transcript.sh", "timeout": 10},
        {"type": "command", "command": ".hxsk/hooks/save-session-changes.sh", "timeout": 10}
      ]}
    ]
  }
}
```

### Step 7: 메모리 시스템 확인 (Claude Code만)

> Claude Code가 아닌 에이전트는 이 단계를 건너뛰세요.

```bash
# 메모리 저장
bash .hxsk/hooks/md-store-memory.sh "제목" "내용" "태그" "타입"

# 메모리 검색
bash .hxsk/hooks/md-recall-memory.sh "검색어" "." 5 compact
```

### Step 8: README에 뱃지 추가 (선택)

```markdown
[![HExoskeleton](https://img.shields.io/badge/assisted%20with-HExoskeleton-blueviolet?style=flat-square)](https://github.com/SukbeomH/HExoskeleton)
```

### 완료 확인

- [ ] 에이전트 지침 파일이 프로젝트 루트에 존재
- [ ] `.hxsk/` 디렉토리에 SPEC.md, STATE.md, PATTERNS.md 존재
- [ ] SPEC.md에 프로젝트 실제 내용 반영 (플레이스홀더 `{...}` 가 남아있으면 안 됨)
- [ ] 필수 스킬 5개가 에이전트 설정 디렉토리에 배치됨 (bootstrap, planner, executor, verifier, memory-protocol)
- [ ] 에이전트 정의 파일이 에이전트 설정 디렉토리에 배치됨
- [ ] (선택) 에이전트별 심볼릭 링크 생성됨
- [ ] (Claude Code) 훅 **8개 이벤트** 모두 `.claude/settings.json`에 등록됨 (SessionStart, PreToolUse, PostToolUse, PreCompact, Stop, SubagentStop, SessionEnd)
- [ ] (Claude Code) 메모리 명령어 동작 확인

### 초기 설치 후 다음 단계

```
/bootstrap    # 프로젝트 분석 및 메모리 초기화 (← .bootstrap-version 자동 생성)
/planner      # SPEC 기반 실행 계획 수립
```

---

## 업데이트

이전 설치가 감지되었습니다.

### Step 1: bootstrap 실행

```bash
bash .hxsk/scripts/bootstrap.sh
```

출력 태그:
- `[OK]` — 변경 없음
- `[NEW]` — 새로 추가됨
- `[UPDATED]` — 변경됨 (↳ 관련: 2-hop 컨텍스트 표시)

### Step 2: 에이전트별 설정 갱신

`[NEW]` 또는 `[UPDATED]`가 있는 경우:
- 스킬 추가/변경 → 에이전트 스킬 디렉토리 갱신
- 에이전트 지침 변경 → CLAUDE.md/GEMINI.md/AGENTS.md 갱신

**Claude Code인 경우 추가로:**
- 훅 변경 → `.claude/settings.json` 갱신
- 스킬 변경 → `.claude/skills/{name}/SKILL.md` 복사

### Step 3: 확인

```bash
bash .hxsk/scripts/bootstrap.sh
```

모든 항목이 `[OK]`이면 업데이트 완료.

첨부 파일

파일	설명
`setup.md`	통합 setup 프롬프트 (모든 에이전트 지원)
`AGENTS.md`	공통 에이전트 지침
`CLAUDE.md`	Claude Code 지침
`GEMINI.md`	Gemini CLI 지침
`llms.txt`	LLM 진입점 (리소스 목록)

v5.4.0 · 초기 설치/업데이트를 자동 감지합니다.

Navigation Menu

Repository navigation

Setup v5.4.0

Choose a tag to compare

Sorry, something went wrong.

Sorry, something went wrong.

Uh oh!

No results found

Quick Start

Changes in v5.4.0

신규 — Git Forge 통합 작업 관리 (PR #131)

신규 — lessons-learned 체계 (PR #127)

개선 — 메모리 티어 최적화 (PR #132)

신규 — doc-lint 검증 체계 (PR #123, #126)

수정

setup.md

첨부 파일

Uh oh!