@moreih29/nexus-core 0.7.1 → 0.8.0

package/manifest.json

@@ -1,6 +1,6 @@
 {
-  "nexus_core_version": "0.7.1",
-  "nexus_core_commit": "d2da7dede9540a14bc5925904c2382795f383b1e",
+  "nexus_core_version": "0.8.0",
+  "nexus_core_commit": "254efc7d8f4f52e45b548706dd42389fdb9801b2",
   "schema_contract_version": "2.0",
   "agents": [
     {
@@ -20,24 +20,25 @@
       "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",
+      "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": "engineer",
-      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
+      "id": "reviewer",
+      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
     {
-      "name": "designer",
-      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
-      "task": "UI/UX design, interaction patterns, user experience",
-      "alias_ko": "디자이너",
+      "name": "strategist",
+      "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
+      "task": "Business strategy, market analysis, competitive positioning",
+      "alias_ko": "전략가",
       "category": "how",
       "resume_tier": "persistent",
       "model_tier": "high",
@@ -46,14 +47,14 @@
         "no_task_create",
         "no_task_update"
       ],
-      "id": "designer",
-      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
+      "id": "strategist",
+      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
-      "name": "strategist",
-      "description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
-      "task": "Business strategy, market analysis, competitive positioning",
-      "alias_ko": "전략가",
+      "name": "designer",
+      "description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
+      "task": "UI/UX design, interaction patterns, user experience",
+      "alias_ko": "디자이너",
       "category": "how",
       "resume_tier": "persistent",
       "model_tier": "high",
@@ -62,8 +63,8 @@
         "no_task_create",
         "no_task_update"
       ],
-      "id": "strategist",
-      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
+      "id": "designer",
+      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     },
     {
       "name": "researcher",
@@ -80,6 +81,20 @@
       "id": "researcher",
       "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
+    {
+      "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": "postdoc",
       "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
@@ -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",
@@ -143,17 +143,26 @@
   ],
   "skills": [
     {
-      "name": "nx-run",
-      "description": "Execution — user-directed agent composition.",
-      "summary": "Execution — user-directed agent composition",
-      "triggers": [
-        "run"
-      ],
+      "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-run",
-      "body_hash": "sha256:6c8d1a36626d4034209ff83780dec6238297ec4710612441b2ef09daac714ca8"
+      "id": "nx-init",
+      "body_hash": "sha256:b828a974ab4722dd7f1d15a4338d1380fdae47cd42c1bd4a5539277075efb6fc"
+    },
+    {
+      "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",
+      "body_hash": "sha256:3ee8dd780d53f2e04472de6c701e16bc1fbde7f2ce9ed4e680b7cd2010530a22"
     },
     {
       "name": "nx-plan",
@@ -166,28 +175,20 @@
         "resume_invocation"
       ],
       "id": "nx-plan",
-      "body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
+      "body_hash": "sha256:cd7a5fd1815530be6ffad18358a1295d1f74ef8a24132e75b73522c106eb6ae5"
     },
     {
-      "name": "nx-sync",
-      "description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
-      "summary": "Context knowledge synchronization",
+      "name": "nx-run",
+      "description": "Execution — user-directed agent composition.",
+      "summary": "Execution — user-directed agent composition",
       "triggers": [
-        "sync"
+        "run"
       ],
-      "id": "nx-sync",
-      "body_hash": "sha256:a7b0ae8f13ebcd10e52361d0ada1570ff0c47933f731deec07e95539c63e6946"
-    },
-    {
-      "name": "nx-init",
-      "description": "Project onboarding — scan, mission, essentials, context generation",
-      "summary": "Project onboarding — scan, mission, essentials, context generation",
-      "manual_only": true,
       "harness_docs_refs": [
-        "instruction_file"
+        "resume_invocation"
       ],
-      "id": "nx-init",
-      "body_hash": "sha256:3c8230ecc0f87c541ec0ff80492a28f28bf173d0b9781901adadfae69a54b8ed"
+      "id": "nx-run",
+      "body_hash": "sha256:0e2c443efceeab4621709a85cd4e2ba50471d2e850680c655d776cbb62814549"
     }
   ],
   "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.8.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.