@rudderhq/agent-runtime-codex-local 0.5.0 → 0.5.1

package/skills/rudder-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rudder-docs
-description: "Use when the user asks how Rudder works or how to use, configure, extend, operate, or troubleshoot Rudder; needs current guidance for Rudder agents, issues, Chat, runs, reviews, approvals, automations, Library, projects, skills, workspaces, CLI, MCP tools, APIs, or source behavior; or needs an exact supported command or product contract. Do not use for greetings, ordinary work merely running inside Rudder, routine actions already clear from the active context and typed tools, or general coding and research tasks that do not ask about Rudder."
+description: "Use when the user asks how Rudder works; needs current Rudder docs, exact behavior, commands, contracts, APIs, or source evidence; asks to create, hire, or configure Rudder agents; or asks to scaffold, develop, or verify Rudder plugins. For explicit creation requests, verify the current interface before acting within existing authorization. Do not use for greetings, ordinary work merely running inside Rudder, routine actions already clear from the active context and typed tools, non-Rudder plugin work, or general coding and research tasks that do not ask about Rudder."
 ---
 
 # Rudder Docs
@@ -33,6 +33,8 @@ Choose one primary class before retrieving evidence:
   tests, API compatibility, or an exact source-level explanation.
 - **Discrepancy, troubleshooting, or release:** observed behavior differs from
   guidance, a Rudder operation failed, or the answer depends on a version.
+- **Explicit creation or authoring:** the user asks to create, hire, or
+  configure a Rudder Agent, or to scaffold, develop, or verify a Rudder Plugin.
 - **Offline or restricted:** the preferred live, public, or source evidence is
   unavailable.
 
@@ -49,6 +51,16 @@ exact installed command's `--help`. Consult the relevant part of the CLI
 reference only after those live checks. Use the API reference only for an
 explicit internal, debugging, or compatibility question.
 
+### Explicit Agent Or Plugin Work
+
+For Agent creation or configuration, read
+[Agent creation](references/agent-creation.md). For Plugin scaffolding or
+authoring, read [Plugin authoring](references/plugin-authoring.md). Verify the
+current typed capability, installed command, engineering contract, or source
+before acting. Only an explicit user request to perform the creation or change
+authorizes entering a mutation workflow; a question about how it works remains
+read-only.
+
 ### Official Public Documentation
 
 For public user guidance, start with
@@ -120,12 +132,16 @@ Read only the reference needed for the request:
    compatibility endpoint contracts; not the normal first interface.
 2. [CLI reference](references/cli-reference.md) — typed MCP capability and
    installed CLI fallback catalog plus exact command semantics.
-3. [Control-plane practices](references/control-plane-practices.md) — exact
+3. [Agent creation](references/agent-creation.md) — permission-aware Agent
+   configuration, governed hiring, approval, revision, and evidence workflow.
+4. [Plugin authoring](references/plugin-authoring.md) — current scaffold,
+   manifest, worker, UI, capability, route, and verification workflow.
+5. [Work practices](references/operating-practices.md) — exact
    conditional behavior for ownership, reviews, approvals, budgets,
    workspaces, Library handoff, authentication, and safe git use.
-4. [Organization skills](references/organization-skills.md) — discover,
+6. [Organization skills](references/organization-skills.md) — discover,
    import, inspect, enable, and synchronize organization or agent skills.
-5. [Source map](references/source-map.md) — stable official documentation,
+7. [Source map](references/source-map.md) — stable official documentation,
    Product Logic, engineering, implementation, test, release, and search
    routes.
 

package/skills/rudder-docs/evals/retrieval-authority-evals.json

@@ -0,0 +1,262 @@
+[
+  {
+    "query": "Where can I check whether a governed Rudder action was approved and applied?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "approvals",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Which Rudder page explains monthly budget hard stops and cost events?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["BUDGET.ENFORCEMENT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "budgets-and-cost",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "I need the audit trail for a product mutation in Rudder.",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "activity",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where does Rudder explain Run summaries, transcripts, logs, and raw evidence?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["RUN.INTELLIGENCE.001", "RUN.RESULT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/agents",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What owns the current Dashboard health summary?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["DASHBOARD.SUMMARY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/overview",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "How do Calendar events link back to their source work?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CALENDAR.SOURCE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/calendar",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where should a human recover unread work and requests for attention?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["INBOX.ATTENTION.001", "MESSENGER.ATTENTION.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/chat-messenger",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where did Rudder's old Control Plane documentation move?",
+    "locale": "en",
+    "query_mode": "legacy_compatibility",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001", "BUDGET.ENFORCEMENT.001", "ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "在哪里查看受治理动作的审批结论和实际应用结果？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "approvals",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 的月度预算硬限制和成本事件以哪个页面为准？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["BUDGET.ENFORCEMENT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "budgets-and-cost",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "我需要查一项产品变更的活动审计记录。",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "activity",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "运行摘要、完整记录、日志和原始证据应该看哪一页？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["RUN.INTELLIGENCE.001", "RUN.RESULT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/agents",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Dashboard 当前状态汇总的权威说明在哪里？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["DASHBOARD.SUMMARY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/overview",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Calendar 事件怎样回到来源任务？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CALENDAR.SOURCE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/calendar",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "负责人应该在哪里找回未读工作和需要人处理的事项？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["INBOX.ATTENTION.001", "MESSENGER.ATTENTION.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/chat-messenger",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 以前的 Control Plane 文档迁移到哪里了？",
+    "locale": "zh",
+    "query_mode": "legacy_compatibility",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001", "BUDGET.ENFORCEMENT.001", "ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What are all valid Issue statuses, including cancelled and review states?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ISSUE.STATE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/issue-statuses",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where can I compare local Agent runtime choices and readiness labels?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.ADAPTERS.001", "AGENT.RUNTIME.PERMISSIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/runtime-types",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Which paths belong to Library, Project Context, run workspaces, and backups?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CONTEXT.RESOURCES.001", "LIBRARY.FILES.001", "WORKSPACE.PROJECT.001", "WORKSPACE.RUN.001", "WORKSPACE.BACKUP.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/workspace-boundaries",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "How do chat_output and track_issue route Automation results?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AUTOMATION.OUTPUT.001", "AUTOMATION.RUN.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/automation-output-routing",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What are Rudder's platform, credential, browser, and local trust boundaries?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.PERMISSIONS.001", "AGENT.BROWSER.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/permissions-and-platforms",
+    "expected_anchor": "boundaries",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "哪里可以查到包括 cancelled 和评审状态在内的全部 Issue 状态？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ISSUE.STATE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/issue-statuses",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "在哪里比较本地 Agent 运行环境选项和就绪提示？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.ADAPTERS.001", "AGENT.RUNTIME.PERMISSIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/runtime-types",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Library、Project Context、运行工作区和备份各自放什么？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CONTEXT.RESOURCES.001", "LIBRARY.FILES.001", "WORKSPACE.PROJECT.001", "WORKSPACE.RUN.001", "WORKSPACE.BACKUP.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/workspace-boundaries",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "chat_output 和 track_issue 会把自动化结果分别送到哪里？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AUTOMATION.OUTPUT.001", "AUTOMATION.RUN.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/automation-output-routing",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 的平台、凭据、浏览器和本地信任边界在哪里查？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.PERMISSIONS.001", "AGENT.BROWSER.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/permissions-and-platforms",
+    "expected_anchor": "boundaries",
+    "illustrative_case_sufficient": false
+  }
+]

package/skills/rudder-docs/evals/trigger-evals.json

@@ -16,19 +16,19 @@
     "should_trigger": true
   },
   {
-    "query": "Where in the official Rudder source are bundled skills materialized for local runtime adapters, and which tests protect stale managed-skill cleanup?",
+    "query": "请在 Rudder 里创建一个 Researcher Agent，让它向 CTO 汇报；先核对当前权限、runtime config、role enum 和 approval 流程，再执行创建。",
     "should_trigger": true
   },
   {
-    "query": "Rudder 显示这个 skill 已 enabled，但刚才的 run 没有使用它。这是 selected、loaded 和 used 语义不同，还是运行时出了 bug？请核对当前契约。",
+    "query": "Scaffold a new Rudder Plugin named @acme/quality-gate in a temporary external package directory. Verify the current create-rudder-plugin and SDK workflow first, then run its typecheck, tests, and build.",
     "should_trigger": true
   },
   {
-    "query": "我把交付文档写进 Rudder Library 后，为什么评论里必须使用返回的 markdownLink，不能手写 library-entry URL？请给出准确规则。",
+    "query": "Rudder Plugin 的 worker capability、same-origin UI、routePath 和 ctx.assets 现在到底有哪些边界？请查当前 authoring guide、SDK 和源码后回答。",
     "should_trigger": true
   },
   {
-    "query": "Which Rudder API endpoint is the compatibility fallback behind the CLI issue checkout command, and under what failure conditions is direct API fallback allowed?",
+    "query": "Before hiring a Founding Engineer in Rudder, compare the installed Codex runtime configuration with existing agents and explain the correct role, title, reportsTo, SOUL.md, desiredSkills, and sourceIssueId fields.",
     "should_trigger": true
   },
   {
@@ -44,7 +44,7 @@
     "should_trigger": false
   },
   {
-    "query": "这个 React 组件在当前 Rudder run 里渲染成空白了，帮我修复状态更新逻辑并补一个组件测试。",
+    "query": "这个 React 组件在当前 Rudder run 里渲染成空白了，帮我修复状态更新逻辑并补一个组件测试；这不是 Rudder 产品行为问题。",
     "should_trigger": false
   },
   {
@@ -56,27 +56,27 @@
     "should_trigger": false
   },
   {
-    "query": "把下面这段提到 rudder control 的英文产品文案总结成三条中文要点；这里的 rudder 是船舵控制，不是软件产品。",
+    "query": "The target Agent and new title are already in context. Use the exposed typed Agent update tool to change only its title to Staff Engineer; do not look up Rudder docs.",
     "should_trigger": false
   },
   {
-    "query": "在这个 Rudder run 里分析附件中的三家竞品定价表，算出年付折扣并推荐我们的套餐价格。",
+    "query": "给这个普通 Vite 应用写一个 markdown-it plugin，把内部链接加上 target 属性；它不是 Rudder Plugin，也不需要 Rudder SDK。",
     "should_trigger": false
   },
   {
-    "query": "Write a short email to the design team saying the issue is complete and that the new screenshots are ready for review.",
+    "query": "在这个 Rudder run 里分析附件中的三家竞品定价表，算出年付折扣并推荐我们的套餐价格。",
     "should_trigger": false
   },
   {
-    "query": "Please fix the spelling mistakes on the docs page in this repository, preserve its existing tone, and run the markdown linter afterward.",
+    "query": "Write a short email to the design team saying the issue is complete and that the new screenshots are ready for review.",
     "should_trigger": false
   },
   {
-    "query": "帮我设计一个名叫 Rudder 的船舵图标：深蓝色、圆形徽章、透明背景，输出 1024px PNG。",
+    "query": "Please fix spelling mistakes on an unrelated library's docs page in this repository, preserve its tone, and run the markdown linter; no Rudder behavior needs clarification.",
     "should_trigger": false
   },
   {
-    "query": "用当前已经暴露的 Library 文件读取工具打开季度计划，把第二节复制到这条聊天里；路径和权限都已在上下文中。",
+    "query": "帮我设计一个名叫 Rudder 的船舵图标：深蓝色、圆形徽章、透明背景，输出 1024px PNG。",
     "should_trigger": false
   }
 ]

package/skills/rudder-docs/references/agent-creation.md

@@ -0,0 +1,153 @@
+# Agent Creation
+
+Use this workflow for an explicit request to create, hire, or configure a
+Rudder Agent. A question about Agent behavior or configuration is read-only.
+Only an explicit user request to perform the action authorizes mutation, and
+normal organization, permission, approval, and safety boundaries still apply.
+
+For exact installed command syntax, use [CLI reference](cli-reference.md) after
+checking live capabilities and `--help`. Use [API reference](api-reference.md)
+only for internal debugging or compatibility work.
+
+## Section Map
+
+- [Verify authority and context](#verify-authority-and-context)
+- [Discover a current runtime configuration](#discover-a-current-runtime-configuration)
+- [Design the durable Agent identity](#design-the-durable-agent-identity)
+- [Submit the governed hire](#submit-the-governed-hire)
+- [Handle direct creation or approval](#handle-direct-creation-or-approval)
+- [Report evidence](#report-evidence)
+
+## Verify Authority And Context
+
+Before designing or creating an Agent:
+
+1. Verify the actor, organization, and authentication with
+   `rudder agent me --json` or an equivalent exposed typed identity
+   capability.
+2. Board access may create an Agent. An Agent actor needs
+   `canCreateAgents=true` in the same organization.
+3. If identity or authorization is unavailable, stop and report the missing
+   authority. Do not ask for or print `RUDDER_API_KEY`, create files as a
+   substitute, or cross an organization boundary.
+4. If the request is advisory rather than an explicit request to create or
+   change an Agent, remain read-only and return the verified guidance.
+
+For a source issue, preserve its identity for the hire payload rather than
+creating an unlinked Agent and repairing the relationship later.
+
+## Discover A Current Runtime Configuration
+
+Inspect exposed typed capabilities first. If a governed typed Agent-hire
+capability is exposed by the current runtime, prefer it. The standard Rudder
+Rudder tool set currently has no Agent-hire mutation tool, so verify and
+use `rudder agent hire` as the canonical installed fallback.
+
+Discover before drafting:
+
+1. Read `rudder agent config index` to learn which runtime configuration
+   documents this instance exposes.
+2. Read one relevant `rudder agent config doc <agent-runtime-type>` document.
+3. Compare related Agents with `rudder agent list`,
+   `rudder agent config list`, and, where necessary,
+   `rudder agent config get`.
+4. Reuse a proven pattern only after checking that its working directory,
+   model, runtime options, and responsibilities fit the new role.
+5. If the role needs `desiredSkills` on day one, inspect the organization skill
+   inventory and import or validate required skills before hiring. Follow
+   [Organization skills](organization-skills.md) for that workflow.
+
+Installed help and live capability evidence win over this reference when a
+version differs. Do not hand-create Agent directories, configuration records,
+or instruction files as a fallback.
+
+## Design The Durable Agent Identity
+
+An Agent is a durable team member. Draft the smallest complete payload that
+defines its organizational responsibility and runnable configuration:
+
+- `name` is optional; when omitted, Rudder assigns a distinct personal name.
+- `role` is one fixed enum value: `ceo`, `cto`, `cmo`, `cfo`, `engineer`,
+  `designer`, `pm`, `qa`, `devops`, `researcher`, or `general`.
+- `title` carries the specific job title. For example, use role `engineer` and
+  title `Founding Engineer`, never a new `founding_engineer` role.
+- `reportsTo` identifies an in-organization manager and must preserve the
+  intended reporting line.
+- `capabilities` states the work this Agent owns and the boundaries it should
+  not silently cross.
+- `agentRuntimeType`, `agentRuntimeConfig`, and `runtimeConfig` must follow the
+  current adapter documentation and a valid local environment.
+- `desiredSkills` contains only skills already available to the organization
+  and actually needed for the role.
+- `sourceIssueId` or `sourceIssueIds` links the hire to the originating work.
+- Omit `icon` for a normal hire so Rudder generates and persists its default
+  Oreo avatar. Supply an icon only when the operator provided an explicit
+  supported `oreo:<shape>:<palette>:<uuid>`, DiceBear Notionists, or uploaded
+  `asset:<uuid>` reference.
+
+For supported local runtimes, `agentRuntimeConfig.promptTemplate` becomes the
+managed `SOUL.md`. Write durable role/persona guidance rather than a one-line
+command. A substantial role should define:
+
+- an opening identity statement;
+- mission and owned outcome;
+- durable responsibilities;
+- boundaries and escalation points;
+- decision principles;
+- communication voice; and
+- continuity rules for what should become memory or instruction updates.
+
+Do not copy Rudder's shared filesystem, memory, safety, or operating contract
+into `promptTemplate`; the runtime injects that shared contract separately.
+Keep secrets out of the payload unless the verified adapter contract requires a
+supported secret mechanism.
+
+## Submit The Governed Hire
+
+After the payload and authority are verified, use the exposed governed typed
+capability if one exists. Otherwise invoke the installed canonical command:
+
+`rudder agent hire --org-id <org-id> --payload <json> --json`
+
+Verify its exact syntax in [CLI reference](cli-reference.md) or installed
+`rudder agent hire --help` immediately before execution. Do not replace it with
+manual filesystem changes or `rudder approval create --type hire_agent`.
+The canonical hire surface owns both permission checks and the organization's
+direct-create versus approval-required policy.
+
+## Handle Direct Creation Or Approval
+
+The canonical response has two governed branches:
+
+- Direct creation: `approval: null`; the returned Agent is created in its
+  ordinary post-hire state.
+- Approval required: the returned Agent is `pending_approval`, and the response
+  includes an approval record.
+
+For `pending_approval`:
+
+1. Inspect it with `rudder approval get` and keep the source issue visible.
+2. Use a markdown approval comment when review context or revision evidence is
+   needed.
+3. If the board requests changes, revise the existing payload and use
+   `rudder approval resubmit`; do not create a duplicate hire.
+4. Use `rudder approval issues` to inspect linked issues after the server has
+   created the canonical linkage.
+5. After approval, close a linked issue only when the approved hire resolves
+   it; otherwise leave a linked next-action comment.
+
+Never treat a `pending_approval` Agent as runnable, assignable, or fully hired.
+Approval, rejection, and revision semantics remain server-owned.
+
+## Report Evidence
+
+Do not report success merely because a payload was drafted or files were
+written. Success requires the canonical hire operation to return:
+
+- `agent.id` for the created or pending Agent; and
+- `approval.id` when approval is required.
+
+Report the organization, Agent identity, role/title, reporting line, runtime,
+source issue, and direct versus approval branch without exposing secrets.
+If execution was not explicitly requested, report only the verified proposed
+configuration and the current command or capability that would govern it.

package/skills/rudder-docs/references/api-reference.md

@@ -1,12 +1,12 @@
 # Rudder API Reference
 
-Internal/debug reference for the Rudder control plane API.
+Internal/debug reference for the Rudder API.
 
 - The `rudder-docs` router treats this as a compatibility and source-debugging
   reference, not the normal first interface for agent operations.
 - The stable agent command catalog lives in `cli-reference.md`.
 - Conditional ownership, review, workspace, and authentication guidance lives
-  in `control-plane-practices.md`.
+  in `operating-practices.md`.
 - Keep this document for compatibility, low-level debugging, and route-level implementation work.
 
 ## Section Map
@@ -146,6 +146,7 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/issues`
 - `POST /api/orgs/:orgId/issues`
 - `GET /api/orgs/:orgId/agents`
+- `POST /api/orgs/:orgId/agent-hires`
 - `GET /api/orgs/:orgId/org`
 - `GET /api/orgs/:orgId/dashboard`
 - `GET /api/orgs/:orgId/projects`
@@ -160,6 +161,12 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/costs/by-agent`
 - `GET /api/orgs/:orgId/costs/by-project`
 
+`POST /api/orgs/:orgId/agent-hires` is the governed Agent creation route behind
+`rudder agent hire`. It returns `approval: null` for direct creation or an Agent
+in `pending_approval` plus the approval record when organization policy requires
+review. Normal runtime work should follow [Agent creation](agent-creation.md)
+and the installed CLI instead of calling this route directly.
+
 ### Resources
 
 - `GET /api/orgs/:orgId/resources`

package/skills/rudder-docs/references/cli-reference.md

@@ -19,14 +19,14 @@ returns a transport or configuration error.
 ## Operating Policy Owners
 
 Keep this file focused on commands and CLI-specific I/O. Consult the exact
-control-plane owner for operating behavior:
+operating-practices guide for operating behavior:
 
-- [Interface and Chat/issue scope](control-plane-practices.md#interface-and-scope)
-- [Ownership, checkout, and wake scope](control-plane-practices.md#ownership-checkout-and-wake-scope)
-- [Comments, mentions, and evidence](control-plane-practices.md#comments-mentions-and-evidence)
-- [Review and close-out](control-plane-practices.md#review-and-close-out)
-- [Durable Library artifacts](control-plane-practices.md#durable-library-artifacts)
-- [Git identity and attribution](control-plane-practices.md#git-identity-and-attribution)
+- [Interface and Chat/issue scope](operating-practices.md#interface-and-scope)
+- [Ownership, checkout, and wake scope](operating-practices.md#ownership-checkout-and-wake-scope)
+- [Comments, mentions, and evidence](operating-practices.md#comments-mentions-and-evidence)
+- [Review and close-out](operating-practices.md#review-and-close-out)
+- [Durable Library artifacts](operating-practices.md#durable-library-artifacts)
+- [Git identity and attribution](operating-practices.md#git-identity-and-attribution)
 
 ## Defaults
 
@@ -48,7 +48,7 @@ control-plane owner for operating behavior:
 | `rudder_agent_me` | `rudder agent me` | Show the authenticated agent identity, budget, and chain of command. | no | no | no | no |
 | `rudder_agent_inbox` | `rudder agent inbox` | List the compact assignee and reviewer work inbox for the authenticated agent. | no | no | no | no |
 | `rudder_agent_capabilities` | `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
-| `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's control-plane identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
+| `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
 | `rudder_agent_skills_create` | `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_enable` | `rudder agent skills enable <agent-id> <selection-ref...>` | Add skill selections to an agent without replacing existing enabled skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_sync` | `rudder agent skills sync <agent-id>` | Sync the desired enabled skill set for an agent. | yes | no | no | attached when available |
@@ -110,7 +110,7 @@ control-plane owner for operating behavior:
 | `rudder_chat_messages` | `rudder chat messages <chat-id> [--limit <n>] [--cursor <cursor>] [--include-transcript]` | Read bounded chat messages with page cursors; transcript output is omitted unless requested. | no | no | no | no |
 | `rudder_chat_transcript` | `rudder chat transcript <chat-id> [--limit <n>] [--cursor <cursor>] [--max-output-chars <n>]` | Read paginated chat messages with assistant transcript entries clipped in human output. | no | no | no | no |
 | `rudder_chat_read` | `rudder chat read <chat-id> [--turn-limit <n>] [--cursor <cursor>] [--include-output]` | Read a bounded recent-message snapshot for one chat with page cursors. | no | no | no | no |
-| `rudder_chat_create` | `rudder chat create --org-id <id>` | Create a chat conversation. | yes | required | no | attached when available |
+| `rudder_chat_create` | `rudder chat create --org-id <id> --body <text>` | Create a chat conversation with its first message. | yes | required | no | attached when available |
 | `rudder_chat_send` | `rudder chat send <chat-id> --body <text>` | Send an agent-authored message directly to the operator in a chat. | yes | no | required | attached when available |
 | `rudder_chat_archive` | `rudder chat archive <chat-id>` | Archive a chat conversation without deleting it. | yes | no | no | attached when available |
 | `rudder_runs_list` | `rudder runs list --org-id <id> [--used-skill <skill>] [--loaded-skill <skill>] [--cursor <cursor>] [--full]` | List lightweight run summaries with stable pagination and filters; use --full only for legacy full-row compatibility. | no | required | no | no |
@@ -125,7 +125,7 @@ control-plane owner for operating behavior:
 
 ## Issue Command I/O And Shapes
 
-Operating rules live in [ownership, checkout, and wake scope](control-plane-practices.md#ownership-checkout-and-wake-scope), [comments and evidence](control-plane-practices.md#comments-mentions-and-evidence), and [review and close-out](control-plane-practices.md#review-and-close-out). The CLI close-out shapes are:
+Operating rules live in [ownership, checkout, and wake scope](operating-practices.md#ownership-checkout-and-wake-scope), [comments and evidence](operating-practices.md#comments-mentions-and-evidence), and [review and close-out](operating-practices.md#review-and-close-out). The CLI close-out shapes are:
 
 - progress: `rudder issue comment <issue> --body-file <path> [--image <path>]`
 - done: `rudder issue done <issue> --comment-file <path> [--image <path>]`
@@ -139,7 +139,7 @@ Issue comment responses include `shortRef` when available. `rudder issue comment
 
 ## Renderable Library CLI Output
 
-File placement and handoff policy lives in [Durable Library artifacts](control-plane-practices.md#durable-library-artifacts). Request a renderable reference with `rudder library file ref <library-relative-path> --json`.
+File placement and handoff policy lives in [Durable Library artifacts](operating-practices.md#durable-library-artifacts). Request a renderable reference with `rudder library file ref <library-relative-path> --json`.
 
 The relevant JSON fields are:
 
@@ -151,7 +151,7 @@ The `ref` argument is Library-relative, not an absolute filesystem path. CLI fal
 
 ## Reviewer Decision Command Shapes
 
-Reviewer policy lives in [Review and close-out](control-plane-practices.md#review-and-close-out). Supported decision command shapes are:
+Reviewer policy lives in [Review and close-out](operating-practices.md#review-and-close-out). Supported decision command shapes are:
 
 - `rudder issue review <issue> --decision approve --comment-file <path>`
 - `rudder issue review <issue> --decision request_changes --comment-file <path>`