[RFC]: Make quest startup skill resolution overlay-aware and plugin-friendly

[gaofeng21cn]

Summary

DeepScientist currently works very well as an automated research runtime, but its quest bootstrap path appears to assume that bundled core skills should win over downstream overlays.

For cross-disciplinary adopters who treat DeepScientist as a runtime and layer a domain-specific overlay on top, this creates a hard integration problem: during quest startup, DeepScientist now appears to replace overlay-provided skills with its own versions before the quest begins.

I would like to propose a more explicit and flexible extension model so overlays or plugins can customize behavior in a stable way without modifying DeepScientist core.

Motivation

Our use case is medical research rather than computer-science-native research workflows.

To adapt DeepScientist for this setting, our current architecture is:

• DeepScientist as the runtime
• a domain-specific overlay on top of it
• domain-specific skills, prompts, and controller logic kept outside DeepScientist core

This approach is intentional: we do not want DeepScientist core to absorb medical-specific logic, and we do not want to fork core behavior whenever we need domain adaptation.

However, after a recent update, quest startup seems to force bundled DeepScientist skill versions into place and overwrite the overlay-provided versions. In practice, this breaks compatibility for downstream runtimes that rely on overlays as their main customization surface.

From our perspective, the problem is not only domain-specific. It is architectural:

• DeepScientist appears to make strong assumptions about default workflow and skill composition
• there is no explicit precedence contract between core skills and overlay/plugin skills
• downstream projects cannot reliably depend on overlay customization surviving bootstrap

This makes non-CS and cross-disciplinary adaptation much harder than it needs to be.

Proposed design

I think DeepScientist would benefit from an explicit extension contract for quest bootstrap and skill resolution. Possible directions:

1. Define a stable precedence model

   Make the resolution order explicit, for example:

   • core bundled skills
   • plugin-provided skills
   • overlay/project-local skills
   • per-quest overrides

   Or another ordering, but the important part is that the order is documented and stable.

2. Add an official overlay/plugin registration mechanism

   Instead of implicit replacement during startup, let external runtimes register overlays/plugins through a public interface. That could include:

   • a manifest-based registration step
   • explicit overlay roots
   • startup hooks that resolve skills from declared providers

3. Allow bootstrap to preserve external overrides

   Provide a supported mode where quest startup does not overwrite already-installed overlay skills, or only syncs missing core defaults without replacing higher-precedence providers.

4. Expose a bootstrap policy knob

   For example, a config option or startup contract that chooses among policies such as:

   • core-only
   • core-plus-missing-defaults
   • overlay-wins
   • explicit ordered providers

5. Document which extension points are public and stable

   If overlays/plugins are a supported integration style, downstream users need to know which contracts are safe to build on and which ones are internal implementation details.

Alternatives considered

• Forking DeepScientist core

  This would technically solve the immediate problem, but it creates an unnecessary long-term maintenance burden and defeats the purpose of using DeepScientist as a shared runtime.

• Re-applying the overlay after every quest bootstrap step

  This is fragile and effectively becomes a race against upstream bootstrap behavior. It is not a reliable contract.

• Moving all domain logic into external controllers only

  This helps in some cases, but it does not address the skill-resolution problem when the domain adaptation itself depends on custom stage skills or prompt surfaces.

Affected areas

• quest bootstrap / startup flow
• skill installation and resolution
• overlay or plugin loading model
• public extension contracts
• compatibility guarantees for downstream runtimes built on DeepScientist

Compatibility and migration

Ideally this should be additive:

• existing default users can keep current behavior
• advanced users can opt into an explicit overlay/plugin model
• downstream runtimes can migrate to a documented precedence contract instead of depending on implicit startup behavior

If the recent startup replacement behavior is intentional, it would be helpful to document it clearly.
If it is not intentional, this may also indicate a regression in extension behavior.

Related context

This is adjacent to, but different from, #9.

Issue #9 is about documenting external controllers built on stable public contracts.
This RFC is about making quest bootstrap and skill resolution themselves extensible enough that overlays/plugins remain viable for domain adaptation.