@moreih29/nexus-core 0.7.1 → 0.9.0

package/docs/consumer-implementation-guide.md

@@ -160,8 +160,6 @@ Nexus state is split into two categories with different scopes, persistence, and
 │   ├── plan.json
 │   ├── tasks.json
 │   ├── tool-log.jsonl
-│   ├── edit-tracker.json
-│   ├── reopen-tracker.json
 │   ├── artifacts/
 │   └── {harness-id}/         ← harness namespace (see §Harness-local State Extension)
 │       └── agent-tracker.json
@@ -193,7 +191,6 @@ At session start, your harness must:
 | `state/tasks.json` | Session | No | `task_add` tool (first call) | `task_close` tool |
 | `state/{harness-id}/agent-tracker.json` | Session | No | session_start hook | session_end hook |
 | `state/tool-log.jsonl` | Session | No | post_tool_use hook | session_end hook |
-| `state/edit-tracker.json` | Session | No | post_tool_use hook (first edit) | task_close / session_end |
 | `history.json` | Project | Yes | `plan_start` or `task_close` (first archive) | Never |
 
 ### Schema validation
@@ -235,7 +232,7 @@ For every tool, implement exactly the parameter schema, return shape, and side e
 Specific requirements to enforce:
 
 - `plan_start`: when a prior `plan.json` exists, archive it to `history.json` before creating the new session. Failure to archive on replace will cause data loss.
-- `task_close`: delete `plan.json`, `tasks.json`, `edit-tracker.json`, and `reopen-tracker.json` after archiving. Leaving these files causes stale state on next session.
+- `task_close`: delete `plan.json` and `tasks.json` after archiving. Leaving these files causes stale state on next session. Files such as `edit-tracker.json` and `reopen-tracker.json` are harness-local concerns and are not managed by `task_close`; delete them in your session_end hook if your harness maintains them.
 - `artifact_write`: create `.nexus/state/artifacts/` on demand if it does not exist. Do not require the directory to pre-exist.
 - `context`: return `{ active: false }` (for plan_status) or `{ exists: false }` (for task_list) when the relevant state file is absent. Do not return an error.
 
@@ -567,8 +564,8 @@ Identify the equivalent events in your harness's plugin system and implement the
 
 **Expected consumer behavior:**
 - Update `.nexus/state/{harness-id}/agent-tracker.json`: set `status=completed`, record `stopped_at` timestamp.
-- Compute `files_touched` from your tool-log or the subagent's tool usage record. Record which files were created or modified.
-- Update `edit-tracker.json` with the files touched by this agent. This data feeds the bounded-tier resume evaluation on subsequent spawns.
+- Compute `files_touched` from your tool-log or the subagent's tool usage record. Record which files were created or modified in the `files_touched` array of the agent's `agent-tracker.json` entry. This field is the authoritative source for bounded-tier resume evaluation.
+- (Optional, harness-local) If your harness maintains a separate `edit-tracker.json` for cross-session file-touch history, update it here. This is not a nexus-core requirement; it is a harness-local optimization.
 - Check if the completed task has pending acceptance criteria that were not verified. If the task has `acceptance` defined and no `tester` or `reviewer` subagent has been scheduled, surface a reminder to Lead.
 - Update the task status in `tasks.json` via the `task_update` tool: set to `completed`.
 
@@ -593,7 +590,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
 
 **Expected consumer behavior:**
 - Append a log entry to `.nexus/state/tool-log.jsonl`: timestamp, agent_id, tool name, file path (if a file was touched), result status.
-- If the tool was a file-editing tool, update `edit-tracker.json`: record the file path and the agent_id that modified it. This is the data source for bounded-tier resume evaluation.
+- (Optional, harness-local) If your harness maintains `edit-tracker.json`, record the file path and agent_id here. This is a harness-local optimization and is not required by nexus-core. The `files_touched` array in `agent-tracker.json` is the nexus-core-defined record of which files an agent touched.
 - If the tool result indicates an error, record the error in the log for diagnostic purposes. Do not suppress error results.
 
 ---
@@ -704,8 +701,8 @@ Before attempting to resume, verify that your harness supports the resume mechan
 
 For `bounded` agents evaluating resume eligibility:
 - Check `.nexus/state/{harness-id}/agent-tracker.json` for the prior agent ID assigned to this task.
-- Check `edit-tracker.json` to determine if any other agent has modified the target files since the last session.
-- If any intervening edit is found, use a fresh spawn regardless of `owner_reuse_policy`.
+- Scan the `files_touched` arrays of all other completed agents in `agent-tracker.json`. If any other agent has touched the same target files since the last session, treat that as an intervening edit and use a fresh spawn regardless of `owner_reuse_policy`. The `files_touched` field is defined in `state-schemas/agent-tracker.schema.json` and is the nexus-core-defined source for this check.
+- If your harness additionally maintains `edit-tracker.json` for finer-grained cross-session tracking, you may consult it as a supplemental heuristic, but it is not required by nexus-core.
 
 Full resume tier definitions are in [behavioral-contracts.md §3](./behavioral-contracts.md).
 
@@ -807,7 +804,7 @@ Implement tag detection in your `user_message` hook. When `[plan]` is detected,
 |-------|--------------------------|
 | `session_start` | Create `.nexus/state/{harness-id}/` directory; initialize `agent-tracker.json` as `[]` |
 | `user_message` | Detect `[plan]` tag; load `skills/nx-plan/body.md`; inject into Lead's context |
-| `session_end` | Check for `tasks.json`; if present with incomplete tasks, warn the user |
+| `session_end` | Check for `tasks.json`; if present with incomplete tasks, warn the user. If the harness maintains local tracker files (e.g. `edit-tracker.json`, `reopen-tracker.json`), delete them here — see the `session_end` subsection in §9 for full details. |
 
 ### State files (3 minimum)
 

package/docs/nexus-layout.md

@@ -12,13 +12,15 @@ This document is the canonical reference for the `.nexus/` directory structure u
 │   ├── plan.json
 │   ├── tasks.json
 │   ├── tool-log.jsonl
-│   ├── edit-tracker.json
-│   ├── reopen-tracker.json
 │   ├── artifacts/
 │   ├── claude-nexus/         ← harness-namespaced directory (example)
-│   │   └── agent-tracker.json
+│   │   ├── agent-tracker.json
+│   │   ├── edit-tracker.json
+│   │   └── reopen-tracker.json
 │   └── opencode-nexus/       ← harness-namespaced directory (example)
-│       └── agent-tracker.json
+│       ├── agent-tracker.json
+│       ├── edit-tracker.json
+│       └── reopen-tracker.json
 ├── history.json              ← project-scoped (git-tracked, append-only)
 ├── memory/                   ← project-scoped (git-tracked)
 │   └── *.md
@@ -103,7 +105,7 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 ---
 
-#### `state/edit-tracker.json`
+#### `state/{harness-id}/edit-tracker.json`
 
 **Purpose.** Tracks which files have been edited in the current session. Used by the bounded resume tier to detect intervening edits before allowing agent reuse.
 
@@ -111,13 +113,13 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 **Git tracking.** Ignored.
 
-**Lifecycle.** Created on first file edit. Cleared at session end.
+**Lifecycle.** Created on first file edit. Cleared at session end by the consumer harness session hook.
 
-**Owner.** Harness file-edit hooks.
+**Owner.** Consumer harness session hook. Not managed by any nexus-core MCP tool.
 
 ---
 
-#### `state/reopen-tracker.json`
+#### `state/{harness-id}/reopen-tracker.json`
 
 **Purpose.** Records tasks or plan issues that have been reopened within the current cycle, to prevent infinite reopen loops.
 
@@ -125,9 +127,9 @@ This document is the canonical reference for the `.nexus/` directory structure u
 
 **Git tracking.** Ignored.
 
-**Lifecycle.** Created on first reopen event. Cleared at cycle end.
+**Lifecycle.** Created on first reopen event. Cleared at cycle end by the consumer harness session hook.
 
-**Owner.** Task and plan lifecycle tools.
+**Owner.** Consumer harness session hook. Not managed by any nexus-core MCP tool.
 
 ---
 

package/docs/nexus-outputs-contract.md

@@ -101,8 +101,8 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 **Schema reference**: `conformance/state-schemas/agent-tracker.schema.json`
 
 **Interop requirement**:
-- 하네스는 `agent-tracker.json`을 기록할 때 MUST `conformance/state-schemas/agent-tracker.schema.json`에 유효한 JSON을 기록해야 한다.
-- MUST required 2 필드(`harness_id`, `started_at`)를 포함해야 한다.
+- 하네스는 `agent-tracker.json`을 기록할 때 MUST `conformance/state-schemas/agent-tracker.schema.json`에 유효한 JSON을 기록해야 한다. 파일의 top-level 구조는 배열(`[]`)이며 각 원소가 하나의 에이전트 인스턴스 entry이다.
+- 각 entry는 MUST required 2 필드(`harness_id`, `started_at`)를 포함해야 한다.
 - SHOULD cross-harness display/liveness를 위한 추가 필드(`agent_name`, `status`)를 제공한다.
 - `owner_agent_id`는 MUST harness-scoped opaque string으로 취급되어야 한다 — 다른 하네스의 `agent_id`를 parse하거나 추론하는 것은 MUST NOT 허용되어서는 안 된다. `agent_id`는 하네스별 내부 식별자이며 cross-harness 해석 대상이 아니다.
 - `agent-tracker.json`은 MUST NOT git-tracked 상태로 commit되어서는 안 된다.
@@ -195,7 +195,6 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 - **MUST NOT**: 다른 하네스의 namespace 디렉토리에 쓰거나 읽는다.
 - **MUST NOT**: `{harness-id}/` 하위에서 공통 schema 파일명(plan.json, tasks.json, history.json)을 재사용한다. 예: `.nexus/state/claude-nexus/plan.json` 금지.
 - **허용**: `.nexus/state/claude-nexus/agent-tracker.json` ✓ — shared-purpose file이며 §Shared filename convention에 등록된 첫 사례. 공통 schema 파일명 재사용 금지 규칙의 예외가 아니라, shared-purpose 유형으로 별도 분류된다.
-- **예외**: v0.3.x 이하에 루트 경로로 등록된 legacy 2종(`edit-tracker.json`, `reopen-tracker.json`)은 `task_close` tool 계약에 묶여 있어 backward-compat으로 루트 유지 허용한다. 신규 파일에는 예외 편승 금지.
 
 ### Archive 정책
 
@@ -220,16 +219,14 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
 │   ├── plan.extension.json            ← plan.json의 확장 (priority, estimated_effort 등)
 │   ├── tasks.extension.json
 │   ├── history.extension.json         ← 하네스 자체 archive
-│   ├── edit-tracker.json              ← 독립 파일
-│   ├── reopen-tracker.json            ← 독립 파일
+│   ├── edit-tracker.json              ← 하네스 독립 파일
+│   ├── reopen-tracker.json            ← 하네스 독립 파일
 │   └── tool-log.jsonl
 └── opencode-nexus/                    ← sibling 하네스 namespace 디렉토리
     ├── agent-tracker.json             ← shared-purpose file (동일 파일명, harness-local)
     └── ...
 ```
 
-(루트 레벨 `edit-tracker.json`/`reopen-tracker.json`은 legacy carve-out으로 v0.3.x 이하 호환 유지)
-
 ### Reference example
 
 `conformance/examples/plan.extension.schema.example.json`에 non-normative 참조 예시가 있다. 이 파일은 다음 요소를 보여준다:

package/docs/nexus-state-overview.md

@@ -102,7 +102,7 @@ The Nexus state layout is divided into two categories:
 
 **Purpose.** Tracks agent instance activity during the session — which agents were spawned, their instance IDs, and what artifacts they touched. Used by the harness to evaluate `owner_reuse_policy` on subsequent `task_add` calls and to support agent resume. Each harness writes its own file under a harness-specific subdirectory, keeping records isolated across harness namespaces.
 
-**Schema.** The file contains a JSON object. Required fields: `harness_id` (string, identifies the writing harness) and `started_at` (ISO 8601 timestamp of session start). The following fields are optional: `agent_id`, `tasks`, `artifacts`, and any harness-defined extension fields.
+**Schema.** The file contains a JSON array. Each entry is an object representing one spawned agent instance. Required fields per entry: `harness_id` (string, identifies the writing harness) and `started_at` (ISO 8601 timestamp when the agent instance was first started). The following fields are optional per entry: `agent_name`, `agent_id`, `last_resumed_at`, `resume_count`, `status`, `stopped_at`, `last_message`, and `files_touched`. Harness-defined extension fields are not permitted — `additionalProperties` is false per the schema.
 
 The `agent_id` field, when present, is a harness-specific opaque agent instance identifier. Its format is defined by the writing harness (for example, a UUID, a composite string, or another harness-native scheme). Consumers of this file treat the value as opaque — they do not parse it or infer agent identity across harness namespaces.
 

package/docs/nexus-tools-contract.md

@@ -326,13 +326,14 @@ None.
 | `total_cycles` | `number` | Total number of cycles in `history.json` after closure |
 | `memoryHint.taskCount` | `number` | Number of tasks in the closed cycle |
 | `memoryHint.decisionCount` | `number` | Number of decided issues in the closed cycle |
-| `memoryHint.hadLoopDetection` | `boolean` | `true` if the edit tracker recorded three or more edits to any single file during the cycle |
 | `memoryHint.cycleTopics` | `string[]` | Non-empty strings from `plan.topic` and `tasks.goal` |
 
 ### Side Effects
 
 - Appends a cycle record to `.nexus/history.json` (creating the file if absent). The record contains `completed_at`, `branch`, `plan` (full `PlanFile` or `null`), and `tasks` (full `Task[]`).
-- Deletes the following session-scoped files if they exist: `plan.json`, `tasks.json`, `edit-tracker.json`, `reopen-tracker.json` (all within `.nexus/state/`).
+- Deletes the following session-scoped files if they exist: `plan.json`, `tasks.json` (all within `.nexus/state/`).
+
+Harness-local tracker files (`edit-tracker.json`, `reopen-tracker.json`, and any other files under `.nexus/state/{harness-id}/`) are not managed by `task_close`. Their lifecycle is the responsibility of consumer harness session hooks.
 
 ### Error Conditions
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.7.1",
-  "nexus_core_commit": "d2da7dede9540a14bc5925904c2382795f383b1e",
+  "nexus_core_version": "0.9.0",
+  "nexus_core_commit": "ff5fb5de66dc2bf5f45dfba141901ccca7eb48e9",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -19,20 +19,6 @@
       "id": "architect",
       "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
-    {
-      "name": "engineer",
-      "description": "Implementation — writes code, debugs issues, follows specifications from Lead and architect",
-      "task": "Code implementation, edits, debugging",
-      "alias_ko": "엔지니어",
-      "category": "do",
-      "resume_tier": "bounded",
-      "model_tier": "standard",
-      "capabilities": [
-        "no_task_create"
-      ],
-      "id": "engineer",
-      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
-    },
     {
       "name": "designer",
       "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
@@ -49,6 +35,35 @@
       "id": "designer",
       "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     },
+    {
+      "name": "reviewer",
+      "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
+      "task": "Content verification, fact-checking, grammar review",
+      "alias_ko": "리뷰어",
+      "category": "check",
+      "resume_tier": "ephemeral",
+      "model_tier": "standard",
+      "capabilities": [
+        "no_file_edit",
+        "no_task_create"
+      ],
+      "id": "reviewer",
+      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
+    },
+    {
+      "name": "engineer",
+      "description": "Implementation — writes code, debugs issues, follows specifications from Lead and architect",
+      "task": "Code implementation, edits, debugging",
+      "alias_ko": "엔지니어",
+      "category": "do",
+      "resume_tier": "bounded",
+      "model_tier": "standard",
+      "capabilities": [
+        "no_task_create"
+      ],
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
+    },
     {
       "name": "strategist",
       "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
@@ -96,21 +111,6 @@
       "id": "postdoc",
       "body_hash": "sha256:da9b8c2568b8b5812abed6d6324139f814379d48dc63cdc5d0b5b263f5407814"
     },
-    {
-      "name": "reviewer",
-      "description": "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables",
-      "task": "Content verification, fact-checking, grammar review",
-      "alias_ko": "리뷰어",
-      "category": "check",
-      "resume_tier": "ephemeral",
-      "model_tier": "standard",
-      "capabilities": [
-        "no_file_edit",
-        "no_task_create"
-      ],
-      "id": "reviewer",
-      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
-    },
     {
       "name": "tester",
       "description": "Testing and verification — tests, verifies, validates stability and security of implementations",
@@ -153,20 +153,19 @@
         "resume_invocation"
       ],
       "id": "nx-run",
-      "body_hash": "sha256:6c8d1a36626d4034209ff83780dec6238297ec4710612441b2ef09daac714ca8"
+      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
     },
     {
-      "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"
-      ],
+      "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": [
-        "resume_invocation"
+        "instruction_file",
+        "slash_command_display"
       ],
-      "id": "nx-plan",
-      "body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
+      "id": "nx-init",
+      "body_hash": "sha256:b828a974ab4722dd7f1d15a4338d1380fdae47cd42c1bd4a5539277075efb6fc"
     },
     {
       "name": "nx-sync",
@@ -176,18 +175,20 @@
         "sync"
       ],
       "id": "nx-sync",
-      "body_hash": "sha256:a7b0ae8f13ebcd10e52361d0ada1570ff0c47933f731deec07e95539c63e6946"
+      "body_hash": "sha256:3ee8dd780d53f2e04472de6c701e16bc1fbde7f2ce9ed4e680b7cd2010530a22"
     },
     {
-      "name": "nx-init",
-      "description": "Project onboarding — scan, mission, essentials, context generation",
-      "summary": "Project onboarding — scan, mission, essentials, context generation",
-      "manual_only": true,
+      "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": [
-        "instruction_file"
+        "resume_invocation"
       ],
-      "id": "nx-init",
-      "body_hash": "sha256:3c8230ecc0f87c541ec0ff80492a28f28bf173d0b9781901adadfae69a54b8ed"
+      "id": "nx-plan",
+      "body_hash": "sha256:cd7a5fd1815530be6ffad18358a1295d1f74ef8a24132e75b73522c106eb6ae5"
     }
   ],
   "vocabulary": {
@@ -320,6 +321,32 @@
           "*"
         ]
       }
+    ],
+    "invocations": [
+      {
+        "id": "skill_activation",
+        "description": "Activate another skill within the current conversation.",
+        "intent": "skill_entry_dispatch",
+        "fallback_behavior": "If the harness lacks a live skill activation primitive, re-emit the\nskill's trigger tag (e.g., '[plan:auto]') as a self-dispatch signal,\nrelying on tag detection to re-enter the skill. The skill id must be\nmapped to its canonical trigger tag by the harness's own docs.\n"
+      },
+      {
+        "id": "subagent_spawn",
+        "description": "Spawn a new subagent session with a specific role and prompt.",
+        "intent": "subagent_session_create",
+        "fallback_behavior": "If the harness lacks an explicit subagent spawn primitive (e.g.,\nhooks-based implicit routing), inject the target_role as a routing\nhint and structure the prompt so the harness's own delegation rules\ncatch it. A harness that cannot spawn agents must document this\nlimitation and treat the invocation as a no-op with a warning.\n"
+      },
+      {
+        "id": "task_register",
+        "description": "Register a task for user-visible progress tracking.",
+        "intent": "execution_visibility_register",
+        "fallback_behavior": "If the harness has no TUI task tracker, omit the call entirely. This\nprimitive is best-effort — failure or absence must not block\nexecution. Logging the label and state to the conversation transcript\nis acceptable as a degraded fallback for auditability.\n"
+      },
+      {
+        "id": "user_question",
+        "description": "Ask the user a structured question with selectable options.",
+        "intent": "structured_user_prompt",
+        "fallback_behavior": "If the harness lacks a structured question tool (e.g., opencode-nexus),\npresent the question as prose followed by the options enumerated as a\nnumbered list, then await the user's free-form reply. The LLM is\nexpected to map the reply to the most appropriate option or treat it\nas a free-form answer if no options were given.\n"
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moreih29/nexus-core",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Nexus ecosystem Authoring layer — canonical prompts, neutral metadata, and vocabulary shared by Nexus harnesses",
   "license": "MIT",
   "repository": {

package/schema/manifest.schema.json

@@ -34,27 +34,42 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "name", "description", "triggers", "body_hash"],
+        "required": ["id", "name", "description", "body_hash"],
         "properties": {
           "id": { "$ref": "common.schema.json#/$defs/id" },
           "name": { "type": "string" },
           "description": { "type": "string" },
+          "summary": { "type": "string", "minLength": 10, "maxLength": 120 },
           "triggers": { "type": "array", "items": { "type": "string" } },
+          "harness_docs_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
           "alias_ko": { "type": "string" },
           "manual_only": { "type": "boolean" },
           "body_hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
-        }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "manual_only": { "const": true } },
+              "required": ["manual_only"]
+            },
+            "then": {},
+            "else": {
+              "required": ["triggers"]
+            }
+          }
+        ]
       }
     },
     "vocabulary": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["capabilities", "categories", "resume_tiers", "tags"],
+      "required": ["capabilities", "categories", "resume_tiers", "tags", "invocations"],
       "properties": {
         "capabilities": { "type": "array" },
         "categories": { "type": "array" },
         "resume_tiers": { "type": "array" },
-        "tags": { "type": "array" }
+        "tags": { "type": "array" },
+        "invocations": { "type": "array" }
       }
     }
   }

package/schema/vocabulary.schema.json

@@ -92,6 +92,51 @@
       "properties": {
         "tags": { "type": "array", "items": { "$ref": "#/$defs/tagEntry" } }
       }
+    },
+    "invocationParam": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description", "required"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "required": { "type": "boolean" },
+        "value_type": { "type": "string", "minLength": 1 }
+      }
+    },
+    "invocationEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description", "intent", "semantic_params", "prose_guidance", "fallback_behavior"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "intent": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "semantic_params": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/invocationParam" }
+        },
+        "prose_guidance": {
+          "type": "string",
+          "minLength": 40
+        },
+        "fallback_behavior": {
+          "type": "string",
+          "minLength": 20
+        }
+      }
+    },
+    "invocationFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["invocations"],
+      "properties": {
+        "invocations": { "type": "array", "items": { "$ref": "#/$defs/invocationEntry" } }
+      }
     }
   }
 }

package/scripts/lib/lint.ts

@@ -3,6 +3,70 @@ import { readFile } from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import path from 'node:path';
 
+// ─── Invocation ID cache ──────────────────────────────────────────────────────
+
+let _invocationIds: Set<string> | null = null;
+
+async function loadInvocationIds(root: string): Promise<Set<string>> {
+  if (_invocationIds !== null) return _invocationIds;
+  try {
+    const raw = await readFile(path.join(root, 'vocabulary', 'invocations.yml'), 'utf8');
+    const data = parseYaml(raw) as { invocations?: Array<{ id: string }> };
+    _invocationIds = new Set((data.invocations ?? []).map((e) => e.id));
+  } catch {
+    _invocationIds = new Set();
+  }
+  return _invocationIds;
+}
+
+// ─── Pre-processing helpers ───────────────────────────────────────────────────
+
+/**
+ * Mask heredoc blocks (>>LABEL ... <<LABEL) with spaces, preserving newlines
+ * so line numbers remain accurate. Returns masked source.
+ *
+ * Per spec: heredoc internals are opaque for DISTINCTIVE/AMBIGUOUS G6 scanning.
+ * Note: the spec also says tool call patterns inside heredocs should still be
+ * caught. We do that via a separate scanRegex pass on the original source for
+ * the CALL-PATTERN-ONLY regexes (Cat 2) and NAMESPACE regexes (Cat 3), which
+ * are applied to the unmasked source.
+ */
+function maskHeredocs(source: string): string {
+  // Match >>LABEL (optionally preceded by = or whitespace) through <<LABEL
+  return source.replace(
+    />>([A-Z][A-Z0-9_]*)([\s\S]*?)<<\1/g,
+    (_match, _label: string, body: string) => {
+      // Replace non-newline chars with spaces
+      const masked = body.replace(/[^\n]/g, ' ');
+      return `>>${_label}${masked}<<${_label}`;
+    }
+  );
+}
+
+/**
+ * Mask macro invocations {{ ... }} with spaces, preserving newlines.
+ * The primitive_id token immediately after {{ is preserved for validation;
+ * everything else inside the braces is replaced with spaces.
+ *
+ * Returns { masked, macros } where macros is a list of { id, line }.
+ */
+function maskMacros(
+  source: string
+): { masked: string; macros: Array<{ id: string; line: number }> } {
+  const macros: Array<{ id: string; line: number }> = [];
+  const masked = source.replace(
+    /\{\{([a-z_][a-z0-9_]*)([^}]*)\}\}/g,
+    (match, id: string, rest: string, offset: number) => {
+      const line = source.slice(0, offset).split('\n').length;
+      macros.push({ id, line });
+      // Replace the entire macro token with spaces (preserve newlines)
+      const inner = (id as string) + (rest as string);
+      return '{{' + inner.replace(/[^\n]/g, ' ') + '}}';
+    }
+  );
+  return { masked, macros };
+}
+
 /**
  * Common ValidationResult type. Imported from ./validate.ts for consistency,
  * but declared here as well for isolation.
@@ -46,12 +110,19 @@ const LINT_INCLUDE: string[] = [
 
 // G6: harness-specific tool names
 // Distinctive tools — unambiguous, safe to scan in ALL files including body.md prose
-const CLAUDE_CODE_TOOLS_DISTINCTIVE = /\b(NotebookEdit|BashOutput|KillShell|Glob|Grep|WebFetch|WebSearch|TodoWrite|SendMessage|TeamCreate|AskUserQuestion|mcp__plugin_[a-z0-9_]+)\b/g;
+const CLAUDE_CODE_TOOLS_DISTINCTIVE = /\b(NotebookEdit|BashOutput|KillShell|Glob|Grep|WebFetch|WebSearch|TodoWrite|SendMessage|TeamCreate|AskUserQuestion|mcp__plugin_[a-z0-9_]+|TaskCreate|TaskUpdate|TaskList|TaskGet|TaskStop|TaskOutput|subagent_type|prompt_user)\b/g;
 // Ambiguous tools — also common English words (Read, Write, Edit, Bash, Task, Monitor)
 // Only scanned in meta.yml and vocabulary where they are clearly tool references, not prose.
 const CLAUDE_CODE_TOOLS_AMBIGUOUS = /\b(Read|Write|Edit|Bash|Task|Monitor)\b/g;
 const OPENCODE_TOOLS = /\b(edit|write|patch|multiedit|bash)\b/g;
 
+// G6 Category 2: Call-pattern only (prose words that become violations only with open-paren)
+// "Agent role", "Skill activation" etc. are fine; "Agent(", "Skill(" are forbidden.
+const CALL_PATTERN_TOOLS = /\b(Skill|Agent)\s*\(/g;
+
+// G6 Category 3: Harness namespace slash-command patterns
+const HARNESS_NAMESPACE = /\/(?:claude-nexus|opencode-nexus):/g;
+
 // G7: concrete model names
 const CONCRETE_MODELS = /\b(opus|sonnet|haiku|gpt-[0-9][a-z0-9.-]*|claude-[0-9][a-z0-9.-]*)\b/gi;
 
@@ -98,32 +169,93 @@ function scanRegex(
 
 /** G6: harness-specific tool names forbidden in body/meta/vocabulary.
  *
- * CLAUDE_CODE_TOOLS (capitalized, distinctive) — scanned in ALL lint-included files.
- * OPENCODE_TOOLS (lowercase, indistinguishable from English words in prose) — scanned
- * ONLY in meta.yml and vocabulary/*.yml, NOT in body.md or prose_guidance fields.
- * Rationale: "edit", "write", "bash" are common English words that legitimately appear
- * in descriptive body prose. Scanning body.md for these produces mass false positives.
+ * CLAUDE_CODE_TOOLS_DISTINCTIVE — unambiguous, scanned in ALL lint-included files.
+ *   For body.md: source is pre-processed (heredoc + macro masking) so that
+ *   macro internals and heredoc bodies do not produce false positives.
+ *
+ * CLAUDE_CODE_TOOLS_AMBIGUOUS (Read/Write/Edit/Bash/Task/Monitor) + OPENCODE_TOOLS —
+ *   scanned ONLY in meta.yml and vocabulary/*.yml, not in body.md prose.
+ *
+ * CALL_PATTERN_TOOLS (Skill(, Agent() — scanned in ALL files on raw source
+ *   (after macro+heredoc masking). Prose words without parens are never flagged.
+ *
+ * HARNESS_NAMESPACE (/claude-nexus:, /opencode-nexus:) — scanned in ALL files.
+ *   For body.md: applied to macro/heredoc-masked source.
+ *
+ * Cat 4 (Macro whitelist): {{primitive_id}} macros in body.md are extracted and
+ *   their primitive_id is validated against vocabulary/invocations.yml enum.
+ *   Unknown primitive_ids emit a warning (consumer expander cannot handle them).
  */
 export async function checkHarnessSpecific(root: string): Promise<ValidationResult[]> {
+  const invocationIds = await loadInvocationIds(root);
   const results: ValidationResult[] = [];
   for await (const file of iterFiles(root)) {
     const source = await readFile(file, 'utf8');
     const rel = path.relative(root, file);
-    // Distinctive Claude Code tools (unambiguous) — all files
-    results.push(
-      ...scanRegex(source, CLAUDE_CODE_TOOLS_DISTINCTIVE, rel, 'G6-harness-lint',
-        (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
-    );
-    // Ambiguous tools (Read/Write/Edit/Bash/Task/Monitor + OpenCode lowercase) — meta.yml and vocabulary only
-    if (rel.endsWith('meta.yml') || rel.startsWith('vocabulary/')) {
+    const isBody = rel.endsWith('body.md');
+
+    if (isBody) {
+      // Pre-process: mask heredocs first, then macros
+      const heredocMasked = maskHeredocs(source);
+      const { masked, macros } = maskMacros(heredocMasked);
+
+      // Cat 1 (Distinctive) — on masked source
+      results.push(
+        ...scanRegex(masked, CLAUDE_CODE_TOOLS_DISTINCTIVE, rel, 'G6-harness-lint',
+          (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
+      );
+
+      // Cat 2 (Call-pattern) — on masked source (macros/heredocs won't contain Agent(/Skill()
       results.push(
-        ...scanRegex(source, CLAUDE_CODE_TOOLS_AMBIGUOUS, rel, 'G6-harness-lint',
+        ...scanRegex(masked, CALL_PATTERN_TOOLS, rel, 'G6-harness-lint',
+          (m) => `Harness-specific tool call syntax forbidden: '${m}'. Use abstract capability or remove.`)
+      );
+
+      // Cat 3 (Namespace) — on masked source
+      results.push(
+        ...scanRegex(masked, HARNESS_NAMESPACE, rel, 'G6-harness-lint',
+          (m) => `Harness namespace slash-command forbidden: '${m}'. Use capability abstraction.`)
+      );
+
+      // Cat 4 (Macro whitelist) — validate primitive_ids against invocations.yml
+      for (const macro of macros) {
+        if (!invocationIds.has(macro.id)) {
+          results.push({
+            file: rel,
+            gate: 'G6-harness-lint',
+            severity: 'warning',
+            line: macro.line,
+            message: `Macro primitive_id '${macro.id}' is not registered in vocabulary/invocations.yml — consumer expander cannot handle it.`,
+          });
+        }
+      }
+    } else {
+      // meta.yml and vocabulary files — scan raw source
+      results.push(
+        ...scanRegex(source, CLAUDE_CODE_TOOLS_DISTINCTIVE, rel, 'G6-harness-lint',
           (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
       );
+
       results.push(
-        ...scanRegex(source, OPENCODE_TOOLS, rel, 'G6-harness-lint',
-          (m) => `OpenCode tool name forbidden: '${m}'. Use abstract capability or remove.`)
+        ...scanRegex(source, CALL_PATTERN_TOOLS, rel, 'G6-harness-lint',
+          (m) => `Harness-specific tool call syntax forbidden: '${m}'. Use abstract capability or remove.`)
       );
+
+      results.push(
+        ...scanRegex(source, HARNESS_NAMESPACE, rel, 'G6-harness-lint',
+          (m) => `Harness namespace slash-command forbidden: '${m}'. Use capability abstraction.`)
+      );
+
+      if (rel.endsWith('meta.yml') || rel.startsWith('vocabulary/')) {
+        results.push(
+          ...scanRegex(source, CLAUDE_CODE_TOOLS_AMBIGUOUS, rel, 'G6-harness-lint',
+            (m) => `Harness-specific tool name forbidden: '${m}'. Use abstract capability or remove.`)
+        );
+        results.push(
+          ...scanRegex(source, OPENCODE_TOOLS, rel, 'G6-harness-lint',
+            (m) => `OpenCode tool name forbidden: '${m}'. Use abstract capability or remove.`)
+        );
+      }
     }
   }
   return results;

package/scripts/lib/validate.ts

@@ -65,11 +65,28 @@ interface TagEntry {
   variants?: string[];
 }
 
+interface InvocationParam {
+  name: string;
+  description: string;
+  required: boolean;
+  value_type?: string;
+}
+
+interface InvocationEntry {
+  id: string;
+  description: string;
+  intent: string;
+  semantic_params: InvocationParam[];
+  prose_guidance: string;
+  fallback_behavior: string;
+}
+
 interface Vocab {
   capabilities: CapabilityEntry[];
   categories: SimpleEntry[];
   resume_tiers: SimpleEntry[];
   tags: TagEntry[];
+  invocations: InvocationEntry[];
 }
 
 interface ManifestAgent extends AgentMeta {
@@ -80,6 +97,13 @@ interface ManifestSkill extends SkillMeta {
   body_hash: string;
 }
 
+interface ManifestInvocationEntry {
+  id: string;
+  description: string;
+  intent: string;
+  fallback_behavior: string;
+}
+
 interface Manifest {
   nexus_core_version: string;
   nexus_core_commit: string;
@@ -91,6 +115,7 @@ interface Manifest {
     categories: SimpleEntry[];
     resume_tiers: SimpleEntry[];
     tags: TagEntry[];
+    invocations: ManifestInvocationEntry[];
   };
 }
 
@@ -173,11 +198,18 @@ export async function loadSchemas(root: string): Promise<void> {
     $id: 'vocabulary-tag-file',
     $defs: vocabDefs,
   };
+  const invocationFileSchema = {
+    ...vocabDefs['invocationFile'],
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'vocabulary-invocation-file',
+    $defs: vocabDefs,
+  };
 
   const capabilityValidator = await ajv.compileAsync(capabilityFileSchema);
   const categoryValidator = await ajv.compileAsync(categoryFileSchema);
   const resumeTierValidator = await ajv.compileAsync(resumeTierFileSchema);
   const tagValidator = await ajv.compileAsync(tagFileSchema);
+  const invocationValidator = await ajv.compileAsync(invocationFileSchema);
 
   const manifestAjv = new Ajv2020({
     strict: false,
@@ -204,7 +236,7 @@ export async function loadSchemas(root: string): Promise<void> {
   };
 
   // Store all vocab validators for internal use
-  _vocabValidators = { capabilityValidator, categoryValidator, resumeTierValidator, tagValidator };
+  _vocabValidators = { capabilityValidator, categoryValidator, resumeTierValidator, tagValidator, invocationValidator };
 }
 
 interface VocabValidators {
@@ -212,6 +244,7 @@ interface VocabValidators {
   categoryValidator: ValidateFunction;
   resumeTierValidator: ValidateFunction;
   tagValidator: ValidateFunction;
+  invocationValidator: ValidateFunction;
 }
 
 let _vocabValidators: VocabValidators | null = null;
@@ -440,6 +473,49 @@ export function checkCapabilityEntryIntegrity(capabilities: CapabilityEntry[]):
   return results;
 }
 
+// ─── G6': Invocation entry integrity ─────────────────────────────────────────
+
+export function checkInvocationEntryIntegrity(invocations: InvocationEntry[]): ValidationResult[] {
+  const results: ValidationResult[] = [];
+  for (const inv of invocations) {
+    if (!SNAKE_CASE_RE.test(inv.intent)) {
+      results.push({
+        file: 'vocabulary/invocations.yml',
+        gate: 'G6-invocation-integrity',
+        severity: 'error',
+        message: `Invocation '${inv.id}': 'intent' must match snake_case /^[a-z][a-z0-9_]*$/, got '${inv.intent}'`,
+      });
+    }
+    if (!inv.prose_guidance || inv.prose_guidance.trim().length < 40) {
+      results.push({
+        file: 'vocabulary/invocations.yml',
+        gate: 'G6-invocation-integrity',
+        severity: 'error',
+        message: `Invocation '${inv.id}': 'prose_guidance' must be at least 40 characters`,
+      });
+    }
+    if (!inv.fallback_behavior || inv.fallback_behavior.trim().length < 20) {
+      results.push({
+        file: 'vocabulary/invocations.yml',
+        gate: 'G6-invocation-integrity',
+        severity: 'error',
+        message: `Invocation '${inv.id}': 'fallback_behavior' must be at least 20 characters`,
+      });
+    }
+    for (const param of inv.semantic_params ?? []) {
+      if (!SNAKE_CASE_RE.test(param.name)) {
+        results.push({
+          file: 'vocabulary/invocations.yml',
+          gate: 'G6-invocation-integrity',
+          severity: 'error',
+          message: `Invocation '${inv.id}': param name '${param.name}' must match snake_case /^[a-z][a-z0-9_]*$/`,
+        });
+      }
+    }
+  }
+  return results;
+}
+
 // ─── Vocabulary loading ───────────────────────────────────────────────────────
 
 async function loadVocab(root: string): Promise<{ vocab: Vocab | null; results: ValidationResult[] }> {
@@ -483,14 +559,15 @@ async function loadVocab(root: string): Promise<{ vocab: Vocab | null; results:
     return data as T;
   }
 
-  const [capData, catData, resumeData, tagData] = await Promise.all([
+  const [capData, catData, resumeData, tagData, invocationData] = await Promise.all([
     loadYaml<{ capabilities: CapabilityEntry[] }>('capabilities.yml', _vocabValidators.capabilityValidator),
     loadYaml<{ categories: SimpleEntry[] }>('categories.yml', _vocabValidators.categoryValidator),
     loadYaml<{ resume_tiers: SimpleEntry[] }>('resume-tiers.yml', _vocabValidators.resumeTierValidator),
     loadYaml<{ tags: TagEntry[] }>('tags.yml', _vocabValidators.tagValidator),
+    loadYaml<{ invocations: InvocationEntry[] }>('invocations.yml', _vocabValidators.invocationValidator),
   ]);
 
-  if (!capData || !catData || !resumeData || !tagData) {
+  if (!capData || !catData || !resumeData || !tagData || !invocationData) {
     return { vocab: null, results };
   }
 
@@ -500,6 +577,7 @@ async function loadVocab(root: string): Promise<{ vocab: Vocab | null; results:
       categories: catData.categories,
       resume_tiers: resumeData.resume_tiers,
       tags: tagData.tags,
+      invocations: invocationData.invocations,
     },
     results,
   };
@@ -539,6 +617,13 @@ export async function generateManifest(
     })
   );
 
+  const invocationSummaries: ManifestInvocationEntry[] = vocab.invocations.map((inv) => ({
+    id: inv.id,
+    description: inv.description,
+    intent: inv.intent,
+    fallback_behavior: inv.fallback_behavior,
+  }));
+
   return {
     nexus_core_version: version,
     nexus_core_commit: commit,
@@ -550,6 +635,7 @@ export async function generateManifest(
       categories: vocab.categories,
       resume_tiers: vocab.resume_tiers,
       tags: vocab.tags,
+      invocations: invocationSummaries,
     },
   };
 }
@@ -624,6 +710,8 @@ export async function runAll(root: string): Promise<ValidationResult[]> {
     allResults.push(...checkTagIntegrity(validSkills, tags));
     // G5': capability entry field integrity
     allResults.push(...checkCapabilityEntryIntegrity(vocab.capabilities));
+    // G6': invocation entry field integrity
+    allResults.push(...checkInvocationEntryIntegrity(vocab.invocations));
   }
 
   // Manifest generation — only on full success (no errors)

package/skills/nx-init/body.md

@@ -16,9 +16,9 @@ Scans the project and builds Nexus knowledge in the flat .nexus/ structure. On f
 
 ## Trigger
 
-- `/claude-nexus:nx-init` — full onboarding (or resume)
-- `/claude-nexus:nx-init --reset` — back up existing `.nexus/` knowledge and re-onboard
-- `/claude-nexus:nx-init --reset --cleanup` — show backup list + selective deletion
+- Manual trigger — full onboarding (or resume). See harness docs: slash_command_display.
+- Manual trigger with `--reset` flag — back up existing `.nexus/` knowledge and re-onboard. See harness docs: slash_command_display.
+- Manual trigger with `--reset --cleanup` flags — show backup list + selective deletion. See harness docs: slash_command_display.
 
 ---
 
@@ -51,9 +51,7 @@ Show backup directory list, let user select backups to delete.
 ```
 IF --reset --cleanup flag:
   Show list of .nexus/bak.*/ directories
-  Prompt user with options (using the harness's interactive prompt mechanism):
-    question: "Select a backup to delete (or cancel)"
-    options: [...backup list..., { label: "Cancel", description: "Exit without changes" }]
+  Prompt user with options via `{{user_question question="Select a backup to delete (or cancel)" options=[<backup list...>, {label: Cancel, description: "Exit without changes"}]}}`.
   Delete selected backup and exit
 
 ELSE IF --reset flag:
@@ -162,15 +160,7 @@ On completion: "context knowledge N files generated"
 Check whether team custom rules are needed.
 
 ```
-prompt_user({
-  questions: [{
-    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" }
-    ]
-  }]
-})
+{{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"}]}}
 ```
 
 If "Set up": present a draft based on scan results → user confirms → save via the harness's file-creation primitive to `.nexus/rules/{topic}.md`.
@@ -192,5 +182,5 @@ Output a summary of the onboarding results.
 ### Next Steps
 - [plan] — research, analyze, and plan before execution
 - [run] — execute from a plan
-- /claude-nexus:nx-init --reset — re-run onboarding (existing knowledge will be backed up)
+- Manual re-run trigger with `--reset` flag — re-run onboarding (existing knowledge will be backed up). See harness docs: slash_command_display.
 ```

package/skills/nx-init/meta.yml

@@ -4,4 +4,5 @@ summary: "Project onboarding — scan, mission, essentials, context generation"
 manual_only: true
 harness_docs_refs:
   - instruction_file
+  - slash_command_display
 id: nx-init

package/skills/nx-plan/body.md

@@ -35,7 +35,7 @@ Facilitate structured multi-perspective analysis using subagents to decompose is
 
 ## Auto Mode (`[plan:auto]`)
 
-When triggered with `[plan:auto]` or invoked via `Skill({ args: "auto" })`, run the full planning process **without user interaction**:
+When triggered with `[plan:auto]` or invoked via `{{skill_activation skill=nx-plan mode=auto}}`, run the full planning process **without user interaction**:
 
 1. **Research** — spawn researcher+Explore subagents (same as interactive)
 2. **Issue derivation** — Lead identifies issues from research
@@ -93,8 +93,8 @@ Understand code, core knowledge, and prior decisions before forming a planning a
 
 | Scenario | Approach |
 |----------|----------|
-| Codebase orientation | Spawn Explore agent (`subagent_type: "Explore"`) for file/code search |
-| External research needed | Spawn Researcher agent (`subagent_type: "claude-nexus:researcher"`) for web search |
+| Codebase orientation | `{{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 codebase and external | Spawn Explore + Researcher in parallel |
 
 - NEVER call `nx_plan_start` before research is complete.

package/skills/nx-run/body.md

@@ -24,16 +24,16 @@ Execution norm that Lead follows when the user invokes the [run] tag. Composes s
 - **Branch Guard**: if on main/master, create a branch appropriate to the task type before proceeding (prefix: `feat/`, `fix/`, `chore/`, `research/`, etc. — Lead's judgment). Auto-create without user confirmation.
 - Check for `tasks.json`:
   - **Exists** → read it and proceed to Step 2.
-  - **Absent** → auto-invoke `Skill({ skill: "claude-nexus:nx-plan", args: "auto" })` to generate tasks.json. Do NOT ask — `[run]` implies execution intent. After plan generation, proceed to Step 2.
+  - **Absent** → auto-invoke `{{skill_activation skill=nx-plan mode=auto}}` to generate tasks.json. Do NOT ask — `[run]` implies execution intent. After plan generation, proceed to Step 2.
 - If tasks.json exists, check prior decisions with `nx_plan_status`.
 
 ### Step 1.5: TUI Progress
 
 Register tasks for visual progress tracking (Ctrl+T):
 
-- **≤ 10 tasks**: `TaskCreate` per task
-- **> 10 tasks**: group by `plan_issue`, `TaskCreate` per group
-- Use `TaskUpdate` to reflect progress (`in_progress` / `completed`) as execution proceeds
+- **≤ 10 tasks**: `{{task_register label="<per-task label>" state=pending}}` per task
+- **> 10 tasks**: group by `plan_issue`, `{{task_register label="<group label>" state=pending}}` per group
+- Update the registered entry via `{{task_register label="<label>" state=in_progress}}` / `{{task_register label="<label>" state=completed}}` as execution proceeds
 - **Skip only if**: non-TTY environment (VSCode, headless)
 - **Known issue**: TUI may freeze during auto-compact (#27919) — task data on disk remains correct
 
@@ -90,7 +90,7 @@ For each task, Lead chooses between fresh spawn and resume based on the `owner`'
 
 Execute in order:
 
-1. **nx-sync**: invoke `Skill({ skill: "claude-nexus:nx-sync" })` if code changes were made in this cycle. Best effort — failure does not block cycle completion.
+1. **nx-sync**: invoke `{{skill_activation skill=nx-sync}}` if code changes were made in this cycle. Best effort — failure does not block cycle completion.
 2. **nx_task_close**: call to archive plan+tasks to history.json. This updates `.nexus/history.json`.
 3. **git commit**: stage and commit source changes, build artifacts (`bridge/`, `scripts/`), `.nexus/history.json`, and any modified `.nexus/memory/` or `.nexus/context/`. Use explicit `git add` with paths (not `git add -A`) and a HEREDOC commit message with `Co-Authored-By`. This ensures the cycle's history archive lands in the same commit as the code changes, giving a 1:1 cycle-commit mapping.
 4. **Report**: summarize to user — changed files, key decisions applied, and suggested next steps. Merge/push is the user's decision and outside this skill's scope.

package/skills/nx-sync/body.md

@@ -44,8 +44,9 @@ Only update files where a concrete change is detected. If no staleness is found,
 Spawn Writer agent to update affected context documents:
 
 ```
-Agent({ subagent_type: "claude-nexus:writer", name: "writer-sync-context",
-  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}" })
+{{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
 ```
 
 The Writer agent:

package/vocabulary/invocations.yml

@@ -0,0 +1,116 @@
+# Harness-neutral invocation semantic definitions.
+# Each entry describes WHAT is invoked and what params are semantically required.
+# Consumers (claude-nexus, opencode-nexus) maintain their own
+# local map from these semantic primitives to concrete tool call syntax in their own repo.
+# nexus-core does not and must not know those tool names.
+#
+# body.md uses macro syntax: {{primitive_id key1=val1 key2=val2}}
+# See Spec γ (plan session #4, Issue #2) for macro grammar.
+
+invocations:
+  - id: skill_activation
+    description: "Activate another skill within the current conversation."
+    intent: skill_entry_dispatch
+    semantic_params:
+      - name: skill
+        description: "Canonical skill id from manifest.json skills list."
+        required: true
+      - name: mode
+        description: "Activation mode (e.g., 'auto' for non-interactive)."
+        required: false
+    prose_guidance: |
+      Invoke a skill whose logic should be inlined into the current session.
+      The target skill must exist in the current harness's skill registry.
+      The invocation transfers execution context to the named skill; the
+      calling skill yields until the activated skill completes or signals
+      a return. Optional mode parameters modify activation behavior (e.g.,
+      bypassing interactive prompts for fully autonomous execution).
+      Only skill ids that appear in manifest.json are valid targets.
+    fallback_behavior: |
+      If the harness lacks a live skill activation primitive, re-emit the
+      skill's trigger tag (e.g., '[plan:auto]') as a self-dispatch signal,
+      relying on tag detection to re-enter the skill. The skill id must be
+      mapped to its canonical trigger tag by the harness's own docs.
+
+  - id: subagent_spawn
+    description: "Spawn a new subagent session with a specific role and prompt."
+    intent: subagent_session_create
+    semantic_params:
+      - name: target_role
+        description: "Canonical agent id from manifest.json agents list (e.g., 'writer', 'engineer')."
+        required: true
+      - name: prompt
+        description: "Structured task prompt. May be multiline (heredoc in body.md)."
+        required: true
+      - name: name
+        description: "Optional instance label for this subagent session."
+        required: false
+      - name: resume_tier_hint
+        description: "Optional hint from vocabulary/resume-tiers.yml (e.g., 'bounded', 'ephemeral')."
+        required: false
+    prose_guidance: |
+      Delegates a bounded unit of work to an agent with the given role.
+      The target_role must match an id in manifest.json agents list; the
+      harness resolves this to a concrete session or thread configuration.
+      The prompt provides the complete task specification for the subagent,
+      including all context the agent needs — do not rely on ambient session
+      state unless the resume_tier_hint indicates persistent context.
+      resume_tier_hint is advisory: harnesses may override based on their
+      own session management constraints.
+    fallback_behavior: |
+      If the harness lacks an explicit subagent spawn primitive (e.g.,
+      hooks-based implicit routing), inject the target_role as a routing
+      hint and structure the prompt so the harness's own delegation rules
+      catch it. A harness that cannot spawn agents must document this
+      limitation and treat the invocation as a no-op with a warning.
+
+  - id: task_register
+    description: "Register a task for user-visible progress tracking."
+    intent: execution_visibility_register
+    semantic_params:
+      - name: label
+        description: "Short human-readable task label."
+        required: true
+      - name: state
+        description: "Current state (pending / in_progress / completed)."
+        required: true
+    prose_guidance: |
+      Primarily for TUI progress rendering — allows the user to see which
+      work items are active, pending, or done during multi-step execution.
+      The label should be concise enough to display in a progress panel.
+      The state values are constrained to a three-state lifecycle: pending
+      (enqueued but not started), in_progress (currently executing), and
+      completed (done). Harnesses without TUI progress support may silently
+      no-op this primitive; failure must not block execution flow.
+    fallback_behavior: |
+      If the harness has no TUI task tracker, omit the call entirely. This
+      primitive is best-effort — failure or absence must not block
+      execution. Logging the label and state to the conversation transcript
+      is acceptable as a degraded fallback for auditability.
+
+  - id: user_question
+    description: "Ask the user a structured question with selectable options."
+    intent: structured_user_prompt
+    semantic_params:
+      - name: question
+        description: "The question text shown to the user."
+        required: true
+      - name: options
+        description: "Array of option objects, each with 'label' and 'description'. If empty, free-form response is expected."
+        required: true
+    prose_guidance: |
+      Presents the user with a structured decision point. When options is
+      non-empty, the user is expected to select one of the provided choices;
+      when empty, the user provides a free-form text response. The harness
+      is responsible for rendering options in a way appropriate to its UI
+      (e.g., numbered list, interactive picker, inline buttons). The LLM
+      should not proceed with execution until a response is received.
+      Use this primitive for branch points that require explicit user input,
+      not for informational messages or confirmations that could be inferred
+      from context.
+    fallback_behavior: |
+      If the harness lacks a structured question tool (e.g., opencode-nexus),
+      present the question as prose followed by the options enumerated as a
+      numbered list, then await the user's free-form reply. The LLM is
+      expected to map the reply to the most appropriate option or treat it
+      as a free-form answer if no options were given.