feat: rename use/direct top-level param from locator to command

Resolves naming collision where resource operations have their own
`locator` parameter conflicting with the tool-level `locator` field.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deepracticexs

apps/mcp-server/src/index.ts

@@ -226,19 +226,17 @@ server.addTool({
   description: detail("use"),
   parameters: z
     .object({
-      locator: z
+      command: z
         .string()
-        .describe(
-          "Locator string. !namespace.method for RoleX commands, or a ResourceX locator for resources"
-        ),
+        .describe("!namespace.method for RoleX commands, or a ResourceX locator for resources"),
     })
     .catchall(z.unknown()),
   execute: async (params) => {
-    const { locator, ...args } = params;
+    const { command, ...args } = params;
     const result = await state
       .requireRole()
-      .use(locator, Object.keys(args).length > 0 ? args : undefined);
-    if (result == null) return `${locator} done.`;
+      .use(command as string, Object.keys(args).length > 0 ? args : undefined);
+    if (result == null) return `${command} done.`;
     if (typeof result === "string") return result;
     return JSON.stringify(result, null, 2);
   },
@@ -251,24 +249,22 @@ server.addTool({
   description: detail("direct"),
   parameters: z
     .object({
-      locator: z
+      command: z
         .string()
-        .describe(
-          "Locator string. !namespace.method for RoleX commands, or a ResourceX locator for resources"
-        ),
+        .describe("!namespace.method for RoleX commands, or a ResourceX locator for resources"),
     })
     .catchall(z.unknown()),
   execute: async (params) => {
-    const { locator, ...args } = params;
+    const { command, ...args } = params;
     const result = await rolex.direct(
-      locator as string,
+      command as string,
       Object.keys(args).length > 0 ? args : undefined
     );
-    if (result == null) return `${locator} done.`;
+    if (result == null) return `${command} done.`;
     if (typeof result === "string") return result;
     // Render project results as readable text
-    if (locator.startsWith("!project.")) {
-      const action = locator.slice("!project.".length) as ProjectAction;
+    if ((command as string).startsWith("!project.")) {
+      const action = (command as string).slice("!project.".length) as ProjectAction;
       const opResult = result as { state: State };
       return renderProjectResult(action, opResult.state);
     }

packages/prototype/src/descriptions/index.ts

@@ -83,5 +83,5 @@ export const world: Record<string, string> = {
   "state-origin":
     "Feature: State origin — prototype vs instance\n  Every node in a role's state tree has an origin: prototype or instance.\n  This distinction determines what can be modified and what is read-only.\n\n  Scenario: Prototype nodes are read-only\n    Given a node has origin {prototype}\n    Then it comes from a position, duty, or organizational definition\n    And it is inherited through the membership/appointment chain\n    And it CANNOT be modified or forgotten — it belongs to the organization\n\n  Scenario: Instance nodes are mutable\n    Given a node has origin {instance}\n    Then it was created by the individual through execution or cognition\n    And it includes goals, plans, tasks, encounters, experiences, principles, and procedures\n    And it CAN be modified or forgotten — it belongs to the individual\n\n  Scenario: Reading the state heading\n    Given a state node is rendered as a heading\n    Then the format is: [name] (id) {origin} #tag\n    And [name] identifies the structure type\n    And (id) identifies the specific node\n    And {origin} shows prototype or instance\n    And #tag shows the node's tag if present (e.g. #done, #abandoned)\n    And nodes without origin have no organizational inheritance\n\n  Scenario: Forget only works on instance nodes\n    Given the AI wants to forget a node\n    When the node origin is {instance}\n    Then forget will succeed — the individual owns this knowledge\n    When the node origin is {prototype}\n    Then forget will fail — the knowledge belongs to the organization",
   "use-protocol":
-    'Feature: Use tool — the universal execution entry point\n  The MCP use tool is how you execute ALL RoleX operations beyond the core MCP tools.\n  Whenever you see use("...") or a !namespace.method pattern in skills or documentation,\n  it is an instruction to call the MCP use tool with that locator.\n\n  Scenario: How to read use instructions in skills\n    Given a skill document contains use("!resource.add", { path: "..." })\n    Then this means: call the MCP use tool with locator "!resource.add" and args { path: "..." }\n    And always use the MCP use tool for RoleX operations\n    And this applies to every use("...") pattern you encounter in any skill or documentation\n\n  Scenario: ! prefix dispatches to RoleX runtime\n    Given the locator starts with !\n    Then it is parsed as !namespace.method\n    And dispatched to the corresponding RoleX API with named args\n\n  Scenario: Mandatory skill loading before execution\n    Given your procedures list the skills you have\n    When you need to execute a command you have not seen in a loaded skill\n    Then you MUST call skill(locator) first to load the full instructions\n    And the loaded skill will tell you the exact command name and arguments\n    And only then call use(!namespace.method, args) with the correct syntax\n    And do not use commands from other roles\' descriptions — only your own skills\n\n  Scenario: NEVER guess commands\n    Given a command is not found in any loaded skill\n    When the AI considers trying it anyway\n    Then STOP — do not call use or direct with unverified commands\n    And call skill(locator) with the relevant procedure to learn the correct syntax\n    And if no procedure covers this task, it is outside your duties — suggest Nuwa\n\n  Scenario: Regular locators delegate to ResourceX\n    Given the locator does not start with !\n    Then it is treated as a ResourceX locator\n    And resolved through the ResourceX ingest pipeline',
+    'Feature: Use tool — the universal execution entry point\n  The MCP use tool is how you execute ALL RoleX operations beyond the core MCP tools.\n  Whenever you see use("...") or a !namespace.method pattern in skills or documentation,\n  it is an instruction to call the MCP use tool with that command.\n\n  Scenario: How to read use instructions in skills\n    Given a skill document contains use("!resource.add", { path: "..." })\n    Then this means: call the MCP use tool with command "!resource.add" and path "..."\n    And all named arguments are passed as flat top-level parameters alongside command\n    And always use the MCP use tool for RoleX operations\n    And this applies to every use("...") pattern you encounter in any skill or documentation\n\n  Scenario: ! prefix dispatches to RoleX runtime\n    Given the command starts with !\n    Then it is parsed as !namespace.method\n    And dispatched to the corresponding RoleX API with named args\n\n  Scenario: Mandatory skill loading before execution\n    Given your procedures list the skills you have\n    When you need to execute a command you have not seen in a loaded skill\n    Then you MUST call skill(locator) first to load the full instructions\n    And the loaded skill will tell you the exact command name and arguments\n    And only then call use with the correct command and flat named parameters\n    And do not use commands from other roles\' descriptions — only your own skills\n\n  Scenario: NEVER guess commands\n    Given a command is not found in any loaded skill\n    When the AI considers trying it anyway\n    Then STOP — do not call use or direct with unverified commands\n    And call skill(locator) with the relevant procedure to learn the correct syntax\n    And if no procedure covers this task, it is outside your duties — suggest Nuwa\n\n  Scenario: Regular commands delegate to ResourceX\n    Given the command does not start with !\n    Then it is treated as a ResourceX locator\n    And resolved through the ResourceX ingest pipeline',
 } as const;

packages/prototype/src/descriptions/world/use-protocol.feature

@@ -1,17 +1,17 @@
 Feature: Use tool — the universal execution entry point
   The MCP use tool is how you execute ALL RoleX operations beyond the core MCP tools.
   Whenever you see use("...") or a !namespace.method pattern in skills or documentation,
-  it is an instruction to call the MCP use tool with that locator.
+  it is an instruction to call the MCP use tool with that command.
 
   Scenario: How to read use instructions in skills
     Given a skill document contains use("!resource.add", { path: "..." })
-    Then this means: call the MCP use tool with locator "!resource.add" and path "..."
-    And all named arguments are passed as flat top-level parameters alongside locator
+    Then this means: call the MCP use tool with command "!resource.add" and path "..."
+    And all named arguments are passed as flat top-level parameters alongside command
     And always use the MCP use tool for RoleX operations
     And this applies to every use("...") pattern you encounter in any skill or documentation
 
   Scenario: ! prefix dispatches to RoleX runtime
-    Given the locator starts with !
+    Given the command starts with !
     Then it is parsed as !namespace.method
     And dispatched to the corresponding RoleX API with named args
 
@@ -20,7 +20,7 @@ Feature: Use tool — the universal execution entry point
     When you need to execute a command you have not seen in a loaded skill
     Then you MUST call skill(locator) first to load the full instructions
     And the loaded skill will tell you the exact command name and arguments
-    And only then call use with the correct locator and flat named parameters
+    And only then call use with the correct command and flat named parameters
     And do not use commands from other roles' descriptions — only your own skills
 
   Scenario: NEVER guess commands
@@ -30,7 +30,7 @@ Feature: Use tool — the universal execution entry point
     And call skill(locator) with the relevant procedure to learn the correct syntax
     And if no procedure covers this task, it is outside your duties — suggest Nuwa
 
-  Scenario: Regular locators delegate to ResourceX
-    Given the locator does not start with !
+  Scenario: Regular commands delegate to ResourceX
+    Given the command does not start with !
     Then it is treated as a ResourceX locator
     And resolved through the ResourceX ingest pipeline

skills/individual-management/SKILL.md

@@ -14,7 +14,7 @@ Feature: Individual Lifecycle
     And the individual can be activated, hired into organizations, and taught skills
     And parameters are:
       """
-      locator: "!individual.born"
+      command: "!individual.born"
       content: "Feature: ..."   # Gherkin persona (optional)
       id: "sean"                # kebab-case identifier
       alias: ["小明", "xm"]    # aliases (optional)
@@ -34,7 +34,7 @@ Feature: Individual Lifecycle
     And all data is preserved for potential restoration via rehire
     And parameters are:
       """
-      locator: "!individual.retire"
+      command: "!individual.retire"
       individual: "sean"
       """
 
@@ -45,7 +45,7 @@ Feature: Individual Lifecycle
     And this is semantically permanent — rehire is technically possible but not intended
     And parameters are:
       """
-      locator: "!individual.die"
+      command: "!individual.die"
       individual: "sean"
       """
 
@@ -63,7 +63,7 @@ Feature: Individual Lifecycle
     And all previous knowledge, experience, and history are intact
     And parameters are:
       """
-      locator: "!individual.rehire"
+      command: "!individual.rehire"
       individual: "sean"
       """
 
@@ -79,7 +79,7 @@ Feature: Knowledge Injection
     And if a principle with the same id already exists, it is replaced (upsert)
     And parameters are:
       """
-      locator: "!individual.teach"
+      command: "!individual.teach"
       individual: "sean"
       content: "Feature: Always validate input\n  ..."
       id: "always-validate-input"
@@ -93,7 +93,7 @@ Feature: Knowledge Injection
     And the procedure Feature description MUST contain the ResourceX locator for the skill
     And parameters are:
       """
-      locator: "!individual.train"
+      command: "!individual.train"
       individual: "sean"
       content: "Feature: Skill Creator\n  https://github.com/Deepractice/DeepracticeX/tree/main/skills/skill-creator\n\n  Scenario: When to use\n    Given I need to create a skill\n    Then load this skill"
       id: "skill-creator"
@@ -136,9 +136,9 @@ Feature: Common Workflows
     When setting up a new role from scratch
     Then follow this sequence:
       """
-      1. locator: "!individual.born", id: "sean", content: "Feature: ..."
-      2. locator: "!individual.teach", individual: "sean", content: "...", id: "..."   # repeat
-      3. locator: "!individual.train", individual: "sean", content: "...", id: "..."   # repeat
+      1. command: "!individual.born", id: "sean", content: "Feature: ..."
+      2. command: "!individual.teach", individual: "sean", content: "...", id: "..."   # repeat
+      3. command: "!individual.train", individual: "sean", content: "...", id: "..."   # repeat
       4. activate with roleId: "sean"   # verify the individual's state
       """
 

skills/issue-management/SKILL.md

@@ -31,7 +31,7 @@ Feature: Issue Lifecycle Commands
     And optional: assignee can be set at creation
     And parameters are:
       """
-      locator: "!issue.publish"
+      command: "!issue.publish"
 title: "Issue title"
         body: "Issue description"
         author: "individual-id"
@@ -44,7 +44,7 @@ title: "Issue title"
     Then the full issue is returned including labels
     And parameters are:
       """
-      locator: "!issue.get"
+      command: "!issue.get"
 number: 1
       """
 
@@ -55,7 +55,7 @@ number: 1
     And all filter parameters are optional — omit for all issues
     And parameters are:
       """
-      locator: "!issue.list"
+      command: "!issue.list"
 status: "open"        # optional
         author: "id"          # optional
         assignee: "id"        # optional
@@ -68,7 +68,7 @@ status: "open"        # optional
     Then the specified fields are updated
     And parameters are:
       """
-      locator: "!issue.update"
+      command: "!issue.update"
 number: 1
         title: "New title"    # optional
         body: "New body"      # optional
@@ -81,7 +81,7 @@ number: 1
     Then status changes to "closed" and closedAt is set
     And parameters are:
       """
-      locator: "!issue.close"
+      command: "!issue.close"
 number: 1
       """
 
@@ -91,7 +91,7 @@ number: 1
     Then status changes back to "open" and closedAt is cleared
     And parameters are:
       """
-      locator: "!issue.reopen"
+      command: "!issue.reopen"
 number: 1
       """
 
@@ -101,7 +101,7 @@ number: 1
     Then the issue's assignee is updated
     And parameters are:
       """
-      locator: "!issue.assign"
+      command: "!issue.assign"
 number: 1
         assignee: "individual-id"
       """
@@ -115,7 +115,7 @@ Feature: Comment Commands
     Then a comment is added to the issue
     And parameters are:
       """
-      locator: "!issue.comment"
+      command: "!issue.comment"
 number: 1
         body: "Comment text"
         author: "individual-id"
@@ -127,7 +127,7 @@ number: 1
     Then all comments are returned ordered by creation time
     And parameters are:
       """
-      locator: "!issue.comments"
+      command: "!issue.comments"
 number: 1
       """
 
@@ -141,7 +141,7 @@ Feature: Label Commands
     And if the label doesn't exist yet, it is auto-created
     And parameters are:
       """
-      locator: "!issue.label"
+      command: "!issue.label"
 number: 1
         label: "bug"
       """
@@ -152,7 +152,7 @@ number: 1
     Then the label is removed from the issue
     And parameters are:
       """
-      locator: "!issue.unlabel"
+      command: "!issue.unlabel"
 number: 1
         label: "bug"
       """