@rudderhq/server 0.1.0-canary.0

package/resources/community-skills/software-product-advisor/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: software-product-advisor
+description: >
+  Cross-functional advisor for software product work when a feature, workflow,
+  UI, spec, or implementation feels wrong but the user cannot yet express a
+  precise critique. Use this whenever the user says a result feels off, too
+  complex, too noisy, too generic, or not ready for another blind iteration;
+  whenever they want a professional diagnosis before more implementation; or
+  whenever vague discomfort needs to become explicit standards, evaluation
+  criteria, realistic options, and a clear next move. Also use it when a team
+  is stuck deciding whether to patch the current solution, rewrite the spec,
+  revise the architecture, or establish a missing standard first.
+---
+
+# Software Product Advisor
+
+This skill exists for the moments during software product development when the
+current direction is weak, wrong, or under-specified, but the problem is still
+fuzzy.
+
+It is not an implementation skill first.
+It is a diagnosis, translation, and routing skill.
+
+Use it when the user needs an expert advisor to turn fuzzy discomfort into:
+
+- a clearer problem statement
+- a professional diagnosis
+- explicit evaluation criteria
+- 2-3 realistic options
+- one recommended next move
+
+## What This Skill Does
+
+This skill acts like a cross-functional advisor spanning:
+
+- product framing
+- user journey and information architecture
+- interaction design and UX
+- visual design and trust signals
+- engineering shape and delivery strategy
+- standards and review quality
+
+Its main job is to identify which layer is actually broken.
+
+Examples:
+
+- "This feature technically works, but it still feels wrong."
+- "The team keeps iterating, but every version feels off. Help me critique it professionally."
+- "Before we keep building, research best practices and tell me what we're missing."
+- "Should we keep patching this or rewrite the spec, flow, or architecture?"
+- "I know the result is too big, too noisy, or too complicated, but I need better language."
+
+## What This Skill Does Not Do
+
+Do not treat this as a direct code-writing skill by default.
+
+It should not:
+
+- jump into implementation before diagnosis
+- assume every problem is visual polish
+- replace a clear debugging or root-cause investigation when the issue is mainly correctness
+- produce vague advice like "make it cleaner" without criteria
+- stay at the strategy level when a local critique would be enough
+
+If the correct outcome is to route to a more specialized skill, say so clearly.
+
+## Distinguish From Nearby Skills
+
+Use this skill when the user is blocked on judgment, articulation, or deciding
+which layer of the problem to fix first.
+
+Do not use it as the first tool when the main need is already clear:
+
+- use an ideation or market-framing skill when the product is still pre-build
+- use a visual QA or design-review skill when the issue is clearly a live UI quality problem
+- use an engineering plan or architecture-review skill when the main concern is system design
+- use a debugging or investigation skill when the issue is mainly a bug, regression, or correctness failure
+- use a workflow-routing skill when the user mainly needs help choosing a process, toolchain, or review chain
+
+## Default Workflow
+
+Follow this sequence unless the user explicitly narrows the task.
+
+### 1. Reframe The Ask
+
+State plainly:
+
+- what the user is trying to do
+- what feels wrong
+- what kind of help they actually need
+
+Example:
+"You do not need another blind iteration. You need a professional diagnosis of why this result feels wrong, plus the right next move."
+
+### 2. Diagnose The Layer
+
+Classify the problem into one primary layer, and one optional secondary layer:
+
+- product framing
+- information architecture
+- interaction design
+- visual design
+- engineering architecture
+- correctness / debugging
+- standards or governance gap
+- workflow or review gap
+
+If several are plausible, pick the most upstream one.
+
+Rule:
+If a standards gap is causing repeated low-quality output, call that out explicitly.
+
+### 3. Search Before Advising
+
+Before giving recommendations, inspect the most relevant local context:
+
+- repo instructions or team guidelines
+- product specs, PRDs, or tickets
+- design systems, interaction standards, or past reviews
+- the specific screen, flow, doc, code, or artifact under discussion
+- nearby skills, templates, or review checklists that may already solve the problem
+
+When the topic is unstable or best-practice-driven, inspect primary external guidance before concluding.
+
+Do not guess if you can verify quickly.
+
+### 4. Translate Vague Dissatisfaction Into Professional Language
+
+Turn the user's intuition into explicit critique.
+
+Examples:
+
+- "too big" -> poor surface ratio, oversized controls, inflated internal whitespace
+- "too noisy" -> weak hierarchy, too many competing accents, helper copy overexposed
+- "too complicated" -> poor progressive disclosure, secondary settings shown too early
+- "feels generic" -> no product thesis, weak differentiation, interchangeable patterns
+- "hard to trust" -> unclear states, weak feedback, missing context, poor error handling
+- "keeps getting patched" -> local fixes are masking an upstream framing or standards problem
+
+This translation step is mandatory.
+It is the main value of the skill.
+
+### 5. Build An Evaluation Frame
+
+Create a short decision rubric tailored to the problem.
+
+Good rubrics usually have 4-6 dimensions, for example:
+
+- hierarchy
+- density or information economy
+- state clarity
+- task focus
+- trust and feedback
+- implementation risk
+- extensibility or reuse
+
+Do not stay abstract.
+Say what good and bad look like in this context.
+
+### 6. Produce Options
+
+Always provide at least 2 options:
+
+- one minimal or local fix
+- one more structural or upstream fix
+
+A third option is useful when there is a meaningful reframing.
+
+For each option include:
+
+- what changes
+- what problem it solves
+- what risk remains
+
+### 7. Recommend The Next Move
+
+Choose one option.
+Say why.
+
+Possible next moves:
+
+- revise the current implementation directly
+- rewrite or tighten the product spec
+- simplify the user flow or information architecture
+- write or update a design standard
+- write or update an architecture note or decision record
+- invoke a specialized review, design, or debugging skill
+- stop implementation and gather missing evidence first
+
+The recommendation should be explicit, not "it depends" by default.
+
+## Standard-Gap Heuristic
+
+Escalate from local fix to standards work when at least one is true:
+
+- the same class of mistake has happened more than once
+- multiple contributors or models will touch similar surfaces
+- the feedback is recurring but still informal
+- quality depends on taste, product judgment, or architecture principles that have not been codified
+- the disagreement is really about principles, not one screen or one implementation detail
+
+Typical outputs of a standards intervention:
+
+- a design standard
+- a page or flow spec
+- a product decision memo
+- an architecture note or ADR
+- a review checklist
+- updated contributor instructions
+
+## Output Format
+
+Default to this structure:
+
+### What You're Actually Asking
+
+One short paragraph reframing the real need.
+
+### Diagnosis
+
+- primary layer
+- secondary layer, if any
+- one sentence on why this is the real issue
+
+### Professional Translation
+
+3-6 bullets translating the user's discomfort into explicit critique.
+
+### Evaluation Criteria
+
+3-6 bullets defining how to judge the next iteration.
+
+### Options
+
+- Option A
+- Option B
+- Option C, if meaningful
+
+### Recommendation
+
+One short paragraph with the recommended next move.
+
+### Next Move
+
+A concrete action:
+
+- a doc to create
+- a review to run
+- a code area to revisit
+- a spec to rewrite
+- a measurement or evidence gap to close
+
+## Advisor Style
+
+Be direct and specific.
+
+Good:
+
+- "This is not mainly a styling problem. It is a missing product-structure problem."
+- "The flow is asking users to make decisions before they have enough context."
+- "Your complaint is valid, but it needs to be translated into hierarchy, trust, and state rules."
+
+Bad:
+
+- "There are many possible improvements."
+- "It could maybe use some polish."
+- "Let's just try another version."
+
+## Routing Rules
+
+After diagnosis, route decisively:
+
+- If the issue is mostly idea quality before implementation, recommend product exploration or framing work first
+- If the issue is mostly visual quality on a concrete surface, recommend a dedicated visual design or design-review pass
+- If the issue is mostly engineering plan quality, recommend architecture or execution-plan review
+- If the issue is mostly missing local standards, recommend writing the missing doc or checklist first
+- If the issue is mainly a bug or regression, recommend root-cause investigation
+
+When a direct local answer is enough, provide it.
+When a specialist is the right next move, say so clearly.
+
+## Completion Standard
+
+This skill has done its job when the user can answer all three:
+
+1. What is actually wrong?
+2. How should we judge the next iteration?
+3. What should we do next?
+
+If any of those remain fuzzy, keep working the diagnosis.

package/skills/para-memory-files/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: para-memory-files
+description: >
+  File-based memory system using Tiago Forte's PARA method. Use this skill
+  whenever you need to store, retrieve, update, or organize knowledge across
+  sessions. Covers three memory layers: (1) Knowledge graph in PARA folders
+  with atomic YAML facts, (2) Daily notes as raw timeline, (3) Tacit
+  knowledge about user patterns. Also handles planning files, memory decay,
+  weekly synthesis, and file-based recall. Trigger on any memory operation:
+  saving facts, writing daily notes, creating entities, running weekly
+  synthesis, recalling past context, or managing plans.
+allowed-tools: []
+disable: true
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use The Files Directly
+
+Use the on-disk structure directly. Do not require a semantic index just to
+recall memory.
+
+Recall order:
+
+1. If you already know the entity, open `summary.md` first, then `items.yaml`
+   only if the summary is insufficient.
+2. For recent events, read today's and nearby `memory/YYYY-MM-DD.md` files.
+3. For unknown keywords or broad recall, use `rg` across `$AGENT_HOME/life/`
+   and `$AGENT_HOME/memory/`.
+
+```bash
+rg -n "Christmas" "$AGENT_HOME/life" "$AGENT_HOME/memory"
+rg -n "specific phrase" "$AGENT_HOME/life" "$AGENT_HOME/memory"
+```
+
+The files are the source of truth. Search is only a way to locate the right
+file, then verify against the stored fact or note.
+
+## Planning
+
+Keep shared plans in timestamped files under `$RUDDER_ORG_PLANS_DIR` when that path is available, not in ad-hoc repo or project-root `plans/` folders. These plan files are shared workspace artifacts, not personal memory. Use `rg` to search plan files and prefer the newest dated file when several match. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/skills/para-memory-files/references/schemas.md

@@ -0,0 +1,35 @@
+# Schemas and Memory Decay
+
+## Atomic Fact Schema (items.yaml)
+
+```yaml
+- id: entity-001
+  fact: "The actual fact"
+  category: relationship | milestone | status | preference
+  timestamp: "YYYY-MM-DD"
+  source: "YYYY-MM-DD"
+  status: active # active | superseded
+  superseded_by: null # e.g. entity-002
+  related_entities:
+    - companies/acme
+    - people/jeff
+  last_accessed: "YYYY-MM-DD"
+  access_count: 0
+```
+
+## Memory Decay
+
+Facts decay in retrieval priority over time so stale info does not crowd out recent context.
+
+**Access tracking:** When a fact is used in conversation, bump `access_count` and set `last_accessed` to today. During heartbeat extraction, scan the session for referenced entity facts and update their access metadata.
+
+**Recency tiers (for summary.md rewriting):**
+
+- **Hot** (accessed in last 7 days) -- include prominently in summary.md.
+- **Warm** (8-30 days ago) -- include at lower priority.
+- **Cold** (30+ days or never accessed) -- omit from summary.md. Still in items.yaml, retrievable on demand.
+- High `access_count` resists decay -- frequently used facts stay warm longer.
+
+**Weekly synthesis:** Sort by recency tier, then by access_count within tier. Cold facts drop out of the summary but remain in items.yaml. Accessing a cold fact reheats it.
+
+No deletion. Decay only affects retrieval priority via summary.md curation. The full record always lives in items.yaml.

package/skills/rudder/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: rudder
+description: Interact with the Rudder control plane through the `rudder` CLI to manage tasks, approvals, comments, issue documents, and organization skills during heartbeats. Use for Rudder coordination only, not for the domain work itself.
+---
+
+# Rudder Skill
+
+You run in **heartbeats**: short execution windows triggered by Rudder. Each heartbeat, wake up, inspect assigned work, do one useful chunk, communicate clearly, and exit.
+
+This skill is now **CLI-first**.
+
+- Use `rudder ... --json` for control-plane work.
+- Use `rudder agent capabilities --json` when you need machine-readable discovery of supported commands.
+- Use `references/cli-reference.md` for the stable command catalog.
+- Treat `references/api-reference.md` as **internal/debug/compatibility** documentation, not the normal agent interface.
+- If a remote runtime wake text explicitly says **HTTP compatibility mode**, follow that wake text for that run. Otherwise use the CLI.
+
+## Authentication
+
+Rudder injects the runtime context for you. Common env vars:
+
+- `RUDDER_AGENT_ID`
+- `RUDDER_ORG_ID`
+- `RUDDER_API_URL`
+- `RUDDER_API_KEY`
+- `RUDDER_RUN_ID`
+
+Optional wake-context vars may also appear:
+
+- `RUDDER_TASK_ID`
+- `RUDDER_WAKE_REASON`
+- `RUDDER_WAKE_COMMENT_ID`
+- `RUDDER_APPROVAL_ID`
+- `RUDDER_APPROVAL_STATUS`
+- `RUDDER_LINKED_ISSUE_IDS`
+
+Rules:
+
+- Never ask for `RUDDER_API_KEY` inside a normal heartbeat.
+- Never hard-code the API URL.
+- For local adapters and packaged desktop, `rudder` is expected to already be on `PATH`.
+- In manual local CLI mode outside heartbeats, use `rudder agent local-cli <agent-ref> --org-id <org-id>` to mint an agent key, optionally install bundled Rudder skills locally, and print the required `RUDDER_*` exports.
+
+## Shared Workspace
+
+Each organization has one system-managed shared workspace root at:
+
+- `~/.rudder/instances/<instance>/organizations/<org-id>/workspaces`
+
+Important files and conventions:
+
+- Structured shared references live in the org `Resources` catalog. Agents receive those catalog entries in run context automatically.
+- Use Workspaces for disk-backed shared files, plans, and skill packages.
+- When you need to place shared output on disk, prefer the managed workspace paths Rudder injected for this run such as `$RUDDER_ORG_PLANS_DIR`, `$RUDDER_ORG_SKILLS_DIR`, and the active `$RUDDER_WORKSPACE_CWD` or `$RUDDER_ORG_WORKSPACE_ROOT`. Do not invent new top-level `projects/` folders.
+- If a `resources.md` file exists, treat it like a normal workspace file rather than a reserved Rudder surface.
+- Agent-specific files live under `workspaces/agents/<workspace-key>/...`.
+- New projects do not create or configure their own workspace roots.
+
+## Heartbeat Procedure
+
+Follow this order unless the wake context clearly requires a different first step.
+
+**Step 1 — Identity.** If identity is not already known, run:
+
+```bash
+rudder agent me --json
+```
+
+Use the result for your id, org, role, budget, and `chainOfCommand`.
+
+**Step 2 — Approval follow-up.** If `RUDDER_APPROVAL_ID` is set, review it first:
+
+```bash
+rudder approval get "$RUDDER_APPROVAL_ID" --json
+rudder approval issues "$RUDDER_APPROVAL_ID" --json
+```
+
+For each linked issue:
+
+- mark it done if the approval fully resolves the work
+- or add a comment explaining what remains open and what happens next
+
+**Step 3 — Get assignments.** Prefer the compact inbox:
+
+```bash
+rudder agent inbox --json
+```
+
+Work `in_progress` first, then `todo`. Skip `blocked` unless you can actually unblock it.
+
+If `RUDDER_TASK_ID` is set and the task is assigned to you, prioritize it first.
+
+**Step 4 — Mention-triggered wakes.** If `RUDDER_WAKE_COMMENT_ID` is set, read the relevant issue context before doing anything else on that task:
+
+```bash
+rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
+```
+
+If the comment explicitly asks you to take ownership, you may self-assign by checkout. Otherwise respond only if useful and continue with your assigned work.
+
+**Step 5 — Checkout before work.** Never start work without checkout.
+
+```bash
+rudder issue checkout "<issue-id-or-identifier>" --json
+```
+
+Rules:
+
+- `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`
+- mutating CLI commands automatically attach `RUDDER_RUN_ID` when present
+- a `409` means another agent owns the task; do not retry it
+
+**Step 6 — Understand context.** Prefer the compact heartbeat context instead of replaying everything:
+
+```bash
+rudder issue context "<issue-id-or-identifier>" --json
+```
+
+Comment reading rules:
+
+- if `RUDDER_WAKE_COMMENT_ID` is set, fetch context with that wake comment first
+- if you already know the thread and only need updates, use:
+
+```bash
+rudder issue comments list "<issue-id-or-identifier>" --after "<last-comment-id>" --order asc --json
+```
+
+- use the full comment list only when cold-starting or when incremental context is not enough
+
+**Step 7 — Do the work.** Use your normal tools for the domain task itself.
+
+**Step 8 — Communicate outcome.**
+
+Before exiting an active `todo` or `in_progress` issue run, leave exactly one clear close-out signal. Use a progress comment if work remains, `issue done` if complete, `issue block` if blocked, or an explicit handoff comment when ownership changes. Rudder may wake you again with `RUDDER_WAKE_REASON=issue_passive_followup` when a successful run exits without that signal.
+
+- progress-only update:
+
+```bash
+rudder issue comment "<issue-id-or-identifier>" --body "<markdown>" --json
+```
+
+- completion:
+
+```bash
+rudder issue done "<issue-id-or-identifier>" --comment "<markdown>" --json
+```
+
+- blocker:
+
+```bash
+rudder issue block "<issue-id-or-identifier>" --comment "<markdown>" --json
+```
+
+- generic patch when workflow commands are not enough:
+
+```bash
+rudder issue update "<issue-id-or-identifier>" ... --json
+```
+
+**Step 9 — Delegate if needed.** Create subtasks with the generic create surface only when the workflow really needs a new task:
+
+```bash
+rudder issue create --org-id "$RUDDER_ORG_ID" ... --json
+```
+
+Always set `parentId`. Set `goalId` unless you are intentionally creating top-level management work.
+
+## Organization Skills Workflow
+
+When a board user, CEO, or manager asks you to find, import, inspect, or assign organization skills:
+
+1. Read `references/organization-skills.md`
+2. Use the CLI surfaces in this order:
+
+```bash
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+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 agent skills sync "<agent-id>" --desired-skills "<csv>" --json
+```
+
+Do not fall back to raw `curl` for this workflow in local adapters or packaged desktop.
+
+## Planning And Issue Documents
+
+If asked to make or revise a plan, update the issue document with key `plan` instead of appending plan text to the issue description.
+
+Typical flow:
+
+```bash
+rudder issue documents get "<issue-id-or-identifier>" plan --json
+rudder issue documents revisions "<issue-id-or-identifier>" plan --json
+rudder issue documents put "<issue-id-or-identifier>" plan --title "Plan" --format markdown --body "<markdown>" --json
+rudder issue comment "<issue-id-or-identifier>" --body "<mention that the plan document was updated>" --json
+```
+
+Planning rules:
+
+- do not mark the issue done when the request was only to create or revise a plan
+- reassign back to the requester if that is the expected workflow
+- when you reference the plan in comments, link directly to `#document-plan`
+
+## Critical Rules
+
+- Always checkout before doing task work.
+- Never retry a `409` from checkout.
+- Never look for unassigned work.
+- Self-assign only on explicit @-mention handoff.
+- Always communicate before exit on active work, except blocked issues with no new context.
+- Treat `issue_passive_followup` as close-out governance, not a fresh assignment: inspect current state, then comment, finish, block, or hand off explicitly.
+- If blocked, explicitly set the issue to `blocked` with a blocker comment before exit.
+- Never cancel cross-team tasks. Reassign upward with explanation.
+- Use `chainOfCommand` for escalation.
+- Above 80% spend, focus on critical work only.
+- Use `rudder-create-agent` for hiring or new-agent creation workflows.
+- If you make a git commit you MUST add `Co-Authored-By: Rudder <noreply@github.com/Undertone0809/rudder>` to the end of each commit message.
+
+## Comment Style (Required)
+
+Use concise markdown with:
+
+- a short status line
+- bullets for what changed or what is blocked
+- links to related issues, approvals, projects, agents, or documents when available
+
+**Ticket references are links.** Never leave bare ticket ids like `PAP-224` in comments or descriptions when you can link them:
+
+- `[PAP-224](/PAP/issues/PAP-224)`
+- `[ZED-24](/ZED/issues/ZED-24)`
+
+**Company-prefixed URLs are required.** Derive the prefix from the issue identifier and use it in all internal links:
+
+- issues: `/<prefix>/issues/<issue-identifier>`
+- issue comments: `/<prefix>/issues/<issue-identifier>#comment-<comment-id>`
+- issue documents: `/<prefix>/issues/<issue-identifier>#document-<document-key>`
+- agents: `/<prefix>/agents/<agent-url-key>`
+- projects: `/<prefix>/projects/<project-url-key>`
+- approvals: `/<prefix>/messenger/approvals/<approval-id>`
+- runs: `/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>`
+
+Example:
+
+```md
+## Update
+
+Plan updated and ready for review.
+
+- Plan: [PAP-142 plan](/PAP/issues/PAP-142#document-plan)
+- Depends on: [PAP-224](/PAP/issues/PAP-224)
+- Approval: [ca6ba09d](/PAP/messenger/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
+```
+
+## Discovery
+
+When you are unsure which Rudder commands are supported in this runtime, use:
+
+```bash
+rudder agent capabilities --json
+```
+
+For the human-readable command catalog, read `references/cli-reference.md`.
+For API debugging and compatibility investigations only, read `references/api-reference.md`.