claude-nexus 0.8.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "claude-nexus",
       "description": "Agent orchestration plugin for Claude Code. Injects optimized context per agent role with minimal overhead.",
-      "version": "0.7.0",
+      "version": "0.10.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Agent orchestration plugin for Claude Code — optimized context injection per role",
   "author": {
     "name": "kih"

package/README.en.md

@@ -0,0 +1,149 @@
+# claude-nexus
+
+[![npm version](https://img.shields.io/npm/v/claude-nexus)](https://www.npmjs.com/package/claude-nexus)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/moreih29/claude-nexus/blob/main/LICENSE)
+
+> 🌏 [한국어](README.md)
+
+Agent orchestration plugin for Claude Code.
+
+## Why
+
+Specialized agent teams handle development and research systematically — director, architect, engineer, QA for development; principal, postdoc, researcher for research. One tag triggers automatic orchestration of complex tasks across the right agents without manual coordination.
+
+## Quick Start
+
+**1. Install**
+
+```bash
+claude plugin marketplace add https://github.com/moreih29/claude-nexus.git
+claude plugin install claude-nexus@nexus
+```
+
+**2. Onboard your project**
+
+Run `/claude-nexus:nx-sync` — on first run it scans your project and auto-generates structured knowledge under `.claude/nexus/knowledge/`.
+
+**3. Start using**
+
+- **Consult**: `[consult] How should we design the auth system?` — clarify intent and align before executing
+- **Develop**: `[dev] Implement login API` — agent team handles analysis through implementation
+- **Research**: `[research] React vs Svelte performance comparison` — independent investigation with synthesis report
+
+## Usage
+
+Tag your message to route it to the right workflow:
+
+| Tag | Action | Example |
+|-----|--------|---------|
+| `[consult]` | Pre-execution consultation | `[consult] Discuss DB migration strategy` |
+| `[dev]` | Development (auto Sub/Team) | `[dev] Refactor payment module` |
+| `[dev!]` | Force team mode | `[dev!] Overhaul auth system` |
+| `[research]` | Research execution | `[research] Compare caching strategies` |
+| `[research!]` | Force research team | `[research!] Investigate competitor tech stacks` |
+
+Typical flow: use `[consult]` to discuss and align → decide → use `[dev]` or `[research]` to execute.
+
+## Agents
+
+### Dev Team (4 agents)
+
+| Agent | Invocation | Role | Model |
+|-------|-----------|------|-------|
+| **Director** | `claude-nexus:director` | Project direction, scope, and priority decisions | opus |
+| **Architect** | `claude-nexus:architect` | Technical design and architecture review (read-only) | opus |
+| **Engineer** | `claude-nexus:engineer` | Code implementation and debugging | sonnet |
+| **QA** | `claude-nexus:qa` | Verification, testing, and security review | sonnet |
+
+### Research Team (3 agents)
+
+| Agent | Invocation | Role | Model |
+|-------|-----------|------|-------|
+| **Principal** | `claude-nexus:principal` | Research direction, agenda, and confirmation bias prevention | opus |
+| **Postdoc** | `claude-nexus:postdoc` | Methodology design, evidence evaluation, synthesis documents | opus |
+| **Researcher** | `claude-nexus:researcher` | Web search, independent investigation, source reporting | sonnet |
+
+## Skills
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **nx-consult** | `[consult]` | Structured consultation. Clarify requirements → record decisions (`[d]`) → recommend execution tag |
+| **nx-dev** | `[dev]` / `[dev!]` | Development execution. Auto-selects solo or team (Director→Architect→Engineer→QA) based on complexity |
+| **nx-research** | `[research]` / `[research!]` | Research execution. Auto-selects solo or team (Principal→Postdoc→Researcher) based on complexity |
+| **nx-setup** | `/claude-nexus:nx-setup` | Interactive setup. Injects agent/skill/tag configuration into CLAUDE.md |
+| **nx-sync** | `/claude-nexus:nx-sync` | Auto-generates knowledge on first run, then detects and fixes drift with source changes. --reset for re-initialization |
+
+## Advanced
+
+<details>
+<summary>MCP Tools</summary>
+
+Claude-callable tools exposed by the Nexus MCP server.
+
+### Core (5 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `nx_knowledge_read/write` | Project knowledge management (git-tracked) |
+| `nx_context` | Current session state lookup |
+| `nx_task_list/add/update/clear` | Task management backed by tasks.json |
+| `nx_decision_add` | Record architecture decisions |
+
+### Code Intelligence (10 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `nx_lsp_hover` | Symbol type information |
+| `nx_lsp_goto_definition` | Jump to definition |
+| `nx_lsp_find_references` | List all references |
+| `nx_lsp_diagnostics` | Compiler and linter errors |
+| `nx_lsp_rename` | Project-wide symbol rename |
+| `nx_lsp_code_actions` | Auto-fix and refactoring suggestions |
+| `nx_lsp_document_symbols` | Symbols in a file |
+| `nx_lsp_workspace_symbols` | Project-wide symbol search |
+| `nx_ast_search` | AST pattern search (tree-sitter) |
+| `nx_ast_replace` | AST pattern replacement (dryRun supported) |
+
+LSP auto-detects the project language (e.g., `tsconfig.json` → TypeScript).
+AST tools require `@ast-grep/napi`: `bun install @ast-grep/napi`
+
+</details>
+
+<details>
+<summary>Hook</summary>
+
+Nexus registers a single Gate module as a Claude Code hook.
+
+| Event | Role |
+|-------|------|
+| `UserPromptSubmit` | Prompt preprocessing and context injection |
+| `Stop` | Post-session cleanup |
+
+</details>
+
+<details>
+<summary>Project Knowledge</summary>
+
+Project knowledge is stored under `.claude/nexus/knowledge/` and tracked by git.
+
+- `nx-sync` auto-generates knowledge files tailored to your project on first run (structure is not fixed)
+- Nexus configuration is stored in `config.json`
+
+</details>
+
+<details>
+<summary>Runtime State</summary>
+
+Runtime state is stored under `.nexus/` and is excluded from git.
+
+```
+.nexus/
+├── branches/               ← Per-branch isolation
+│   └── {branch}/
+│       ├── tasks.json      ← Task list
+│       ├── decisions.json  ← Architecture decision list
+│       └── reports/        ← Research outputs
+└── sync-state.json         ← Last sync commit
+```
+
+</details>

package/README.md

@@ -3,18 +3,46 @@
 [![npm version](https://img.shields.io/npm/v/claude-nexus)](https://www.npmjs.com/package/claude-nexus)
 [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/moreih29/claude-nexus/blob/main/LICENSE)
 
-Claude Code를 위한 에이전트 오케스트레이션 플러그인. 전문화된 에이전트와 스킬을 통해 코드, 분석, 설계, 테스트, 문서화를 체계적으로 관리합니다.
+> 🌏 [English](README.en.md)
 
-## 설치
+Claude Code를 위한 에이전트 오케스트레이션 플러그인.
+
+## Why
+
+복잡한 개발/리서치 작업을 혼자 처리하는 대신, 전문화된 에이전트 팀이 역할을 나눠 체계적으로 수행합니다. 태그 하나로 상담, 개발, 리서치 워크플로우가 자동 오케스트레이션됩니다.
+
+## Quick Start
+
+**설치**
 
 ```bash
 claude plugin marketplace add https://github.com/moreih29/claude-nexus.git
 claude plugin install claude-nexus@nexus
 ```
 
-## 에이전트
+**온보딩**
+
+`/claude-nexus:nx-sync`를 처음 실행하면 프로젝트를 스캔해 `.claude/nexus/knowledge/`에 지식을 자동 생성합니다.
+
+**첫 사용**
+
+- **상담**: `[consult] 인증 시스템 어떻게 설계하면 좋을까?` — 실행 전 의도 파악, 설계 상담
+- **개발**: `[dev] 로그인 API 구현해줘` — 에이전트 팀이 분석부터 구현까지 실행
+- **리서치**: `[research] React vs Svelte 성능 비교` — 독립 조사 후 synthesis 문서 작성
+
+## 사용법
+
+| 태그 | 동작 | 예시 |
+|------|------|------|
+| `[consult]` | 실행 전 상담, 의도 파악 | `[consult] DB 마이그레이션 전략 논의` |
+| `[dev]` | 개발 실행 (Sub/Team 자동 판단) | `[dev] 결제 모듈 리팩토링` |
+| `[dev!]` | 팀 모드 강제 | `[dev!] 인증 시스템 전면 개편` |
+| `[research]` | 리서치 실행 (Sub/Team 자동 판단) | `[research] 캐싱 전략 비교 분석` |
+| `[research!]` | 리서치 팀 강제 | `[research!] 경쟁사 기술 스택 조사` |
 
-특화된 에이전트가 각각의 역할을 담당합니다.
+흐름: `[consult]`로 방향을 잡은 뒤 `[dev]` 또는 `[research]`로 실행합니다.
+
+## 에이전트
 
 ### 개발 팀 (4개)
 
@@ -35,30 +63,29 @@ claude plugin install claude-nexus@nexus
 
 ## 스킬
 
-대화형 워크플로우를 통해 복잡한 작업을 단계별로 진행합니다.
-
 | 스킬 | 트리거 | 설명 |
 |------|--------|------|
-| **nx-consult** | `[consult]` 또는 "어떻게 하면 좋을까" | 4단계 상담(Explore→Clarify→Propose→Converge) — 실행 전 의도 파악 |
-| **nx-dev** | `[dev]` 또는 "계획 세워" | Team-driven, tasks.json 중심으로 계획 생성 및 nonstop 실행 |
-| **nx-research** | `[research]` / `[research!]` | 리서치 팀(principal+postdoc+researcher) 구성 및 조사 실행 |
-| **nx-init** | `[init]` 또는 "온보딩" | 프로젝트를 Nexus에 온보드 - 기존 문서 스캔하여 지식 생성 |
-| **nx-setup** | `[setup]` 또는 "nexus 설정" | Nexus 대화형 설정 마법사 |
-| **nx-sync** | `[sync]` 또는 "지식 동기화" | 소스 코드와 지식 문서 간 불일치 감지 및 수정 |
+| **nx-consult** | `[consult]` | 구조화된 상담. 요구사항 정리 → 결정 기록(`[d]`) → 실행 태그 추천 |
+| **nx-dev** | `[dev]` / `[dev!]` | 개발 실행. 복잡도에 따라 단독 또는 팀(Director→Architect→Engineer→QA) 자동 편성 |
+| **nx-research** | `[research]` / `[research!]` | 리서치 실행. 복잡도에 따라 단독 또는 팀(Principal→Postdoc→Researcher) 자동 편성 |
+| **nx-setup** | `/claude-nexus:nx-setup` | 대화형 설정. CLAUDE.md에 에이전트/스킬/태그 설정 주입 |
+| **nx-sync** | `/claude-nexus:nx-sync` | 첫 실행 시 knowledge 자동 생성, 이후 소스 변경과의 불일치 감지 및 수정. --reset으로 초기화 가능 |
 
-## MCP 도구
+## 고급 기능
+
+<details>
+<summary>MCP 도구</summary>
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (6개)
+### Core (5개)
 
 | 도구 | 용도 |
 |------|------|
 | `nx_knowledge_read/write` | 프로젝트 지식 관리 (git 추적) |
 | `nx_context` | 현재 세션 상태 조회 |
-| `nx_task_list/add/update` | tasks.json 기반 태스크 관리 |
+| `nx_task_list/add/update/clear` | tasks.json 기반 태스크 관리 |
 | `nx_decision_add` | 아키텍처 결정 기록 |
-| `nx_plan_archive` | 완료된 계획 아카이브 |
 
 ### Code Intelligence (10개)
 
@@ -78,43 +105,43 @@ Claude가 직접 호출하는 도구입니다.
 LSP는 프로젝트 언어를 자동 감지합니다 (tsconfig.json → TypeScript 등).
 AST는 `@ast-grep/napi` 필요: `bun install @ast-grep/napi`
 
-## Hook
+</details>
+
+<details>
+<summary>Hook</summary>
 
-Gate 단일 모듈로 동작합니다 (v2에서 3개 → 1개로 통합).
+Gate 단일 모듈로 동작합니다.
 
 | 이벤트 | 역할 |
 |--------|------|
 | `UserPromptSubmit` | 프롬프트 전처리 및 컨텍스트 주입 |
 | `Stop` | 세션 종료 후처리 |
 
-## 프로젝트 지식
+</details>
 
-`.claude/nexus/knowledge/` 디렉토리에 팀이 공유하는 장기 프로젝트 지식을 저장합니다. git으로 추적됩니다.
+<details>
+<summary>프로젝트 지식</summary>
 
-```
-.claude/nexus/
-├── knowledge/              ← 공유 지식 (git 추적)
-│   ├── architecture.md
-│   ├── agents-catalog.md
-│   ├── conventions.md
-│   ├── workflows.md
-│   ├── hook-modules.md
-│   ├── mcp-tools.md
-│   ├── dev-workflow.md
-│   └── decisions/          ← 아키텍처 결정 기록
-├── config.json             ← Nexus 설정
-└── plans/                  ← 브랜치별 구현 계획
-    └── feature--*/
-        └── plan.md
-```
+`.claude/nexus/knowledge/`에 프로젝트 지식을 저장합니다. git으로 추적됩니다.
+
+- `nx-sync` 첫 실행 시 프로젝트에 맞는 knowledge 파일을 자동 생성합니다 (구조 고정 아님)
+- `config.json`에 Nexus 설정이 저장됩니다
 
-## 런타임 상태
+</details>
+
+<details>
+<summary>런타임 상태</summary>
 
 `.nexus/` 디렉토리에 런타임 상태가 저장됩니다. gitignore 대상입니다.
 
 ```
 .nexus/
-├── tasks.json              ← 태스크 목록
-├── decisions.json          ← 아키텍처 결정 목록
-└── archives/               ← 아카이브된 계획 (NN-title.md)
+├── branches/               ← 브랜치별 격리
+│   └── {branch}/
+│       ├── tasks.json      ← 태스크 목록
+│       ├── decisions.json  ← 아키텍처 결정 목록
+│       └── reports/        ← 리서치 산출물
+└── sync-state.json         ← 마지막 sync 커밋
 ```
+
+</details>

package/VERSION

@@ -1 +1 @@
-0.7.0
+0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Agent orchestration plugin for Claude Code — optimized context injection per role",
   "author": "kih",

package/skills/nx-setup/SKILL.md

@@ -88,55 +88,21 @@ chmod +x ~/.claude/hooks/nexus-statusline.sh
 
 ### Step 3: CLAUDE.md Nexus Section
 
-Generate the Nexus section in CLAUDE.md using `<!-- NEXUS:START -->` / `<!-- NEXUS:END -->` markers.
+Write the Nexus section in CLAUDE.md using `<!-- NEXUS:START -->` / `<!-- NEXUS:END -->` markers.
 
 If a Nexus section already exists, replace the content between markers. Content outside the markers is preserved unchanged.
 
 Write location depends on scope selected in Step 1.
 
-Section content:
+**Section content is NOT hardcoded here.** Read it dynamically at runtime:
 
-```markdown
-<!-- NEXUS:START -->
-## Nexus Agent Orchestration
+1. **Read `~/.claude/CLAUDE.md`** — extract content between `<!-- NEXUS:START -->` and `<!-- NEXUS:END -->` markers
+2. **If not found (first install):** Read the plugin's own CLAUDE.md from the cache directory:
+   - Glob `~/.claude/plugins/cache/nexus/claude-nexus/*/CLAUDE.md` → pick the latest version
+   - Extract the `<!-- NEXUS:START -->` to `<!-- NEXUS:END -->` section
+3. **If neither found:** Error — "Nexus 섹션 템플릿을 찾을 수 없습니다. 플러그인이 올바르게 설치되었는지 확인하세요."
 
-**Default: DELEGATE** — route code work, analysis, and multi-file changes to agents.
-
-### Agent Routing
-
-병렬 작업이나 다른 관점이 필요할 때 에이전트를 활용하라.
-
-| Task | Agent |
-|------|-------|
-| Code implementation, edits | builder |
-| Architecture, design decisions, code review | architect |
-| Debugging, tracing issues | debugger |
-| Deep analysis, research | analyst |
-| Validation, testing, security review | guard |
-
-단순 작업(파일 1-2개 읽기/수정)은 직접 처리하라.
-
-### Skills
-
-| Skill | Trigger | Purpose |
-|-------|---------|---------|
-| nx-consult | [consult] | Interactive discovery — understand intent before executing |
-| nx-team | [team] | Team-driven planning with tasks.json, nonstop execution |
-| nx-sub | [sub] | Lightweight execution — Lead analyzes directly, spawns Builder subagents |
-| nx-init | /claude-nexus:nx-init | Onboard project — generate knowledge from existing docs |
-| nx-setup | /claude-nexus:nx-setup | Configure Nexus interactively |
-| nx-sync | /claude-nexus:nx-sync | Sync knowledge docs with source files |
-
-### Tags
-
-| Tag | Purpose |
-|-----|---------|
-| [consult] | 상담 — 실행 전 의도 파악 |
-| [team] | team mode — 계획 생성 및 nonstop 실행 |
-| [sub] | 경량 실행 — Lead 직접 분석 + Builder direct spawn |
-| [d] | 결정 기록 (nx_decision_add 호출) |
-<!-- NEXUS:END -->
-```
+Write the extracted section to the target CLAUDE.md (respecting scope from Step 1).
 
 ### Step 4: OMC Conflict Detection
 
@@ -245,7 +211,7 @@ AskUserQuestion({
     multiSelect: false,
     options: [
       { label: "Yes (Recommended)", description: "기존 문서(README, CLAUDE.md 등)를 분석해 .claude/nexus/knowledge/ 생성" },
-      { label: "Skip", description: "나중에 /claude-nexus:nx-init으로 직접 실행" }
+      { label: "Skip", description: "나중에 /claude-nexus:nx-sync으로 직접 실행" }
     ]
   }]
 })
@@ -259,7 +225,7 @@ Skip 시: 다음 단계로.
 설정 완료 메시지 출력:
 - 적용된 설정 요약
 - 사용 가능한 스킬/에이전트 간략 소개
-- "시작하려면 작업을 말하거나 [consult]로 상담, [team]으로 팀 실행, [sub]로 경량 실행하세요"
+- "시작하려면 작업을 말하거나 [consult]로 상담, [dev]로 개발, [research]로 리서치하세요"
 
 ## Key Principles
 

package/skills/nx-sync/SKILL.md

@@ -1,127 +1,109 @@
 ---
 name: nx-sync
-description: Detect and fix drift between source code changes and knowledge documents.
+description: Sync knowledge documents with the current state of the codebase. On first run, scans and generates knowledge from scratch.
 triggers: ["sync", "sync knowledge", "지식 동기화", "문서 동기화"]
 ---
 
 # Sync
 
-소스 코드 변경점을 감지하고 knowledge 문서와의 불일치를 찾아 수정한다.
+knowledge 문서를 코드베이스 현황과 동기화한다. 처음 실행 시 프로젝트를 스캔하여 knowledge를 자동 생성한다.
 
-## Why This Exists
+## Trigger
 
-`.claude/nexus/knowledge/` 문서들은 에이전트의 공유 기억이다. 코드가 바뀌면 — 모듈 추가, 의존성 변경, 구조 리팩토링 — 이 문서들이 실제 코드와 어긋날 수 있다. 이 스킬은 그 drift를 잡아낸다.
+- `/claude-nexus:nx-sync` — knowledge 동기화
+- `/claude-nexus:nx-sync --reset` — knowledge 초기화 후 재생성
 
-## Prerequisites
+## Modes
 
-- **git repository** 필수. git이 없으면 변경점 추적이 불가능하므로 sync를 실행할 수 없다.
-- `.claude/nexus/knowledge/`에 knowledge 파일이 2개 이상 존재해야 한다.
+### First Run (knowledge 0개)
 
-## Process
-
-### Phase 0: Context Detection
+프로젝트 전체 스캔 → knowledge 자동 생성 + CLAUDE.md 슬림화. 사용자 승인 없이 자동 진행한다.
 
-knowledge 파일 존재 여부로 실행 모드를 결정한다.
+### Sync (knowledge 존재)
 
-```
-knowledge_files = Glob(".claude/nexus/knowledge/*.md")
-# decisions/ 하위는 ADR이므로 sync 대상에서 제외
-
-IF knowledge_files 개수 < 2:
-  → 사용자에게 안내:
-    "knowledge 파일이 부족합니다. `/claude-nexus:nx-init`을 실행하면
-     프로젝트 분석을 기반으로 knowledge가 자동 생성됩니다."
-  → 종료
-ELSE:
-  → DIFF SCAN 모드로 Phase 1 진행
-```
+git diff 기반으로 drift를 감지 → 리포트 출력 → 사용자 승인 후 수정.
 
-### Phase 1: Detect Changes (소스 변경점 감지)
+### Reset (`--reset` 플래그)
 
-#### Step 1-1: base 커밋 결정
+기존 knowledge를 삭제 → First Run으로 재진입. 사용자 확인 후 진행.
 
-```
-IF .nexus/sync-state.json 존재:
-  base = sync-state.json의 lastSyncCommit
-  git rev-parse --verify {base} 로 유효성 확인
-  유효하지 않으면 → Step 1-1 fallback
+---
 
-ELSE (fallback):
-  base = HEAD~20  # sync-state 없을 때의 안전한 기본값
-```
+## Process
 
-#### Step 1-2: 변경 파일 목록 수집
+### Phase 0: Mode Detection
 
-```bash
-git diff --name-status {base}..HEAD
 ```
+IF --reset 플래그:
+  AskUserQuestion({
+    questions: [{
+      question: "기존 knowledge 파일이 모두 삭제됩니다. 진행할까요?",
+      options: [
+        { label: "Yes", description: "기존 knowledge 삭제 후 처음부터 재생성" },
+        { label: "No", description: "취소" }
+      ]
+    }]
+  })
+  No 선택 시 → 종료
+  Yes 선택 시 → 기존 knowledge 파일 전부 삭제 → First Run 진입
+
+ELSE IF .claude/nexus/knowledge/ 에 .md 파일 0개:
+  → First Run 진입
 
-결과를 파싱하여 변경 목록을 만든다:
-- `A` (Added) → 새 파일
-- `M` (Modified) → 수정된 파일
-- `D` (Deleted) → 삭제된 파일
-- `R` (Renamed) → 이름 변경
-
-#### Step 1-3: 영향도 분류
+ELSE:
+  → Sync 진입
+```
 
-변경 파일 목록을 아래 기준으로 분류한다. **High/Medium만 후속 Phase에서 처리한다.**
+### Phase 1: Scan
 
-| 영향도 | 기준 | 예시 |
-|--------|------|------|
-| **High** | 새 디렉토리/모듈 생성, 설정 파일 변경, 의존성 변경, 진입점 변경 | 새 `src/auth/` 디렉토리, `package.json` 변경, `main.ts` 변경 |
-| **Medium** | 주요 소스 파일의 export/인터페이스/타입 변경, 파일 삭제/이름 변경 | 함수 시그니처 변경, 파일명 변경 |
-| **Low** | 내부 구현만 변경, 테스트 파일만 변경, 스타일/포맷 변경 | 함수 내부 로직, `*.test.ts` |
+#### First Run 모드
 
-**판단 방법:**
-1. 파일 경로로 1차 분류 (설정 파일, 소스 디렉토리, 테스트 등)
-2. 경로만으로 판단이 어려우면 `git diff {base}..HEAD -- {file}` 로 변경 내용을 읽어서 판단
-3. **의심스러우면 Medium 이상으로 분류** (놓치는 것보다 과탐이 낫다)
+다음 항목을 수집한다:
 
-변경 파일이 없으면:
-```
-"마지막 sync 이후 변경사항이 없습니다. (base: {base})"
-→ 종료
-```
+- **프로젝트 구조**: 최상위 디렉토리, 언어/프레임워크(package.json, Cargo.toml, pyproject.toml, go.mod 등), 빌드/테스트 시스템
+- **기존 문서**: CLAUDE.md, README.md, docs/, .cursorrules, .github/copilot-instructions.md 등 존재하는 모든 문서
+- **git 컨텍스트**: 최근 커밋 메시지, 브랜치 구조
 
-### Phase 2: Scan Knowledge (knowledge 현황 파악)
+**중요: 기존 문서의 구조나 파일명을 따르지 않는다. 수집한 정보를 바탕으로 어떤 knowledge 파일이 필요한지, 어떤 구조와 계층이 적합한지 LLM이 독자적으로 판단한다. 기존 문서는 정보 소스일 뿐이다.**
 
-`.claude/nexus/knowledge/*.md` 파일을 모두 읽는다. `decisions/` 하위 ADR 파일은 제외한다.
+#### Sync 모드
 
-각 파일에서 다음을 추출한다:
-1. **태그** — `<!-- tags: ... -->` HTML 코멘트가 있으면 파싱
-2. **헤더 구조** — `#`/`##` 헤더를 목록으로 수집
-3. **소스 참조** — 파일 내에 언급된 소스 파일 경로 (코드 블록, 인라인 코드 등)
+- `.nexus/sync-state.json`이 있으면 `lastSyncCommit`을 base로 사용. 없으면 `HEAD~20` 사용.
+- `git diff --name-status {base}..HEAD` 로 변경 파일 목록 수집
+- 변경 파일을 영향도로 분류 (High/Medium만 후속 처리, Low 스킵):
 
-이 정보로 각 knowledge 파일의 **커버리지 영역**을 파악한다.
+| 영향도 | 기준 |
+|--------|------|
+| **High** | 새 디렉토리/모듈, 설정 파일, 의존성, 진입점 변경 |
+| **Medium** | export/인터페이스/타입 변경, 파일 삭제/이름 변경 |
+| **Low** | 내부 구현만, 테스트 파일만, 스타일/포맷 변경 |
 
-예:
-```
-architecture.md → tags: [architecture, modules], 참조 경로: [src/hooks/, bridge/, agents/]
-conventions.md → tags: [conventions, style], 참조 경로: 없음 (규칙 기술)
-```
+판단이 애매하면 Medium 이상으로 분류한다. 변경 파일이 없으면 안내 후 종료.
 
-### Phase 3: Compare and Report
+### Phase 2: Analyze & Generate
 
-Phase 1의 High/Medium 변경 파일과 Phase 2의 knowledge 커버리지를 대조한다.
+#### First Run 모드
 
-#### Step 3-1: 매칭
+- 스캔 결과를 분석하여 knowledge 파일을 생성한다.
+- 파일명, 구조, 계층은 프로젝트 특성에 맞게 자유 결정. 하드코딩된 템플릿 없음.
+- CLAUDE.md 슬림화: 핵심 지시사항만 유지, 나머지는 knowledge로 이동. 원본은 `.claude/nexus/knowledge/` 에 백업. 사용자 승인은 불필요하지만 "CLAUDE.md를 슬림화합니다" 안내를 출력한다.
+- `nx_knowledge_write`로 파일 생성.
 
-각 변경 파일에 대해:
-1. knowledge 파일들의 **소스 참조**에 해당 경로가 포함되어 있는지 확인
-2. knowledge 파일들의 **태그/헤더**가 해당 변경 영역과 관련되는지 판단
-3. 매칭된 knowledge 파일의 해당 섹션을 읽어 **실제 내용이 변경 사항과 일치하는지** 확인
+#### Sync 모드
 
-#### Step 3-2: 불일치 판정
+- `.claude/nexus/knowledge/` 하위 모든 .md 파일을 읽는다 (하위 디렉토리 포함, 제외 규칙 없음).
+- 각 파일에서 태그(`<!-- tags: ... -->`), 헤더 구조, 소스 참조 경로를 추출하여 커버리지 영역을 파악한다.
+- Phase 1의 High/Medium 변경 파일과 knowledge 커버리지를 대조하여 불일치를 판정한다:
 
-| 유형 | 조건 | 예시 |
-|------|------|------|
-| **STALE** | knowledge가 기술하는 내용이 코드에서 변경됨 | architecture.md에 "모듈 3개"라고 적혀있는데 실제로 4개 |
-| **MISSING** | 새 모듈/구조가 추가됐는데 어떤 knowledge에도 기록 없음 | 새 `src/auth/` 디렉토리가 추가됐지만 architecture.md에 미기재 |
-| **ORPHAN** | knowledge가 기술하는 대상이 코드에서 삭제됨 | architecture.md에 `src/legacy/` 설명이 있는데 해당 디렉토리 삭제됨 |
+| 유형 | 조건 |
+|------|------|
+| **STALE** | knowledge가 기술하는 내용이 코드에서 변경됨 |
+| **MISSING** | 새 모듈/구조가 추가됐는데 어떤 knowledge에도 미기록 |
+| **ORPHAN** | knowledge가 기술하는 대상이 코드에서 삭제됨 |
 
-**확신이 없으면 리포트에 포함하되 `[UNCERTAIN]` 표시.** LLM이 추측으로 판정하지 않는다.
+확신이 없으면 `[UNCERTAIN]` 표시. 추측으로 판정하지 않는다.
 
-#### Step 3-3: 리포트 출력
+리포트 형식:
 
 ```
 ## Sync Report
@@ -133,46 +115,42 @@ Phase 1의 High/Medium 변경 파일과 Phase 2의 knowledge 커버리지를 대
 ### Issues Found: N
 
 #### STALE (X)
-- architecture.md §"디렉토리 구조" — src/auth/ 모듈이 추가됐지만 미기재
-- conventions.md §"네이밍" — 함수 접두사가 create→make로 변경됨
+- {파일명} §"{섹션}" — {이유}
 
 #### MISSING (X)
-- 새 모듈 src/payments/ — 어떤 knowledge에도 미기록
+- {대상} — {이유}
 
 #### ORPHAN (X)
-- architecture.md §"레거시 모듈" — src/legacy/ 삭제됨
+- {파일명} §"{섹션}" — {이유}
 
 #### UNCERTAIN (X)
-- architecture.md §"의존성" — package.json 변경됐으나 주요 의존성 변경인지 불확실
+- {파일명} §"{섹션}" — {이유}
 
 ### No Issues
-- conventions.md — 관련 변경 없음
+- {파일명} — 관련 변경 없음
 ```
 
-### Phase 4: Apply Fixes (사용자 승인 후)
-
-리포트를 제시한 뒤: **"이 불일치를 수정할까요?"**
+### Phase 3: Apply
 
-사용자가 승인하면:
+#### First Run 모드
 
-#### 수정 규칙
+자동 적용 (Phase 2에서 이미 생성됨). 완료 안내 출력: "초기 knowledge N개 파일 생성, CLAUDE.md 슬림화 완료"
 
-1. **surgical edit만** — 변경된 부분만 수정. 전체 섹션을 다시 쓰지 않는다
-2. **기존 스타일 유지** — 해당 knowledge 파일의 기존 형식(테이블, 리스트, 코드 블록 등)을 따른다
-3. **소스에 있는 정보만** — 코드에서 확인할 수 없는 내용을 추측해서 쓰지 않는다
-4. **UNCERTAIN은 건드리지 않는다** — 리포트에만 남기고 사용자가 직접 판단하도록 한다
+#### Sync 모드
 
-#### 수정 절차
+리포트 출력 후 자동으로 수정을 적용한다.
 
-각 이슈별로:
-1. 대상 knowledge 파일의 해당 섹션을 Read
-2. Edit으로 최소 범위 수정 적용
-3. MISSING의 경우: 관련 knowledge 파일이 있으면 해당 파일에 섹션 추가, 없으면 새 파일 생성을 제안 (사용자 확인 후)
-4. ORPHAN의 경우: 해당 섹션/항목을 삭제
+수정 규칙:
+1. **surgical edit만** — 변경된 부분만 수정. 전체 섹션을 재작성하지 않는다.
+2. **기존 스타일 유지** — 해당 knowledge 파일의 형식(테이블, 리스트, 코드 블록 등)을 따른다.
+3. **소스에 있는 정보만** — 코드에서 확인할 수 없는 내용을 추측하지 않는다.
+4. **UNCERTAIN은 건드리지 않는다** — 리포트에만 남기고 사용자가 직접 판단한다.
+5. MISSING: 관련 knowledge 파일이 있으면 섹션 추가, 없으면 새 파일 생성.
+6. ORPHAN: 해당 섹션/항목 삭제.
 
-#### sync-state 갱신
+### Phase 4: Finalize
 
-모든 수정 완료 후 `.nexus/sync-state.json`을 갱신한다:
+`.nexus/sync-state.json` 갱신:
 ```json
 {
   "lastSyncCommit": "{현재 HEAD 커밋 해시}",
@@ -182,11 +160,12 @@ Phase 1의 High/Medium 변경 파일과 Phase 2의 knowledge 커버리지를 대
 
 `.nexus/` 디렉토리가 없으면 생성한다.
 
-## What Belongs in Knowledge (장기 기억 기준)
+---
 
-sync가 MISSING을 판정할 때, 모든 새 코드가 knowledge에 기록될 필요는 없다. 아래 기준으로 판단한다:
+## What Belongs in Knowledge
 
 ### 기록해야 하는 것
+
 - 아키텍처: 디렉토리 구조, 모듈 간 관계, 데이터 흐름
 - 컨벤션: 네이밍 규칙, 코드 스타일, 패턴
 - 기술 스택: 언어, 프레임워크, 주요 의존성, 빌드/테스트 도구
@@ -195,18 +174,22 @@ sync가 MISSING을 판정할 때, 모든 새 코드가 knowledge에 기록될
 - 개발 워크플로우: 빌드, 테스트, 배포 명령
 
 ### 기록하지 않는 것
+
 - 구현 디테일 (함수 내부 로직) — 코드가 source of truth
 - API 스키마 — 타입 정의에서 직접 확인 가능
 - TODO/진행 상황 — tasks.json이 담당
 - 자동 조회 가능한 정보 — LSP/AST로 실시간 확인
 - 비밀 정보 — 보안 위험
 
-**판단 휴리스틱**: "이 정보가 없으면 에이전트가 코드베이스를 처음 보는 것처럼 느낄 것인가?" → Yes면 MISSING으로 보고.
+**판단 휴리스틱**: "이 정보가 없으면 에이전트가 코드베이스를 처음 보는 것처럼 느낄 것인가?" → Yes면 기록 대상.
+
+---
 
 ## Important Constraints
 
-- knowledge 문서만 수정한다. 소스 코드는 수정하지 않는다.
-- 확실하지 않은 변경은 리포트에 [UNCERTAIN]으로 포함하고, 수정하지 않는다.
-- 소스 코드에서 확인할 수 없는 정보를 추측하여 knowledge에 쓰지 않는다.
-- knowledge 파일에 새 섹션을 추가할 때는 기존 파일의 스타일/구조를 따른다.
-- git이 없는 프로젝트에서는 동작하지 않는다.
+- knowledge 문서만 수정한다 (First Run 시에는 생성도 포함). 소스 코드는 수정하지 않는다.
+- 확실하지 않은 변경은 [UNCERTAIN]으로 리포트하고 수정하지 않는다.
+- 소스에서 확인 불가한 정보를 추측하여 knowledge에 쓰지 않는다.
+- 기존 파일 삭제는 `--reset` 시에만 (사용자 확인 후).
+- git이 없는 프로젝트: First Run은 가능, Sync는 불가 (안내 후 종료).
+- 비밀 정보(API 키 등)를 knowledge에 저장하지 않는다.

package/skills/nx-init/SKILL.md

@@ -1,194 +0,0 @@
----
-name: nx-init
-description: Onboard a project to Nexus — auto-generate knowledge from existing docs.
-disable-model-invocation: true
----
-# Init
-
-Onboard Nexus into an existing project — scan, triage, and restructure project knowledge for optimal context efficiency.
-
-## Trigger
-- Direct invocation: `/claude-nexus:nx-init`
-
-## What It Does
-
-Scans the existing project, triages documentation, and generates structured Nexus knowledge files — replacing scattered .md files with a clean, efficient knowledge base.
-
-```
-SCAN → TRIAGE → PROPOSE → GENERATE → VERIFY
-```
-
-## Prerequisites
-
-- Nexus plugin must be installed and active
-- `.claude/nexus/knowledge/` directory should NOT already have project-specific files (if it does, ask user if they want to re-init)
-
-## Workflow
-
-### Phase 1: SCAN (자동)
-
-Gather all available project context:
-
-**Project Structure:**
-```
-- List top-level directories and their purpose (src/, test/, docs/, config files)
-- Identify language/framework (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
-- Identify build system, test framework, linter
-- Count files by type for scale understanding
-```
-
-**Existing Documentation:**
-```
-- CLAUDE.md (always loaded by Claude Code — most critical)
-- README.md
-- .claude/ directory contents (contexts, settings, etc.)
-- docs/ directory if exists
-- Any other .md files in project root
-- .cursorrules, .github/copilot-instructions.md, etc. (other AI tool configs)
-```
-
-**Git Context:**
-```
-- Recent commit messages (last 20) for project activity pattern
-- Branch structure for workflow understanding
-- Contributors for team context
-```
-
-Output: A structured summary of everything found.
-
-### Phase 2: TRIAGE (자동)
-
-Classify every piece of existing documentation into 4 categories:
-
-| Category | Meaning | Action |
-|----------|---------|--------|
-| **Essential** | Architecture, conventions, decisions that agents MUST know | → `knowledge/` |
-| **Useful** | Tips, practices, context that helps but isn't critical | → `knowledge/` (condensed) |
-| **Redundant** | Info that Nexus handles better (workflow instructions, agent tips) | → Skip |
-| **Outdated** | Stale, auto-generated, or no longer relevant | → Skip |
-
-**Triage Rules:**
-- Code structure descriptions → Essential (architecture.md)
-- Coding conventions, style rules → Essential (conventions.md)
-- Architecture decisions with rationale → Essential (decisions/)
-- Project goals, roadmap, team context → Useful (project-context.md)
-- "How to use Claude" instructions → Redundant (Nexus replaces this)
-- Auto-memory instructions, hook configs → Redundant
-- Old TODO lists, resolved issues → Outdated
-- Generated API docs → Outdated (can be regenerated)
-
-### Phase 3: PROPOSE (사용자 상호작용)
-
-Present the triage result using `AskUserQuestion`:
-
-```
-AskUserQuestion({
-  questions: [
-    {
-      question: "CLAUDE.md 슬림화 방식을 선택해주세요.",
-      header: "CLAUDE.md",
-      multiSelect: false,
-      options: [
-        {
-          label: "슬림화 (Recommended)",
-          description: "핵심 지시사항만 유지, 나머지는 knowledge/로 이동",
-          preview: "## 기존 CLAUDE.md (150줄)\n핵심 지시: 15줄\n프로젝트 지식: 100줄 → knowledge/로\n중복/불필요: 35줄 → 제거\n\n## 새 CLAUDE.md (20줄)\n- 핵심 지시사항 (15줄)\n- Nexus 연동 안내 (5줄)"
-        },
-        {
-          label: "유지 + 추가만",
-          description: "기존 CLAUDE.md 건드리지 않고 Nexus 연동만 추가"
-        },
-        {
-          label: "완전 교체",
-          description: "CLAUDE.md를 Nexus 전용으로 교체 (기존은 백업)"
-        }
-      ]
-    },
-    {
-      question: "knowledge 파일로 이동할 항목을 확인해주세요.",
-      header: "Knowledge",
-      multiSelect: true,
-      options: [
-        { label: "architecture.md", description: "코드 구조, 기술 스택, 주요 의존성" },
-        { label: "conventions.md", description: "코딩 규칙, 네이밍, 패턴" },
-        { label: "project-context.md", description: "프로젝트 목적, 현재 상태, 팀 컨텍스트" }
-      ]
-    }
-  ]
-})
-```
-
-Note: The actual options should be populated based on SCAN/TRIAGE results, not hardcoded. The above is a template.
-
-### Phase 4: GENERATE (자동)
-
-Based on user approval:
-
-1. **Backup existing CLAUDE.md:**
-```
-cp CLAUDE.md .claude/nexus/knowledge/original-claude-md.md
-```
-
-2. **Generate knowledge files** in `.claude/nexus/knowledge/`:
-```
-architecture.md:
-  - # {Project Name} Architecture
-  - ## Tech Stack (language, framework, build, test)
-  - ## Directory Structure (with purpose annotations)
-  - ## Key Dependencies
-  - ## Entry Points
-
-conventions.md:
-  - # Coding Conventions
-  - ## Style (from existing linter/prettier config + CLAUDE.md rules)
-  - ## Naming Patterns (from code analysis)
-  - ## Testing Conventions
-  - ## Git/PR Conventions
-
-project-context.md:
-  - # Project Context
-  - ## Purpose (from README/CLAUDE.md)
-  - ## Current State (from git activity)
-  - ## Team Context (if available)
-  - ## Key Decisions (extracted from docs)
-```
-
-3. **Slim down CLAUDE.md** (if user chose slimming):
-```markdown
-# {Project Name}
-
-{핵심 지시사항 — 기존에서 추출, 5-15줄}
-
-## Nexus
-- 프로젝트 지식: `.claude/nexus/knowledge/` 참조
-- 아카이브: `.nexus/archives/` (로컬, 세션 독립)
-- 원본 CLAUDE.md: `.claude/nexus/knowledge/original-claude-md.md`
-```
-
-4. **Add `.claude/nexus/` to git** if not already tracked.
-
-### Phase 5: VERIFY (자동)
-
-Quick validation:
-1. All generated knowledge files are valid markdown
-2. `nx_knowledge_read` can read them successfully
-3. CLAUDE.md is valid and not empty
-4. Original CLAUDE.md backup exists
-5. Report: "Init 완료. knowledge N개 파일, CLAUDE.md X줄 → Y줄"
-
-## Important Constraints
-
-- NEVER delete existing files without user approval — always backup first
-- If `.claude/nexus/knowledge/` already has files, ask before overwriting
-- If CLAUDE.md has critical instructions (API keys, deploy commands), keep them in CLAUDE.md
-- Don't extract secrets or credentials into knowledge files
-- If the project has no CLAUDE.md, create a minimal one
-
-## Re-init
-
-If nexus knowledge already exists, `[init]` should:
-1. Detect existing knowledge files
-2. Ask: "기존 knowledge가 있습니다. 다시 초기화할까요?"
-3. If yes: backup existing knowledge to `.claude/nexus/knowledge/backup-{date}/`
-4. Re-run full workflow
-