feat(subagents): manage MCP instruction loading

[Waishnav]

ChatGPT MCP workspaces currently fall back to the packaged subagents skill, which exposes package-manager-specific paths and leaves instruction loading fixed. This change synchronizes the bundled skill into the reserved ~/.devspace/skills/subagents/SKILL.md path when MCP workspace skills are loaded and refreshes that managed copy from the installed DevSpace package.

It also adds subagents.instructions with on-demand as the default and preload as the alternative. On-demand advertises the skill for the model to read only when delegation is useful; preload includes the workflow in the initial open_workspace instructions instead. Coding Agent installation through the Skills CLI remains separate and unchanged.

Summary by CodeRabbit

• New Features

  • Added subagents.instructions configuration with on-demand and preload modes.
  • On-demand mode makes subagent guidance available when needed; preload includes it when opening a workspace.
  • DevSpace now maintains an authoritative subagent skill copy for enabled subagent workflows.
  • Subagent guidance clarifies that delegation is intended for work benefiting from independent context or specialization.

• Documentation

  • Updated configuration, setup, workflow, and troubleshooting guidance for subagent skills and instruction modes.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: c8c2e6ec-f8d9-453f-87d1-be486769f504

📥 Commits

Reviewing files that changed from the base of the PR and between 521e1fa and c803ce4.

📒 Files selected for processing (22)

• docs/chatgpt-coding-workflow.md
• docs/configuration.md
• docs/gotchas.md
• docs/setup.md
• schema/v1/devspace.schema.json
• skills/subagents/SKILL.md
• src/cli.test.ts
• src/config-schema.ts
• src/config.test.ts
• src/local-agent-catalog.test.ts
• src/local-agent-config.test.ts
• src/local-agent-config.ts
• src/local-agent-manager.test.ts
• src/local-agent-profiles.test.ts
• src/onboarding.test.ts
• src/onboarding.ts
• src/server.test.ts
• src/server.ts
• src/skills.test.ts
• src/skills.ts
• src/workspace-conversation.test.ts
• src/workspaces.test.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

DevSpace adds subagents.instructions with on-demand and preload modes. It synchronizes the bundled subagents skill to a managed path and updates workspace loading, configuration handling, tests, and documentation.

Changes

Subagent instruction delivery

Layer / File(s)	Summary
Configuration contract and propagation schema/v1/devspace.schema.json, src/config-schema.ts, src/local-agent-config.ts, src/onboarding.ts, src/*test.ts	The new setting accepts on-demand or preload, defaults to on-demand, and remains preserved through parsing and onboarding.
Managed skill synchronization src/skills.ts, src/skills.test.ts, skills/subagents/SKILL.md	DevSpace atomically synchronizes the bundled skill to ~/.devspace/skills/subagents/SKILL.md, removes conflicting entries, and reloads the managed copy.
Workspace instruction composition src/server.ts, src/server.test.ts	open_workspace exposes the skill on demand or embeds its content when preload mode is enabled.
Configuration and workflow documentation docs/chatgpt-coding-workflow.md, docs/configuration.md, docs/gotchas.md, docs/setup.md	The documentation describes the managed skill path, instruction modes, and separate Coding Agent installation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to c803c

This change adds configurable subagent instruction delivery and synchronizes the bundled workflow into the managed DevSpace skill path. The supported configuration and workspace behaviors are covered, with no identified merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant open_workspace
  participant loadSkills
  participant ManagedSkill
  open_workspace->>loadSkills: load skills for the workspace
  loadSkills->>ManagedSkill: synchronize and reload subagents SKILL.md
  ManagedSkill-->>loadSkills: return managed skill
  loadSkills-->>open_workspace: return skills and workspace context
  open_workspace->>open_workspace: embed instructions when mode is preload

Loading

Poem

A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 16 files. (6 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: configurable MCP instruction loading and management for subagents.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 16 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/subagent-skill-loading

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR introduces configurable loading of the managed Subagents workflow for MCP workspaces.

• Synchronizes the packaged subagents skill into the reserved DevSpace skills directory and gives it precedence over other skills with the same name.
• Adds subagents.instructions with on-demand and preload modes.
• Advertises the managed skill on demand or embeds its contents in initial workspace instructions when preloading.
• Preserves the selected instruction mode through onboarding and updates configuration schemas, documentation, and tests.

Confidence Score: 5/5

The PR appears safe to merge with no actionable correctness, security, or repository-rule violations identified.

Managed-skill synchronization, configuration compatibility, onboarding preservation, and both instruction-loading modes remain internally consistent and are covered by focused tests.

Important Files Changed

Filename	Overview
src/skills.ts	Synchronizes the packaged Subagents skill into the managed directory and ensures that managed copy is authoritative.
src/server.ts	Selects between advertising the Subagents skill and embedding its workflow in initial workspace instructions.
src/local-agent-config.ts	Adds validated on-demand and preload instruction modes with a backward-compatible default.
src/onboarding.ts	Preserves the configured instruction-loading mode when onboarding updates provider selections.
schema/v1/devspace.schema.json	Publishes the new instruction mode and default in the versioned configuration schema.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Load workspace skills] --> B{Subagents enabled?}
    B -- No --> C[Remove reserved subagents skill]
    B -- Yes --> D[Refresh managed SKILL.md]
    D --> E[Load managed subagents skill]
    E --> F{Instruction mode}
    F -- on-demand --> G[Advertise skill in open_workspace]
    F -- preload --> H[Hide skill advertisement]
    H --> I[Embed workflow in initial workspace instructions]

Loading

_{Reviews (1): Last reviewed commit: "docs(subagents): clarify managed instruc..." | Re-trigger Greptile}