@rudderhq/agent-runtime-claude-local 0.1.0-canary.0

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

@@ -0,0 +1,67 @@
+# Rudder Agent CLI Reference
+
+Stable CLI contract for agents using the bundled `rudder` skill. Prefer these commands over direct `/api` calls.
+
+## Defaults
+
+- All commands support `--json`.
+- `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
+- `--run-id` defaults to `RUDDER_RUN_ID` and is attached to mutating requests when available.
+- `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`.
+
+## Agent V1 Commands
+
+| Command | Description | Mutating | Org | Agent | Run ID |
+| --- | --- | --- | --- | --- | --- |
+| `rudder agent me` | Show the authenticated agent identity, budget, and chain of command. | no | no | no | no |
+| `rudder agent inbox` | List the compact assigned-work inbox for the authenticated agent. | no | no | no | no |
+| `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
+| `rudder agent skills sync <agent-id>` | Sync the desired enabled skill set for an agent. | yes | no | no | attached when available |
+| `rudder issue get <issue>` | Read a full issue by UUID or identifier. | no | no | no | no |
+| `rudder issue context <issue>` | Read the compact heartbeat context for an issue. | no | no | no | no |
+| `rudder issue checkout <issue>` | Atomically checkout an issue for the current or specified agent. | yes | no | required | attached when available |
+| `rudder issue comment <issue> --body <text>` | Add a comment to an issue. | yes | no | no | attached when available |
+| `rudder issue comments list <issue>` | List issue comments, optionally only newer comments after a cursor. | no | no | no | no |
+| `rudder issue comments get <issue> <comment-id>` | Read one issue comment by id. | no | no | no | no |
+| `rudder issue update <issue> ...` | Apply generic issue updates when workflow commands are not enough. | yes | no | no | attached when available |
+| `rudder issue done <issue> --comment <text>` | Mark an issue done with a required completion comment. | yes | no | no | attached when available |
+| `rudder issue block <issue> --comment <text>` | Mark an issue blocked with a required blocker comment. | yes | no | no | attached when available |
+| `rudder issue release <issue>` | Release an issue back to todo and clear ownership. | yes | no | no | attached when available |
+| `rudder issue documents list <issue>` | List issue documents. | no | no | no | no |
+| `rudder issue documents get <issue> <key>` | Read one issue document by key. | no | no | no | no |
+| `rudder issue documents put <issue> <key> --body <text>` | Create or update an issue document. | yes | no | no | attached when available |
+| `rudder issue documents revisions <issue> <key>` | List revisions for an issue document. | no | no | no | no |
+| `rudder approval get <approval-id>` | Read one approval request. | no | no | no | no |
+| `rudder approval issues <approval-id>` | List the issues linked to an approval. | no | no | no | no |
+| `rudder approval comment <approval-id> --body <text>` | Add a comment to an approval. | yes | no | no | attached when available |
+| `rudder skill list --org-id <id>` | List organization-visible skills. | no | required | no | no |
+| `rudder skill get <skill-id> --org-id <id>` | Read one organization skill detail. | no | required | no | no |
+| `rudder skill file <skill-id> --org-id <id> [--path SKILL.md]` | Read one file from an organization skill package. | no | required | no | no |
+| `rudder skill import --org-id <id> --source <source>` | Import a skill package into the organization skill library. | yes | required | no | attached when available |
+| `rudder skill scan-local --org-id <id> [--roots <csv>]` | Scan local roots for skill packages and import new ones. | yes | required | no | attached when available |
+| `rudder skill scan-projects --org-id <id> [--project-ids <csv>] [--workspace-ids <csv>]` | Scan the org workspace and any legacy project workspace records for skill packages and import new ones. | yes | required | no | attached when available |
+
+## Issue Close-Out Signals
+
+Before a successful `todo` or `in_progress` issue run exits, leave one close-out signal with the command that matches the outcome:
+
+- progress remains: `rudder issue comment <issue> --body <text>`
+- work is complete: `rudder issue done <issue> --comment <text>`
+- work is blocked: `rudder issue block <issue> --comment <text>`
+- ownership changes: add an explicit handoff comment before or with the assignee update
+
+If `RUDDER_WAKE_REASON=issue_passive_followup`, the run is close-out governance for the same issue. Inspect current issue state first, then leave a progress comment, completion, blocker, or explicit handoff.
+
+## Compatibility Commands
+
+- `rudder agent list --org-id <id>` — List agents for an organization.
+- `rudder agent get <agent-id-or-shortname>` — Read one agent by id or shortname.
+- `rudder agent hire --org-id <id> --payload <json>` — Create a new hire using the canonical hire workflow.
+- `rudder agent config index` — Read the installed agent runtime configuration index.
+- `rudder agent config doc <agent-runtime-type>` — Read adapter-specific configuration guidance for one runtime.
+- `rudder agent config list --org-id <id>` — List redacted agent configuration snapshots for an organization.
+- `rudder agent config get <agent-id-or-shortname>` — Read one redacted agent configuration snapshot by id or shortname.
+- `rudder agent icons` — List allowed agent icon names for create and hire payloads.
+- `rudder issue create --org-id <id> ...` — Create a new issue or subtask with the generic issue surface.
+- `rudder approval create --org-id <id> --type <type> --payload <json>` — Create a new approval request.
+- `rudder approval resubmit <approval-id> [--payload <json>]` — Resubmit a revision-requested approval, optionally with updated payload.

package/skills/rudder/references/organization-skills.md

@@ -0,0 +1,155 @@
+# Organization Skills Workflow
+
+Use this reference when a board user, CEO, or manager asks you to discover, import, inspect, or enable organization skills.
+
+This workflow is now **CLI-first** for the bundled `rudder` skill.
+
+## Canonical Model
+
+1. import or scan the skill into the organization library
+2. inspect the imported skill if needed
+3. sync the desired enabled skills onto the target agent
+
+## Core CLI Surface
+
+```bash
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
+rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
+```
+
+Defaults:
+
+- `--org-id` can come from `RUDDER_ORG_ID`
+- mutating commands attach `RUDDER_RUN_ID` automatically when present
+
+## Source Types
+
+Use these sources in priority order:
+
+| Source format | Example | When to use |
+| --- | --- | --- |
+| `skills.sh` URL | `https://skills.sh/google-labs-code/stitch-skills/design-md` | Preferred when the user gives a managed registry URL |
+| key-style source | `google-labs-code/stitch-skills/design-md` | Shorthand for the same managed skill |
+| GitHub URL | `https://github.com/vercel-labs/agent-browser` | When the skill is on GitHub but not on `skills.sh` |
+| local path | `/abs/path/to/skill-dir` | Local dev or testing only |
+
+If the user gives a `skills.sh` URL, keep it as `skills.sh` or key-style. Do not rewrite it to a GitHub URL.
+
+## Import Examples
+
+Preferred managed import:
+
+```bash
+rudder skill import \
+  --org-id "$RUDDER_ORG_ID" \
+  --source "https://skills.sh/google-labs-code/stitch-skills/design-md" \
+  --json
+```
+
+Equivalent key-style import:
+
+```bash
+rudder skill import \
+  --org-id "$RUDDER_ORG_ID" \
+  --source "google-labs-code/stitch-skills/design-md" \
+  --json
+```
+
+GitHub import:
+
+```bash
+rudder skill import \
+  --org-id "$RUDDER_ORG_ID" \
+  --source "https://github.com/vercel-labs/agent-browser" \
+  --json
+```
+
+Local skill scan:
+
+```bash
+rudder skill scan-local \
+  --org-id "$RUDDER_ORG_ID" \
+  --roots "/abs/path/to/.agents,/abs/path/to/other-skill-root" \
+  --json
+```
+
+Shared workspace scan:
+
+```bash
+rudder skill scan-projects \
+  --org-id "$RUDDER_ORG_ID" \
+  --project-ids "<project-id-1>,<project-id-2>" \
+  --json
+```
+
+Notes:
+
+- Rudder now uses one fixed org workspace root at `~/.rudder/instances/<instance>/organizations/<org-id>/workspaces`.
+- `scan-projects` should be treated as a compatibility command that scans the shared org workspace plus any legacy project workspace records that still exist.
+- The org `Resources` catalog is the canonical place to register shared repos, docs, URLs, and connector objects for agents.
+- Workspaces remains the disk-backed shared file surface for plans, notes, and skill packages.
+
+## Inspect Imported Skills
+
+List skills:
+
+```bash
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+```
+
+Read one skill:
+
+```bash
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+```
+
+Read `SKILL.md` or another file from the package:
+
+```bash
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path references/notes.md --json
+```
+
+## Enable Skills On An Existing Agent
+
+`desiredSkills` accepts:
+
+- exact organization skill key
+- exact organization skill id
+- exact slug when it is unique in the organization
+
+```bash
+rudder agent skills sync \
+  "<agent-id>" \
+  --desired-skills "vercel-labs/agent-browser/agent-browser" \
+  --json
+```
+
+For multiple skills:
+
+```bash
+rudder agent skills sync \
+  "<agent-id>" \
+  --desired-skills "agent-browser,design-md" \
+  --json
+```
+
+## Permission Model
+
+- organization skill reads: any same-organization actor
+- organization skill mutations: board, CEO, or an agent with effective `agents:create`
+- agent skill sync: same permission model as updating that agent
+
+## Notes
+
+- Built-in Rudder skills live in the organization library but are not auto-enabled.
+- New organizations also seed optional community preset skills into the organization library. They stay organization-managed and default-off for agents.
+- If a skill reference is missing or ambiguous, Rudder returns `422`.
+- Prefer linking back to the relevant issue, approval, and agent when commenting about skill changes.
+- This document only covers library import/inspect/sync.
+- Hire and create flows now live on the CLI-first `rudder-create-agent` path.

package/skills/rudder-create-agent/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: rudder-create-agent
+description: Create new agents in Rudder through the `rudder` CLI with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hire request.
+---
+
+# Rudder Create Agent Skill
+
+Use this skill when you are asked to hire or create an agent in Rudder.
+
+## Preconditions
+
+You need either:
+
+- board access, or
+- agent permission `canCreateAgents=true` in your org
+
+If you do not have this permission, escalate to your CEO or board.
+
+This workflow is **CLI-first**.
+
+- Use `rudder ... --json` for structured reads and mutations.
+- Use `references/cli-reference.md` as the canonical command catalog for this skill.
+- Treat `references/api-reference.md` as internal/debug/compatibility documentation, not the normal runtime interface.
+- Do not create agent directories, instruction files, or org metadata manually as a fallback.
+- If CLI auth is unavailable in a heartbeat run, stop and report the auth problem instead of mutating the filesystem.
+
+## Workflow
+
+1. Confirm identity and organization context.
+
+```sh
+rudder agent me --json
+```
+
+If this returns `{"error":"Agent authentication required"}`, treat it as a run-auth failure:
+
+- do not ask for `RUDDER_API_KEY` inside the heartbeat
+- do not fall back to manual filesystem creation
+- stop and report that injected agent authentication is missing or invalid for this run
+
+2. Discover available adapter configuration docs for this Rudder instance.
+
+```sh
+rudder agent config index
+```
+
+3. Read adapter-specific docs for the runtime you plan to use.
+
+```sh
+rudder agent config doc codex_local
+rudder agent config doc claude_local
+```
+
+4. Compare existing agents and redacted configurations in your organization.
+
+```sh
+rudder agent list --org-id "$RUDDER_ORG_ID" --json
+rudder agent config list --org-id "$RUDDER_ORG_ID" --json
+rudder agent config get "<agent-id>" --json
+```
+
+5. Discover allowed agent icons and pick one that matches the role.
+
+```sh
+rudder agent icons
+```
+
+6. If the role needs organization skills on day one, inspect or import them before hiring.
+
+```sh
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
+```
+
+7. Draft the hire payload.
+
+Required thinking:
+
+- role / title / optional `name`
+- `name` is optional; if omitted, Rudder assigns a distinct personal name automatically
+- `icon` from `rudder agent icons`
+- reporting line (`reportsTo`)
+- adapter type
+- optional `desiredSkills` from the organization skill library
+- adapter and runtime config aligned to this environment
+- capabilities
+- run prompt in adapter config (`promptTemplate` where applicable)
+- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
+
+8. Submit the canonical hire request.
+
+```sh
+rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "<ceo-agent-id>",
+  "capabilities": "Owns technical roadmap, architecture, staffing, execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
+  "sourceIssueId": "<issue-id>"
+}' --json
+```
+
+`agent hire` is the canonical surface because it preserves the real server behavior:
+
+- if the organization does not require approval, it creates the agent directly and returns `"approval": null`
+- if the organization requires approval, it creates the agent in `pending_approval` and returns both `agent` and `approval`
+
+Do **not** substitute `rudder approval create --type hire_agent` for this step unless you are doing low-level debugging. That bypasses the canonical direct-create vs pending-approval behavior.
+
+9. Handle governance state.
+
+If the hire response includes `approval`, monitor and discuss on the approval thread:
+
+```sh
+rudder approval get "<approval-id>" --json
+rudder approval comment "<approval-id>" --body "## CTO hire request submitted
+
+- Approval: [<approval-id>](/<prefix>/messenger/approvals/<approval-id>)
+- Pending agent: [<agent-ref>](/<prefix>/agents/<agent-url-key-or-id>)
+- Source issue: [<issue-ref>](/<prefix>/issues/<issue-identifier-or-id>)
+
+Updated prompt and adapter config per board feedback." --json
+rudder approval resubmit "<approval-id>" --payload '{"title":"Revised title","agentRuntimeConfig":{"cwd":"/abs/path/to/repo","model":"o4-mini"}}' --json
+rudder approval issues "<approval-id>" --json
+```
+
+When the board approves, you may be woken with `RUDDER_APPROVAL_ID`:
+
+```sh
+rudder approval get "$RUDDER_APPROVAL_ID" --json
+rudder approval issues "$RUDDER_APPROVAL_ID" --json
+```
+
+For each linked issue, either:
+
+- close it if the approval resolved the request, or
+- comment in markdown with links to the approval and next actions
+
+## Quality Bar
+
+Before sending a hire request:
+
+- if the role needs skills, make sure they already exist in the org library or import them first using the Rudder org-skills workflow
+- reuse proven config patterns from related agents where possible
+- set a concrete `icon` from `rudder agent icons` so the new hire is identifiable in org and task views
+- avoid secrets in plain text unless required by adapter behavior
+- ensure the reporting line is correct and in-org
+- ensure the prompt is role-specific and operationally scoped
+- prefer `sourceIssueId` or `sourceIssueIds` in the hire payload instead of manual approval linking
+- if board requests revision, update the payload and resubmit through the approval flow
+- do not report success unless `rudder agent hire` itself succeeded and you can cite the returned `agent.id` or `approval.id`
+- creating local directories or instruction files is not evidence that an agent exists in Rudder
+
+For canonical command syntax and examples, read:
+`references/cli-reference.md`
+
+For low-level route shapes and underlying compatibility endpoints, read:
+`references/api-reference.md`

package/skills/rudder-create-agent/references/api-reference.md

@@ -0,0 +1,172 @@
+# Rudder Create Agent API Reference
+
+Internal/debug reference for the bundled `rudder-create-agent` skill.
+
+- Normal runtime execution should follow the CLI-first workflow in `../SKILL.md`.
+- The canonical command catalog lives in `cli-reference.md`.
+- Keep this document for route-level debugging, compatibility work, and payload-shape inspection.
+
+## CLI-to-API Mapping
+
+| CLI command | Primary route |
+| --- | --- |
+| `rudder agent config index` | `GET /llms/agent-configuration.txt` |
+| `rudder agent config doc <agentRuntimeType>` | `GET /llms/agent-configuration/:agentRuntimeType.txt` |
+| `rudder agent icons` | `GET /llms/agent-icons.txt` |
+| `rudder agent config list --org-id <orgId>` | `GET /api/orgs/:orgId/agent-configurations` |
+| `rudder agent config get <agentId>` | `GET /api/agents/:agentId/configuration` |
+| `rudder agent hire --org-id <orgId> --payload <json>` | `POST /api/orgs/:orgId/agent-hires` |
+| `rudder approval get <approvalId>` | `GET /api/approvals/:approvalId` |
+| `rudder approval comment <approvalId> --body <text>` | `POST /api/approvals/:approvalId/comments` |
+| `rudder approval resubmit <approvalId> [--payload <json>]` | `POST /api/approvals/:approvalId/resubmit` |
+| `rudder approval issues <approvalId>` | `GET /api/approvals/:approvalId/issues` |
+
+## Reflection Endpoints
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:agentRuntimeType.txt`
+- `GET /llms/agent-icons.txt`
+
+Auth:
+
+- board access, or
+- same-org agent auth with `canCreateAgents=true`
+
+These endpoints return plain text. The CLI wraps them directly.
+
+## Configuration Snapshots
+
+- `GET /api/orgs/:orgId/agent-configurations`
+- `GET /api/agents/:agentId/configuration`
+
+These responses are redacted snapshots for comparison and reuse.
+
+Representative shape:
+
+```json
+{
+  "id": "uuid",
+  "orgId": "uuid",
+  "name": "CTO",
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "status": "idle",
+  "reportsTo": "uuid-or-null",
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {
+    "cwd": "/absolute/path",
+    "model": "o4-mini"
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "permissions": {
+    "canCreateAgents": true
+  },
+  "updatedAt": "2026-04-19T12:00:00.000Z"
+}
+```
+
+## `POST /api/orgs/:orgId/agent-hires`
+
+Canonical hire route used by `rudder agent hire`.
+
+Request body:
+
+```json
+{
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "uuid-or-null",
+  "capabilities": "Owns architecture and engineering execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {
+    "cwd": "/absolute/path",
+    "model": "o4-mini",
+    "promptTemplate": "You are CTO..."
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "budgetMonthlyCents": 0,
+  "sourceIssueId": "uuid-or-null",
+  "sourceIssueIds": ["uuid-1", "uuid-2"]
+}
+```
+
+Response when approval is required:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "pending_approval"
+  },
+  "approval": {
+    "id": "uuid",
+    "type": "hire_agent",
+    "status": "pending",
+    "payload": {
+      "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
+    }
+  }
+}
+```
+
+Response when approval is not required:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "idle"
+  },
+  "approval": null
+}
+```
+
+Important notes:
+
+- `name` is optional; if omitted or blank, Rudder assigns a distinct first name automatically
+- `desiredSkills` accepts organization skill ids, canonical keys, or a unique slug; the server resolves and stores canonical organization skill keys
+- `sourceIssueId` and `sourceIssueIds` are the canonical way to link the hire back to originating issues
+- this route is preferred over creating `hire_agent` approvals manually because it preserves the organization's approval policy
+
+## Approval Lifecycle
+
+Relevant routes:
+
+- `GET /api/approvals/:approvalId`
+- `POST /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/resubmit`
+- `GET /api/approvals/:approvalId/issues`
+
+Statuses:
+
+- `pending`
+- `revision_requested`
+- `approved`
+- `rejected`
+- `cancelled`
+
+For hire approvals:
+
+- approved: linked agent transitions `pending_approval -> idle`
+- rejected: linked agent is terminated
+
+## Safety Notes
+
+- Config read APIs redact obvious secrets.
+- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
+- All hire and approval actions are logged in activity for auditability.
+- Use markdown in issue and approval comments and include links to the approval, agent, and source issue.

package/skills/rudder-create-agent/references/cli-reference.md

@@ -0,0 +1,126 @@
+# Rudder Create Agent CLI Reference
+
+Canonical CLI contract for the bundled `rudder-create-agent` skill. Prefer these commands over direct `/api` calls.
+
+## Defaults
+
+- All commands support `--json`.
+- `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
+- Mutating commands attach `RUDDER_RUN_ID` automatically when available.
+- `agent config index`, `agent config doc`, and `agent icons` print plain text by default. With `--json`, they emit that text as a JSON string.
+
+## Core CLI Surface
+
+### Identity and discovery
+
+```sh
+rudder agent me --json
+rudder agent list --org-id "$RUDDER_ORG_ID" --json
+rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent config index
+rudder agent config doc "<agent-runtime-type>"
+rudder agent config list --org-id "$RUDDER_ORG_ID" --json
+rudder agent config get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent icons
+```
+
+Use these in order:
+
+1. `agent me` to verify auth and org context
+2. `agent config index` to discover installed runtimes
+3. `agent config doc` to read one runtime's required fields and examples
+4. `agent list` plus `agent config list/get` to reuse proven patterns from related agents
+5. `agent icons` to choose an allowed `icon`
+
+### Organization skills
+
+```sh
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
+```
+
+Use these before hiring when the new role needs `desiredSkills`.
+
+`desiredSkills` accepts:
+
+- exact organization skill key
+- exact organization skill id
+- exact slug when it is unique in the organization
+
+### Canonical hire flow
+
+```sh
+rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "<ceo-agent-id>",
+  "capabilities": "Owns technical roadmap, architecture, staffing, execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
+  "sourceIssueId": "<issue-id>"
+}' --json
+```
+
+Canonical semantics:
+
+- this wraps `POST /api/orgs/:orgId/agent-hires`
+- if the organization does not require board approval, the response contains `approval: null` and the agent is created directly
+- if the organization requires board approval, the response contains both `agent` and `approval`, and the new agent stays `pending_approval`
+
+Do not use `rudder approval create --type hire_agent` as a replacement for `agent hire` during normal skill execution. That is a lower-level compatibility surface and does not preserve the canonical direct-create behavior.
+
+### Approval follow-up
+
+```sh
+rudder approval get "<approval-id>" --json
+rudder approval comment "<approval-id>" --body "<markdown>" --json
+rudder approval resubmit "<approval-id>" --payload '{"...":"..."}' --json
+rudder approval issues "<approval-id>" --json
+```
+
+Notes:
+
+- `approval comment` should use markdown and link the approval, pending agent, and source issue when available
+- `approval resubmit` is only for a revision-requested approval; update the payload instead of creating a second hire
+- if the run wakes with `RUDDER_APPROVAL_ID`, treat that approval as the first task
+
+## Payload Notes
+
+The `agent hire` payload accepts the same shape as the hire API, including:
+
+- `name` optional; blank or omitted means Rudder assigns a distinct first name
+- `role`
+- `title`
+- `icon`
+- `reportsTo`
+- `capabilities`
+- `desiredSkills`
+- `agentRuntimeType`
+- `agentRuntimeConfig`
+- `runtimeConfig`
+- `budgetMonthlyCents`
+- `metadata`
+- `sourceIssueId`
+- `sourceIssueIds`
+
+Issue linkage rule:
+
+- prefer `sourceIssueId` or `sourceIssueIds` inside the hire payload
+- use `approval issues` to inspect the resulting approval links after the server creates them
+
+## Related Commands
+
+Post-hire adjustments use the normal agent and skill surfaces:
+
+```sh
+rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
+rudder agent local-cli "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+```