@moreih29/nexus-core 0.1.2 → 0.3.0

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "nexus_core_version": "0.1.2",
-  "nexus_core_commit": "93d8d74493b8897a80e9de1342c0da5f0d04f6e2",
-  "schema_contract_version": "1.0",
+  "nexus_core_version": "0.3.0",
+  "nexus_core_commit": "c5953c739cd5e24be7dd9eb2bb2940e96f611039",
+  "schema_contract_version": "2.0",
   "agents": [
     {
       "name": "architect",
@@ -17,7 +17,7 @@
         "no_task_update"
       ],
       "id": "architect",
-      "body_hash": "sha256:a9424a28d14e04a8c487ab9c1718f9ac929e8a2558abcf848a7c1722ceb8a79d"
+      "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
     {
       "name": "designer",
@@ -33,22 +33,21 @@
         "no_task_update"
       ],
       "id": "designer",
-      "body_hash": "sha256:9ccab5e29cca4b57250c41ffaea6656fc655bee2a19fc5e29c08e2e4ab669021"
+      "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",
+      "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_file_edit",
         "no_task_create"
       ],
-      "id": "reviewer",
-      "body_hash": "sha256:76312fd237bb9f76fff243b5f10e9efa8ac726c793f401d30846423c11871feb"
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
     },
     {
       "name": "strategist",
@@ -64,21 +63,7 @@
         "no_task_update"
       ],
       "id": "strategist",
-      "body_hash": "sha256:32e70f5ad8e1a37fb544c398147c39020b19fed8cde8c066fad02cea37481cc2"
-    },
-    {
-      "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:79ce728ef86027c3301b26454ae5e1ed2db58cf4ce812521df4f6473661e3cd3"
+      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
       "name": "researcher",
@@ -93,7 +78,7 @@
         "no_task_create"
       ],
       "id": "researcher",
-      "body_hash": "sha256:5ec30a3449047fadfbeabc01778204baa66f3016f48bed3bc95bdff9c9b386bd"
+      "body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
     },
     {
       "name": "postdoc",
@@ -109,7 +94,22 @@
         "no_task_update"
       ],
       "id": "postdoc",
-      "body_hash": "sha256:62633ddb64097e249959cde60b40e44a99b163d08c1c950afbe04309dbf5d37c"
+      "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",
@@ -124,7 +124,7 @@
         "no_task_create"
       ],
       "id": "tester",
-      "body_hash": "sha256:6455a816b3a1c80fd689c19779d9fc5b411948d768cdd240d964b1feea3f51a0"
+      "body_hash": "sha256:4dd04e1c93ff9c0c9fa6aebb60ece3f9719e82f9714b13feea01b6163633caec"
     },
     {
       "name": "writer",
@@ -138,94 +138,102 @@
         "no_task_create"
       ],
       "id": "writer",
-      "body_hash": "sha256:ff017d33ffd9d8c8e6e34b7c43a39215b0121cace4e5421ad6d7b7dd9ee7b497"
+      "body_hash": "sha256:2edd9bf52e537c446b5ebfaafab214ebaaad2491f019aa8534453bff3f1cd37b"
     }
   ],
   "skills": [
     {
       "name": "nx-run",
       "description": "Execution — user-directed agent composition.",
+      "summary": "Execution — user-directed agent composition",
       "triggers": [
         "run"
       ],
+      "harness_docs_refs": [
+        "resume_invocation"
+      ],
       "id": "nx-run",
-      "body_hash": "sha256:04e99cfbc01cf170e1515404aceb6656e7e92feac308eb8a67c6a625eab995d3"
+      "body_hash": "sha256:6c8d1a36626d4034209ff83780dec6238297ec4710612441b2ef09daac714ca8"
     },
     {
-      "name": "nx-setup",
-      "description": "Interactive project setup wizard for Nexus configuration.",
-      "manual_only": true,
-      "id": "nx-setup",
-      "body_hash": "sha256:bbcb07f8ede7b410c71668c97d47e59843f13aef064c1f337ae7e44ecc257ae4"
+      "name": "nx-plan",
+      "description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
+      "summary": "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan",
+      "triggers": [
+        "plan"
+      ],
+      "harness_docs_refs": [
+        "resume_invocation"
+      ],
+      "id": "nx-plan",
+      "body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
     },
     {
       "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"
+      ],
       "id": "nx-init",
-      "body_hash": "sha256:ab636e7c338b58e2288855c2a99ce079c53bb39f7adf3af3ce5769b5a32f73b1"
+      "body_hash": "sha256:3c8230ecc0f87c541ec0ff80492a28f28bf173d0b9781901adadfae69a54b8ed"
     },
     {
       "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:dbd3933c0474b2831a857308d9dd6ccd2c072f089327c22ce8d2842894fc3216"
-    },
-    {
-      "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.",
-      "triggers": [
-        "plan"
-      ],
-      "id": "nx-plan",
-      "body_hash": "sha256:461097c9b69db300c0b6afe56fc138eca0c26f019ab5fe3c0d245fddcd848a22"
+      "body_hash": "sha256:a7b0ae8f13ebcd10e52361d0ada1570ff0c47933f731deec07e95539c63e6946"
     }
   ],
   "vocabulary": {
     "capabilities": [
       {
         "id": "no_file_edit",
-        "description": "Agent cannot create or modify files in the user's workspace",
-        "harness_mapping": {
-          "claude_code": [
-            "Edit",
-            "Write",
-            "NotebookEdit"
-          ],
-          "opencode": [
-            "edit",
-            "write",
-            "patch",
-            "multiedit"
-          ]
-        }
+        "description": "Agent cannot create, modify, or delete files in the user's workspace.",
+        "intent": "workspace_write_denial",
+        "blocks_semantic_classes": [
+          "file_creation",
+          "file_modification",
+          "file_deletion",
+          "partial_file_edit",
+          "structured_document_edit"
+        ],
+        "prose_guidance": "Block any tool whose primary effect is to alter content at a workspace\nfile path. This includes: creating new files at arbitrary paths, rewriting\nwhole file contents, applying partial edits (diffs, patches, find-replace,\nmulti-edit batches), deleting or truncating files, and cell-level edits in\nstructured documents such as notebooks.\nRead-only operations are NOT blocked: reading file contents, querying\nmetadata, listing directories, and running code-intelligence queries that\ndo not mutate files.\n"
       },
       {
         "id": "no_task_create",
-        "description": "Agent cannot create new tasks in the Nexus task pipeline",
-        "harness_mapping": {
-          "claude_code": [
-            "mcp__plugin_claude-nexus_nx__nx_task_add"
-          ],
-          "opencode": [
-            "nx_task_add"
-          ]
-        }
+        "description": "Agent cannot create new tasks in the Nexus task pipeline.",
+        "intent": "task_pipeline_append_denial",
+        "blocks_semantic_classes": [
+          "nexus_task_creation"
+        ],
+        "prose_guidance": "Block any tool that appends a new task to the Nexus task pipeline (the\nmechanism by which Lead-owned work is enqueued for execution). Tools that\nread, list, or query existing tasks are NOT blocked. Tools that modify\nexisting task state belong to a separate capability (no_task_update) and\nare not governed here.\n"
       },
       {
         "id": "no_task_update",
-        "description": "Agent cannot update the state of existing Nexus tasks",
-        "harness_mapping": {
-          "claude_code": [
-            "mcp__plugin_claude-nexus_nx__nx_task_update"
-          ],
-          "opencode": [
-            "nx_task_update"
-          ]
-        }
+        "description": "Agent cannot update the state of existing Nexus tasks.",
+        "intent": "task_pipeline_mutate_denial",
+        "blocks_semantic_classes": [
+          "nexus_task_state_transition",
+          "nexus_task_metadata_modification"
+        ],
+        "prose_guidance": "Block any tool that mutates an existing Nexus task: changing its status,\nediting its description, reassigning ownership, closing it, or modifying\nany field on its record. Tools that read, list, or query tasks are NOT\nblocked. Creation of new tasks is governed by no_task_create, not here.\n"
+      },
+      {
+        "id": "no_shell_exec",
+        "description": "Agent cannot execute arbitrary shell commands or spawn subprocesses.",
+        "intent": "shell_execution_denial",
+        "blocks_semantic_classes": [
+          "shell_command_exec",
+          "subprocess_spawn",
+          "interactive_shell_session"
+        ],
+        "prose_guidance": "Block any tool whose primary effect is to run a command-line invocation,\nshell script, or spawn a subprocess on the user's machine. This includes\ngeneral-purpose shell runners, background process managers, shell output\nreaders, and shell-session kill operations. Tools that read files, query\nmetadata, or call specialized non-shell APIs (HTTP, language-server\nqueries, sandboxed code evaluators that do not spawn user-machine\nprocesses) are NOT blocked.\n"
       }
     ],
     "categories": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moreih29/nexus-core",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Nexus ecosystem Authoring layer — canonical prompts, neutral metadata, and vocabulary shared by Nexus harnesses",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,8 @@
     "./skills/*": "./skills/*",
     "./vocabulary/*": "./vocabulary/*",
     "./schema/*": "./schema/*",
+    "./conformance/*": "./conformance/*",
+    "./docs/*": "./docs/*",
     "./manifest.json": "./manifest.json"
   },
   "files": [
@@ -24,6 +26,8 @@
     "skills",
     "vocabulary",
     "schema",
+    "conformance",
+    "docs",
     "manifest.json"
   ],
   "engines": {

package/schema/common.schema.json

@@ -12,10 +12,6 @@
     "description": {
       "type": "string",
       "minLength": 1
-    },
-    "harnessId": {
-      "type": "string",
-      "enum": ["claude_code", "opencode"]
     }
   }
 }

package/schema/skill.schema.json

@@ -15,7 +15,22 @@
       "items": { "$ref": "common.schema.json#/$defs/id" }
     },
     "alias_ko": { "type": "string" },
-    "manual_only": { "type": "boolean", "default": false }
+    "manual_only": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, this skill MUST NOT be auto-invoked by the LLM from natural language inference. Only explicit user-initiated triggers (slash command or bracket tag typed by the user) may activate it."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 120,
+      "description": "Short one-line identity for UI/catalog rendering. Not a substitute for description."
+    },
+    "harness_docs_refs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "List of harness-specific documentation keys that consumers should surface when rendering this skill. Keys reference entries in a consumer-local harness-docs directory."
+    }
   },
   "allOf": [
     {

package/schema/vocabulary.schema.json

@@ -6,18 +6,23 @@
     "capabilityEntry": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "description", "harness_mapping"],
+      "required": ["id", "description", "intent", "blocks_semantic_classes", "prose_guidance"],
       "properties": {
         "id": { "$ref": "common.schema.json#/$defs/id" },
         "description": { "$ref": "common.schema.json#/$defs/description" },
-        "harness_mapping": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["claude_code", "opencode"],
-          "properties": {
-            "claude_code": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-            "opencode": { "type": "array", "items": { "type": "string", "minLength": 1 } }
-          }
+        "intent": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "blocks_semantic_classes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }
+        },
+        "prose_guidance": {
+          "type": "string",
+          "minLength": 40
         }
       }
     },

package/skills/nx-init/body.md

@@ -4,11 +4,11 @@ Scans the project and builds Nexus knowledge in the flat .nexus/ structure. On f
 
 ## Constraints
 
-- NEVER modify source code. Slimming down CLAUDE.md beyond the project section is not this skill's responsibility.
+- NEVER modify source code. Slimming down the instruction file beyond the project section is not this skill's responsibility.
 - NEVER infer or guess information that cannot be confirmed from code — do not write it to context/.
 - NEVER store secrets (API keys, credentials, etc.) in knowledge files.
-- NEVER overwrite existing files without `--reset`. On resume, preserve existing files.
-- Project section in CLAUDE.md MUST go through user confirmation before writing.
+- NEVER overwrite existing files without `--reset`. On resume, preserve existing files intact.
+- Project section in the instruction file MUST go through user confirmation before writing.
 - NEVER reference or create identity/, codebase/, reference/, or core/ paths.
 - Essentials section MUST NOT exceed 10 lines. If more items are needed, move lower-priority ones to .nexus/context/.
 
@@ -51,12 +51,9 @@ Show backup directory list, let user select backups to delete.
 ```
 IF --reset --cleanup flag:
   Show list of .nexus/bak.*/ directories
-  AskUserQuestion({
-    questions: [{
-      question: "Select a backup to delete (or cancel)",
-      options: [...backup list..., { label: "Cancel", description: "Exit without changes" }]
-    }]
-  })
+  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" }]
   Delete selected backup and exit
 
 ELSE IF --reset flag:
@@ -79,7 +76,7 @@ ELSE:
 
 Auto-detect code structure and tech stack. Create the flat `.nexus/` directory structure if it does not exist.
 
-Create directories (using Bash mkdir):
+Create directories (using shell command execution):
 - `.nexus/memory/`
 - `.nexus/context/`
 - `.nexus/state/`
@@ -119,7 +116,7 @@ Do not include items that are standard defaults for the detected tech stack. Do
 Present the full draft to the user in this format:
 
 ```
-The following will be added to CLAUDE.md (existing content will not be changed):
+The following will be added to the instruction file (see harness docs: instruction_file) (existing content will not be changed):
 
 <!-- PROJECT:START -->
 ## {project-name}
@@ -136,7 +133,7 @@ Any changes?
 
 Wait for the user to confirm or provide edits. Apply all changes in one pass — do not ask about Mission and Essentials separately.
 
-After confirmation, write the section into CLAUDE.md inside markers using the Edit tool. If CLAUDE.md already contains `<!-- PROJECT:START -->` markers, replace the content between them. If CLAUDE.md does not exist, create it with the markers.
+After confirmation, write the section into the instruction file inside markers using the harness's file-editing primitive. If the instruction file already contains `<!-- PROJECT:START -->` markers, replace the content between them. If the instruction file does not exist, create it with the markers.
 
 ### Step 3: Context Knowledge Auto-Generation
 
@@ -152,9 +149,9 @@ Principles:
 Generation targets (select and name based on what the project actually needs):
 - Development stack (languages, frameworks, runtimes, key dependencies, build/test/deploy workflow)
 - Design and architecture (module relationships, data flow, core entry points, conventions)
-- Implementation specifics (pipeline details, configuration patterns, file structure conventions, tool restrictions — anything too specific for CLAUDE.md but not readable from code alone)
+- Implementation specifics (pipeline details, configuration patterns, file structure conventions, tool restrictions — anything too specific for the instruction file but not readable from code alone)
 
-Use the Write tool to create files at `.nexus/context/{chosen-name}.md`.
+Use the harness's file-creation primitive to create files at `.nexus/context/{chosen-name}.md`.
 
 For large projects, spawn Writer subagents per topic to generate context knowledge in parallel. Lead coordinates and reviews outputs.
 
@@ -165,7 +162,7 @@ On completion: "context knowledge N files generated"
 Check whether team custom rules are needed.
 
 ```
-AskUserQuestion({
+prompt_user({
   questions: [{
     question: "Do you want to set up development rules now?",
     options: [
@@ -176,7 +173,7 @@ AskUserQuestion({
 })
 ```
 
-If "Set up": present a draft based on scan results → user confirms → save via Write tool to `.nexus/rules/{topic}.md`.
+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`.
 
 If "Skip": inform and proceed to Step 5.
 
@@ -188,7 +185,7 @@ Output a summary of the onboarding results.
 ## Nexus Initialization Complete
 
 ### Generated Files
-- CLAUDE.md: project section — mission and essentials (<!-- PROJECT:START/END -->)
+- instruction file: project section — mission and essentials (<!-- PROJECT:START/END -->)
 - .nexus/context/: {list of generated files}
 - .nexus/rules/: {generated files or "none (skipped)"}
 

package/skills/nx-init/meta.yml

@@ -1,4 +1,7 @@
 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
 id: nx-init

package/skills/nx-plan/body.md

@@ -8,7 +8,7 @@ Facilitate structured multi-perspective analysis using subagents to decompose is
 - NEVER call `nx_plan_start` before research is complete (research_summary is required)
 - NEVER present multiple issues at once — one issue at a time only
 - NEVER ask groundless questions — always research code/knowledge/decisions first
-- NEVER use TeamCreate. SendMessage is permitted ONLY for resuming completed subagents whose `resume_tier` is `persistent` or `bounded`, and ONLY within the constraints of the Resume Policy section below. SendMessage to a `name` (running teammate communication) remains forbidden in plan sessions.
+- NEVER use the harness's team creation primitive. Inter-agent messaging for resume is permitted ONLY for resuming completed subagents whose `resume_tier` is `persistent` or `bounded`, and ONLY within the constraints of the Resume Policy section below. Direct inter-agent communication to running teammates remains forbidden in plan sessions.
 - MUST record all decisions with `[d]` tag so they are not scattered across turns
 - MUST call `nx_plan_decide` when recording `[d]`
 - MUST check for existing plan.json before starting a new session
@@ -28,7 +28,7 @@ Facilitate structured multi-perspective analysis using subagents to decompose is
 ## Trigger
 
 - Explicit tag: `[plan]` — continue existing session if plan.json exists, otherwise start new
-- Additional analysis needed mid-session: spawn HOW subagents independently via Agent tool
+- Additional analysis needed mid-session: spawn HOW subagents independently via the harness's subagent spawn primitive
 - Continuing conversation without a tag → continue existing session
 
 ---
@@ -50,7 +50,7 @@ When triggered with `[plan:auto]` or invoked via `Skill({ args: "auto" })`, run
 5. **Plan document** — generate tasks.json following Step 7 rules (including HOW-assisted decomposition if `how_agents` present in plan.json issues). Apply owner table and verification auto-pairing.
 
 Key differences from interactive mode:
-- No `AskUserQuestion` or comparison tables — Lead decides autonomously
+- No user prompts or comparison tables — Lead decides autonomously
 - No dynamic agenda proposals — Lead handles all derived issues internally
 - Output: tasks.json ready for `[run]` execution
 
@@ -87,7 +87,7 @@ Determine planning depth and identify which HOW subagents to delegate analysis t
 
 Understand code, core knowledge, and prior decisions before forming a planning agenda.
 
-**Start by checking existing knowledge**: before spawning any subagent, use Glob/Read to scan `.nexus/memory/` and `.nexus/context/` for relevant memos and context files, and use `nx_history_search` to check for prior decisions on this topic. If the needed information is already there, use it directly and skip or narrow the subagent spawn. Only spawn subagents to fill gaps not covered by existing knowledge.
+**Start by checking existing knowledge**: before spawning any subagent, use file pattern search and file reading to scan `.nexus/memory/` and `.nexus/context/` for relevant memos and context files, and use `nx_history_search` to check for prior decisions on this topic. If the needed information is already there, use it directly and skip or narrow the subagent spawn. Only spawn subagents to fill gaps not covered by existing knowledge.
 
 **Approach selection:**
 
@@ -99,7 +99,7 @@ Understand code, core knowledge, and prior decisions before forming a planning a
 
 - NEVER call `nx_plan_start` before research is complete.
 - `research_summary` parameter in `nx_plan_start` is required — forces research completion before session creation.
-- Researcher subagents are spawned via the Agent tool and return findings to Lead. They do not join the plan session.
+- Researcher subagents are spawned via the harness's subagent spawn primitive and return findings to Lead. They do not join the plan session.
 
 **Existing session (plan.json present):**
 - Check current state with `nx_plan_status`.
@@ -120,7 +120,7 @@ Register the planning session.
 For each issue:
 
 1. **Current State Analysis** — Lead summarizes the current state and problems, drawing on research.
-2. **Subagent Analysis** — for complex issues, spawn HOW subagents (architect, strategist, etc.) in parallel via Agent tool. Each subagent independently analyzes the issue and returns findings.
+2. **Subagent Analysis** — for complex issues, spawn HOW subagents (architect, strategist, etc.) in parallel via the harness's subagent spawn primitive. Each subagent independently analyzes the issue and returns findings.
    - **Domain-Agent mapping** — match issue keywords to recommended HOW subagents:
 
    | Domain keywords | Recommended HOW |
@@ -154,7 +154,7 @@ For each issue:
 
 ## Resume Policy
 
-When `.nexus/state/runtime.json` shows `teams_enabled: false`, ALL resume paths are disabled — force fresh spawn. Otherwise:
+When the harness's resume mechanism is unavailable, ALL resume paths are disabled — force fresh spawn. Otherwise:
 
 | resume_tier | Same-issue default | Cross-issue | Disqualifiers |
 |---|---|---|---|
@@ -211,7 +211,7 @@ All issues decided → generate the plan document (tasks.json) immediately:
    - `deps` — task dependencies based on execution order
    - `owner` — assign based on delegation analysis:
 
-   | Task type | owner | Criteria |
+   | Work type | owner | Criteria |
    |-----------|-------|----------|
    | Single file, small change | **lead** | Subagent overhead > task effort |
    | Code implementation (.ts, .js, .py, etc.) | **engineer** | Source code creation/modification |
@@ -220,11 +220,14 @@ All issues decided → generate the plan document (tasks.json) immediately:
    | Design analysis / review | **architect** etc. HOW | Technical trade-off judgment |
    | Sequential edits to same file | **lead** | Parallel subagents risk conflict |
 
-   **Verification task auto-pairing** — create separate verification tasks:
-   - Task with `owner: "engineer"` + `acceptance` field → pair a **tester** task (verify acceptance criteria)
-   - Task with `owner: "writer"` → pair a **reviewer** task (verify deliverable)
+   **Verification auto-pairing** — create separate verification tasks:
+   - Any task with `owner: "engineer"` + `acceptance` field → pair a **tester** task (verify acceptance criteria)
+   - Any task with `owner: "writer"` → pair a **reviewer** task (verify deliverable)
    - Paired verification tasks are linked via `deps` to the original task
-4. **Write tasks.json** via `nx_task_add`:
+
+   **DO/CHECK decomposition principle**: DO category agents (engineer, writer, researcher) and CHECK category agents (tester, reviewer) operate on artifact-level scope and accumulate less per-task context than HOW category agents. When a task involves multiple independent artifacts (several files, several verification targets, multiple research questions), decompose the task across multiple parallel DO/CHECK subagents rather than bundling them into a single subagent. Single-subagent bundles risk context exhaustion with no wall-clock benefit over parallel decomposition. HOW agents benefit from consolidated context and should generally remain as single sessions. Task granularity is assessed per-task by the plan author, not declared per-agent in meta.yml.
+
+4. **Populate tasks.json** via `nx_task_add`:
    - Set `goal` from the plan topic
    - Set `decisions` from plan.json decided summaries
    - Call `nx_task_add(plan_issue=N, approach, acceptance, risk, owner)` for each task
@@ -292,8 +295,8 @@ Proceed with `[run]` to execute.
 ```
 
 - **Create**: `nx_plan_start(topic, issues, research_summary)` — called in Step 3; auto-archives any existing plan.json
-- **Read**: `nx_plan_status()` — check current issue state + decisions
-- **Update**: `nx_plan_update(action, ...)` — add/remove/edit/reopen issues
+- **Status**: `nx_plan_status()` — check current issue state + decisions
+- **Update**: `nx_plan_update(action, ...)` — add/remove/modify/reopen issues
 - **Decide**: `nx_plan_decide(issue_id, summary)` — marks issue as `decided`, writes decision inline
 - **File presence = session in progress**
 

package/skills/nx-plan/meta.yml

@@ -2,6 +2,9 @@ name: nx-plan
 description: Structured multi-perspective analysis to decompose issues, align on
   decisions, and produce an enriched plan before execution. Plan only — does not
   execute.
+summary: "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan"
 triggers:
   - plan
+harness_docs_refs:
+  - resume_invocation
 id: nx-plan

package/skills/nx-run/body.md

@@ -4,10 +4,10 @@ Execution norm that Lead follows when the user invokes the [run] tag. Composes s
 
 ## Constraints
 
-- NEVER modify files via Bash (sed, echo >, cat <<EOF, tee, etc.) — always use Edit/Write tools (Gate enforced)
+- NEVER modify files via shell commands (sed, echo redirection, heredoc, tee, etc.) — always use the harness's dedicated file-editing primitives (gate enforced)
 - NEVER terminate while pending tasks remain (Gate Stop nonstop)
 - NEVER spawn a new branch without checking for main/master first
-- MUST check tasks.json before executing — if absent, write the plan first
+- MUST check tasks.json before executing — if absent, generate the plan first
 - MUST spawn subagents per-task based on owner field — Do not handle multi-task work as Lead solo when task count ≥ 2 or target files ≥ 2
 - MUST NOT spawn parallel Engineers if their target files overlap — serialize instead
 - MUST call nx_task_close before completing the cycle — archive plan+tasks to history.json
@@ -61,7 +61,7 @@ For each task, Lead chooses between fresh spawn and resume based on the `owner`'
 2. If `ephemeral` → fresh spawn. Stop.
 3. If `bounded` → check tasks.json history: did the same `owner` previously work on overlapping target files? If yes AND no intervening edits by other agents → resume candidate. Otherwise fresh. Always include "re-read target files before any modification" instruction in the resume prompt.
 4. If `persistent` → resume by default if the same agent worked earlier in this run. Cross-task reuse allowed.
-5. Before issuing SendMessage for any resume, verify `.nexus/state/runtime.json` has `teams_enabled: true`. Otherwise fall back to fresh spawn silently — do NOT throw an error.
+5. Before attempting any resume, verify the harness's resume mechanism is available. If unavailable, fall back to fresh spawn silently — do NOT throw an error.
 
 ### Step 3: Verify (Lead + Check subagents)
 
@@ -142,7 +142,7 @@ ACCEPTANCE:
 6. **SubagentStop escalation** — when a subagent stops with incomplete work, escalate through HOW diagnosis → re-delegation → user report. Max 1 cycle per task.
 7. **Gate Stop nonstop** — cannot terminate while pending tasks exist
 8. **Plan first** — if tasks.json is absent, nx-plan must run before Step 2
-9. **No file modification via Bash** — sed, echo >, cat <<EOF, tee, and similar Bash-based file edits are prohibited. Always use Edit/Write tools (Gate enforced)
+9. **No file modification via shell commands** — sed, echo redirection, heredoc, tee, and similar shell-based file edits are prohibited. Always use the harness's dedicated file-editing primitives (gate enforced)
 ## State Management
 
 `.nexus/state/tasks.json` — produced by nx-plan, managed via `nx_task_add`/`nx_task_update`. Gate Stop enforcement.

package/skills/nx-run/meta.yml

@@ -1,5 +1,8 @@
 name: nx-run
 description: Execution — user-directed agent composition.
+summary: "Execution — user-directed agent composition"
 triggers:
   - run
+harness_docs_refs:
+  - resume_invocation
 id: nx-run