@yzxoi/dsh-holos-research

Structured research management as a dsh (Cordis) plugin: project state machine, entity lifecycles, adversarial review, audit trail — files as the single source of truth, no UI panel, no compute submission.

This is the dsh port of the Synergy plugin holos-research (v1.1.1). It ships:

• 14 model-facing tools (research_init, research_state, research_idea, research_plan, research_experiment, research_claim, research_exhibit, research_paper, research_submission, research_wiki, research_timeline, research_monitor, research_journal, research_checkpoint_brief)
• 17 skills served through ctx.skills (provider holos-package), consumable by dsh-tool-skill
• 4 agent prompt assets (critic / methodologist / auditor / editor) plus an example agent preset with persona-ized dsh-tool-subagent instances
• 10 utility scripts + 5 matplotlib themes materialized into .research/scripts/ by research_init (including the compose pre-writing gates: contribution_check.py, results_validation_check.py, latex_guard.py, numeric_consistency_check.py, compose_progress_check.py)
• Node-only runtime (ESM, node:fs); no Bun, no UI panel, no compute_submit

Install

pnpm add @yzxoi/dsh-holos-research

Add the plugin to a cordis.yml:

- name: '@yzxoi/dsh-holos-research'

The research root is resolved per tool execution in this order:

1. root from the plugin config (explicit override; used by tests and deployments)
2. the calling agent's session cwd
3. process.cwd()

- name: '@yzxoi/dsh-holos-research'
  config:
    root: /path/to/research/project

The research project lives in <root>/.research/. Configure the agent row with a cwd (or set the plugin root) before using the tools — without either, the first tool call fails loudly with guidance.

Agent preset (4 persona-ized subagent tools)

examples/presets/holos/agent.cordis.yml mounts the plugin plus four dsh-tool-subagent instances (subagent_critic, subagent_methodologist, subagent_auditor, subagent_editor) whose persona fields inline the four agent prompts. The preset requires the subagent seam in the host composition:

- name: '@deepseek-ai/dsh-subagent-spawn-in-process'   # provider `spawn`
- name: '@deepseek-ai/dsh-tool-subagent'
- name: '@yzxoi/dsh-holos-research'

The agent prompts are also exported from the package (AGENTS, AGENT_PROMPTS) for custom mounts.

Skills

The 17 skills are served by a runtime provider (holos-package); no disk layout is required. dsh-tool-skill (or any ctx.skills consumer) lists them and loads bodies plus references/ assets. The plugin registers the provider opportunistically — deployments without the skill seam keep every tool working.

Data compatibility

.research/ remains the single source of truth and the on-disk format is byte-identical to the Synergy version: same paths, YAML/JSONL structure, entity id prefixes (idea_ / plan_ / exp_ / claim_ / exh_ / paper_ / sub_), status enums, the 6-phase project state machine, red-lines R1–R7, authenticity grades, and index.yaml registration semantics.

• Existing projects: uninstall the Synergy plugin, mount this one, continue. No migration, no rewrite.
• Legacy projects (no index.yaml): the first read auto-bootstraps the index with a one-time read-only scan.
• The plugin never migrates, rewrites, or moves existing .research/ data.

Differences vs the Synergy plugin

Surface	Synergy plugin	dsh port
Runtime	Synergy Plugin API 4, Bun	dsh (Cordis), Node ESM
.research/ disk format	source of truth	identical, byte-compatible
Tools	15 (compute_submit included)	14 (compute_submit not migrated)
Monitor workbench panel	yes	not migrated (no UI)
Monitor query operation()s	9	not migrated (research_monitor keeps the model-facing read actions)
Skills	17 via Synergy skill registry	17 via ctx.skills provider holos-package
Agents	4 agent() registrations	4 prompt assets + example preset of dsh-tool-subagent instances
research.changed event	yes (UI refresh)	not migrated (no session event)
File I/O	workspace service + Bun.file	node:fs/promises (mutex + tmp-rename atomic writes + traversal/symlink guards preserved)
Compute submission	compute_submit → SII Inspire	not migrated (external platform)

research_experiment still records backend/job metadata (inspire, local, api, manual) exactly as before — executing jobs is out of scope for the plugin.

Development

pnpm install
pnpm run gen          # regenerate src/generated/assets.ts + examples preset (idempotent)
pnpm run typecheck    # tsc --noEmit (strict)
pnpm run lint         # biome check
pnpm test             # vitest run (domain + tools + provider + loader smoke + compat fixtures)
pnpm run build        # tsc → lib/ + lib/types
pnpm run pack         # npm pack --dry-run (files: lib, agents, skills, scripts, src/generated)

src/generated/assets.ts is generated — never hand-edit; run pnpm run gen after touching agents/, skills/, or scripts/.

License

MIT — Copyright (c) 2026 yzxoi