@rudderhq/agent-runtime-opencode-local 0.4.6-canary.9 → 0.5.1-canary.0

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 → rudder-docs}/references/api-reference.md

@@ -1,11 +1,27 @@
 # Rudder API Reference
 
-Internal/debug reference for the Rudder control plane API.
+Internal/debug reference for the Rudder API.
 
-- Normal heartbeats should use the CLI-first workflow in `../SKILL.md`.
+- 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 `operating-practices.md`.
 - Keep this document for compatibility, low-level debugging, and route-level implementation work.
 
+## Section Map
+
+- [Canonical terms](#canonical-terms)
+- [Core agent context](#core-agent-context)
+- [Issue workflows](#issue-workflows)
+- [Organization surfaces](#organization-surfaces)
+- [Approval workflows](#approval-workflows)
+- [Agent configuration and instructions](#agent-configuration-and-instructions)
+- [Organization skills](#organization-skills)
+- [OpenClaw invite](#openclaw-invite)
+- [Organization portability](#organization-portability)
+- [Worked example](#worked-example-ic-heartbeat)
+
 ## Canonical Terms
 
 - Use `orgId` and `/api/orgs/...` routes.
@@ -130,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`
@@ -144,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 → rudder-docs}/references/cli-reference.md

@@ -1,15 +1,32 @@
 # Rudder Agent CLI Reference
 
-Stable compatibility contract for agents using the bundled `rudder` skill. Prefer first-party Rudder MCP tools when the runtime exposes them; use these CLI commands as fallback when MCP is unavailable or a Rudder MCP tool returns a transport/configuration error.
-
-## Chat And Issue Surface Boundary
-
-Chat and issues are parallel ways to advance real tasks. Chat supports
-conversation-driven execution; issues add explicit ownership, status, priority,
-dependencies, and review structure. Do not create or require an issue merely
-because Chat work is executable, long-running, reviewable, or durable. Use the
-issue checkout and close-out commands below only for issue-scoped work, or when
-operator intent or team governance requires that structure.
+Stable typed-tool and CLI fallback catalog for the bundled `rudder-docs`
+package. Prefer first-party Rudder MCP tools when the runtime exposes them; use
+these CLI commands as fallback when MCP is unavailable or a Rudder MCP tool
+returns a transport or configuration error.
+
+## Section Map
+
+- [Operating policy owners](#operating-policy-owners)
+- [Defaults](#defaults)
+- [JSON output contract](#json-output-contract)
+- [Agent V1 commands](#agent-v1-commands)
+- [Issue command I/O and shapes](#issue-command-io-and-shapes)
+- [Renderable Library CLI output](#renderable-library-cli-output)
+- [Reviewer decision command shapes](#reviewer-decision-command-shapes)
+- [Compatibility commands](#compatibility-commands)
+
+## Operating Policy Owners
+
+Keep this file focused on commands and CLI-specific I/O. Consult the exact
+operating-practices guide for operating behavior:
+
+- [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
 
@@ -24,8 +41,6 @@ operator intent or team governance requires that structure.
 
 `rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
 
-Direct API fallback is allowed for heartbeat close-out only when a required CLI command fails diagnostically or returns exit 0 with empty stdout. When using fallback, note the affected command and reason in the issue comment or run notes so the CLI path can be fixed.
-
 ## Agent V1 Commands
 
 | MCP Tool | CLI Fallback | Description | Mutating | Org | Agent | Run ID |
@@ -33,7 +48,7 @@ Direct API fallback is allowed for heartbeat close-out only when a required CLI
 | `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 |
@@ -95,113 +110,53 @@ Direct API fallback is allowed for heartbeat close-out only when a required CLI
 | `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 |
 | `rudder_runs_by_skill` | `rudder runs by-skill <skill> --org-id <id> [--evidence <used-or-loaded>] [--cursor <cursor>] [--full]` | Build a paginated skill evidence packet from lightweight run summaries; use --full only for legacy full-row compatibility. | no | required | no | no |
-| `rudder_runs_get` | `rudder runs get <run-id>` | Read one observed run detail. | no | no | no | no |
-| `rudder_runs_events` | `rudder runs events <run-id> [--after-seq <n>] [--limit <n>]` | List a bounded page of persisted run events with a sequence cursor. | no | no | no | no |
+| `rudder_runs_get` | `rudder runs get <run-id> [--full]` | Read one bounded run summary; use --full only from a direct trusted CLI for raw detail. | no | no | no | no |
+| `rudder_runs_events` | `rudder runs events <run-id> [--cursor <cursor>] [--after-seq <n>] [--limit <n>] [--full]` | List a bounded page of persisted run events with a lossless opaque cursor and clipped payload previews. | no | no | no | no |
 | `rudder_runs_log` | `rudder runs log <run-id> [--offset <bytes>] [--limit-bytes <n>]` | Read a bounded byte range of stored run log content. | no | no | no | no |
-| `rudder_runs_transcript` | `rudder runs transcript <run-id> [--turn-limit <n>] [--cursor <cursor>] [--include-output]` | Read the server-normalized run transcript; human output is compact and JSON includes full entries. | no | no | no | no |
+| `rudder_runs_transcript` | `rudder runs transcript <run-id> [--turn-limit <n>] [--cursor <cursor>] [--include-output] [--full]` | Read a compact server-normalized transcript; --json changes encoding only and --full is direct-CLI-only raw access. | no | no | no | no |
 | `rudder_runs_errors` | `rudder runs errors <run-id>` | List failed tool calls, stderr, runtime failures, and jump-to-context commands. | no | no | no | no |
 | `rudder_runs_cancel` | `rudder runs cancel <run-id>` | Cancel a heartbeat run through the governed server route. | yes | no | no | attached when available |
 | `rudder_runs_retry` | `rudder runs retry <run-id>` | Retry a failed, timed out, or cancelled run through the governed server route. | yes | no | 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-file <path> [--image <path>]`
-- work is complete: `rudder issue done <issue> --comment-file <path> [--image <path>]`
-- work is blocked: `rudder issue block <issue> --comment-file <path> [--image <path>]`
-- ownership changes: add an explicit handoff comment before or with the assignee update
+## Issue Command I/O And Shapes
 
-If a comment wakes you on an issue not assigned to you, including user-owned or
-unassigned issues, treat that comment as the scope of the wake unless it
-explicitly asks you to implement, modify files, close the issue, or take
-ownership. Questions should get answers, corrections should get acknowledgment
-or explanation, and narrow requests should not become permission to finish the
-whole issue.
+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:
 
-If an issue has a reviewer, moving it to `blocked` also routes reviewer work: the reviewer should confirm the blocker, request changes, approve, or keep explicit follow-up open with `rudder issue review`.
+- progress: `rudder issue comment <issue> --body-file <path> [--image <path>]`
+- done: `rudder issue done <issue> --comment-file <path> [--image <path>]`
+- blocked: `rudder issue block <issue> --comment-file <path> [--image <path>]`
 
-Issue comment and close-out commands accept comment bodies only from files or stdin. For any multiline Markdown, command names, code spans, code blocks, test summaries, or screenshot evidence, write the comment to a temporary Markdown file and pass `--body-file <path>` or `--comment-file <path>`, or pass `-` to read the body from stdin.
+Issue comment and close-out commands accept comment bodies only from files or stdin. For multiline Markdown, command names, code spans, code blocks, test summaries, or screenshot evidence, pass `--body-file <path>` or `--comment-file <path>`, or pass `-` to read the body from stdin.
 
 Issue comment responses include `shortRef` when available. `rudder issue comments get <issue> <comment-id-or-cmt-ref>` accepts a full comment UUID or `cmt_<uuid-prefix>`, and `rudder issue comments list <issue> --after <comment-id-or-cmt-ref>` accepts the same forms for the pagination anchor. Use the full UUID when a short ref is ambiguous within the issue.
 
 `--image` may be repeated. The CLI uploads each local PNG/JPEG/WebP/GIF as an issue attachment and appends Markdown image links to the comment text before sending it.
 
-If your issue comment cites a screenshot path or visual validation artifact, attach that file with `--image <path>` instead of leaving only the local path in the text.
+## Renderable Library CLI Output
 
-If `RUDDER_WAKE_REASON=issue_passive_followup`, the run is issue follow-up for the same issue. Inspect current issue state first, then leave a progress comment, completion, blocker, or explicit handoff.
+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`.
 
-## Renderable Library References
+The relevant JSON fields are:
 
-Agents should not hand-write `library-entry://...` URLs. Local trusted agents
-should create and update durable project files directly under
-`$RUDDER_PROJECT_LIBRARY_ROOT` with normal filesystem tools when the run has
-project context. When there is no project context, write durable generated
-chat/work artifacts under
-`$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`
-and reference the Library-relative product path
-`artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. After creating,
-updating, or reading a durable Library file, use `rudder library file ref` to
-get the CLI-returned `markdownLink` for issue comments, review comments,
-blocker notes, done comments, and chat replies.
+- `libraryEntryId`: stable identity for the Library file.
+- `mentionHref`: raw renderable target, optionally with a Rudder-generated path hint.
+- `markdownLink`: complete Markdown link for the renderer.
 
-```bash
-printf '%s\n' "<markdown body>" > "$RUDDER_PROJECT_LIBRARY_ROOT/<issue>.md"
-result="$(rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<issue>.md" --json)"
-printf '%s\n' "$result" | jq -r .markdownLink
+The `ref` argument is Library-relative, not an absolute filesystem path. CLI fallback shapes are `rudder library file get <library-relative-path> --json` and `rudder library file put <library-relative-path> --body-file <path> --json`. `rudder library file link <library-relative-path> --json` remains a compatibility alias for `ref`.
 
-mkdir -p "$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>"
-printf '%s\n' "<markdown body>" > "$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<artifact>.md"
-result="$(rudder library file ref "artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>" --json)"
-printf '%s\n' "$result" | jq -r .markdownLink
-```
+## Reviewer Decision Command Shapes
 
-The relevant JSON fields are:
+Reviewer policy lives in [Review and close-out](operating-practices.md#review-and-close-out). Supported decision command shapes are:
 
-- `libraryEntryId`: stable identity for the Library file.
-- `mentionHref`: raw `library-entry://<id>` target, optionally with a
-  Rudder-generated `p` query parameter as a path hint for the current Library
-  path.
-- `markdownLink`: complete Markdown link that the renderer turns into a Library
-  chip. Its identity remains the entry id; any `p` query value is only a
-  synchronous navigation hint and agents should not hand-write it.
-
-Use `rudder library file get/put` only when local filesystem access to the
-Library is unavailable, such as remote or restricted runtimes. `rudder library
-file link <path> --json` remains as a compatibility alias for `ref`. The
-`ref` path is Library-relative, for example
-`$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` with project context or
-`artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>` without project
-context; do not pass absolute filesystem paths such as
-`$RUDDER_PROJECT_LIBRARY_ROOT/...` or `$RUDDER_ORG_WORKSPACE_ROOT/...`. Posting
-the returned `markdownLink` is the Rudder-visible handoff checkpoint for direct
-filesystem writes. If `$RUDDER_PROJECT_LIBRARY_ROOT` is unset or inaccessible
-but `$RUDDER_PROJECT_LIBRARY_PATH` exists, use
-`rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>"` as
-the remote or restricted runtime fallback. If there is no project context, use
-the organization artifacts fallback path instead. Treat `library-file://...` as
-legacy weak path syntax and use it only when preserving old content that has no
-`libraryEntryId`.
-
-## Git Identity Policy
-
-Codex local runs preserve the operator `HOME` for host CLI auth while using managed `CODEX_HOME` and Git sidecars for runtime isolation. Codex local runs and runtime-created git worktrees are prepared with `user.useConfigOnly=true` so missing identity fails fast instead of producing `*@*.local` commits. If Git reports missing author or committer identity, configure the repository explicitly with `git config user.name <name>` and `git config user.email <safe-email>`; do not unset the guard or accept auto-detected local-host metadata.
-
-## Reviewer Close-Out Signals
-
-When the inbox row or wake context says `relationship: "reviewer"`, `role: "reviewer"`, or `wakeSource: "review"`, finish the review with one structured reviewer decision. Reviewer work can be either `in_review` or `blocked`; blocked reviewer work means blocker triage, not implementation takeover.
-
-- approve: `rudder issue review <issue> --decision approve --comment-file <path>`
-- request changes: `rudder issue review <issue> --decision request_changes --comment-file <path>`
-- needs follow-up: `rudder issue review <issue> --decision needs_followup --comment-file <path>`
-- blocked or blocker confirmed: `rudder issue review <issue> --decision blocked --comment-file <path>`; use this only for a confirmed human/external blocker and name the next human action.
-
-Do not rely on a free-form reject or accept comment as the review outcome. The structured decision is the durable close-out signal. If a blocked reviewer decision needs human input, name the next human action in the review comment; Rudder records only the reviewer decision and removes the issue from repeated reviewer pickup until the board changes the issue.
+- `rudder issue review <issue> --decision approve --comment-file <path>`
+- `rudder issue review <issue> --decision request_changes --comment-file <path>`
+- `rudder issue review <issue> --decision needs_followup --comment-file <path>`
+- `rudder issue review <issue> --decision blocked --comment-file <path>`
 
 ## Compatibility Commands
 

package/skills/rudder-docs/references/operating-practices.md

@@ -0,0 +1,231 @@
+# Rudder Work Practices
+
+Consult this reference only for questions about exact Rudder operating
+behavior. It is conditional documentation, not a trigger and not an always-run
+workflow. For exact tool and CLI syntax, pair the relevant rule with
+`cli-reference.md` instead of recreating its command table here.
+
+## Section Map
+
+- [Interface and scope](#interface-and-scope)
+- [Ownership, checkout, and wake scope](#ownership-checkout-and-wake-scope)
+- [Comments, mentions, and evidence](#comments-mentions-and-evidence)
+- [Review and close-out](#review-and-close-out)
+- [Approvals](#approvals)
+- [Delegation, escalation, and budget](#delegation-escalation-and-budget)
+- [Git identity and attribution](#git-identity-and-attribution)
+- [Workspaces, projects, and resources](#workspaces-projects-and-resources)
+- [Durable Library artifacts](#durable-library-artifacts)
+- [Organization and agent skills](#organization-and-agent-skills)
+- [Authentication and runtime environment](#authentication-and-runtime-environment)
+- [User activity context](#user-activity-context)
+
+## Interface And Scope
+
+- Prefer exposed first-party Rudder typed tools for normal Rudder work.
+  Use the installed `rudder ... --json` CLI as the compatibility fallback when
+  MCP is unavailable or a Rudder tool has a transport or configuration error.
+- Use `rudder agent capabilities --json` to discover the current capability
+  set. Treat direct API use as an internal, debugging, or compatibility path,
+  not the normal interface.
+- Direct API fallback for required close-out is acceptable only when the CLI
+  exits nonzero with a diagnostic error or incorrectly exits zero with empty
+  stdout. Record the failed command and fallback reason in the issue comment or
+  run notes.
+- If wake text explicitly declares HTTP compatibility mode, follow that
+  bounded mode for the run.
+
+Chat and issues are parallel work surfaces. Continue chat-scoped work in Chat
+unless the operator asks for issue structure or team policy requires explicit
+ownership, status, dependencies, or review. Do not create an issue merely
+because work is executable, durable, long-running, or reviewable.
+
+## Ownership, Checkout, And Wake Scope
+
+- Before issue-scoped execution, checkout the assigned issue. Never retry a
+  checkout that returns `409`; stop and report the ownership conflict.
+- Never look for unassigned work. Work the authenticated agent's assignee or
+  reviewer inbox and the explicit wake context.
+- Self-assign only when a wake comment explicitly transfers ownership.
+- A wake on an issue not assigned to the agent, including a user-owned or
+  unassigned issue, is scoped to that comment unless it explicitly requests
+  implementation, file changes, close-out, or ownership transfer. Answer a
+  question as a question; do not silently take over the whole issue.
+- Treat `issue_passive_followup` as follow-up on the same issue, not a fresh
+  assignment. Treat `issue_review_closeout_missing` as review follow-up.
+
+## Comments, Mentions, And Evidence
+
+- Keep issue comments concise: a short status line, the material change or
+  blocker, validation evidence, and links to related entities, Library files,
+  or external pages.
+- Use normal Markdown links with Rudder's canonical renderable entity schemes:
+  `issue://`, `agent://`, `automation://`, `project://`, `chat://`, and
+  `skill://`. Add `?c=<comment-id>` to an issue URI for a specific comment.
+- Add `?intent=wake` to an agent URI only when intentionally waking that agent;
+  omit it for a reference-only link. Plain text names are not wake requests.
+- For Library files, copy the returned `markdownLink` instead of constructing a
+  URI. Link external pages with a descriptive Markdown `https` link.
+- Multiline comments, code spans, test summaries, and Markdown should be passed
+  from a file or stdin according to the CLI reference. Do not depend on fragile
+  shell interpolation.
+- Attach each screenshot or image with `--image` when it is evidence in an
+  issue comment or close-out. A local filesystem path alone is not inspectable
+  by board users.
+- Always communicate before exiting active issue work, except when a blocked
+  issue has no new context to report.
+
+## Review And Close-Out
+
+Use the close-out signal matching the outcome: a progress comment when work
+remains, done with completion evidence, blocked with a blocker comment, or an
+explicit handoff comment with an ownership change.
+
+If blocked, set the issue to `blocked`, identify the blocker, name the next
+actor or action, and leave the blocker comment before exit. Do not present
+partial work as complete.
+
+A reviewer does not take over implementation unless explicitly asked.
+Reviewer work may cover `in_review` or `blocked`; the latter is blocker triage,
+not implementation ownership. Record one structured durable decision:
+
+- `--decision approve` for accepted work;
+- `--decision request_changes` for required changes;
+- `--decision needs_followup` when review remains open; or
+- `--decision blocked` only for a confirmed human or external blocker, with
+  the next human action named.
+
+Do not rely on free-form accept, reject, or change-request text as the review
+outcome. The structured decision is the durable close-out signal.
+
+## Approvals
+
+When `RUDDER_APPROVAL_ID` is present, read the approval and its linked issues
+before acting. Preserve the approval boundary: comment, request revision,
+resubmit, approve, or reject only through the governed approval surface and
+only when the current actor is authorized. An approval question does not grant
+permission for the underlying mutation. When an approval remains unresolved,
+report the status and required follow-up rather than bypassing it.
+
+## Delegation, Escalation, And Budget
+
+- Agent-created issues default to the creating agent when no assignee is
+  supplied. Set an explicit assignee when delegating to someone else.
+- Always set `parentId` for delegated work. Set `goalId` unless intentionally
+  creating top-level management work. When the organization has a mature label
+  taxonomy, choose at least one suitable label after inspecting the available
+  labels.
+- Never cancel cross-team work. Reassign upward with an explanation, and use
+  `chainOfCommand` for escalation.
+- Above 80% spend, focus on critical work only and avoid expanding scope.
+- Use [Agent creation](agent-creation.md) for the canonical governed hiring
+  workflow rather than assembling a raw Rudder API payload.
+
+## Git Identity And Attribution
+
+Every agent-created commit must include this trailer at the end of the commit
+message:
+
+`Co-Authored-By: Rudder <285064165+Rudderhq@users.noreply.github.com>`
+
+Use an explicit safe Git identity. Rudder prepares isolated runtime worktrees
+with `user.useConfigOnly=true`; if Git reports a missing identity, configure
+repository-local `user.name` and `user.email`. Do not bypass the guard and
+never accept `*@*.local` author or committer metadata.
+
+## Workspaces, Projects, And Resources
+
+Each organization has one managed shared workspace under its Rudder instance.
+The organization storage key is filesystem-safe; for UUID-backed organizations
+it is the first 12 lowercase hexadecimal characters with dashes removed. APIs
+continue to use the full organization ID.
+
+- The organization Resources catalog is reusable shared context, but it is not
+  injected wholesale into every run.
+- A project-linked run or chat receives only that project's attached
+  resources. Project Context is the curated starting set, not a knowledge
+  boundary; inspect broader Library or organization workspace knowledge when
+  the attached set is insufficient.
+- Library resources use `sourceType: "library"` and safe locators below
+  `library:projects/<project-key>/`. External resources retain their original
+  URL, local path, repository path, or connector locator.
+- Use Workspaces for disk-backed shared files and skill packages. Agent-private
+  files live below the agent's workspace key. New projects do not create
+  independent workspace roots.
+- Preserve organization and workspace boundaries. Do not query or copy another
+  organization's private resources to fill a context gap.
+- Use the typed project or stable CLI surface for project records; do not
+  substitute ad hoc API mutations.
+
+## Durable Library Artifacts
+
+With project context in a local trusted run, write durable project work under
+`$RUDDER_PROJECT_LIBRARY_ROOT`. Use
+`$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` only when requesting a
+renderable Rudder reference.
+
+Without project context, write durable generated chat or work artifacts under
+`$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`
+and use the product locator
+`library:artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. Do not choose an existing project, such as Getting Started, merely to obtain a project
+Library path. Reserve temporary directories for scratch and verification
+artifacts.
+
+After creating or changing a durable Library file, request its stable
+`markdownLink` using `rudder library file ref` with the Library-relative path.
+Use that returned link in the final chat reply, issue comment, review, blocker,
+or done comment. Direct filesystem writes are not complete Rudder-visible
+handoff evidence until the returned link is posted.
+
+Do not hand-write `library-entry://` URLs or their query parameters. Copy the
+returned `mentionHref` or `markdownLink`; the entry ID is stable identity and a
+Rudder-generated `p` value is only a synchronous path hint. Treat
+`library-file://` and `library-doc://` as legacy references for existing
+content, not new links.
+
+Use `rudder library file get/put` only when the local Library filesystem is
+unavailable, such as a remote or restricted runtime. With project context the
+fallback path is `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>`; without it,
+use `artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. These are
+Library-relative paths, never absolute workspace paths.
+
+Do not mark an issue done when the request was only to create or revise a plan.
+Reassign the plan for review when that is the expected workflow, and include
+the returned `markdownLink` in the handoff. The retired `rudder issue
+documents` surface is not a durable-plan path.
+
+## Organization And Agent Skills
+
+For private skills used only by the running agent, prefer agent-private skill
+creation under `AGENT_HOME/skills`, then confirm the skill is enabled in the
+agent snapshot. Installed but disabled skills do not load on future runs.
+
+For organization discovery, import, inspection, and assignment, consult
+`organization-skills.md`. `skills enable` is additive and preserves existing
+optional selections; `skills sync` replaces the full optional enabled-skill
+set and should be used only when replacement is intentional. Do not fall back
+to raw HTTP for this workflow in local adapters or packaged Desktop.
+
+## Authentication And Runtime Environment
+
+Rudder normally injects the runtime context, including `RUDDER_AGENT_ID`,
+`RUDDER_ORG_ID`, `RUDDER_API_URL`, `RUDDER_API_KEY`, and `RUDDER_RUN_ID`.
+Issue, wake, or approval contexts may also provide `RUDDER_TASK_ID`,
+`RUDDER_WAKE_REASON`, `RUDDER_WAKE_COMMENT_ID`, `RUDDER_APPROVAL_ID`,
+`RUDDER_APPROVAL_STATUS`, and `RUDDER_LINKED_ISSUE_IDS`.
+
+Never ask for `RUDDER_API_KEY`; never print it. Do not hard-code the API URL.
+For local adapters and packaged Desktop, the installed `rudder` binary should
+already be on `PATH`. Manual local CLI setup outside a managed run may use the
+documented local-cli authentication flow, but it must preserve organization
+scope and should not expose the minted key in durable output.
+
+## User Activity Context
+
+Use the user activity ledger when a question depends on recent user-authored
+Rudder activity, such as today's conversations, feedback, or handoff context.
+The ledger's excerpts are pointers with provenance, not ground truth when exact
+wording matters. Inspect the cited source before writing durable memory,
+profile changes, or stable preference conclusions. Do not use the ledger to
+bypass permissions or promote private content into long-term memory without a
+clear durable operating lesson.