@moreih29/nexus-core 0.12.0 → 0.13.0

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

@@ -0,0 +1,161 @@
+---
+name: nx-run
+description: Execution — user-directed agent composition.
+summary: "Execution — user-directed agent composition"
+triggers:
+  - run
+harness_docs_refs:
+  - resume_invocation
+id: nx-run
+---
+
+## Role
+
+사용자가 [run] 태그를 호출할 때 Lead가 따르는 실행 규범이다. 사용자 지시에 따라 서브에이전트를 동적으로 조합하고, intake부터 완료까지 전체 실행 파이프라인을 구동한다.
+
+## Constraints
+
+- NEVER modify files via shell commands (sed, echo redirection, heredoc, tee, etc.) — harness의 전용 파일 편집 primitive를 항상 사용한다 (gate 강제)
+- NEVER terminate while pending tasks remain (Gate Stop nonstop)
+- NEVER spawn a new branch without checking for main/master first
+- MUST check tasks.json before executing — 없으면 먼저 plan을 생성한다
+- MUST spawn subagents per-task based on owner field — 태스크 수 ≥ 2 또는 대상 파일 ≥ 2인 경우 Lead 단독으로 처리하지 않는다
+- MUST NOT spawn parallel Engineers if their target files overlap — 겹치면 직렬화한다
+- MUST call nx_task_close before completing the cycle — plan+tasks를 history.json에 아카이브한다
+
+## Guidelines
+
+## Flow
+
+### Step 1: Intake (Lead)
+
+- **사용자가 에이전트/방향을 지정** → 지시를 그대로 따른다.
+- **[run] only (방향 없음)** → 진행 전 사용자에게 방향을 확인한다.
+- 사용자가 SCOPE와 구성을 결정한다. 명시되지 않은 부분은 Lead가 채운다.
+- **Branch Guard**: main/master에 있으면 진행 전에 태스크 유형에 맞는 브랜치를 생성한다 (prefix: `feat/`, `fix/`, `chore/`, `research/` 등 — Lead의 판단). 사용자 확인 없이 자동 생성한다.
+- `tasks.json` 확인:
+  - **존재** → 읽고 Step 2로 진행한다.
+  - **없음** → `{{skill_activation skill=nx-plan mode=auto}}`를 자동 호출하여 tasks.json을 생성한다. 묻지 않는다 — `[run]`은 실행 의도를 내포한다. plan 생성 후 Step 2로 진행한다.
+- tasks.json이 존재하면 `nx_plan_status`로 기존 결정을 확인한다.
+
+### Step 1.5: TUI Progress
+
+시각적 진행 추적(Ctrl+T)을 위해 태스크를 등록한다:
+
+- **태스크 ≤ 10개**: 태스크당 `{{task_register label="<per-task label>" state=pending}}`
+- **태스크 > 10개**: `plan_issue`로 그룹화하여 그룹당 `{{task_register label="<group label>" state=pending}}`
+- 실행이 진행됨에 따라 `{{task_register label="<label>" state=in_progress}}` / `{{task_register label="<label>" state=completed}}`로 등록 항목을 업데이트한다
+- **건너뛰는 경우**: non-TTY 환경 (VSCode, headless)
+- **Known issue**: auto-compact 중 TUI가 멈출 수 있다 (#27919) — 디스크의 태스크 데이터는 정확하게 유지된다
+
+### Step 2: Execute
+
+- **tasks.json을 사용자에게 제시한다** — owner, deps, approach 요약과 함께 태스크 목록을 보여준다. 확인을 묻지 않고 즉시 진행한다.
+- `owner` 필드에 따라 태스크를 실행한다:
+  - `owner: "lead"` → Lead가 직접 처리한다
+  - `owner: "engineer"`, `"researcher"`, `"writer"` 등 → owner 역할에 맞는 서브에이전트를 스폰한다
+  - `owner: "architect"`, `"tester"`, `"reviewer"` 등 → 해당 HOW/CHECK 서브에이전트를 스폰한다
+- 각 서브에이전트에게 태스크의 `context`, `approach`, `acceptance`를 프롬프트로 전달한다.
+- **병렬 실행**: 독립적인 태스크(대상 파일이 겹치지 않고, deps 없음)는 병렬로 스폰할 수 있다. 대상 파일이 공유되는 태스크는 직렬화해야 한다.
+- **SubagentStop 에스컬레이션 체인**: 서브에이전트가 미완성 상태로 종료되면:
+  1. **Do/Check 실패** → 해당 HOW 에이전트를 스폰하여 (예: Engineer 실패 → Architect) 실패를 진단하고, 접근법을 검토하며, 조정안을 제안하게 한다.
+  2. **재위임** → HOW의 조정된 접근법을 적용하여 새 Do/Check 에이전트에게 재위임한다.
+  3. **HOW도 실패** → Lead가 진단 내용과 함께 사용자에게 실패를 보고하고 방향을 요청한다.
+  - 최대: 태스크당 HOW 진단 1회 + 재위임 1회. 이후에는 사용자에게 에스컬레이션한다.
+  - 관련 HOW 매핑: Engineer→Architect, Writer→Strategist, Researcher→Postdoc, Tester→Architect.
+
+### Resume Dispatch Rule
+
+각 태스크에 대해 Lead는 `owner`의 `resume_tier`에 따라 새로 스폰할지 resume할지 결정한다:
+
+1. `agents/{owner}.md` frontmatter에서 `resume_tier`를 조회한다 (없으면 → `ephemeral`로 처리).
+2. `ephemeral`이면 → 새로 스폰한다. 종료.
+3. `bounded`이면 → tasks.json 이력을 확인한다: 동일 `owner`가 겹치는 대상 파일에 이전에 작업했는가? 그렇고 다른 에이전트의 개입 편집이 없으면 → resume 후보. 아니면 새로 스폰. resume 프롬프트에는 항상 "수정 전 대상 파일을 다시 읽을 것" 지시를 포함한다.
+4. `persistent`이면 → 이번 실행에서 동일 에이전트가 이전에 작업했으면 기본적으로 resume한다. 크로스 태스크 재사용 허용.
+5. resume 시도 전 harness의 resume 메커니즘이 사용 가능한지 확인한다. 사용 불가이면 오류를 발생시키지 않고 조용히 새로 스폰으로 폴백한다.
+
+### Step 3: Verify (Lead + Check subagents)
+
+**Lead**: 빌드 + E2E 통과/실패 여부를 확인한다.
+
+**Tester — acceptance criteria 검증**:
+- Tester는 tasks.json에서 완료된 각 태스크의 `acceptance` 필드를 읽는다
+- 각 기준을 PASS/FAIL로 판정한다
+- 태스크를 완료로 간주하려면 모든 기준을 통과해야 한다
+- 기준 하나라도 실패 → Step 2 재작업 (태스크 재개)
+- Tester 스폰 조건 (하나라도 해당되면):
+  - tasks.json에 `acceptance` 필드가 있는 태스크가 1개 이상
+  - 변경된 파일이 3개 이상
+  - 기존 테스트 파일이 수정됨
+  - 외부 API/DB 접근 코드가 변경됨
+  - 해당 영역의 실패 이력이 memory에 존재
+
+**Reviewer — writer 산출물 검증**:
+- Step 2에서 Writer가 산출물을 생성한 경우, Reviewer가 반드시 검증해야 한다
+- Writer → Reviewer는 선택이 아닌 필수 페어링이다
+- Reviewer 확인 항목: 사실 정확성, 소스 일관성, 문법/형식
+
+- 문제 발견 시: 코드 문제 → Step 2 재작업; 설계 문제 → 재실행 전 nx-plan을 다시 수행한다.
+
+### Step 4: Complete
+
+순서대로 실행한다:
+
+1. **nx-sync**: 이번 사이클에 코드 변경이 있었으면 `{{skill_activation skill=nx-sync}}`를 호출한다. Best effort — 실패해도 사이클 완료를 막지 않는다.
+2. **nx_task_close**: 호출하여 plan+tasks를 history.json에 아카이브한다. `.nexus/history.json`이 업데이트된다.
+3. **git commit**: 소스 변경, 빌드 artifact (`bridge/`, `scripts/`), `.nexus/history.json`, 수정된 `.nexus/memory/` 또는 `.nexus/context/`를 스테이징하고 커밋한다. 명시적인 `git add`에 경로를 지정한다 (`git add -A` 사용 금지). `Co-Authored-By`가 포함된 HEREDOC 커밋 메시지를 사용한다. 이렇게 하면 사이클의 history 아카이브가 코드 변경과 같은 커밋에 포함되어 1:1 사이클-커밋 매핑이 보장된다.
+4. **Report**: 사용자에게 요약 보고 — 변경된 파일, 적용된 핵심 결정, 권장 다음 단계. Merge/push는 사용자의 결정이며 이 스킬의 SCOPE 밖이다.
+
+---
+
+## Reference Framework
+
+| Phase | Owner | Content |
+|-------|-------|---------|
+| 1. Intake | Lead | 의도 파악, 방향 확인, Branch Guard, tasks.json 확인 / 없으면 nx-plan 호출 |
+| 2. Execute | Do subagents | owner별 태스크당 스폰, 위임 기준, 안전한 경우 병렬 실행 |
+| 3. Verify | Lead + Check subagent | 빌드 확인, 품질 검증 |
+| 4. Complete | Lead | nx-sync, nx_task_close, git commit, 보고 |
+
+---
+
+## Structured Delegation
+
+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}
+```
+
+---
+
+## Key Principles
+
+1. **Lead = 사용자 지시 해석 + 조율 + 태스크 직접 처리**
+2. **사용자가 SCOPE와 구성을 결정한다**
+3. **tasks.json이 상태의 단일 진실 소스** — nx-plan이 생성하고, Step 1에서 읽으며, 태스크가 완료됨에 따라 업데이트된다
+4. **Do subagents = owner별 실행** — Lead는 `owner` 필드에 따라 태스크당 하나의 서브에이전트를 스폰한다. Engineer는 코드 변경에 집중한다. 문서 업데이트는 Step 4에서 Writer가 일괄 처리한다. Researcher는 즉시 reference/에 기록한다.
+5. **Check subagents = 검증** — Lead의 판단 + 4가지 조건
+6. **SubagentStop 에스컬레이션** — 서브에이전트가 미완성 상태로 종료되면 HOW 진단 → 재위임 → 사용자 보고 순으로 에스컬레이션한다. 태스크당 최대 1사이클.
+7. **Gate Stop nonstop** — 미결 태스크가 존재하는 동안 종료할 수 없다
+8. **Plan first** — tasks.json이 없으면 Step 2 전에 반드시 nx-plan을 실행한다
+9. **shell 명령으로 파일 수정 금지** — sed, echo redirection, heredoc, tee 및 유사한 shell 기반 파일 편집은 금지된다. harness의 전용 파일 편집 primitive를 항상 사용한다 (gate 강제)
+
+## State Management
+
+`.nexus/state/tasks.json` — nx-plan이 생성하고 `nx_task_add`/`nx_task_update`로 관리한다. Gate Stop 강제.
+사이클 종료 시 `nx_task_close`를 통해 plan+tasks를 `.nexus/history.json`에 아카이브한다.

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

@@ -1,3 +1,14 @@
+---
+name: nx-run
+description: Execution — user-directed agent composition.
+summary: "Execution — user-directed agent composition"
+triggers:
+  - run
+harness_docs_refs:
+  - resume_invocation
+id: nx-run
+---
+
 ## Role
 
 Execution norm that Lead follows when the user invokes the [run] tag. Composes subagents dynamically based on user direction and drives the full execution pipeline from intake to completion.

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

@@ -0,0 +1,92 @@
+---
+name: nx-sync
+description: Context knowledge synchronization — scans project state and updates
+  .nexus/context/ design documents
+summary: "Context knowledge synchronization"
+triggers:
+  - sync
+id: nx-sync
+---
+
+## Role
+
+현재 프로젝트 상태를 스캔하고 `.nexus/context/` 설계 문서를 동기화한다. git diff를 사용하여 코드 변경 사항을 식별한 뒤, 코드만으로는 추론할 수 없는 추상 설계 문서(원칙, 철학, 개발 스택, 아키텍처 결정)를 업데이트한다.
+
+## Constraints
+
+- 기존 context 파일을 절대 삭제하지 않는다 — 업데이트하거나 추가만 한다
+- 소스 코드를 절대 수정하지 않는다 — 이 skill은 문서만 업데이트한다
+- 소스에서 확인할 수 없는 정보는 추측하지 않는다 — 대신 "needs verification"으로 표시한다
+- 기존 내용 구조를 반드시 보존한다 — 전체 파일을 불필요하게 재작성하지 않고 섹션만 업데이트한다
+- 사용 중단된 MCP 지식 도구는 절대 사용하지 않는다 — harness의 파일 읽기 및 파일 생성 프리미티브만 사용한다
+
+## Guidelines
+
+## Trigger
+
+- `[sync]` — 현재 프로젝트 상태와 `.nexus/context/`를 동기화한다
+
+## Process
+
+### Step 1: Gather Sources
+
+모든 사용 가능한 소스에서 정보를 수집한다:
+
+1. **git diff** — `git diff --name-only HEAD~10..HEAD` 실행 (또는 최근 커밋을 사용하여 변경된 파일 식별)
+   - 어떤 소스 파일이 변경되었는지 식별한다
+   - 어떤 context 문서가 오래되었는지 판단하는 1차 신호
+2. **대화 context** — 현재 세션에서 사용 가능한 경우
+   - 논의되었으나 아직 context 문서에 반영되지 않은 설계 결정
+   - 모든 업데이트의 보조 소스
+
+### Step 2: Read Current Context
+
+harness의 파일 읽기 프리미티브를 사용하여 `.nexus/context/`의 모든 파일을 읽는다:
+
+- 파일 목록 확인: `ls .nexus/context/`
+- 각 파일을 읽어 현재 문서화된 상태를 파악한다
+- 감지된 변경 사항과 비교하여 누락되거나 오래된 내용을 식별한다
+
+구체적인 변경이 감지된 파일만 업데이트한다. 오래된 내용이 없으면 "already current"를 보고하고 건너뛴다.
+
+### Step 3: Execute Updates
+
+Writer agent를 스폰하여 영향받은 context 문서를 업데이트한다:
+
+```
+{{subagent_spawn target_role=writer name=writer-sync-context prompt=>>WRITER_SYNC_PROMPT}}
+Update .nexus/context/ documents based on the following changes. Read current files with the harness's file-reading primitive, then write updates with the harness's file-creation primitive. Changes: {change_manifest}
+<<WRITER_SYNC_PROMPT
+```
+
+Writer agent:
+- harness의 파일 읽기 프리미티브로 각 관련 context 파일을 읽는다
+- 오래된 섹션만 수정하는 표적 업데이트를 적용한다
+- harness의 파일 생성 프리미티브로 업데이트된 파일을 다시 작성한다
+- 이미 정확한 파일은 재작성하지 않는다
+
+### Step 4: Report
+
+다음을 사용자에게 보고한다:
+- 스캔한 context 파일
+- 업데이트된 파일과 변경된 내용
+- 이미 최신 상태인 파일
+- "needs verification"으로 표시된 항목
+
+## Key Principles
+
+1. **전체 재작성보다 표적 업데이트** — 실제로 오래된 섹션만 변경한다
+2. **증거 기반** — 모든 업데이트는 소스(git diff 또는 대화)를 추적할 수 있어야 한다
+3. **구조 보존** — 기존 문서 구성, 헤딩, 형식을 유지한다
+4. **추측 금지** — 변경 사항이 context 문서에 미치는 영향이 불명확하면 추측하지 않고 표시한다
+
+## What .nexus/context/ Contains
+
+Context 문서는 소스 코드에서 직접 읽을 수 없는 추상 지식을 담는다:
+
+- 설계 원칙 및 철학
+- 아키텍처 결정과 그 근거
+- 개발 스택 선택과 제약
+- 프로젝트 컨벤션과 표준
+
+이 문서들은 코드 변경이 원칙의 전환을 반영하거나, 새로운 아키텍처 결정이 내려지거나, 개발 스택이 변화할 때 업데이트된다. 기저 설계를 변경하지 않는 일상적인 코드 추가에는 업데이트하지 않는다.

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

@@ -1,3 +1,13 @@
+---
+name: nx-sync
+description: Context knowledge synchronization — scans project state and updates
+  .nexus/context/ design documents
+summary: "Context knowledge synchronization"
+triggers:
+  - sync
+id: nx-sync
+---
+
 ## Role
 
 Scans the current project state and synchronizes .nexus/context/ design documents. Uses git diff to identify code changes, then updates abstract design documents (principles, philosophy, development stack, architectural decisions) that cannot be inferred from code alone.

package/assets/tools/tool-name-map.yml

@@ -0,0 +1,353 @@
+# tool-name-map.yml
+# nexus standard tool names (PascalCase) -> 3 harness native mapping
+# Used by wrapper (runtime.ts) for alias transformation and Bash command parsing
+#
+# Sources:
+#   - plan.json Issue #3 decision (tool name standard + Bash parsing)
+#   - plan.json Issue #4 decision (Codex limit workarounds, extended Bash parse patterns)
+#   - plan.json Issue #5 decision §6 (PascalCase standard for matcher)
+#   - .nexus/memory/external-codex-hooks-tools.md §8 (3-harness tool mapping table)
+#
+# null = tool not natively supported by that harness
+# Codex shell tools: primary is "shell" (most general); aliases listed for alias transformation
+
+tools:
+
+  # ── General tools ────────────────────────────────────────────────────────────
+
+  Bash:
+    claude: Bash
+    codex:
+      primary: shell
+      aliases: [shell_command, exec_command, exec]
+    opencode: bash
+
+  Read:
+    claude: Read
+    codex: null          # No standalone Read; uses shell cat/head/tail (see bash_parse_patterns)
+    opencode: read
+
+  Edit:
+    claude: Edit
+    codex: apply_patch   # Codex uses apply_patch for all file edits
+    opencode: edit
+
+  Write:
+    claude: Write
+    codex: apply_patch
+    opencode: write
+
+  MultiEdit:
+    claude: MultiEdit
+    codex: apply_patch
+    opencode: edit
+
+  # ApplyPatch: Codex-native concept; Claude decomposes into Edit/MultiEdit
+  ApplyPatch:
+    claude: [Edit, MultiEdit]          # Claude has no single ApplyPatch; uses per-file tools
+    codex: apply_patch
+    opencode: [apply_patch, edit]      # OpenCode supports both forms
+
+  Grep:
+    claude: Grep
+    codex: null          # Uses shell + rg (see bash_parse_patterns)
+    opencode: grep
+
+  Glob:
+    claude: Glob
+    codex: null          # Uses shell + find (see bash_parse_patterns)
+    opencode: glob
+
+  LS:
+    claude: LS
+    codex: list_dir
+    opencode: list
+
+  WebFetch:
+    claude: WebFetch
+    codex: null          # No equivalent; web_search only
+    opencode: webfetch
+
+  WebSearch:
+    claude: WebSearch
+    codex: web_search
+    opencode: websearch
+
+  ViewImage:
+    claude: Read         # Claude handles images via Read (branch on mime type)
+    codex: view_image
+    opencode: null       # Confirmed unavailable per memory §8
+
+  REPL:
+    claude: REPL
+    codex: [js_repl, js_repl_reset]
+    opencode: null       # Confirmed unavailable per memory §8
+
+  ToolSearch:
+    claude: ToolSearch
+    codex: [tool_search, tool_suggest]
+    opencode: null       # Confirmed unavailable per memory §8
+
+  # ── Meta tools — invocation guidance only; wrapper mapping not required (#3 decision) ──
+
+  Task:                  # Subagent spawn
+    claude: Agent        # Claude exposes this as the Agent tool (also called Task in docs)
+    codex: spawn_agent
+    opencode: task
+
+  Skill:
+    claude: Skill
+    codex: null          # Codex uses $skill-name syntax directly in composer (no tool call)
+    opencode: skill
+
+  TodoWrite:
+    claude: TodoWrite
+    codex: update_plan
+    opencode: todowrite
+
+  TodoRead:
+    claude: TodoRead
+    codex: update_plan   # update_plan subsumes read via plan/step/status fields
+    opencode: todoread
+
+  AskUserQuestion:
+    claude: AskUserQuestion
+    codex: request_user_input
+    opencode: question
+
+  RequestPermissions:
+    claude: null         # Claude uses PermissionRequest hook event, not a tool
+    codex: request_permissions
+    opencode: null       # permission.ask (#7006) confirmed non-firing; out of portable scope
+
+# ── MCP tool prefix convention ────────────────────────────────────────────────
+# MCP tools are exposed under a namespaced prefix in all three harnesses.
+# wrapper normalizes any mcp__<server>__<tool> name to this canonical form.
+mcp_tool_prefix: "mcp__<server>__<tool>"
+
+# ── Bash parse patterns ───────────────────────────────────────────────────────
+# Used by wrapper to normalize Codex Bash (shell) commands into nexus standard tool_name.
+# Applies to: PreToolUse / PostToolUse tool_input.command (Codex), post-tool-telemetry matcher.
+# Strategy: best-effort single-entrypoint match on command string prefix.
+# Compound commands, pipes, and sudo are NOT matched and remain tool_name=Bash.
+#
+# Source: plan.json Issue #3 section "Bash parsing" + Issue #4 section 2 "Bash parsing extension"
+
+bash_parse_patterns:
+
+  Read:
+    - "^(cat|head|tail|less|more) "
+
+  LS:
+    - "^ls( |$)"
+
+  Glob:
+    - "^find "
+
+  Grep:
+    - "^(rg|grep) "
+
+  Write:
+    - "^echo .+ > "       # stdout redirect (overwrite)
+    - "^touch "
+    - "^tee "
+    - "^cp "
+    - "^cat > .+ <<"      # heredoc write
+
+  Edit:
+    - "^echo .+ >> "      # stdout redirect (append)
+    - "^sed -i "
+    - "^mv "
+
+# ── Capability notes (non-normative) ─────────────────────────────────────────
+# Authoritative capability data lives in assets/hooks/capability-matrix.yml.
+# These notes summarize key harness gaps relevant to alias mapping.
+#
+# Codex:
+#   - No standalone Read/Edit/Write tools; file operations go through apply_patch or shell
+#   - apply_patch does not emit PreToolUse/PostToolUse as of 2026-04-18
+#     (PR #18391 pending merge; capability matrix entry: event.pre_tool_use.edit.codex=false)
+#   - MCP tools do not emit PreToolUse/PostToolUse (Codex #16732, Claude-only)
+#   - Skill invocation is $skill-name syntax, not a tool call
+#
+# OpenCode:
+#   - permission.ask (#7006) confirmed non-firing; RequestPermissions out of portable scope
+#   - PostToolUse additional_context injection not adopted as standard (YAGNI, plan.json #6)
+
+# ── invocations ───────────────────────────────────────────────────────────────
+# Canonical invocation patterns for cross-harness agent/skill coordination.
+# These are NOT wrapper-normalized tool names — they are prose/template references
+# for skill authors and build scripts that emit harness-specific call syntax.
+#
+# Each template uses {placeholder} for substituted values.
+# Optional arguments are shown as {arg?} — omit the surrounding delimiters when absent.
+# Build scripts must strip optional segments when the corresponding arg is absent.
+#
+# Sources (per template):
+#   Claude Agent tool:     https://code.claude.com/docs/en/sub-agents
+#                          Verified: .nexus/memory/external-claude-code-hooks-tools.md §6 (Agent/Task tool)
+#   Claude Skill tool:     https://code.claude.com/docs/en/skills
+#                          Verified: .nexus/memory/external-claude-code-hooks-tools.md — Skill §
+#   OpenCode task tool:    https://opencode.ai/docs/tools/ (task tool Zod schema)
+#                          Verified: .nexus/memory/external-opencode-hooks-tools.md §15 (official params)
+#   OpenCode skill tool:   https://opencode.ai/docs/skills/
+#                          Verified: .nexus/memory/external-opencode-hooks-tools.md — Skill § (name param only)
+#   Codex spawn_agent:     https://developers.openai.com/codex/config-reference
+#                          Verified: .nexus/memory/external-codex-hooks-tools.md §7-5
+#   Codex skill ($prefix): https://developers.openai.com/codex/skills
+#                          Verified: .nexus/memory/external-codex-hooks-tools.md — Skill §
+#   Codex update_plan:     .nexus/memory/external-codex-hooks-tools.md §7-4
+#   Codex request_user_input: .nexus/memory/external-codex-hooks-tools.md §7-4
+
+invocations:
+
+  # subagent_spawn — spawn a new subagent from within a skill or agent body.
+  #
+  # args:
+  #   target_role : string  — role/type ID of the agent to spawn (e.g. "engineer")
+  #   prompt      : string  — instruction text delivered to the subagent
+  #   name        : string? — optional human-readable label / description
+  #
+  # Claude — Agent tool (also referred to as "Task" in docs).
+  #   subagent_type selects the agent role. description is the optional display label.
+  #   Source: https://code.claude.com/docs/en/sub-agents (Agent tool: subagent_type, prompt, description)
+  #   Verified: .nexus/memory/external-claude-code-hooks-tools.md §6
+  #
+  # OpenCode — task tool. Official Zod schema: { subagent_type, prompt, description, task_id? }
+  #   description is required in OpenCode (unlike Claude where it is optional).
+  #   task_id is used to resume a prior session; omitted on initial spawn.
+  #   Source: https://opencode.ai/docs/tools/
+  #   Verified: .nexus/memory/external-opencode-hooks-tools.md §15 (source-confirmed schema)
+  #
+  # Codex — spawn_agent tool. Second arg is the instruction prompt.
+  #   Codex agent roles are resolved from native agent config (config.toml [agents.*]).
+  #   Source: https://developers.openai.com/codex/config-reference
+  #   Verified: .nexus/memory/external-codex-hooks-tools.md §7-5
+  subagent_spawn:
+    args: [target_role, prompt, name]   # name is optional
+    templates:
+      claude: 'Agent({ subagent_type: "{target_role}", prompt: "{prompt}", description: "{name}" })'
+      opencode: 'task({ subagent_type: "{target_role}", prompt: "{prompt}", description: "{name}" })'
+      codex: 'spawn_agent("{target_role}", "{prompt}")'
+    notes:
+      claude: >
+        description field is optional; omit when name arg is absent.
+        model field may be added to override the spawned agent's model.
+      opencode: >
+        description is required by OpenCode's Zod schema — use target_role as
+        fallback when name is absent. task_id param enables session resume (§15).
+      codex: >
+        Agent role must be pre-registered in config.toml [agents.<target_role>].
+        No description equivalent in spawn_agent call signature.
+
+  # skill_activation — invoke a skill from within an agent or skill body.
+  #
+  # args:
+  #   skill : string  — canonical skill name (e.g. "nx-plan")
+  #   mode  : string? — optional argument / mode string passed to the skill
+  #
+  # Claude — Skill tool. Single `command` string parameter only; no `args` field.
+  #   Plugin-namespaced skills use "plugin:skill" form (e.g. "claude-nexus:nx-plan").
+  #   Source: https://code.claude.com/docs/en/skills
+  #   Verified: .nexus/memory/external-claude-code-hooks-tools.md — Skill § (command param schema)
+  #
+  # OpenCode — skill tool. Single `name` string parameter; no `args` parameter.
+  #   $ARGUMENTS placeholder substitution in SKILL.md body is unconfirmed.
+  #   Source: https://opencode.ai/docs/skills/
+  #   Verified: .nexus/memory/external-opencode-hooks-tools.md — Skill § (name param only)
+  #
+  # Codex — $skill-name composer prefix, not a tool call. Positional and KEY=value
+  #   args are theoretically supported but confirmed only for Custom Prompts, not Skills.
+  #   Source: https://developers.openai.com/codex/skills
+  #   Verified: .nexus/memory/external-codex-hooks-tools.md — Skill § ($ prefix syntax)
+  skill_activation:
+    args: [skill, mode]   # mode is optional
+    templates:
+      claude: 'Skill({ command: "{skill}" })'
+      opencode: 'skill({ name: "{skill}" })'
+      codex: '${skill}'
+    notes:
+      claude: >
+        The Skill tool accepts only the `command` string; mode/args cannot be
+        passed as a separate parameter. Mode must be embedded in the SKILL.md body
+        via $ARGUMENTS placeholder substitution.
+      opencode: >
+        The skill tool accepts only `name`; args passing is unconfirmed per source
+        review. Design skills to be args-free or embed defaults in SKILL.md body.
+      codex: >
+        Positional args: "$skill-name {mode}". Named args: "$skill-name MODE={mode}".
+        Confirmed only for Custom Prompts; treat as best-effort for Skills.
+        $ prefix is literal in composer input, not a tool call.
+
+  # task_register — register or update a task in the plan tracker.
+  #
+  # args:
+  #   label : string — task subject / display label
+  #   state : string — task status (e.g. "in_progress", "completed", "blocked")
+  #
+  # Claude — TaskCreate tool for new tasks; TaskUpdate (nx_task_update MCP tool) for state.
+  #   TaskCreate is a Claude Code native meta tool.
+  #   Source: https://code.claude.com/docs/en/sub-agents
+  #   Verified: .nexus/memory/external-claude-code-hooks-tools.md §6 (TaskCreate tool entry)
+  #   Note: nx_task_update refers to the MCP tool exposed by nexus-core server.
+  #
+  # OpenCode — nx_task_add MCP tool to create; nx_task_update MCP tool to update state.
+  #   MCP tool names are identical across harnesses (server exposes same tool names).
+  #   Source: nexus-core MCP server implementation (src/mcp/tools/)
+  #
+  # Codex — update_plan native tool manages plan steps including state.
+  #   plan/step/status sub-fields subsume both create and update operations.
+  #   Source: https://developers.openai.com/codex/config-reference
+  #   Verified: .nexus/memory/external-codex-hooks-tools.md §7-4
+  task_register:
+    args: [label, state]
+    templates:
+      claude: 'TaskCreate({ subject: "{label}" }) then nx_task_update({ taskId, status: "{state}" })'
+      opencode: 'nx_task_add({ subject: "{label}" }) then nx_task_update({ taskId, status: "{state}" })'
+      codex: 'update_plan([{ name: "{label}", state: "{state}" }])'
+    notes:
+      claude: >
+        TaskCreate is a Claude Code native tool (not MCP). nx_task_update is the
+        nexus-core MCP tool — full name mcp__plugin_claude-nexus_nx__nx_task_update.
+        taskId is returned by TaskCreate and must be threaded to the update call.
+      opencode: >
+        Both nx_task_add and nx_task_update are nexus-core MCP tools exposed via
+        the nexus MCP server. task_id returned by nx_task_add must be threaded to update.
+      codex: >
+        update_plan subsumes creation and update in a single call via plan/step/status
+        fields. No separate create/update step is needed.
+
+  # user_question — request structured input from the user.
+  #
+  # args:
+  #   question : string   — the question text to present
+  #   options  : string[] — list of choices (may be empty for free-text responses)
+  #
+  # Claude — AskUserQuestion tool. questions[] array supports multiple simultaneous
+  #   questions; single-question usage is the standard nexus pattern.
+  #   Source: https://code.claude.com/docs/en/sub-agents (AskUserQuestion tool)
+  #   Verified: .nexus/memory/external-claude-code-hooks-tools.md §6
+  #
+  # OpenCode — question tool. Single question with choices array.
+  #   Source: https://opencode.ai/docs/tools/
+  #   Verified: .nexus/memory/external-opencode-hooks-tools.md §7 (question tool entry)
+  #
+  # Codex — request_user_input native tool.
+  #   Source: https://developers.openai.com/codex/config-reference
+  #   Verified: .nexus/memory/external-codex-hooks-tools.md §7-4
+  user_question:
+    args: [question, options]
+    templates:
+      claude: 'AskUserQuestion({ questions: [{ question: "{question}", options: {options} }] })'
+      opencode: 'question({ question: "{question}", choices: {options} })'
+      codex: 'request_user_input({ prompt: "{question}", options: {options} })'
+    notes:
+      claude: >
+        options is a JSON array of strings. Omit the options field (not an empty array)
+        for free-text responses. Multiple questions can be batched in the questions[] array.
+      opencode: >
+        choices field name (not options). Omit choices for free-text input.
+      codex: >
+        Exact request_user_input schema (options field name, types) is not fully
+        documented — treat as best-effort. Verified as a native Codex tool in
+        external-codex-hooks-tools.md §7-4.

package/dist/hooks/opencode-mount.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OpenCode plugin adapter — mounts nexus hooks into OpenCode's plugin API.
+ *
+ * 결정 참조: plan.json Issue #1 (3-레이어 책임 분담),
+ *            Issue #3 (OpenCode 2단 처리 — SubagentStart/Stop, agent-tracker),
+ *            Issue #6 (additional_context 주입 우회 — SubagentStop output.output append)
+ */
+export interface OpenCodeHookManifestEntry {
+    name: string;
+    /** Nexus standard event names (PascalCase). */
+    events: string[];
+    /** Glob/regex pattern matched against tool_name or source. */
+    matcher: string;
+    /** Absolute path to the compiled handler .js shell wrapper. */
+    handlerPath: string;
+    priority: number;
+    /** Timeout in seconds; defaults to 30. */
+    timeout?: number;
+}
+export interface OpenCodeHookManifest {
+    hooks: OpenCodeHookManifestEntry[];
+}
+/**
+ * Mount nexus hooks into OpenCode's plugin API.
+ *
+ * Returns an object whose keys are OpenCode plugin hook names. Each value is
+ * the async handler function OpenCode calls when the corresponding event fires.
+ *
+ * @param pluginCtx  OpenCode plugin context (must expose `.directory: string`)
+ * @param manifest   Hook manifest produced by build-hooks.ts
+ */
+export declare function mountHooks(pluginCtx: {
+    directory: string;
+}, manifest: OpenCodeHookManifest): Record<string, (...args: unknown[]) => Promise<void>>;
+//# sourceMappingURL=opencode-mount.d.ts.map