@moreih29/nexus-core 0.17.0 → 0.18.2

package/spec/skills/nx-auto-plan/body.md

@@ -0,0 +1,150 @@
+---
+id: nx-auto-plan
+name: nx-auto-plan
+description: Autonomous planning skill — Lead decomposes, analyzes, and decides issues without user confirmation, producing an execution plan. Keeps nx-plan's research and analysis depth while skipping user dialogue.
+triggers:
+  - "[auto-plan]"
+---
+
+## Role
+
+Performs the same research and analysis process as nx-plan, but Lead makes decisions autonomously without presenting options or waiting for user responses. HOW subagent usage, researcher/explore investigations, prior-knowledge lookup, and issue decomposition are identical to nx-plan. The only difference is at decision time — instead of emitting a comparison table and awaiting user response, Lead deliberates internally and records the decision immediately.
+
+This skill does not execute. Execution is handled separately by the `[run]` flow. It is also the path `[run]` invokes internally when tasks.json is absent.
+
+## Constraints
+
+- **NEVER request user confirmation.** All decisions MUST be made by Lead autonomously and recorded directly.
+- **MUST maintain the same research and analysis depth as nx-plan.** HOW subagent spawning, researcher/explore investigations, and the existing-knowledge-first principle all apply.
+- **MUST record both the selected approach with rationale AND rejected alternatives with dismissal reasons in every decision.** Comparison tables are not output, but internal deliberation is mandatory.
+- **MUST brief all decisions at once after completion.** NEVER notify the user per-decision.
+
+## Procedure
+
+### Step 1: Intent Discovery
+
+Determine issue scope and complexity from the request itself. Do not conduct additional user interviews.
+
+| Level | Signal | Exploration Scope |
+|---|---|---|
+| Specific | File path, function name, error message, or concrete target named | Focus on the relevant file or module |
+| Direction-setting | Open-ended question, "it would be nice if ~", choice needed among approaches | Related area + external case research |
+| Abstract | Goal itself unclear, fundamental direction needed | Full codebase + external research + comparable project comparison |
+
+- Specific request → derive issues immediately.
+- Direction-setting → Lead selects the most reasonable direction based on research findings.
+- Abstract → broaden research scope and have Lead infer the root goal.
+
+#### HOW Subagent Selection
+
+- Lead autonomously selects HOW subagents matching the issue scope.
+- If the user explicitly named HOW agents, use them as-is and add missing axes when visible.
+- Additional HOW subagents can be spawned at any point during analysis.
+
+### Step 2: Research
+
+Understand code, core knowledge, and prior decisions before forming the planning agenda.
+
+#### Existing Knowledge First
+
+- Read `.nexus/memory/` and `.nexus/context/` first.
+- Use `nx_history_search` to check whether prior decisions exist on similar topics.
+- If the needed information is already available, use it directly and skip or narrow subagent spawning.
+
+#### Approach Selection
+
+| Situation | Approach |
+|---|---|
+| Codebase orientation needed | `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` for codebase exploration |
+| External research needed | `{{subagent_spawn target_role=researcher prompt="<research question>"}}` for web search |
+| Both needed | Spawn `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` and `{{subagent_spawn target_role=researcher prompt="<research question>"}}` in parallel |
+
+- Researcher subagents return findings to Lead and do not participate in the auto-plan session itself.
+
+### Step 3: Session Start
+
+Once research is complete, open the planning session with `nx_plan_start`. Any existing `plan.json` is automatically archived. Unlike nx-plan, the issue list is NOT presented to the user beforehand — proceed directly to Step 4.
+
+### Step 4: Issue-by-Issue Analysis
+
+Issues must be processed one at a time. For each issue:
+
+1. Lead summarizes the current state and the problem.
+2. If needed, spawn HOW subagents for independent analysis.
+   - If reusing context from a prior HOW session for the same role is advantageous, check resume routing information with `nx_plan_resume` first.
+   - If resumable, continue with the existing session; otherwise, spawn fresh.
+3. When HOW results return, record them on the issue with `nx_plan_analysis_add(issue_id, role, agent_id=<id from spawn>, summary)`. The `agent_id` is the value `nx_plan_resume` will return on a future resume request for the same role, so always pass it.
+4. **Lead internal deliberation**: enumerate candidate options, compare pros/cons and trade-offs, and select the most reasonable one. Do not output comparison tables or option presentations.
+5. Proceed immediately to Step 5 to record the decision.
+
+#### HOW Domain Mapping
+
+| Domain Keywords | Recommended HOW |
+|---|---|
+| UI, UX, design, interface, user experience, layout | Designer |
+| Architecture, system design, performance, structural change, API, schema | Architect |
+| Business, market, strategy, positioning, competition, revenue | Strategist |
+| Research methodology, evidence evaluation, literature, experiment design | Postdoc |
+
+- If an issue matches a domain above, spawning the corresponding HOW is the default.
+- If the issue crosses multiple domains, spawn multiple HOWs together.
+- To skip spawning, state the reason explicitly in the analysis text.
+
+### Step 5: Record Decision
+
+Use `nx_plan_decide` to mark the issue as decided. The decision text MUST include:
+
+- The selected approach and its rationale
+- The rejected alternatives and their dismissal reasons
+
+If HOW subagents participated in the issue, bundle their contribution information so it can be referenced in future resumes and Step 7 task decomposition.
+
+If the decision creates follow-up questions or derived issues, add them with `nx_plan_update` and move to Step 6. Do not ask the user for confirmation.
+
+### Step 6: Dynamic Agenda Management
+
+- If derived issues emerge, add them via `nx_plan_update` and return to Step 4.
+- If unresolved issues remain, move on to the next issue.
+- Once all issues are decided, Lead checks for gaps against the original request.
+- If gaps exist, register new issues with `nx_plan_update` and return to Step 4.
+
+### Step 7: Briefing and Plan Document Generation
+
+Once all issues are decided, brief the user in a single pass:
+
+```
+[auto-plan complete] N issues, N decisions
+- #1: {selected} ({rejected alternative} — reason)
+- #2: ...
+```
+
+Immediately after briefing, decompose the decisions from `plan.json` into actionable tasks and populate `tasks.json` via `nx_task_add`. From this point, task tools — not plan tools — take over.
+
+Fill in the following fields for each task:
+
+- `approach` — implementation strategy derived from the decision rationale
+- `acceptance` — definition of done, verifiable criteria
+- `risk` — risks surfaced during analysis
+- `deps` — execution-order dependencies
+- `owner` — assigned according to the criteria below
+
+For issues where HOW subagents participated, reference the analysis recorded in Step 4, or re-spawn the same HOW to request domain-appropriate decomposition.
+
+#### Owner Assignment Criteria
+
+| Work Type | owner | Criteria |
+|---|---|---|
+| Single file, small change | `lead` | Subagent overhead exceeds task effort |
+| Code implementation | `engineer` | Source code creation or modification |
+| Documentation/content | `writer` | `.md`, README, docs, non-code content |
+| External research | `researcher` | External information gathering required |
+| Design analysis / review | HOW role | Technical judgment is the core work |
+| Sequential edits to the same file | `lead` | High risk of parallel edit conflicts |
+
+#### Verification Auto-Pairing
+
+- If an `engineer` task has a runtime-behavior criterion in its acceptance, pair a `tester` task.
+- If a `writer` task has a verifiable deliverable criterion in its acceptance, pair a `reviewer` task.
+- Researcher tasks are not auto-paired by default.
+
+Once tasks are generated, instruct the user to execute with `[run]`. If this skill was invoked internally by `[run]`, hand off to the run flow directly without the instruction.

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

@@ -0,0 +1,159 @@
+---
+id: nx-plan
+name: nx-plan
+description: 실행 전에 안건을 분해하고 결정을 정렬하며 보강된 실행 계획을 만드는 구조적 다각도 분석. 계획 전용이며 실행하지 않는다.
+triggers:
+  - "[plan]"
+---
+
+## 역할
+
+실행에 들어가기 전에 안건을 분해하고, 선택지를 비교하고, 결정을 정리해 계획을 만드는 스킬이다. Lead는 서브에이전트의 조사와 분석을 조율하면서도 스스로 입장을 형성하고 권고안을 제시한다.
+
+이 스킬은 실행하지 않는다. 실행은 별도의 `[run]` 흐름이 담당한다.
+
+## 핵심 규칙
+
+- 실행하지 않는다. 이 스킬의 목적은 계획 수립과 결정 정렬이다.
+- 한 번에 하나의 안건만 다룬다. 여러 안건을 동시에 제시하지 않는다.
+- 근거 없이 묻지 않는다. 코드, 기존 지식, 과거 결정을 먼저 조사한다.
+- 결정을 요청할 때는 반드시 비교 표를 제시한다. 선택지를 산문만으로 설명하지 않는다.
+- Lead는 종합자이자 참여자다. 서브에이전트 결과를 단순 중계하지 않고, 스스로 권고안을 만들고 필요하면 반박한다.
+
+## 절차
+
+### 1단계: 의도 파악
+
+요청의 복잡도를 판단하고, 계획을 어느 깊이까지 진행할지 정한다.
+
+| 수준 | 신호 | 탐색 범위 |
+|---|---|---|
+| 구체적 | 파일 경로, 함수명, 에러 메시지, 구체 대상이 명시됨 | 해당 파일이나 모듈에 집중 |
+| 방향 설정형 | 열린 질문, "~하면 좋겠다", 접근 방식 사이의 선택 필요 | 관련 영역 + 외부 사례 조사 |
+| 추상적 | "어떻게 접근해야 할지 모르겠다", 목표 자체가 불명확, 근본 방향 설정 필요 | 전체 코드베이스 + 외부 조사 + 유사 프로젝트 비교 |
+
+- 구체적 요청이면 즉시 안건을 도출한다.
+- 방향 설정형 요청이면 가설 기반 질문으로 의도를 파악한다.
+- 추상적 요청이면 인터뷰를 통해 사용자가 아직 명확히 말하지 않은 근본 목표를 드러낸다.
+
+#### HOW 서브에이전트 선택
+
+- 사용자가 HOW 에이전트를 명시하면 그대로 사용하되, 빠진 축이 보이면 추가를 제안한다.
+- 사용자가 지정하지 않으면 Lead가 안건 범위를 기준으로 제안한다.
+- 추가 HOW 서브에이전트는 분석 도중 언제든지 띄울 수 있다.
+
+### 2단계: 조사
+
+계획 안건을 세우기 전에 코드, 핵심 지식, 기존 결정을 파악한다.
+
+#### 기존 지식 우선
+
+- `.nexus/memory/`와 `.nexus/context/`를 먼저 읽는다.
+- `nx_history_search`로 유사 주제의 과거 결정이 있는지 확인한다.
+- 필요한 정보가 이미 있으면 그대로 활용하고, 서브에이전트 스폰은 생략하거나 범위를 줄인다.
+
+#### 접근법 선택
+
+| 상황 | 접근법 |
+|---|---|
+| 코드베이스 파악이 필요 | `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` 코드베이스 탐색 |
+| 외부 조사가 필요 | `{{subagent_spawn target_role=researcher prompt="<research question>"}}` 웹 검색 |
+| 둘 다 필요 | `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` 와 `{{subagent_spawn target_role=researcher prompt="<research question>"}}` 를 병렬로 스폰 |
+
+- researcher 서브에이전트는 결과를 Lead에게 반환하며, plan 세션 자체에 참여하지 않는다.
+
+### 3단계: 세션 시작
+
+조사가 끝나면 `nx_plan_start`로 계획 세션을 연다. 기존 `plan.json`이 있으면 자동으로 아카이브된다. 안건 목록을 사용자에게 보여주고 진행 방향을 맞춘다.
+
+### 4단계: 안건별 분석
+
+안건은 반드시 하나씩 처리한다. 각 안건마다 다음을 수행한다.
+
+1. Lead가 현재 상태와 문제를 요약한다.
+2. 필요하면 HOW 서브에이전트를 스폰해 독립 분석을 받는다.
+   - 같은 HOW 역할의 맥락을 이어 쓰는 편이 유리하면 `nx_plan_resume`으로 재개 라우팅 정보를 먼저 확인한다.
+   - 재개할 수 있으면 이어서 사용하고, 없으면 새로 스폰한다.
+3. HOW 결과가 돌아오면 `nx_plan_analysis_add(issue_id, role, agent_id=<스폰에서 얻은 id>, summary)`로 해당 안건에 기록한다. `agent_id`는 `nx_plan_resume`가 같은 role 재개 요청 시 되돌려주는 값이므로, 스폰 툴 응답(또는 Lead가 지정한 name)에서 얻은 id를 반드시 넘긴다. 이 기록은 이후 재개 경로와 7단계 태스크 분해의 입력이 된다.
+4. 종합 후 비교 표와 권고안을 제시한다.
+5. 사용자 응답을 받아 결정을 정리한다.
+
+#### HOW 도메인 매핑
+
+| 도메인 키워드 | 권장 HOW |
+|---|---|
+| UI, UX, 디자인, 인터페이스, 사용자 경험, 레이아웃 | Designer |
+| 아키텍처, 시스템 설계, 성능, 구조 변경, API, 스키마 | Architect |
+| 비즈니스, 시장, 전략, 포지셔닝, 경쟁, 수익 | Strategist |
+| 연구 방법론, 근거 평가, 문헌, 실험 설계 | Postdoc |
+
+- 안건이 위 도메인과 맞으면 기본적으로 해당 HOW를 스폰한다.
+- 여러 도메인에 걸치면 여러 HOW를 함께 스폰할 수 있다.
+- 스폰하지 않으려면 그 이유를 분석 텍스트 안에 명시한다.
+
+#### 비교 표 형식
+
+<example>
+
+| 항목 | A: {title} | B: {title} | C: {title} |
+|---|---|---|---|
+| 장점 | ... | ... | ... |
+| 단점 | ... | ... | ... |
+| 트레이드오프 | ... | ... | ... |
+| 적합한 경우 | ... | ... | ... |
+
+**권장안: {X} ({title})**
+
+- 선택지 A는 {reason} 때문에 부족하다
+- 선택지 B는 {reason} 때문에 부족하다
+- 선택지 X는 {limitations}를 극복하며 {core benefit}을 제공한다
+
+</example>
+
+### 5단계: 결정 기록
+
+결정이 내려지면 `nx_plan_decide`로 해당 안건을 결정 상태로 전환한다. HOW 서브에이전트가 참여한 안건이면 그 기여 정보도 함께 묶어, 이후 재개와 태스크 분해에서 참조되도록 한다.
+
+- 결정 직후 `nx_plan_status`로 전체 진행을 확인하고 다음 안건을 한 줄로 안내한다.
+- 새로운 후속 질문이 생겼는지 점검하고, 필요하면 `nx_plan_update`로 후속 안건을 추가한다.
+- 결정을 번복해야 하면 `nx_plan_update`로 해당 안건을 다시 연 뒤 4단계로 돌아간다.
+
+### 6단계: 동적 안건 관리
+
+- 결정이 새로운 질문을 만들면 `nx_plan_update`로 후속 안건을 추가한다.
+- 미결 안건이 남아 있으면 다음 안건으로 넘어간다.
+- 모든 안건이 결정되면 원래 질문을 충분히 커버했는지 누락을 점검한다.
+- 누락이 있으면 `nx_plan_update`로 새 안건을 등록하고 4단계로 돌아간다.
+
+### 7단계: 계획 문서 생성
+
+모든 안건이 결정되면 `plan.json`의 결정을 실행 가능한 태스크로 분해해 `nx_task_add`로 `tasks.json`을 구성한다. 여기서부터는 plan 도구가 아닌 task 도구의 영역이다.
+
+각 태스크에는 다음을 채운다.
+
+- `approach` — 결정 근거에서 도출한 구현 전략
+- `acceptance` — 완료 정의, 검증 가능한 기준
+- `risk` — 분석에서 드러난 위험
+- `deps` — 실행 순서 의존성
+- `owner` — 아래 기준으로 배정
+
+HOW 서브에이전트가 참여한 안건은 4단계에서 기록한 분석 결과를 참고하거나, 같은 HOW를 재스폰해 도메인에 맞는 분해를 제안받는다.
+
+#### owner 배정 기준
+
+| 작업 유형 | owner | 기준 |
+|---|---|---|
+| 단일 파일, 소규모 변경 | `lead` | 서브에이전트 오버헤드가 더 큰 경우 |
+| 코드 구현 | `engineer` | 소스 코드 생성 또는 수정 |
+| 문서/콘텐츠 | `writer` | `.md`, README, docs, 비코드 콘텐츠 |
+| 외부 조사 | `researcher` | 외부 정보 수집이 필요한 경우 |
+| 설계 분석 / 리뷰 | HOW 역할 | 기술적 판단이 중심인 경우 |
+| 동일 파일의 순차 편집 | `lead` | 병렬 편집 충돌 위험이 큰 경우 |
+
+#### 검증 자동 페어링
+
+- `engineer` 태스크에 런타임 동작 기준이 있으면 `tester` 태스크를 붙인다.
+- `writer` 태스크에 검증 가능한 산출물 기준이 있으면 `reviewer` 태스크를 붙인다.
+- researcher 태스크는 기본적으로 자동 페어링하지 않는다.
+
+태스크 생성이 끝나면 요약을 사용자에게 보여주고 `[run]`으로 실행하라고 안내한다.

package/spec/skills/nx-plan/body.md

@@ -0,0 +1,159 @@
+---
+id: nx-plan
+name: nx-plan
+description: Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched execution plan before acting. Planning only — does not execute.
+triggers:
+  - "[plan]"
+---
+
+## Role
+
+A skill for decomposing issues, comparing options, and producing a plan before execution begins. Lead orchestrates subagent research and analysis while forming its own position and presenting recommendations.
+
+This skill does not execute. Execution is handled separately by the `[run]` flow.
+
+## Constraints
+
+- NEVER execute — this skill's purpose is planning and decision alignment, not execution.
+- MUST handle one issue at a time. NEVER present multiple issues simultaneously.
+- NEVER ask groundless questions. MUST investigate code, existing knowledge, and prior decisions first.
+- MUST present a comparison table before requesting a decision. NEVER describe options in prose alone.
+- Lead is both synthesizer and participant — MUST form an independent recommendation and push back when warranted, not merely relay subagent results.
+
+## Procedure
+
+### Step 1: Intent Discovery
+
+Assess the complexity of the request and determine how deeply to pursue the plan.
+
+| Level | Signal | Exploration Scope |
+|---|---|---|
+| Specific | File path, function name, error message, or concrete target named | Focus on the relevant file or module |
+| Direction-setting | Open-ended question, "it would be nice if ~", choice needed among approaches | Related area + external case research |
+| Abstract | "I'm not sure how to approach this", goal itself unclear, fundamental direction needed | Full codebase + external research + comparable project comparison |
+
+- Specific request → derive issues immediately.
+- Direction-setting request → use hypothesis-based questions to understand intent.
+- Abstract request → actively interview to uncover the root goal the user hasn't yet articulated.
+
+#### HOW Subagent Selection
+
+- If the user names HOW agents explicitly, use them as-is; propose additions if gaps are visible.
+- If the user does not specify, Lead proposes agents based on the issue scope.
+- Additional HOW subagents can be spawned at any point during analysis.
+
+### Step 2: Research
+
+Understand code, core knowledge, and prior decisions before forming the planning agenda.
+
+#### Existing Knowledge First
+
+- Read `.nexus/memory/` and `.nexus/context/` first.
+- Use `nx_history_search` to check whether prior decisions exist on similar topics.
+- If the needed information is already available, use it directly and skip or narrow subagent spawning.
+
+#### Approach Selection
+
+| Situation | Approach |
+|---|---|
+| Codebase orientation needed | `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` for codebase exploration |
+| External research needed | `{{subagent_spawn target_role=researcher prompt="<research question>"}}` for web search |
+| Both needed | Spawn `{{subagent_spawn target_role=explore prompt="<file/code search task>"}}` and `{{subagent_spawn target_role=researcher prompt="<research question>"}}` in parallel |
+
+- Researcher subagents return findings to Lead and do not participate in the plan session itself.
+
+### Step 3: Session Start
+
+Once research is complete, open the planning session with `nx_plan_start`. Any existing `plan.json` is automatically archived. Show the issue list to the user and confirm the direction before proceeding.
+
+### Step 4: Issue-by-Issue Analysis
+
+Issues must be processed one at a time. For each issue:
+
+1. Lead summarizes the current state and the problem.
+2. If needed, spawn HOW subagents for independent analysis.
+   - If reusing context from a prior HOW session for the same role is advantageous, check resume routing information with `nx_plan_resume` first.
+   - If resumable, continue with the existing session; otherwise, spawn fresh.
+3. When HOW results return, record them on the issue with `nx_plan_analysis_add(issue_id, role, agent_id=<id from spawn>, summary)`. The `agent_id` is the value `nx_plan_resume` will return on a future resume request for the same role, so always pass the id obtained from the spawn tool response (or the name the Lead assigned). This record feeds both future resume paths and Step 7 task decomposition.
+4. After synthesis, present a comparison table and recommendation.
+5. Receive the user's response and record the decision.
+
+#### HOW Domain Mapping
+
+| Domain Keywords | Recommended HOW |
+|---|---|
+| UI, UX, design, interface, user experience, layout | Designer |
+| Architecture, system design, performance, structural change, API, schema | Architect |
+| Business, market, strategy, positioning, competition, revenue | Strategist |
+| Research methodology, evidence evaluation, literature, experiment design | Postdoc |
+
+- If an issue matches a domain above, spawning the corresponding HOW is the default.
+- If the issue crosses multiple domains, spawn multiple HOWs together.
+- To skip spawning, state the reason explicitly in the analysis text.
+
+#### Comparison Table Format
+
+<example>
+
+| 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 {limitations} and delivers {core benefit}
+
+</example>
+
+### Step 5: Record Decision
+
+When a decision is reached, use `nx_plan_decide` to mark the issue as decided. If HOW subagents participated in the issue, bundle their contribution information so it can be referenced in future resumes and Step 7 task decomposition.
+
+- Immediately after recording, check overall progress with `nx_plan_status` and announce the next issue in one line.
+- Check whether new follow-up questions have emerged, and if so, add follow-up issues with `nx_plan_update`.
+- To reverse a decision, reopen the issue with `nx_plan_update` and return to Step 4.
+
+### Step 6: Dynamic Agenda Management
+
+- If a decision creates new questions, add follow-up issues with `nx_plan_update`.
+- If unresolved issues remain, move on to the next issue.
+- Once all issues are decided, check for gaps against the original question.
+- If gaps exist, register new issues with `nx_plan_update` and return to Step 4.
+
+### Step 7: Plan Document Generation
+
+Once all issues are decided, decompose the decisions from `plan.json` into actionable tasks and populate `tasks.json` via `nx_task_add`. From this point, task tools — not plan tools — take over.
+
+Fill in the following fields for each task:
+
+- `approach` — implementation strategy derived from the decision rationale
+- `acceptance` — definition of done, verifiable criteria
+- `risk` — risks surfaced during analysis
+- `deps` — execution-order dependencies
+- `owner` — assigned according to the criteria below
+
+For issues where HOW subagents participated, reference the analysis recorded in Step 4, or re-spawn the same HOW to request domain-appropriate decomposition.
+
+#### Owner Assignment Criteria
+
+| Work Type | owner | Criteria |
+|---|---|---|
+| Single file, small change | `lead` | Subagent overhead exceeds task effort |
+| Code implementation | `engineer` | Source code creation or modification |
+| Documentation/content | `writer` | `.md`, README, docs, non-code content |
+| External research | `researcher` | External information gathering required |
+| Design analysis / review | HOW role | Technical judgment is the core work |
+| Sequential edits to the same file | `lead` | High risk of parallel edit conflicts |
+
+#### Verification Auto-Pairing
+
+- If an `engineer` task has a runtime-behavior criterion in its acceptance, pair a `tester` task.
+- If a `writer` task has a verifiable deliverable criterion in its acceptance, pair a `reviewer` task.
+- Researcher tasks are not auto-paired by default.
+
+Once tasks are generated, show the user a summary and instruct them to execute with `[run]`.

package/spec/skills/nx-run/body.ko.md

@@ -0,0 +1,132 @@
+---
+id: nx-run
+name: nx-run
+description: Execution — user-directed agent composition.
+triggers:
+  - "[run]"
+---
+
+## 역할
+
+사용자가 `[run]` 태그를 호출할 때 Lead가 따르는 실행 규범이다. tasks.json을 읽어 `owner` 필드에 따라 서브에이전트를 동적으로 조합하고, 실행-검증-완료 사이클을 구동한다.
+
+## 핵심 규칙
+
+- **계획 없이 실행하지 않는다.** tasks.json이 없으면 먼저 nx-auto-plan을 호출해 계획을 세운 뒤 돌아온다.
+- **태스크는 `owner`가 실행 주체다.** Lead 단독 처리보다 owner에 맞는 서브에이전트 위임을 기본으로 한다.
+- **미완료 태스크가 남아 있으면 중단하지 않는다.** `nx_task_list`로 모든 태스크가 `completed`인지 확인할 때까지 사이클을 이어간다.
+- **main/master에서는 작업하지 않는다.** 실행 시작 전에 태스크 유형에 맞는 브랜치로 이동한다.
+
+## 절차
+
+### 1단계: 준비
+
+- **Branch Guard**: main/master에 있으면 태스크 유형에 맞는 브랜치를 생성하고 이동한다 (prefix: `feat/`, `fix/`, `chore/`, `research/` 등 — Lead의 판단).
+- **tasks.json 로드**:
+  - **존재** → `nx_task_list`로 목록을 읽고 `nx_plan_status`로 기존 결정을 확인한다.
+  - **없음** → `{{skill_activation skill=nx-auto-plan}}`을 자동 호출해 tasks.json을 생성한다. `[run]`은 실행 의도를 내포하므로 사용자에게 묻지 않는다.
+
+### 2단계: 실행
+
+#### 태스크 등록
+
+각 태스크에 대해 `{{task_register label="<label>" state=pending}}`을 호출해 진행 추적을 등록한다. 등록 항목은 최대 10개로 유지한다. 태스크가 10개를 넘으면 `plan_issue`나 대상 파일 등 자연스러운 묶음 기준으로 연관 태스크를 엮어 등록 항목이 10개 이내가 되도록 조정한다.
+
+#### 태스크 디스패치
+
+- `owner` 필드에 따라 태스크를 실행한다.
+  - `owner: "lead"` → Lead가 직접 처리한다.
+  - 그 외 → owner 역할에 맞는 서브에이전트를 스폰한다.
+- 각 서브에이전트에게 태스크의 `context`, `approach`, `acceptance`를 프롬프트로 전달한다.
+- **재개 판단**: 각 태스크마다 `nx_task_resume`로 재개 라우팅 정보를 조회하고, 아래 재개 라우팅 규칙에 따라 새로 스폰할지 재개할지 결정한다.
+- **병렬 실행**: deps가 없는 태스크는 병렬로 스폰할 수 있다. 대상 파일이 겹치는 태스크는 직렬화한다.
+
+#### 상태 전환
+
+- 태스크 시작 시 `nx_task_update`로 `in_progress`, 완료 시 `completed`로 전환한다.
+- 서브에이전트를 새로 스폰한 경우 같은 `nx_task_update` 호출에 `owner={role, agent_id: <스폰에서 얻은 id>, resume_tier: <ephemeral|bounded|persistent>}`를 함께 넘겨 이후 `nx_task_resume`가 이 id를 돌려줄 수 있게 한다.
+- 같은 타이밍에 `{{task_register label="<label>" state=in_progress}}` / `{{task_register label="<label>" state=completed}}`로 진행 추적도 갱신한다. 초기 등록 때 정한 label을 그대로 재사용한다.
+
+### 재개 라우팅 규칙
+
+`nx_task_resume`가 반환하는 `resume_tier`와 `agent_id` 값에 따라 Lead가 행동한다.
+
+- `ephemeral` → 새로 스폰한다.
+- `bounded` → 동일 owner가 겹치는 대상 파일에 이전 작업이 있고 중간에 다른 에이전트 편집이 없으면 재개한다. 재개 프롬프트에 "수정 전 대상 파일을 다시 읽을 것" 지시를 반드시 포함한다.
+- `persistent` → 이번 실행에서 동일 에이전트가 이전 태스크에 참여했으면 재개한다. 크로스 태스크 재사용 허용.
+
+재개가 결정되면 `nx_task_resume`가 반환한 `agent_id`로 `{{subagent_resume agent_id="<id>" prompt="<재개 프롬프트>"}}` 도구를 호출한다. 재개 프롬프트는 매번 새로 제공한다 — 일부 하네스(OpenCode)는 실행 중 session에 추가 입력을 push하는 경로가 없고, idle session에 새 prompt를 주입하는 방식으로만 재개를 지원한다.
+
+`nx_task_resume`가 `agent_id: null`을 반환하거나 하네스가 해당 id를 더 이상 찾지 못하면 오류 없이 새로 스폰으로 폴백한다.
+
+### 에스컬레이션 체인
+
+Do와 Check의 핑퐁을 기본 경로로 삼는다. Check가 연속 2회 실패하면 HOW로, HOW 검토 후에도 실패하면 Lead가 사용자에게 에스컬레이션한다.
+
+최대 경로:
+
+```
+Do → Check(실패) → Do → Check(실패) → HOW(검토) → Do → Check(실패) → Lead → 사용자
+```
+
+- **Check 1회 실패** → 같은 Do에게 재위임(재개 가능)해 실패 피드백을 전달하고 수정 후 다시 Check를 돌린다.
+- **Check 2회 연속 실패** → 태스크 도메인에 맞는 HOW 에이전트를 Lead가 선정·스폰해 접근법을 검토·조정받고 Do로 재위임한다.
+- **HOW 검토 후에도 Check 실패** → Lead가 진단 내용과 함께 사용자에게 보고하고 방향을 요청한다.
+
+### 3단계: 검증
+
+각 태스크의 `acceptance` 필드를 기준으로 Check 서브에이전트가 자율적으로 검증한다. 세부 판정 방식은 서브에이전트에게 맡긴다.
+
+- **Tester** — 코드 검증 (engineer 산출물).
+- **Reviewer** — 문서 검증 (writer 산출물).
+
+검증 실패는 위의 에스컬레이션 체인을 따른다.
+
+### 4단계: 완료
+
+순서대로 실행한다.
+
+1. **`nx_task_close`**: plan+tasks를 `.nexus/history.json`에 아카이브한다. `plan.json`과 `tasks.json`이 제거된다.
+2. **git commit**: 소스 변경, 빌드 아티팩트(`bridge/`, `scripts/`), `.nexus/history.json`, 수정된 `.nexus/memory/` 또는 `.nexus/context/`를 한 커밋으로 묶어 사이클-커밋 1:1 매핑을 유지한다. `git add -A` 대신 명시적 경로를 쓴다.
+3. **보고**: 변경된 파일, 적용된 핵심 결정, 권장 다음 단계를 사용자에게 요약한다. Merge/push는 사용자의 결정이며 이 스킬의 scope 밖이다.
+
+---
+
+## 전체 흐름표
+
+| 단계 | 담당 | 내용 |
+|---|---|---|
+| 1. 준비 | Lead | Branch Guard, `nx_task_list`로 tasks.json 확인 / 없으면 nx-auto-plan 호출 |
+| 2. 실행 | Do 서브에이전트 | owner별 스폰, `nx_task_resume`로 재개 판단, `nx_task_update`로 상태 전환 |
+| 3. 검증 | Check 서브에이전트 | `acceptance` 기준으로 Tester(코드)/Reviewer(문서) 검증 |
+| 4. 완료 | Lead | `nx_task_close`, git commit, 보고 |
+
+---
+
+## 구조화된 위임
+
+Lead가 서브에이전트에게 태스크를 위임할 때 다음 형식으로 프롬프트를 구성한다.
+
+```
+TASK: {specific deliverable}
+
+CONTEXT:
+- Current state: {relevant code/doc locations}
+- Dependencies: {results from prior tasks}
+- Prior decisions: {relevant decisions}
+- Target files: {file path list}
+
+CONSTRAINTS:
+- {constraint 1}
+- {constraint 2}
+
+ACCEPTANCE:
+- {completion criterion 1}
+- {completion criterion 2}
+```
+
+---
+
+## 상태 관리
+
+`.nexus/state/tasks.json`은 nx-plan 계열(plan/auto-plan)이 `nx_task_add`로 생성하고, nx-run 사이클 동안 `nx_task_update`로 상태 전환을 반영한다. 조회는 `nx_task_list`, 재개 판단은 `nx_task_resume`가 담당한다. 사이클 종료 시 `nx_task_close`를 호출해 plan+tasks를 `.nexus/history.json`에 아카이브한다.