@moreih29/nexus-core 0.1.2 → 0.2.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.2.0",
+  "nexus_core_commit": "166a3b29f2b5795b9df037442ddc5d2ae7e36e5a",
+  "schema_contract_version": "2.0",
   "agents": [
     {
       "name": "architect",
@@ -17,29 +17,27 @@
         "no_task_update"
       ],
       "id": "architect",
-      "body_hash": "sha256:a9424a28d14e04a8c487ab9c1718f9ac929e8a2558abcf848a7c1722ceb8a79d"
+      "body_hash": "sha256:85f9a3de419f32cdae284436eb1d902bff19a2230c50fe3068ffc642949a63b7"
     },
     {
-      "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",
+      "name": "writer",
+      "description": "Technical writing — transforms research findings, code, and analysis into clear documents and presentations for the intended audience",
+      "task": "Technical writing, documentation, presentations",
+      "alias_ko": "라이터",
+      "category": "do",
+      "resume_tier": "bounded",
+      "model_tier": "standard",
       "capabilities": [
-        "no_file_edit",
-        "no_task_create",
-        "no_task_update"
+        "no_task_create"
       ],
-      "id": "designer",
-      "body_hash": "sha256:9ccab5e29cca4b57250c41ffaea6656fc655bee2a19fc5e29c08e2e4ab669021"
+      "id": "writer",
+      "body_hash": "sha256:2edd9bf52e537c446b5ebfaafab214ebaaad2491f019aa8534453bff3f1cd37b"
     },
     {
-      "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": "리뷰어",
+      "name": "tester",
+      "description": "Testing and verification — tests, verifies, validates stability and security of implementations",
+      "task": "Testing, verification, security review",
+      "alias_ko": "테스터",
       "category": "check",
       "resume_tier": "ephemeral",
       "model_tier": "standard",
@@ -47,14 +45,14 @@
         "no_file_edit",
         "no_task_create"
       ],
-      "id": "reviewer",
-      "body_hash": "sha256:76312fd237bb9f76fff243b5f10e9efa8ac726c793f401d30846423c11871feb"
+      "id": "tester",
+      "body_hash": "sha256:4dd04e1c93ff9c0c9fa6aebb60ece3f9719e82f9714b13feea01b6163633caec"
     },
     {
-      "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": "postdoc",
+      "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
+      "task": "Research methodology, evidence synthesis",
+      "alias_ko": "포닥",
       "category": "how",
       "resume_tier": "persistent",
       "model_tier": "high",
@@ -63,22 +61,8 @@
         "no_task_create",
         "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"
+      "id": "postdoc",
+      "body_hash": "sha256:da9b8c2568b8b5812abed6d6324139f814379d48dc63cdc5d0b5b263f5407814"
     },
     {
       "name": "researcher",
@@ -93,13 +77,13 @@
         "no_task_create"
       ],
       "id": "researcher",
-      "body_hash": "sha256:5ec30a3449047fadfbeabc01778204baa66f3016f48bed3bc95bdff9c9b386bd"
+      "body_hash": "sha256:7f5db3b52ae76a3b3214cf73b076980e15ef85c80b9aa86a9704f737e4b13251"
     },
     {
-      "name": "postdoc",
-      "description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
-      "task": "Research methodology, evidence synthesis",
-      "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",
@@ -108,14 +92,14 @@
         "no_task_create",
         "no_task_update"
       ],
-      "id": "postdoc",
-      "body_hash": "sha256:62633ddb64097e249959cde60b40e44a99b163d08c1c950afbe04309dbf5d37c"
+      "id": "strategist",
+      "body_hash": "sha256:0254b4144a22c66209bd68119553d9057a4fb7f9b1ff7ebb9878687d99583465"
     },
     {
-      "name": "tester",
-      "description": "Testing and verification — tests, verifies, validates stability and security of implementations",
-      "task": "Testing, verification, security review",
-      "alias_ko": "테스터",
+      "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",
@@ -123,51 +107,71 @@
         "no_file_edit",
         "no_task_create"
       ],
-      "id": "tester",
-      "body_hash": "sha256:6455a816b3a1c80fd689c19779d9fc5b411948d768cdd240d964b1feea3f51a0"
+      "id": "reviewer",
+      "body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
     },
     {
-      "name": "writer",
-      "description": "Technical writing — transforms research findings, code, and analysis into clear documents and presentations for the intended audience",
-      "task": "Technical writing, documentation, presentations",
-      "alias_ko": "라이터",
+      "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": "writer",
-      "body_hash": "sha256:ff017d33ffd9d8c8e6e34b7c43a39215b0121cace4e5421ad6d7b7dd9ee7b497"
+      "id": "engineer",
+      "body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
+    },
+    {
+      "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",
+      "capabilities": [
+        "no_file_edit",
+        "no_task_create",
+        "no_task_update"
+      ],
+      "id": "designer",
+      "body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
     }
   ],
   "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-init",
-      "description": "Project onboarding — scan, mission, essentials, context generation",
-      "manual_only": true,
-      "id": "nx-init",
-      "body_hash": "sha256:ab636e7c338b58e2288855c2a99ce079c53bb39f7adf3af3ce5769b5a32f73b1"
+      "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:2e3f4fabb2961c052c4449f19ec16ed940394be037a63d4af90a3d12df8e4895"
     },
     {
       "name": "nx-sync",
       "description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
+      "summary": "Context knowledge synchronization",
       "triggers": [
         "sync"
       ],
@@ -175,57 +179,66 @@
       "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"
+      "name": "nx-init",
+      "description": "Project onboarding — scan, mission, essentials, context generation",
+      "summary": "Project onboarding — scan, mission, essentials, context generation",
+      "manual_only": true,
+      "id": "nx-init",
+      "body_hash": "sha256:11761d37bad2fb30ef1d562d22d9a395e27e0c3ce58ea42ad3b1799f47bf8950"
+    },
+    {
+      "name": "nx-setup",
+      "description": "Interactive project setup wizard for Nexus configuration.",
+      "summary": "Interactive Nexus configuration wizard",
+      "manual_only": true,
+      "id": "nx-setup",
+      "body_hash": "sha256:e66b0116d5da403c6480876a5b0a575110bcd26ecaa30079ce17de64fc112e65"
     }
   ],
   "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.2.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

@@ -7,7 +7,7 @@ Scans the project and builds Nexus knowledge in the flat .nexus/ structure. On f
 - NEVER modify source code. Slimming down CLAUDE.md 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.
+- NEVER overwrite existing files without `--reset`. On resume, preserve existing files intact.
 - Project section in CLAUDE.md 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/`
@@ -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: [

package/skills/nx-init/meta.yml

@@ -1,4 +1,5 @@
 name: nx-init
 description: Project onboarding — scan, mission, essentials, context generation
+summary: "Project onboarding — scan, mission, essentials, context generation"
 manual_only: true
 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
@@ -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:**
 
@@ -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