@moreih29/nexus-core 0.11.0 → 0.13.0

package/assets/schema/lsp-servers.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moreih29/nexus-core/assets/schema/lsp-servers.schema.json",
+  "title": "Nexus Core — LSP Servers Configuration",
+  "type": "object",
+  "required": ["languages"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "languages": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/LanguageDef"
+      }
+    }
+  },
+  "$defs": {
+    "LanguageDef": {
+      "type": "object",
+      "required": ["extensions", "server", "install_hint"],
+      "additionalProperties": false,
+      "properties": {
+        "extensions": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "server": {
+          "$ref": "#/$defs/ServerDef"
+        },
+        "install_hint": {
+          "type": "string"
+        }
+      }
+    },
+    "ServerDef": {
+      "type": "object",
+      "required": ["command_chain", "args"],
+      "additionalProperties": false,
+      "properties": {
+        "command_chain": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        },
+        "search_paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/assets/skills/nx-init/body.ko.md

@@ -0,0 +1,197 @@
+---
+name: nx-init
+description: Project onboarding — scan, mission, essentials, context generation
+summary: "Project onboarding — scan, mission, essentials, context generation"
+manual_only: true
+harness_docs_refs:
+  - instruction_file
+  - slash_command_display
+id: nx-init
+---
+
+## Role
+
+프로젝트를 스캔하고 flat `.nexus/` 구조에 Nexus 지식을 구축한다. 최초 실행 시 5단계 전체 온보딩 시퀀스를 수행한다.
+
+## Constraints
+
+- 소스 코드를 절대 수정하지 않는다. instruction 파일의 project 섹션 외 부분을 줄이는 것은 이 skill의 책임이 아니다.
+- 코드에서 확인할 수 없는 정보는 추론하거나 추측하지 않는다 — context/에 작성하지 않는다.
+- 지식 파일에 secrets (API 키, credentials 등)를 저장하지 않는다.
+- `--reset` 없이는 기존 파일을 덮어쓰지 않는다. 재개 시 기존 파일을 그대로 보존한다.
+- instruction 파일의 project 섹션은 반드시 사용자 확인을 거쳐 작성한다.
+- identity/, codebase/, reference/, core/ 경로를 참조하거나 생성하지 않는다.
+- Essentials 섹션은 10줄을 초과하지 않는다. 항목이 더 필요하면 우선순위가 낮은 항목을 .nexus/context/로 이동한다.
+
+## Guidelines
+
+## Trigger
+
+- 수동 트리거 — 전체 온보딩(또는 재개). harness 문서 참조: slash_command_display.
+- `--reset` 플래그와 함께 수동 트리거 — 기존 `.nexus/` 지식을 백업하고 재온보딩. harness 문서 참조: slash_command_display.
+- `--reset --cleanup` 플래그와 함께 수동 트리거 — 백업 목록 표시 + 선택적 삭제. harness 문서 참조: slash_command_display.
+
+---
+
+## Modes
+
+### First Run (`.nexus/` flat 구조 없음)
+
+5단계 전체 온보딩을 자동으로 실행한다.
+
+감지 기준: `.nexus/context/`, `.nexus/memory/`, `.nexus/state/`, `.nexus/rules/`가 존재하지 않음.
+
+### Resume (`.nexus/`가 부분적으로 존재)
+
+기존 상태를 확인하고 첫 번째 미완료 단계부터 재개한다.
+
+### Reset (`--reset`)
+
+기존 `.nexus/` 지식 디렉터리를 `.nexus/bak.{timestamp}/`로 백업한 뒤 First Run으로 진입한다.
+
+### Cleanup (`--reset --cleanup`)
+
+백업 디렉터리 목록을 표시하고, 사용자가 삭제할 백업을 선택하도록 한다.
+
+---
+
+## Process
+
+### Phase 0: Mode Detection
+
+```
+IF --reset --cleanup flag:
+  .nexus/bak.*/ 디렉터리 목록을 표시
+  `{{user_question question="Select a backup to delete (or cancel)" options=[<backup list...>, {label: Cancel, description: "Exit without changes"}]}}`를 통해 사용자에게 옵션 제시.
+  선택한 백업을 삭제하고 종료
+
+ELSE IF --reset flag:
+  .nexus/{memory,context,state,rules}/ → .nexus/bak.{timestamp}/로 이동
+  안내: "Existing knowledge has been backed up to .nexus/bak.{timestamp}/. Starting re-onboarding."
+  → First Run으로 진입
+
+ELSE IF .nexus/context/ 존재:
+  → Resume으로 진입 (기존 단계 확인 후 재개)
+
+ELSE:
+  → First Run으로 진입 (Step 1부터)
+```
+
+---
+
+## Steps
+
+### Step 1: Project Scan
+
+코드 구조와 기술 스택을 자동 감지한다. `.nexus/` 디렉터리 구조가 존재하지 않으면 생성한다.
+
+디렉터리 생성 (shell 명령어 실행):
+- `.nexus/memory/`
+- `.nexus/context/`
+- `.nexus/state/`
+- `.nexus/rules/`
+
+수집 항목:
+- **디렉터리 구조**: 최상위 레이아웃, 주요 모듈/패키지
+- **기술 스택**: 언어, 프레임워크, 런타임 (package.json, Cargo.toml, pyproject.toml, go.mod, build.gradle 등)
+- **빌드/test 시스템**: 스크립트, CI 설정
+- **기존 문서**: CLAUDE.md, README.md, docs/, .cursorrules 등
+- **git context**: 최근 커밋, 브랜치 구조, 기여자
+
+출력: 스캔 요약 (언어, 프레임워크, 구조 개요)
+
+대규모 프로젝트(최상위 디렉터리 10개 이상 또는 파일 100개 이상)의 경우, Lead context 사용을 줄이기 위해 Explore subagent를 스폰하여 병렬 스캔을 수행하는 것을 고려한다.
+
+### Step 2: Mission + Essentials (Interactive)
+
+Step 1 스캔 결과를 바탕으로 Mission 문장(1–2줄)과 Essentials 목록 초안을 작성한 뒤, 한 번에 사용자에게 제시하여 확인을 받는다.
+
+#### Essentials Guidelines
+
+Essentials는 에이전트에게 필수적인 사실이다 — 알지 못하면 에이전트가 잘못된 결과를 낼 항목들이다. 판단 기준: **"이것을 모르면 에이전트가 잘못된 결과를 낼까?"** 그렇다면 → Essentials. 아니라면 → .nexus/context/.
+
+다음 다섯 범주에서 초안을 작성한다 (해당되는 항목만 포함):
+
+- **Tech stack** — 런타임, 언어, 패키지 매니저, 핵심 프레임워크. 비기본 도구는 표시한다 (예: npm 대신 bun, node 대신 deno).
+- **Workflow** — 빌드, test, 배포 명령어. 커밋 전 필수 lint 또는 타입 검사 단계 등 반드시 따라야 하는 절차.
+- **Constraints** — 사용 금지 도구, 패턴, 또는 접근법. 수정해서는 안 되는 디렉터리 또는 파일.
+- **Domain** — 대상 사용자, 필수 용어 또는 톤, 연구 프로젝트의 컴플라이언스·규제 제약·방법론.
+- **Conventions** — 일반 기본값에서 벗어난 명명, 구조, 또는 스타일. 에이전트가 추론하지 못할 프로젝트 고유 패턴.
+
+감지된 기술 스택의 표준 기본값에 해당하는 항목은 포함하지 않는다. Essentials 섹션은 총 10줄을 초과하지 않는다.
+
+#### Draft Presentation
+
+다음 형식으로 전체 초안을 사용자에게 제시한다:
+
+```
+The following will be added to the instruction file (see harness docs: instruction_file) (existing content will not be changed):
+
+<!-- PROJECT:START -->
+## {project-name}
+
+{mission 1-2 lines}
+
+### Essentials
+- {auto-detected item}
+- {auto-detected item}
+<!-- PROJECT:END -->
+
+Any changes?
+```
+
+사용자의 확인 또는 수정 의견을 기다린다. 모든 변경 사항을 한 번에 반영한다 — Mission과 Essentials를 별도로 묻지 않는다.
+
+확인 후, harness의 파일 편집 프리미티브를 사용하여 마커 안에 섹션을 instruction 파일에 작성한다. instruction 파일에 이미 `<!-- PROJECT:START -->` 마커가 있으면 그 사이 내용을 교체한다. instruction 파일이 존재하지 않으면 마커와 함께 새로 생성한다.
+
+### Step 3: Context Knowledge Auto-Generation
+
+Step 1 스캔 결과를 분석하여 `.nexus/context/`에 context 지식 문서를 생성한다.
+
+원칙:
+- 파일 이름과 내용은 프로젝트 특성에 따라 자유롭게 결정한다. 고정된 템플릿은 없다.
+- 기존 문서는 정보 출처일 뿐 — 구조를 그대로 복제하지 않는다.
+- 코드에서 확인할 수 없는 내용은 추측하여 작성하지 않는다.
+- 보통 1–3개 파일로 충분하다. 파일이 많다고 좋은 것이 아니다.
+- **추상 수준의 내용만 생성한다** — 설계 패턴, 아키텍처 방향, 모듈 관계, 컨벤션. 파일 목록, 함수 시그니처, import 맵 같은 코드 수준 세부 사항은 포함하지 않는다. 그런 내용은 코드에서 직접 읽을 수 있다.
+
+생성 대상 (프로젝트 실제 필요에 따라 선택하고 명명):
+- 개발 스택 (언어, 프레임워크, 런타임, 핵심 의존성, 빌드/test/배포 워크플로우)
+- 설계 및 아키텍처 (모듈 관계, 데이터 흐름, 핵심 진입점, 컨벤션)
+- 구현 세부 사항 (파이프라인 세부 사항, 설정 패턴, 파일 구조 컨벤션, 도구 제한 — instruction 파일에 담기엔 너무 구체적이지만 코드만으로는 파악하기 어려운 내용)
+
+harness의 파일 생성 프리미티브를 사용하여 `.nexus/context/{chosen-name}.md`에 파일을 생성한다.
+
+대규모 프로젝트의 경우, 주제별로 Writer subagent를 스폰하여 context 지식을 병렬로 생성한다. Lead가 조율하고 결과를 검토한다.
+
+완료 시: "context knowledge N files generated" 출력
+
+### Step 4: Rules Initial Setup (Optional)
+
+팀 커스텀 rule이 필요한지 확인한다.
+
+```
+{{user_question question="Do you want to set up development rules now?" options=[{label: "Set up", description: "Coding conventions, test policy, commit rules, etc."}, {label: Skip, description: "Can be added later via [rule] tag"}]}}
+```
+
+"Set up" 선택 시: 스캔 결과를 바탕으로 초안을 제시 → 사용자 확인 → harness의 파일 생성 프리미티브를 사용하여 `.nexus/rules/{topic}.md`에 저장한다.
+
+"Skip" 선택 시: 안내 후 Step 5로 진행한다.
+
+### Step 5: Completion Summary
+
+온보딩 결과 요약을 출력한다.
+
+```
+## Nexus Initialization Complete
+
+### Generated Files
+- instruction file: project section — mission and essentials (<!-- PROJECT:START/END -->)
+- .nexus/context/: {생성된 파일 목록}
+- .nexus/rules/: {생성된 파일 또는 "none (skipped)"}
+
+### Next Steps
+- [plan] — 실행 전 리서치, 분석, 계획 수립
+- [run] — plan에서 실행
+- `--reset` 플래그와 함께 수동 재실행 — 온보딩 재실행 (기존 지식은 백업됨). harness 문서 참조: slash_command_display.
+```

package/{skills → assets/skills}/nx-init/body.md

@@ -1,3 +1,14 @@
+---
+name: nx-init
+description: Project onboarding — scan, mission, essentials, context generation
+summary: "Project onboarding — scan, mission, essentials, context generation"
+manual_only: true
+harness_docs_refs:
+  - instruction_file
+  - slash_command_display
+id: nx-init
+---
+
 ## Role
 
 Scans the project and builds Nexus knowledge in the flat .nexus/ structure. On first run, performs a 5-step full onboarding sequence.

package/assets/skills/nx-plan/body.ko.md

@@ -0,0 +1,361 @@
+---
+name: nx-plan
+description: Structured multi-perspective analysis to decompose issues, align on
+  decisions, and produce an enriched plan before execution. Plan only — does not
+  execute.
+summary: "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan"
+triggers:
+  - plan
+harness_docs_refs:
+  - resume_invocation
+id: nx-plan
+---
+
+## Role
+
+서브에이전트를 활용한 구조적 다각도 분석을 진행자로서 수행한다. 안건을 분해하고, 선택지를 숙의하며, 결정에 합의한다. Lead는 종합자이자 능동적 참여자로서 — 서브에이전트 리서치·분석을 조율하면서 동시에 자신의 입장을 제시한다. 실행은 하지 않는다 — planning only. 실행으로의 전환은 사용자의 결정이다.
+
+## Constraints
+
+- NEVER execute — 이 스킬은 planning only다. 실행으로의 전환은 사용자의 결정이다
+- NEVER call `nx_plan_start` before research is complete (research_summary is required)
+- NEVER present multiple issues at once — one issue at a time only
+- NEVER ask groundless questions — always research code/knowledge/decisions first
+- NEVER use the harness's team creation primitive. Inter-agent messaging for resume is permitted ONLY for resuming completed subagents whose `resume_tier` is `persistent` or `bounded`, and ONLY within the constraints of the Resume Policy section below. Direct inter-agent communication to running teammates remains forbidden in plan sessions.
+- MUST record all decisions with `[d]` tag so they are not scattered across turns
+- MUST call `nx_plan_decide` when recording `[d]`
+- MUST check for existing plan.json before starting a new session
+- `[d]` without an active plan.json is BLOCKED — "[d]는 plan 세션 안에서만 유효합니다."
+- MUST present a comparison table before asking for a decision — never present options as prose only. Format:
+
+```
+| | A: {title} | B: {title} |
+|---|---|---|
+| Pros | ... | ... |
+| Cons | ... | ... |
+| Pick | | **(Recommended)** |
+```
+
+## Guidelines
+
+## Trigger
+
+- 명시적 태그: `[plan]` — plan.json이 존재하면 기존 세션을 계속하고, 없으면 새 세션을 시작한다
+- 세션 도중 추가 분석이 필요한 경우: harness의 subagent spawn primitive를 통해 HOW 서브에이전트를 독립적으로 스폰한다
+- 태그 없이 대화 계속 → 기존 세션 유지
+
+---
+
+## Auto Mode (`[plan:auto]`)
+
+`[plan:auto]`로 트리거되거나 `{{skill_activation skill=nx-plan mode=auto}}`로 호출되면, **사용자 인터랙션 없이** 전체 planning 프로세스를 실행한다:
+
+1. **Research** — researcher+Explore 서브에이전트 스폰 (interactive와 동일)
+2. **안건 도출** — Lead가 리서치 결과에서 안건을 도출한다
+3. **Auto-decide** — 각 안건에 대해 Lead가 선택지를 제시하지 않고 권장 옵션을 선택한다. 각 `nx_plan_decide(summary)`는 반드시 포함해야 한다: 선택한 접근법 + 이유, 그리고 기각한 대안 + 기각 이유. 비교 테이블은 불필요하지만 내부 숙의는 필수다.
+4. **결정 브리핑** — 태스크 생성 전 모든 결정의 간결한 요약을 출력한다:
+   ```
+   [auto-plan complete] N issues, N decisions:
+   - #1: {selected} ({rejected alternative} — reason)
+   - #2: ...
+   ```
+   사용자 응답을 기다리지 않고 즉시 태스크 생성으로 진행한다.
+5. **Plan document** — Step 7 규칙에 따라 tasks.json을 생성한다 (plan.json issues에 `how_agents`가 있으면 HOW-assisted 분해 포함). owner 테이블과 verification auto-pairing을 적용한다.
+
+interactive 모드와의 주요 차이점:
+- 사용자 프롬프트나 비교 테이블 없음 — Lead가 자율적으로 결정한다
+- 동적 agenda 제안 없음 — Lead가 도출된 모든 안건을 내부적으로 처리한다
+- 출력: `[run]` 실행을 위한 tasks.json 준비 완료
+
+**호출 컨텍스트별 SCOPE:**
+- `[plan:auto]` 단독 → auto-plan + 브리핑 + tasks.json 생성. 여기서 종료.
+- `[run]`에 의해 호출됨 (tasks.json 없는 경우) → auto-plan + 브리핑 + tasks.json 생성 + 끊김 없는 실행 전환. plan과 run 사이에 일시정지 없음.
+
+이 모드는 tasks.json이 없을 때 `[run]`이 내부적으로 호출하거나, 사용자가 `[plan:auto]`로 명시적으로 호출한다.
+
+---
+
+## Procedure (Interactive Mode)
+
+### Step 1: Intent Discovery
+
+planning 깊이를 결정하고, Progressive Depth에 기반하여 분석을 위임할 HOW 서브에이전트를 파악한다.
+
+| Level | Signal | Exploration Scope |
+|-------|--------|-------------------|
+| **Specific** | 파일 경로, 함수명, 에러 메시지, 또는 구체적인 대상이 명시됨 | 해당 파일/모듈에 집중 |
+| **Direction-setting** | 열린 질문, "~하면 좋겠다", 접근법 중 선택 필요 | 관련 영역 + 외부 사례 리서치 |
+| **Abstract** | "어떻게 접근해야 할지 모르겠다", 목표 자체가 불명확, 근본적인 방향 설정 | 전체 코드베이스 + 외부 리서치 + 유사 프로젝트 비교 |
+
+- Specific 요청 → 1–2개 질문으로 의도를 확인하고 즉시 안건을 도출한다
+- Direction-setting → 가설 기반 질문으로 의도를 파악한다
+- Abstract/fundamental → 사용자가 명확히 하지 않은 근본 목표를 발굴하기 위해 적극적으로 인터뷰한다
+
+**HOW 서브에이전트 선택 규칙:**
+- 사용자가 에이전트를 명시적으로 지정 → 그대로 사용하되, 빠진 부분이 감지되면 추가를 제안한다
+- 사용자가 에이전트를 지정하지 않음 → Lead가 안건 SCOPE에 기반하여 제안하고 사용자에게 확인받는다
+- 추가 HOW 서브에이전트는 분석 중 언제든지 스폰할 수 있다 (Lead 또는 사용자의 판단으로)
+
+### Step 2: Research
+
+planning agenda를 수립하기 전에 코드, 핵심 지식, 기존 결정을 파악한다.
+
+**기존 지식부터 확인한다**: 서브에이전트를 스폰하기 전에, 파일 패턴 검색과 파일 읽기를 통해 `.nexus/memory/`와 `.nexus/context/`에서 관련 메모와 context 파일을 스캔하고, `nx_history_search`로 해당 주제의 기존 결정을 확인한다. 필요한 정보가 이미 있으면 그대로 활용하고 서브에이전트 스폰을 생략하거나 범위를 줄인다. 기존 지식으로 커버되지 않는 빈 곳을 채우기 위해서만 서브에이전트를 스폰한다.
+
+**접근법 선택:**
+
+| Scenario | Approach |
+|----------|----------|
+| 코드베이스 파악 | `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` 코드베이스 탐색 |
+| 외부 리서치 필요 | `{{subagent_spawn target_role=researcher prompt="<research question>"}}` 웹 검색 |
+| 코드베이스 + 외부 모두 | Explore + Researcher 병렬 스폰 |
+
+- NEVER call `nx_plan_start` before research is complete.
+- `nx_plan_start`의 `research_summary` 파라미터는 필수 — 세션 생성 전 리서치 완료를 강제한다.
+- Researcher 서브에이전트는 harness의 subagent spawn primitive를 통해 스폰되며 결과를 Lead에 반환한다. plan 세션에는 합류하지 않는다.
+
+**기존 세션 (plan.json 존재):**
+- `nx_plan_status`로 현재 상태를 확인한다.
+- 새 주제나 추가 리서치가 필요하면 → 그에 맞게 researcher 서브에이전트를 스폰한다.
+- 리서치가 완료되기 전에 다음 안건으로 진행하지 않는다.
+
+### Step 3: Session Setup
+
+planning 세션을 등록한다.
+
+1. **`nx_plan_start(topic, issues, research_summary)`** — plan.json에 plan을 등록한다. 기존 plan.json이 있으면 자동으로 아카이브한다.
+2. 안건 목록을 사용자에게 보여주고 진행 전 확인받는다.
+
+### Step 4: Analysis
+
+**항상 한 번에 하나의 안건만 진행한다.** 여러 안건을 동시에 제시하지 않는다.
+
+각 안건에 대해:
+
+1. **현재 상태 분석** — Lead가 리서치를 바탕으로 현재 상태와 문제점을 요약한다.
+2. **서브에이전트 분석** — 복잡한 안건의 경우, harness의 subagent spawn primitive를 통해 HOW 서브에이전트(architect, strategist 등)를 병렬로 스폰한다. 각 서브에이전트가 독립적으로 안건을 분석하고 결과를 반환한다.
+   - **도메인-에이전트 매핑** — 안건 키워드를 권장 HOW 서브에이전트에 매핑한다:
+
+   | Domain keywords | Recommended HOW |
+   |----------------|-----------------|
+   | UI, UX, 디자인, 인터페이스, 사용자 경험, 레이아웃 | Designer |
+   | 아키텍처, 시스템 설계, 성능, 구조 변경, API, 스키마 | Architect |
+   | 비즈니스, 시장, 전략, 포지셔닝, 경쟁, 수익 | Strategist |
+   | 연구 방법론, 근거 평가, 문헌, 실험 설계 | Postdoc |
+
+   - **Opt-out 기본값**: 안건이 매핑의 도메인과 일치하면, 스폰이 기본이다. 복수 매핑 → 복수 스폰. 건너뛰려면 분석 텍스트에 "{Agent} not needed — reason: ..."를 명시한다.
+   - **매핑 없음**: 일치하는 도메인이 없으면 Lead가 직접 분석한다. 불확실할 때는 스폰한다 — 불필요한 스폰의 비용이 얕은 분석의 비용보다 낮다.
+   - **HOW 결과 기록**: HOW 서브에이전트가 반환한 후, `nx_plan_decide(how_agents=[...], how_summary={...})`로 결정을 기록할 때 에이전트 이름과 핵심 결과를 포함한다. 이 데이터는 Step 7 태스크 생성을 위해 plan.json에 저장된다.
+3. **선택지 제시** — 종합 후 Lead가 비교를 제시한다:
+
+```
+| Item | A: {title} | B: {title} | C: {title} |
+|------|-----------|-----------|-----------|
+| Pros | ... | ... | ... |
+| Cons | ... | ... | ... |
+| Trade-offs | ... | ... | ... |
+| Best for | ... | ... | ... |
+
+**Recommendation: {X} ({title})**
+
+- Option A falls short because {reason}
+- Option B falls short because {reason}
+- Option X overcomes {A/B limitations} → {core benefit}
+```
+
+4. **사용자 응답 대기** — 자유 형식의 응답을 받는다. 사용자는 선택지를 조합하거나, 반박하거나, 후속 질문을 할 수 있다.
+
+## Resume Policy
+
+harness의 resume 메커니즘을 사용할 수 없으면, 모든 resume 경로가 비활성화된다 — 새로 스폰을 강제한다. 그 외:
+
+| resume_tier | Same-issue default | Cross-issue | Disqualifiers |
+|---|---|---|---|
+| persistent | 기본적으로 resume | Lead opt-in only | 반증 / 번복 / 재검토 안건 → 새로 스폰 |
+| bounded | 조건부 (동일 artifact에 한함) | 금지 | 3회 루프 / 피드백 사이클 (REVISION_REQUIRED) → 새로 스폰 |
+| ephemeral | 금지 | 금지 | N/A (항상 새로 스폰) |
+
+`bounded` 에이전트를 resume하기 전: 프롬프트에 "수정 전 대상 파일을 다시 읽을 것" 지시를 포함한다. re-read 없는 bounded resume은 BLOCKED.
+
+`resume_tier`는 각 에이전트의 frontmatter (`agents/*.md`)에서 읽는다. 없으면 `ephemeral`로 처리한다 (가장 보수적).
+
+### Step 5: Record Decision
+
+사용자가 결정하면 `[d]` 태그로 기록한다.
+
+- gate.ts가 `[d]`를 감지하여 `nx_plan_decide`로 라우팅한다.
+- `nx_plan_decide(issue_id, summary)` — 안건을 `decided`로 표시하고 plan.json에 인라인으로 `decision`을 기록한다.
+- 결정은 decisions.json에 기록하지 않는다 — plan.json이 단일 진실 소스다.
+- plan.json 없이 `[d]`를 사용하면 차단된다.
+- **Progress anchoring**: 기록 직후 한 줄을 출력한다: "Issue #N decided (M of K complete). Next: #X — {title}." 멀티 안건 세션에서 사용자가 진행 상황을 파악하게 한다.
+
+**각 결정 직후**, Lead는 확인한다: "이 결정이 후속 질문이나 새로운 안건을 만들어내는가?" 그렇다면 다음 안건으로 이동하기 전에 `nx_plan_update(action='add')`로 추가를 제안한다.
+
+**결정 번복**: 사용자가 기존 결정을 재고하려 할 때 ("아까 결정 다시 생각해보자", "issue #N 번복"), Lead는 `nx_plan_update(action='reopen', issue_id=N)`을 호출하여 안건을 재개하고 Step 4 분석으로 돌아간다.
+
+### Step 6: Dynamic Agenda + Wrap-up
+
+각 결정 후 Lead는 자동으로 파생 안건을 확인한다.
+
+- **Dynamic agenda 제안**: 결정이 기록된 후, Lead는 해당 결정이 후속 질문이나 미해결 하위 안건을 내포하는지 검토한다. 발견되면 `nx_plan_update(action='add', ...)`로 추가를 제안하고 추가 전 사용자에게 확인받는다.
+- 미결 안건이 남아 있으면 → 자연스럽게 다음 안건으로 전환한다.
+- 모든 안건이 결정됨 → **Gap check**: 원래 질문/주제를 안건 목록과 대조한다.
+  - Gap 발견 → `nx_plan_update(action='add', ...)`로 추가 안건을 등록하고 Step 4로 돌아간다.
+  - Gap 없음 → planning 완료를 알린다.
+- Wrap-up: 모든 분석 스레드가 Lead에 결론을 보고했는지 확인한다.
+- 자동으로 Step 7로 진행한다 — plan document 생성 여부를 묻지 않는다.
+
+### Step 7: Plan Document Generation
+
+모든 안건이 결정되면 즉시 plan document (tasks.json)를 생성한다:
+
+1. **결정 수집** — plan.json에서 모든 `decided` 안건을 수집한다
+2. **태스크 도출** — 결정을 구체적이고 실행 가능한 태스크로 분해한다
+
+   **HOW-assisted 태스크 분해**: plan.json issues의 `how_agents` 필드를 확인한다.
+   - HOW 에이전트가 분석에 참여했으면 → 결정된 접근법 + 기존 `how_summary`를 컨텍스트로 해당 HOW를 다시 스폰한다. 해당 도메인의 태스크 분해와 owner 배정을 제안하도록 요청한다.
+   - HOW 에이전트가 참여하지 않았으면 → Lead가 아래 owner 테이블과 auto-pairing 규칙을 사용하여 단독으로 분해한다.
+   - 이를 통해 태스크 생성 깊이가 plan 분석 깊이에 비례하게 된다.
+
+3. **각 태스크를 보강한다**:
+   - `approach` — 결정 근거에서 도출한 구현 전략
+   - `acceptance` — 완료 정의, 검증 가능한 기준
+   - `risk` — 분석에서 나온 알려진 위험 또는 주의사항
+   - `deps` — 실행 순서에 기반한 태스크 의존성
+   - `owner` — 위임 분석에 기반하여 배정:
+
+   | Work type | owner | Criteria |
+   |-----------|-------|----------|
+   | 단일 파일, 소규모 변경 | **lead** | 서브에이전트 오버헤드 > 태스크 노력 |
+   | 코드 구현 (.ts, .js, .py 등) | **engineer** | 소스 코드 생성/수정 |
+   | 문서/콘텐츠 (.md, 비코드) | **writer** | .md 파일, README, docs, 비코드 콘텐츠 |
+   | 웹 리서치 / 외부 조사 | **researcher** | 외부 정보 수집 필요 |
+   | 설계 분석 / 리뷰 | **architect** 등 HOW | 기술적 trade-off 판단 |
+   | 동일 파일의 순차적 편집 | **lead** | 병렬 서브에이전트는 충돌 위험 |
+
+   **Primary metric — artifact-coherence**: 잘 구성된 태스크는 단일 artifact 또는 긴밀하게 연결된 artifact 클러스터를 대상으로 하며 단일하고 일관된 변경을 수행한다. 변경이 일관된 경우: (a) 한 문장으로 설명할 수 있고, (b) 되돌려도 다른 모든 artifact가 일관성을 유지하며, (c) 출력만 검사하여 acceptance를 검증할 수 있다.
+
+   **Verification auto-pairing (조건부)** — DO 태스크의 acceptance에 적절한 검증 트리거가 포함된 경우에만 CHECK 태스크를 생성한다:
+   - `owner: "engineer"` + acceptance에 런타임 동작 기준 포함 → **tester** 태스크를 페어링한다.
+   - `owner: "writer"` + acceptance에 검증 가능한 산출물 기준 포함 → **reviewer** 태스크를 페어링한다.
+   - 제외: 순수 리팩터 (동작 보존), 타입 전용 변경, docs 인접 태스크 (`vocabulary/task-exceptions.yml`의 `docs_only` 항목으로 분류된 .md 또는 frontmatter 전용), researcher 태스크. Researcher 태스크는 auto-paired CHECK를 받지 않는다 — 리서치 출력은 tester나 reviewer가 아닌 Lead 또는 HOW 에이전트에 직접 전달된다.
+   - 페어링된 검증 태스크는 `deps`를 통해 원래 태스크에 연결된다.
+
+   **Exception catalog**: 태스크 분해 예외는 `vocabulary/task-exceptions.yml`에 정의된다 (`docs_only.coherent`, `docs_only.independent`, `same_file_bundle`, `generated_artifacts`). 태스크에 예외가 적용되면, 다운스트림 툴링이 분류를 추적할 수 있도록 해당 id를 태스크의 `context` 필드에 기록한다.
+
+   **Dedup Layer 1 (plan-time static merge)**: 태스크 목록을 확정하기 전에, 초안 태스크에서 `target_files`가 겹치는 것을 스캔한다. 겹치는 태스크는 `vocabulary/task-exceptions.yml`의 `same_file_bundle` 예외를 통해 단일 owner 태스크로 병합한다. 실행 중 병렬 쓰기 충돌을 방지하기 위함이다.
+
+   **DO/CHECK 분해 원칙**: DO 에이전트 (engineer, writer, researcher)와 CHECK 에이전트 (tester, reviewer)는 HOW 에이전트보다 태스크당 컨텍스트가 적다. 태스크가 여러 독립적인 artifact를 포함할 때, 하나의 owner에 번들하기보다 여러 병렬 DO/CHECK 서브에이전트로 분해한다. HOW 에이전트는 통합된 컨텍스트의 이점을 누리므로 일반적으로 단일 세션으로 유지한다. 병렬 분해는 독립 artifact가 최소 3개 이상일 때 효과적이다. 그 미만이면 병렬화 오버헤드를 피하기 위해 하나의 owner에 번들하는 것이 낫다.
+
+   **HOW 분해 규칙**: HOW 분석을 여러 서브에이전트로 나누는 것은 안건이 도메인-에이전트 매핑 테이블의 서로 다른 행(architect vs designer vs strategist vs postdoc)에 걸쳐 있을 때만 한다. 단일 도메인 행 안의 세부 관심사는 하나의 HOW 세션에서 처리한다.
+
+4. **`nx_task_add`를 통해 tasks.json을 채운다**:
+   - plan 주제에서 `goal`을 설정한다
+   - plan.json에서 결정된 요약으로 `decisions`를 설정한다
+   - 각 태스크에 대해 `nx_task_add(plan_issue=N, approach, acceptance, risk, owner)`를 호출한다
+   - 설계 또는 아키텍처 변경과 관련된 결정이 있으면, 해당 결정을 반영하여 `.nexus/context/`의 관련 파일을 업데이트하는 태스크를 포함한다 (owner: `writer` 또는 `lead`)
+5. **Plan document 제시** — 생성된 tasks.json 요약을 사용자에게 보여주고 검토받는다
+6. **전환 안내**: "`[run]`으로 실행하세요."
+
+**Incremental mode**: tasks.json이 이미 존재하면 (예: 후속 안건 추가 후), 새로운 결정에 대한 태스크만 추가한다. 이미 처리된 안건의 태스크를 중복 생성하지 않도록 `plan_issue` 필드를 확인한다.
+
+---
+
+## plan → run Transition
+
+tasks.json은 이미 Step 7에서 생성된다. Plan의 역할은 여기서 끝난다.
+`[run]`으로 실행한다.
+
+---
+
+## Principles
+
+1. **능동적 intent discovery** — 사용자가 명확히 하지 않은 것을 적극적으로 발굴한다. 인터뷰를 통해 말 뒤에 있는 근본 목표를 드러낸다.
+2. **Lead = 종합자이자 참여자** — Lead는 서브에이전트 결과를 단순 중계하지 않는다. Lead는 자신의 입장을 형성하고, 권고를 내리며, 근거를 가지고 반박한다. Yes-man이 아니다.
+3. **탐색 우선 + 선제적 확장** — planning을 시작하기 전에 코드/지식/외부 소스를 리서치한다. 근거 없는 질문은 절대 하지 않는다.
+4. **가설 기반 질문** — 공허한 질문 대신, 리서치를 바탕으로 가설을 세우고 사용자에게 확인한다.
+5. **Progressive Depth** — 요청 복잡도에 따라 planning 깊이와 HOW 서브에이전트 구성을 자동으로 조정한다.
+6. **한 번에 하나** — 여러 안건을 동시에 제시하지 않는다. 사용자의 인지 부하를 줄인다.
+7. **선택지는 반드시 pros/cons/trade-offs/recommendation 포함** — 권고할 때는 다른 선택지가 왜 부족한지 설명한다.
+8. **객관적 반박** — 사용자가 강한 확신을 가지고 와도, Lead는 모든 실행 가능한 선택지를 독립적으로 분석하고 사용자가 고려하지 않았을 trade-off를 제시해야 한다. 비교 테이블은 사용자가 이미 믿는 것을 확인해주기 위한 것이 아니라, 사용자가 모르는 것을 드러내기 위해 존재한다. 더 나은 대안이 있으면 근거를 가지고 반박한다.
+9. **기본은 자유 대화** — 자유 형식의 사용자 응답(선택지 조합, 반박, 후속 질문)이 planning 품질의 핵심이다.
+10. **Dynamic agenda** — 결정이 새로운 질문을 만든다. Lead는 사용자가 빈 곳을 알아채기를 기다리지 않고 파생 안건을 선제적으로 드러낸다.
+
+---
+
+## State Management
+
+### plan.json
+
+`.nexus/state/plan.json` — MCP tools로 관리한다.
+
+```json
+{
+  "id": 1,
+  "topic": "topic name",
+  "issues": [
+    {
+      "id": 1,
+      "title": "issue title",
+      "status": "pending"
+    },
+    {
+      "id": 2,
+      "title": "issue title",
+      "status": "decided",
+      "decision": "decision summary",
+      "how_agents": ["architect", "designer"],
+      "how_summary": {
+        "architect": "key findings...",
+        "designer": "key findings..."
+      }
+    }
+  ],
+  "research_summary": "...",
+  "created_at": "2026-01-01T00:00:00Z"
+}
+```
+
+- **Create**: `nx_plan_start(topic, issues, research_summary)` — Step 3에서 호출한다. 기존 plan.json이 있으면 자동으로 아카이브한다
+- **Status**: `nx_plan_status()` — 현재 안건 상태 + 결정 확인
+- **Update**: `nx_plan_update(action, ...)` — 안건 추가/제거/수정/재개
+- **Decide**: `nx_plan_decide(issue_id, summary)` — 안건을 `decided`로 표시하고 인라인으로 decision을 기록
+- **파일 존재 = 세션 진행 중**
+
+### Topic Switching
+
+- `[plan]` → plan.json이 있으면 기존 plan을 계속한다. 없으면 새 세션을 시작한다
+- 태그 없이 대화 계속 → 기존 세션 유지
+- 새 `nx_plan_start` 호출 → 새 plan 생성 전 현재 plan.json을 자동으로 아카이브한다
+
+### Session Abort
+
+세션을 중단하려면 `nx_task_close`로 현재 상태를 아카이브한다. 미완료 안건/태스크는 향후 참조를 위해 history.json에 기록된다.
+
+---
+
+## Self-Reinforcing Loop
+
+```
+[plan] start → check/continue existing plan.json (start new if none)
+  ↓
+Intent discovery → research (parallel subagents) → nx_plan_start (register issues)
+  ↓
+Per-issue: HOW subagent analysis (parallel, independent) → Lead synthesis
+  → options comparison → [d] → nx_plan_decide
+  → dynamic agenda check → propose derived issues if found
+  ↓
+Next issue → ... → gap check → planning complete
+  ↓
+Proceed with `[run]` to execute.
+  ↓
+[run]: execution skill handles the full pipeline
+  ↓
+All done → nx_task_close (handled by run skill)
+```
+
+gate.ts는 `[d]`를 감지하여 plan.json이 있으면 `nx_plan_decide`로 라우팅한다. 없으면 차단한다.
+
+## Deactivation
+
+`[run]`으로 전환할 때 Plan의 역할은 끝난다. 실행은 run skill이 처리한다.

package/{skills → assets/skills}/nx-plan/body.md

@@ -1,3 +1,16 @@
+---
+name: nx-plan
+description: Structured multi-perspective analysis to decompose issues, align on
+  decisions, and produce an enriched plan before execution. Plan only — does not
+  execute.
+summary: "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan"
+triggers:
+  - plan
+harness_docs_refs:
+  - resume_invocation
+id: nx-plan
+---
+
 ## Role
 
 Facilitate structured multi-perspective analysis using subagents to decompose issues, deliberate on options, and align on decisions. Lead acts as synthesizer AND active participant — orchestrates subagent research/analysis AND contributes its own position. Does not execute — planning only. Transition to execution is the user's decision.