Skip to content

feat(agents): auto-install coding agent documentation stubs - #454

Merged
Rod-Christensen merged 4 commits into
developfrom
feat/AGENT.md
Mar 27, 2026
Merged

Rod-Christensen merged 4 commits into
developfrom
feat/AGENT.md

Conversation

@Rod-Christensen

@Rod-Christensen Rod-Christensen commented Mar 27, 2026 •

Copy link
Copy Markdown
Collaborator
  • Investigate path traversal vulnerability in services.ts
  • Add sanitizeServiceName(): replaces [^a-zA-Z0-9._-] with _, replaces each leading dot individually with _ using a callback to preserve uniqueness
  • Add isUnderDirectory(): defense-in-depth Uri path check to confirm resolved path stays within schemaDir
  • Build expectedFiles dynamically during write loop so skipped (unsafe) names don't prevent cleanup of unrelated files
  • Run code review and CodeQL security scan — no issues

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

Summary by CodeRabbit

Release Notes

  • New Features

    • Added agent integration settings with auto-detection for AI tools (Cursor, Windsurf, Claude Code, Copilot).
    • Added install and uninstall commands for managing agent stubs.
    • New toggles for optional documentation integrations (CLAUDE.md, AGENTS.md).
    • Automatic agent installation in workspaces on extension activation.
  • Documentation

    • Added comprehensive RocketRide guides: quickstart, pipeline rules, component reference, Python/TypeScript API documentation, and troubleshooting.

Add a system that makes RocketRide documentation discoverable by coding
agents (Cursor, Claude Code, Windsurf, Copilot) via their native
instruction file formats.

Agent stub templates (docs/stubs/):
- cursor.mdc, claude-code.md, windsurf.md, copilot-instructions.md
- CLAUDE.md and AGENTS.md for generic/unrecognized agents
- All use <!-- ROCKETRIDE:BEGIN/END --> markers for idempotent updates

Extension installer framework (apps/vscode/src/agents/):
- BaseAgentInstaller: marker-based install/uninstall with write-safety
  (line-ending normalized content comparison to avoid dirty repos)
- 6 concrete installers (Cursor, Claude Code, Windsurf, Copilot,
  CLAUDE.md, AGENTS.md)
- AgentManager orchestrator with two-pass startup logic:
  Pass 1: auto-detect IDE environment (appName, extensions, ~/.claude/)
  Pass 2: install any manually checked integrations not already covered
- No settings are auto-flipped; user controls individual toggles
- installFromSettings() called on settings save for newly checked items

Service catalog sync (apps/vscode/src/agents/services.ts):
- On server connect, writes individual component schemas to
  .rocketride/schema/<component>.json
- Writes slim services-catalog.json (name, classType, description,
  lanes, invoke)
- Syncs on every servicesUpdated event: adds, updates, removes obsolete

Build pipeline (apps/vscode/scripts/tasks.js):
- Copies docs/agents/*.md and docs/stubs/* into build/vscode/docs/
- Added docs/** to pkg.files for .vsix packaging

Settings & UI:
- New setting: integrations.autoAgentIntegration (default: true)
- New settings: integrations.claudeMd, integrations.agentsMd
- Automatic Agent Integration checkbox on Welcome and Settings pages
- Generic CLAUDE.md and AGENTS.md added to Integration Settings list

Documentation fixes (docs/agents/):
- Removed incorrect { pipeline: { ... } } wrapper from all JSON
  examples across 5 doc files — pipelines use flat format with
  components, source, project_id at top level

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added docs Documentation builder Node builder tooling and ./builder workflows labels Mar 27, 2026
@coderabbitai

coderabbitai Bot commented Mar 27, 2026 •

Copy link
Copy Markdown
Contributor

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a2ffe797-483b-4175-9589-efabb8b31065

📥 Commits

Reviewing files that changed from the base of the PR and between 2b27522 and e7be786.

📒 Files selected for processing (6)
  • apps/vscode/src/agents/services.ts
  • docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md
  • docs/agents/ROCKETRIDE_PIPELINE_RULES.md
  • docs/agents/ROCKETRIDE_QUICKSTART.md
  • docs/agents/ROCKETRIDE_python_API.md
  • docs/agents/ROCKETRIDE_typescript_API.md

📝 Walkthrough

Walkthrough

Adds agent integration tooling to the VS Code extension: new settings and commands, an AgentManager implementing install/uninstall and docs sync, multiple installers for agent stubs, service-catalog/schema generation under .rocketride/, UI wiring for integration toggles, and many documentation and stub files.

Changes

Cohort / File(s) Summary
Extension manifest & build
apps/vscode/package.json, apps/vscode/scripts/tasks.js
Added three new settings (rocketride.integrations.autoAgentIntegration, ...claudeMd, ...agentsMd), two commands (rocketride.agents.install, rocketride.agents.uninstall), and updated staging to include docs/** and conditional copying of docs/agents/ and docs/stubs/ into the packaged extension.
Agent manager & core logic
apps/vscode/src/agents/agent-manager.ts, apps/vscode/src/agents/base-installer.ts, apps/vscode/src/agents/services.ts
Introduced AgentManager (detect/install/uninstall flows, docs sync, .gitignore maintenance, two-pass install), BaseAgentInstaller (marker-based merge/install/uninstall), and syncServiceCatalog (writes per-component schemas and services-catalog.json to .rocketride/).
Concrete installers
apps/vscode/src/agents/*-installer.ts
apps/vscode/src/agents/cursor-installer.ts, apps/vscode/src/agents/windsurf-installer.ts, apps/vscode/src/agents/claude-code-installer.ts, apps/vscode/src/agents/claude-md-installer.ts, apps/vscode/src/agents/copilot-installer.ts, apps/vscode/src/agents/agents-md-installer.ts
Added six small installers extending BaseAgentInstaller, each declaring name, stubSource, and stubTarget for agent-specific stub installation.
Extension integration & commands
apps/vscode/src/extension.ts
Launched non-blocking auto-install on activation (workspace present), registered rocketride.agents.install and rocketride.agents.uninstall commands, and wired servicesUpdated events to call syncServiceCatalog.
Settings & UI
apps/vscode/src/providers/PageSettingsProvider.ts, apps/vscode/src/providers/PageWelcomeProvider.ts, apps/vscode/src/providers/views/PageSettings/..., apps/vscode/src/providers/views/PageWelcome/PageWelcome.tsx
Extended settings payloads and webviews with autoAgentIntegration, integrationClaudeMd, integrationAgentsMd; persist settings and trigger installFromSettings; UI additions for automatic agent integration and per-doc toggles; minor type/formatting edits.
Documentation & stubs
docs/agents/*, docs/stubs/*
Added comprehensive RocketRide docs (ROCKETRIDE_README, QUICKSTART, PIPELINE_RULES, COMPONENT_REFERENCE, python_API, typescript_API, COMMON_MISTAKES) and multiple stub files under docs/stubs/ (CLAUDE.md, AGENTS.md, claude-code.md, copilot-instructions.md, cursor.mdc, windsurf.md).

Sequence Diagram(s)

sequenceDiagram
    participant User as User
    participant VSCode as VS Code
    participant Extension as Extension
    participant AgentMgr as AgentManager
    participant Installers as Installers
    participant Workspace as Workspace

    User->>VSCode: Open workspace
    VSCode->>Extension: activate()
    Extension->>AgentMgr: autoInstall(extensionPath, workspaceRoot)
    AgentMgr->>AgentMgr: installDocs & ensure .gitignore
    AgentMgr->>Workspace: create/modify .rocketride/docs, .gitignore

    alt autoAgentIntegration enabled
        AgentMgr->>AgentMgr: detectEnvironment()
        AgentMgr->>Installers: run detected installers
        Installers->>Workspace: write agent stubs (marker blocks)
    end

    AgentMgr->>AgentMgr: evaluate per-settings integrations
    loop for each enabled integration not yet installed
        AgentMgr->>Installers: installFromSettings()
        Installers->>Workspace: write stub files
    end

    User->>Extension: servicesUpdated(payload)
    Extension->>AgentMgr: syncServiceCatalog(workspaceRoot, services)
    AgentMgr->>Workspace: write .rocketride/schema/*.json and services-catalog.json
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

  • rocketride-org/rocketride-server#323: Touches VS Code packaging/staging (apps/vscode/package.json, apps/vscode/scripts/tasks.js) and may overlap with docs staging changes.
  • rocketride-org/rocketride-server#454: Appears to implement overlapping agent installer framework, stubs, settings, and service-catalog sync.

Suggested labels

module:vscode

Suggested reviewers

  • jmaionchi
  • ryan-t-christensen
  • stepmikhaylov

Poem

🐰 I nibble docs and stitch the stubs,
carrot-bright .rocketride hubs.
Cursor, Claude, Windsurf in a row—
tiny files that help code grow.
Hooray, I hop—install, then go!

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and accurately summarizes the main feature addition: automatic installation of coding agent documentation stubs. It is concise, specific, and directly reflects the core purpose of the changeset.
Docstring Coverage ✅ Passed Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/AGENT.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 11

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/vscode/src/agents/agent-manager.ts`:
- Around line 91-97: The code currently calls runInstaller(...) inside
installAll (and similar loops) but runInstaller swallows exceptions so failed
installers still get added to the installed Set and are logged as installed;
update installAll (and the other installer loops at the referenced locations) to
propagate failures by letting runInstaller throw or by returning a success
boolean, and only add an installer to the installed Set and include it in the
success log if runInstaller completed successfully—i.e., change runInstaller to
surface errors (or have it return true/false), wrap the call in try/catch where
the catch rethrows or returns false, and only execute
installed.add(installer.name) and logger.output(...) when the installer actually
succeeded.
- Around line 204-222: uninstallAll currently only removes installer stubs and
DOCS_DIR but not generated schemas or the services catalog written by
syncServiceCatalog; update uninstallAll to also delete the .rocketride/schema
directory and the .rocketride/services-catalog.json file (use
vscode.Uri.joinPath(workspaceRoot, 'schema') and
vscode.Uri.joinPath(workspaceRoot, 'services-catalog.json') or the existing
SCHEMA_DIR/SERVICES_CATALOG constants if present), call
vscode.workspace.fs.delete(..., { recursive: true }) inside try/catch blocks
like the DOCS_DIR removal, and add logger.output messages similar to the
existing ones to indicate removal or ignore missing files.
- Around line 76-86: The autoInstall method currently calls installDocs and
ensureGitignore unconditionally, which mutates the workspace even when the user
has disabled integrations; modify autoInstall to honor the workspace setting and
per-integration opt-outs by checking
workspaceConfig.get('integrations.autoAgentIntegration') and each
integration-specific flag before performing any writes: only call
this.installDocs(extensionPath, workspaceRoot) and
this.ensureGitignore(workspaceRoot) when autoDetect is true (or when a given
integration's enabled flag is true), and keep the existing installed Set logic
intact to avoid double-installation; update references in autoInstall to guard
those calls behind the configuration checks.

In `@apps/vscode/src/agents/services.ts`:
- Around line 84-94: When removing obsolete files in the try block, emit a log
for each deletion so deletions are observable; inside the loop where you check
fileType === vscode.FileType.File && !expectedFiles.has(fileName) and
before/after calling vscode.workspace.fs.delete(vscode.Uri.joinPath(schemaDir,
fileName)), call the project's logger (e.g., logger.info or console.info if no
shared logger exists) with the fileName and the full Uri (or schemaDir) to show
what was removed; keep the catch behavior but consider logging a debug message
on directory-listing failure as well.

In `@apps/vscode/src/providers/PageSettingsProvider.ts`:
- Around line 332-334: The agent installation error is only logged to console
and runs asynchronously after saveAllSettings reports success; update
saveAllSettings (or the caller that invokes agentManager.installFromSettings) to
await or otherwise handle the returned Promise from
agentManager.installFromSettings(this.extensionUri.fsPath, workspaceFolder.uri)
and surface failures to the user via VS Code notifications (e.g.,
vscode.window.showErrorMessage or showWarningMessage) so users see an in-product
error when installFromSettings rejects instead of only console.error.

In `@docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md`:
- Around line 116-119: The docs incorrectly assert you can define "Multiple
Pipelines" in a single file; remove or reword that claim and instead document
the actual top-level file shape ({ project_id, source, components }) and that
each file represents a single pipeline, or add explicit guidance and an example
showing how to structure multiple pipeline objects if you intend to support
them; update the text around the "Multiple Pipelines" section to either delete
the multi-pipeline-in-one-file sentence or replace it with accurate instructions
referencing the top-level { project_id, source, components } object and the
alternative of separate `.pipe` files sharing a vector DB collection by name.
- Around line 576-585: The ingestion pipeline example incorrectly routes
question embeddings into qdrant (search flow); update the Pipeline 1 node
sequence so embeddings are computed from document lane before storage: replace
the segment that goes "...question → questions → embedding_openai → documents →
qdrant" with a document-preprocessing flow that keeps content on the documents
lane (e.g., "...text → preprocessor_langchain → documents → embedding_openai →
documents → qdrant (collection: 'scenes')"), ensuring nodes referenced (dropper,
video, frame_grabber, image, accessibility_describe, text,
preprocessor_langchain, documents, embedding_openai, qdrant) reflect ingestion
rather than query/search.

In `@docs/agents/ROCKETRIDE_PIPELINE_RULES.md`:
- Around line 363-365: The fenced code blocks like the one containing "source →
processor → output" (and the other similar diagram blocks at the ranges
referenced) lack language specifiers and trigger markdownlint; update each
triple-backtick fence to include a language token (use "text" or "plaintext" for
plain diagrams or "mermaid" if you want rendered diagrams) so all occurrences
(including the blocks around lines 384-388, 394-398, 453-455, 462-464, 516-518,
526-528, 535-537, 545-547, 554-556, 563-565, 572-576, 583-587) consistently
include the language and satisfy linting.
- Around line 655-672: The minimal pipeline example wires response_1 from
source_1 using lane "text", but webhook sources are treated as providing "tags"
elsewhere; update the response_1 "input" to use { "lane": "tags", "from":
"source_1" } (leave components, ids, and providers unchanged) so the graph
matches the linear example and produces a valid wiring between the webhook
provider and the response_text component.

In `@docs/agents/ROCKETRIDE_QUICKSTART.md`:
- Around line 294-303: The directory-tree code block is missing a language
identifier; update the fenced code block that contains the
"my-rocketride-project/" tree to use a plaintext language tag (e.g., change ```
to ```text) so the block is treated as plain text by linters and renderers;
ensure the opening fence is modified only (keep the content and closing ```
unchanged).

In `@docs/agents/ROCKETRIDE_typescript_API.md`:
- Around line 758-788: The function streamSensorData declares the variable
result twice (once from client.use(...) and again from pipe.close()), causing a
redeclaration error; rename the second result (e.g., pipeResult or closeResult)
returned by await pipe.close() and update its references, leaving the first
result (from client.use()) unchanged so that both values are accessible without
shadowing (refer to streamSensorData, client.use, token, and pipe.close).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 69ced0b2-d6f3-40bb-bc53-93c4dd8b3258

📥 Commits

Reviewing files that changed from the base of the PR and between 3a2b38f and 41796ea.

📒 Files selected for processing (30)
  • apps/vscode/package.json
  • apps/vscode/scripts/tasks.js
  • apps/vscode/src/agents/agent-manager.ts
  • apps/vscode/src/agents/agents-md-installer.ts
  • apps/vscode/src/agents/base-installer.ts
  • apps/vscode/src/agents/claude-code-installer.ts
  • apps/vscode/src/agents/claude-md-installer.ts
  • apps/vscode/src/agents/copilot-installer.ts
  • apps/vscode/src/agents/cursor-installer.ts
  • apps/vscode/src/agents/services.ts
  • apps/vscode/src/agents/windsurf-installer.ts
  • apps/vscode/src/extension.ts
  • apps/vscode/src/providers/PageSettingsProvider.ts
  • apps/vscode/src/providers/PageWelcomeProvider.ts
  • apps/vscode/src/providers/views/PageSettings/IntegrationSettings.tsx
  • apps/vscode/src/providers/views/PageSettings/PageSettings.tsx
  • apps/vscode/src/providers/views/PageWelcome/PageWelcome.tsx
  • docs/agents/ROCKETRIDE_COMMON_MISTAKES.md
  • docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md
  • docs/agents/ROCKETRIDE_PIPELINE_RULES.md
  • docs/agents/ROCKETRIDE_QUICKSTART.md
  • docs/agents/ROCKETRIDE_README.md
  • docs/agents/ROCKETRIDE_python_API.md
  • docs/agents/ROCKETRIDE_typescript_API.md
  • docs/stubs/AGENTS.md
  • docs/stubs/CLAUDE.md
  • docs/stubs/claude-code.md
  • docs/stubs/copilot-instructions.md
  • docs/stubs/cursor.mdc
  • docs/stubs/windsurf.md

Comment thread apps/vscode/src/agents/agent-manager.ts Resolved
Comment thread apps/vscode/src/agents/agent-manager.ts Resolved
Comment thread apps/vscode/src/agents/agent-manager.ts Resolved
Comment thread apps/vscode/src/agents/services.ts Resolved
Comment thread docs/agents/ROCKETRIDE_QUICKSTART.md Resolved
- agent-manager: runInstaller returns boolean; callers only add to
  installed Set on success
- agent-manager: uninstallAll removes .rocketride/schema/ and
  services-catalog.json
- agent-manager: defer installDocs/ensureGitignore until first actual
  install via lazy prepareWorkspace()
- services: log obsolete schema file deletions via getLogger()
- PageSettingsProvider: await installFromSettings, surface errors via
  vscode.window.showWarningMessage instead of console.error
- docs: fix "Multiple Pipelines" wording (one pipeline per file)
- docs: fix ingestion pipeline lane flow, add [lane] notation
- docs: add language specifiers to all bare fenced code blocks
- docs: fix duplicate result variable in TypeScript API example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
stepmikhaylov
stepmikhaylov previously approved these changes Mar 27, 2026

@stepmikhaylov stepmikhaylov left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Tested VSCode, Cursor and Windsurf on Windows and macOS

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

♻️ Duplicate comments (2)
apps/vscode/src/agents/agent-manager.ts (1)

180-182: ⚠️ Potential issue | 🟠 Major

Fail installAll() and installFromSettings() when any installer fails.

runInstaller() converts each failure into false, but these callers ignore that result. Both methods therefore resolve successfully after partial failure, so the install command can report success and PageSettingsProvider never reaches its warning path. Aggregate the failed installers and throw (or return them) when any selected install does not succeed.

Also applies to: 196-202, 344-352

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/vscode/src/agents/agent-manager.ts` around lines 180 - 182, installAll()
and installFromSettings() currently ignore runInstaller()'s boolean result so
partial failures appear as success; update both methods to collect failures from
each call to runInstaller(installer, extensionPath, workspaceRoot) (and
selectedInstallers loop in installFromSettings()) and if any installer returns
false throw an Error (or return a rejected Promise) listing the failed installer
identifiers (e.g., installer.id or name) so callers can detect and handle the
failure; ensure the same aggregation logic is applied to the other similar loops
referenced (lines ~196-202 and ~344-352).
docs/agents/ROCKETRIDE_PIPELINE_RULES.md (1)

655-672: ⚠️ Potential issue | 🟠 Major

Insert a tags → text step in the minimal webhook example.

This quick-reference sample wires a webhook source straight into response_text. Earlier in the same guide, the linear example uses webhook -> parse -> response_text, and the lane table treats uploads as tags, not text. As written, the "Minimal Pipeline" is not a valid copy/paste starter.

💡 Minimal fix
 {
 	"project_id": "{guid}", // Replace with your unique GUID
 	"source": "source_1",
 	"components": [
 		{
 			"id": "source_1",
 			"provider": "webhook",
 			"config": {}
 		},
+		{
+			"id": "parse_1",
+			"provider": "parse",
+			"config": {},
+			"input": [{ "lane": "tags", "from": "source_1" }]
+		},
 		{
 			"id": "response_1",
 			"provider": "response_text",
 			"config": {},
-			"input": [{ "lane": "text", "from": "source_1" }]
+			"input": [{ "lane": "text", "from": "parse_1" }]
 		}
 	]
 }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/agents/ROCKETRIDE_PIPELINE_RULES.md` around lines 655 - 672, The minimal
pipeline wires the webhook source directly to response_text; insert a tags→text
step between them by adding a new component (e.g., id "tags_1", provider "tags")
that emits a "text" lane from the webhook; then change the existing response
component ("response_1", provider "response_text") to take its input from that
new "tags_1" component instead of "source_1". Ensure the new component's "input"
references the webhook component id ("source_1") and that "response_1" input
references the new tags component id.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/vscode/src/agents/agent-manager.ts`:
- Around line 193-203: installFromSettings only installs enabled integrations
and never removes ones that were turned off; update the loop in
installFromSettings (where it iterates this.installers and uses
INTEGRATION_CONFIG_KEYS) to check the current workspaceConfig boolean for each
configKey and, if false but a previously managed stub exists, invoke the
corresponding uninstall path (e.g., call installer.uninstall or a new
this.runUninstaller(installer, extensionPath, workspaceRoot)) to remove the
managed files; ensure you detect previously installed state (filesystem markers
or a manifest) so you only remove stubs this extension created, and keep
existing runInstaller(extensionPath, workspaceRoot) behavior for true flags.

In `@docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md`:
- Around line 410-421: The docs conflict: the "UI Layout (Optional)" section
currently instructs programmatic pipeline authors to include the `ui` field,
which contradicts the rule in ROCKETRIDE_PIPELINE_RULES.md that `ui` is optional
and should be omitted for programmatic pipeline creation; update the UI Layout
guidance to match the pipeline rules by explicitly stating that `ui` is optional
and should generally be omitted when creating pipelines programmatically
(mentioning the `ui` field, `position`, `measured`, `nodeType`, and
`formDataValid` as UI-only metadata that the graphic designer may add).

In `@docs/agents/ROCKETRIDE_PIPELINE_RULES.md`:
- Around line 203-213: The numbered list items under the "Type Compatibility",
"Multiple Inputs", and "Multiple Outputs" lines use mixed markers (1., 2., 3.)
which triggers markdownlint MD029; change all list item markers to the repo's
ordered-list style (use "1." for every item) so the block becomes 1. **Type
Compatibility**:..., 1. **Multiple Inputs**:..., 1. **Multiple Outputs**:...
while leaving the JSON example unchanged.

In `@docs/agents/ROCKETRIDE_QUICKSTART.md`:
- Around line 41-47: The processor node in the pipeline JSON (id "processor",
provider "transform") is missing its input edge so it never receives data;
update both pipeline snippets to add an "input" array on the processor node that
references the preceding node(s) (e.g., the source node id such as "input" or
the previous component id) per the ROCKETRIDE_PIPELINE_RULES convention so
client.send() data flows into the transform node; apply the same fix for the
other occurrence around lines 148-154.

In `@docs/agents/ROCKETRIDE_typescript_API.md`:
- Around line 210-223: The example pipeline is invalid because the 'process' and
'output' components are not connected to 'input' and the provider 'response' is
generic; update the pipeline object (the const pipeline and its components
array) to explicitly wire components (e.g., set a routing/next field so 'input'
-> 'process' -> 'output') and replace the generic provider 'response' with a
lane-specific response provider such as 'response_text' or 'response_answers' so
the example will produce a valid pipeline when used with client.use and
client.disconnect.
- Around line 112-132: The example shows building a pipeline object passed to
client.use({ pipeline }) but omits the required source field, making it invalid;
update the snippet so the pipeline is a runnable minimal pipeline (add a simple
source component and wire it into the existing component) or change the example
to only show the config fragment and label it as such; specifically modify the
pipeline object referenced by pipeline and the call to client.use to either
include a minimal source/component graph that includes the required source field
and component ids (so data-processor has an upstream source) or replace the
pipeline variable with a named config fragment and update the surrounding text
to call out that only config is demonstrated.

---

Duplicate comments:
In `@apps/vscode/src/agents/agent-manager.ts`:
- Around line 180-182: installAll() and installFromSettings() currently ignore
runInstaller()'s boolean result so partial failures appear as success; update
both methods to collect failures from each call to runInstaller(installer,
extensionPath, workspaceRoot) (and selectedInstallers loop in
installFromSettings()) and if any installer returns false throw an Error (or
return a rejected Promise) listing the failed installer identifiers (e.g.,
installer.id or name) so callers can detect and handle the failure; ensure the
same aggregation logic is applied to the other similar loops referenced (lines
~196-202 and ~344-352).

In `@docs/agents/ROCKETRIDE_PIPELINE_RULES.md`:
- Around line 655-672: The minimal pipeline wires the webhook source directly to
response_text; insert a tags→text step between them by adding a new component
(e.g., id "tags_1", provider "tags") that emits a "text" lane from the webhook;
then change the existing response component ("response_1", provider
"response_text") to take its input from that new "tags_1" component instead of
"source_1". Ensure the new component's "input" references the webhook component
id ("source_1") and that "response_1" input references the new tags component
id.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: c4e87e97-43cf-4502-a058-c45db2e255b4

📥 Commits

Reviewing files that changed from the base of the PR and between 41796ea and 2b27522.

📒 Files selected for processing (7)
  • apps/vscode/src/agents/agent-manager.ts
  • apps/vscode/src/agents/services.ts
  • apps/vscode/src/providers/PageSettingsProvider.ts
  • docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md
  • docs/agents/ROCKETRIDE_PIPELINE_RULES.md
  • docs/agents/ROCKETRIDE_QUICKSTART.md
  • docs/agents/ROCKETRIDE_typescript_API.md

Comment thread apps/vscode/src/agents/agent-manager.ts Resolved
Comment thread docs/agents/ROCKETRIDE_QUICKSTART.md Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds automatic workspace installation of RocketRide agent documentation (stubs + bundled docs) and syncs the server service catalog into .rocketride/ to support agent-assisted development and up-to-date component schemas.

Changes:

  • Added bundled RocketRide agent docs and per-agent stub templates (Cursor/Claude Code/Windsurf/Copilot + generic CLAUDE.md/AGENTS.md) with idempotent markers.
  • Implemented a VS Code extension agent integration framework (auto-detect + settings-driven installs), plus install/uninstall commands.
  • Added service catalog/schema sync on server connect and updated VSIX build staging to include docs/stubs.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
docs/stubs/windsurf.md Windsurf rule stub template with RocketRide doc pointers and markers
docs/stubs/cursor.mdc Cursor rule stub template with RocketRide doc pointers and markers
docs/stubs/copilot-instructions.md Copilot instructions stub for .github/copilot-instructions.md
docs/stubs/claude-code.md Claude Code rules stub template
docs/stubs/CLAUDE.md Generic CLAUDE.md stub template
docs/stubs/AGENTS.md Generic AGENTS.md stub template
docs/agents/ROCKETRIDE_typescript_API.md TypeScript SDK documentation added for bundling into .rocketride/docs
docs/agents/ROCKETRIDE_python_API.md Python SDK documentation added for bundling into .rocketride/docs
docs/agents/ROCKETRIDE_README.md Core RocketRide overview doc for agent consumption
docs/agents/ROCKETRIDE_QUICKSTART.md Quickstart examples for Python/TS and pipeline basics
docs/agents/ROCKETRIDE_PIPELINE_RULES.md Detailed pipeline structure/rules reference
docs/agents/ROCKETRIDE_COMPONENT_REFERENCE.md Component catalog/schema usage guidance and conventions
docs/agents/ROCKETRIDE_COMMON_MISTAKES.md Troubleshooting and common pitfalls guide
apps/vscode/src/providers/views/PageWelcome/PageWelcome.tsx Adds “Automatic Agent Integration” checkbox to Welcome UI
apps/vscode/src/providers/views/PageSettings/PageSettings.tsx Adds integration-related settings fields and wiring
apps/vscode/src/providers/views/PageSettings/IntegrationSettings.tsx Adds auto-integration toggle + per-agent integration toggles
apps/vscode/src/providers/PageWelcomeProvider.ts Persists integrations.autoAgentIntegration from Welcome page
apps/vscode/src/providers/PageSettingsProvider.ts Persists integration toggles and triggers install-on-save
apps/vscode/src/extension.ts Runs auto-install on activation; adds install/uninstall commands; syncs service catalog on connect
apps/vscode/src/agents/base-installer.ts Marker-based install/update/uninstall base for stubs
apps/vscode/src/agents/agent-manager.ts Orchestrates docs sync, gitignore updates, auto-detect + settings-based installs
apps/vscode/src/agents/cursor-installer.ts Cursor stub installer config
apps/vscode/src/agents/claude-code-installer.ts Claude Code stub installer config
apps/vscode/src/agents/windsurf-installer.ts Windsurf stub installer config
apps/vscode/src/agents/copilot-installer.ts Copilot stub installer config
apps/vscode/src/agents/claude-md-installer.ts Generic CLAUDE.md stub installer config
apps/vscode/src/agents/agents-md-installer.ts Generic AGENTS.md stub installer config
apps/vscode/src/agents/services.ts Writes .rocketride/schema/*.json + services-catalog.json on services update
apps/vscode/scripts/tasks.js Stages docs/stubs into the extension build and includes them in the VSIX
apps/vscode/package.json Adds new settings keys + new commands for agent docs install/uninstall

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread apps/vscode/src/agents/services.ts Resolved
Comment thread apps/vscode/src/extension.ts Resolved
- COMPONENT_REFERENCE: clarify ui field is recommended with position
  only; other ui fields are designer-managed
- PIPELINE_RULES: use consistent "1." markers for ordered list (MD029)
- QUICKSTART: add missing input edge on processor node (both snippets)
- typescript_API: wire process/output nodes with input arrays, use
  response_text provider, add missing source field to env var example
- python_API: same fixes — wire nodes, use response_text, add source

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@Rod-Christensen
Rod-Christensen merged commit 3840d25 into develop Mar 27, 2026
10 of 11 checks passed
@Rod-Christensen
Rod-Christensen deleted the feat/AGENT.md branch March 27, 2026 18:31
anandray added a commit that referenced this pull request May 20, 2026
Top-level `permissions: { contents: write, packages: write, id-token: write }`
on nightly.yaml granted every job in the workflow the union of all writes
any one job needed, including jobs that only consume read-only inputs. The
Scorecard `TokenPermissionsID` rule flags this as the most severe form of
over-grant because top-level writes propagate to every reuse-called
workflow as the upper bound.

Drop the top-level to `contents: read` and raise per-job only where the
job actually writes:

  - build:               contents: read, packages: write
                         (forwarded to _build.yaml for NuGet/vcpkg writes
                          to ghcr.io via VCPKG_BINARY_SOURCES=...readwrite)

  - cleanup-prereleases: contents: write
                         (git push origin --delete <tag> and gh release
                          delete; the tag deletion requires repo write)

  - prerelease:          contents: write, id-token: write
                         (forwarded to _release.yaml for tag push +
                          gh release create + Sigstore keyless signing)

  - docker:              contents: read, packages: write
                         (forwarded to _docker.yaml for ghcr image push;
                          matches release.yaml's docker job pattern)

  - init:                no override, inherits top-level read
                         (_init.yaml is read-only — extracts versions
                          from package.json via jq and stamps github.sha)

The grants mirror the canonical pattern already in place in release.yaml
(committed in the prior TokenPermissionsID cleanup pass that closed #513
and #515 on _build.yaml and _init.yaml).

Closes Scorecard TokenPermissionsID alerts #566 (topLevel contents:write)
and #567 (topLevel packages:write).

The remaining 10 TokenPermissionsID alerts on this repo (#451, #452, #454,
#455, #489, #490, #604, #635, #649, #650) flag job-level writes that are
required for the job's function (ghcr image push, GitHub release publish,
artifact cleanup, model-sync commits). Those are being dismissed
separately with "won't fix" + per-alert justification — Scorecard
penalizes any write, including the unavoidable kind.
AviNormie pushed a commit to AviNormie/rocketride-server that referenced this pull request Nov 9, 2026
…de-org#454)

* feat(agents): auto-install coding agent documentation stubs on startup

Add a system that makes RocketRide documentation discoverable by coding
agents (Cursor, Claude Code, Windsurf, Copilot) via their native
instruction file formats.

Agent stub templates (docs/stubs/):
- cursor.mdc, claude-code.md, windsurf.md, copilot-instructions.md
- CLAUDE.md and AGENTS.md for generic/unrecognized agents
- All use <!-- ROCKETRIDE:BEGIN/END --> markers for idempotent updates

Extension installer framework (apps/vscode/src/agents/):
- BaseAgentInstaller: marker-based install/uninstall with write-safety
  (line-ending normalized content comparison to avoid dirty repos)
- 6 concrete installers (Cursor, Claude Code, Windsurf, Copilot,
  CLAUDE.md, AGENTS.md)
- AgentManager orchestrator with two-pass startup logic:
  Pass 1: auto-detect IDE environment (appName, extensions, ~/.claude/)
  Pass 2: install any manually checked integrations not already covered
- No settings are auto-flipped; user controls individual toggles
- installFromSettings() called on settings save for newly checked items

Service catalog sync (apps/vscode/src/agents/services.ts):
- On server connect, writes individual component schemas to
  .rocketride/schema/<component>.json
- Writes slim services-catalog.json (name, classType, description,
  lanes, invoke)
- Syncs on every servicesUpdated event: adds, updates, removes obsolete

Build pipeline (apps/vscode/scripts/tasks.js):
- Copies docs/agents/*.md and docs/stubs/* into build/vscode/docs/
- Added docs/** to pkg.files for .vsix packaging

Settings & UI:
- New setting: integrations.autoAgentIntegration (default: true)
- New settings: integrations.claudeMd, integrations.agentsMd
- Automatic Agent Integration checkbox on Welcome and Settings pages
- Generic CLAUDE.md and AGENTS.md added to Integration Settings list

Documentation fixes (docs/agents/):
- Removed incorrect { pipeline: { ... } } wrapper from all JSON
  examples across 5 doc files — pipelines use flat format with
  components, source, project_id at top level

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(agents): address CodeRabbit review findings

- agent-manager: runInstaller returns boolean; callers only add to
  installed Set on success
- agent-manager: uninstallAll removes .rocketride/schema/ and
  services-catalog.json
- agent-manager: defer installDocs/ensureGitignore until first actual
  install via lazy prepareWorkspace()
- services: log obsolete schema file deletions via getLogger()
- PageSettingsProvider: await installFromSettings, surface errors via
  vscode.window.showWarningMessage instead of console.error
- docs: fix "Multiple Pipelines" wording (one pipeline per file)
- docs: fix ingestion pipeline lane flow, add [lane] notation
- docs: add language specifiers to all bare fenced code blocks
- docs: fix duplicate result variable in TypeScript API example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(agents): sanitize service names to prevent path traversal in services.ts

Agent-Logs-Url: https://github.com/rocketride-org/rocketride-server/sessions/1175cc18-4f09-4d98-a9ae-540d4c350c46

Co-authored-by: Rod-Christensen <98939082+Rod-Christensen@users.noreply.github.com>

* fix(docs): address additional CodeRabbit review findings

- COMPONENT_REFERENCE: clarify ui field is recommended with position
  only; other ui fields are designer-managed
- PIPELINE_RULES: use consistent "1." markers for ordered list (MD029)
- QUICKSTART: add missing input edge on processor node (both snippets)
- typescript_API: wire process/output nodes with input arrays, use
  response_text provider, add missing source field to env var example
- python_API: same fixes — wire nodes, use response_text, add source

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Rod.Christensen <rod.christensen@aparavi.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
AviNormie pushed a commit to AviNormie/rocketride-server that referenced this pull request Nov 9, 2026
…-org#929)

Top-level `permissions: { contents: write, packages: write, id-token: write }`
on nightly.yaml granted every job in the workflow the union of all writes
any one job needed, including jobs that only consume read-only inputs. The
Scorecard `TokenPermissionsID` rule flags this as the most severe form of
over-grant because top-level writes propagate to every reuse-called
workflow as the upper bound.

Drop the top-level to `contents: read` and raise per-job only where the
job actually writes:

  - build:               contents: read, packages: write
                         (forwarded to _build.yaml for NuGet/vcpkg writes
                          to ghcr.io via VCPKG_BINARY_SOURCES=...readwrite)

  - cleanup-prereleases: contents: write
                         (git push origin --delete <tag> and gh release
                          delete; the tag deletion requires repo write)

  - prerelease:          contents: write, id-token: write
                         (forwarded to _release.yaml for tag push +
                          gh release create + Sigstore keyless signing)

  - docker:              contents: read, packages: write
                         (forwarded to _docker.yaml for ghcr image push;
                          matches release.yaml's docker job pattern)

  - init:                no override, inherits top-level read
                         (_init.yaml is read-only — extracts versions
                          from package.json via jq and stamps github.sha)

The grants mirror the canonical pattern already in place in release.yaml
(committed in the prior TokenPermissionsID cleanup pass that closed rocketride-org#513
and rocketride-org#515 on _build.yaml and _init.yaml).

Closes Scorecard TokenPermissionsID alerts rocketride-org#566 (topLevel contents:write)
and rocketride-org#567 (topLevel packages:write).

The remaining 10 TokenPermissionsID alerts on this repo (rocketride-org#451, rocketride-org#452, rocketride-org#454,
rocketride-org#455, rocketride-org#489, rocketride-org#490, rocketride-org#604, rocketride-org#635, rocketride-org#649, rocketride-org#650) flag job-level writes that are
required for the job's function (ghcr image push, GitHub release publish,
artifact cleanup, model-sync commits). Those are being dismissed
separately with "won't fix" + per-alert justification — Scorecard
penalizes any write, including the unavoidable kind.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

builder Node builder tooling and ./builder workflows docs Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants