AutoResearch — a research project agent for DeepSeek Harness
A preset for DeepSeek Harness (DSH) that turns DSH into a research project team. You write a brief; the agent plans the project with you, executes it step by step with specialized AI roles, verifies every piece before accepting it, traces failures to their cause, and publishes a finished deliverable — mirrored into Linear if you connect it.
What it can do
- Plan from a brief. A few paragraphs in, a structured, immutable plan out: every node, its deliverable, its dependencies, and a mechanical "done" checklist per node. Nothing runs before you approve it.
- Execute without babysitting. Nodes run in dependency order as fresh, single-purpose roles — scouts, verifiers, writers, critics, judges, coders, and an integration editor — each with a declared read/write scope, so no step inherits another step's context.
- Verify at every level. Draft → critique → revise until convergence;
competing drafts are ranked by blind judges (zero-based
pass_NN/judge_NNpackets, digest-boundjudgeContext); mechanical judge degradation routes to the critic gate instead of deciding with a broken panel. - Trace failures causally. A downstream failure attributes to the
responsible upstream node as a bounded, evidence-backed hypothesis —
observemode records it,enforcemode reopens the owning node within hard caps and re-verifies downstream. - Assemble and re-verify whole. The integration pass checks every accepted contribution against a hash-anchored ledger, fixes only editorial issues in place, bounces substantive conflicts back to their owning node, and visually inspects figures before publishing.
- Publish exactly what the plan names. One folder,
outputs/<projectId>/, driven solely by the plan's explicitdeliverableslist — plus aMANIFEST.jsonattributing every file by source, rule, and hash. Publication is transactional: the previous output stays last-known-good until a replacement commits. - See every publish blocker before it blocks. A read-only
autoresearch_publish_preflightruns the same closure computation as the transactional publish and returns the complete violation list at once — active-LaTeX graphic/input/label closure, binary closure companions hashed as bytes, trusted system-TeX roots, destination and cross-run collisions — each with the exact remedy, before any state is changed. - TeX done right. Reproducible builds are
SOURCE_DATE_EPOCH-pinned, word counts cover the resolved input closure, compiler failures keep first-error/line/tail evidence, and a missing toolchain blocks with a clear remediation diagnostic — never a bare error, never a silent pass. - Linear as the live operational surface. Each plan step is an issue
with dependency arrows, and every issue carries a short, human-readable
Current Node Contextblock — what is done, what failed, why it was reopened, what is next — readable on the issue itself, digest-bound so every lifecycle action re-reads it first. - Reopen finished work from feedback.
autoresearch_submit_feedbackstores verbatim user feedback; triage reopens only the smallest responsible closure (cycle-checked, receipt-supersedes-linked, last-known-good preserved), and a repair republishes through the normal gates. - One canonical, unversioned schema. Every record has exactly one
shape identified by
kind; tool schemas are generated from the core definitions; no version markers, no legacy readers at runtime (see Schema discipline). - Honest role confinement. Each role child runs under its own Agent
Preset — the resolved role persona plus that role's resolved tool set — and
broad role tooling (
read/grep/glob/bash/write/edit) unlocks only behind a fresh, run-bound confinement attestation; on deployments that cannot attest it, role children mount only their narrow resolved sets and the preset says so.
How a project runs
- Propose and approve. The planner proposes the DAG; you approve it. The plan is frozen after approval — the agent surfaces drift, never rewrites it.
- Prove the style first, then execute in dependency order.
autoresearch_tex_style_checkcompiles the declared LaTeX template/style before content work; on failure the coordinator asks the user to fix the environment instead of starting the project. Each node: evidence preparation → author loop (A/B/AB) → critique → blind judging → promotion, bounded by the node's budget. - Accept mechanically. Every criterion is accounted for
(PASS/FAIL/WAIVED/NOT_APPLICABLE); content TeX nodes are validated
structurally against the project's real file tree (no per-node compile),
while the assembled master compiles once at the end. Acceptance receipts are
hash-bound to the node contract and its journal revision, with
finalBuildbinding to the accepted run artifact and the tool's own scratch check build recorded separately asverificationBuild. A project exposes as many assembled master.texdeliverables as it needs (each path exactly once; duplicates are refused), references resolve from the integration run dir → node run dirs → workspace root, andautoresearch_project_status().sourcesis the single tracked file inventory. - Integrate and publish. The editor merges accepted contributions, the
verifier checks coverage, a read-only
autoresearch_publish_preflightreports every closure violation before publishing, and the publish transaction lands the deliverable. Each finished node closes out with oneautoresearch_close_nodecall. - Iterate from feedback. Completed projects reopen minimally from user feedback and republish a verified replacement.
Quick start
git clone https://github.com/gavenma/dsh-autoresearch-preset.git
cd dsh-autoresearch-preset
npm run init # guided setup: role models + optional Linear key
npm run verify:snapshot # offline integrity check
npm run install:preset -- "$HOME/.dsh/.agent-presets/research"
npm run initwrites model choices straight intoconfig.default.json— the single source of truth for role routing. It is local-only and gitignored: a fresh clone seeds it from the committed public templateconfig.example.jsonon firstnpm run init(or copy the template by hand). Noconfig.local.jsonoverlay exists.- The Linear key is stored in the DSH credentials store, never in this repo.
- Register the preset with your profile, then restart DSH. On DSH 0.2.1 a
preset is mounted only from a profile bundle layer, so installing files is
not enough:
node scripts/install-preset.mjs <target> --register webcopies the runtime and registers it with thewebprofile through the supporteddsh pluginpath. An already-running process keeps its composition until it is restarted.
What's in this repository
roles/— instructions for every worker role.skills/— the two entry points:research-project(open brief) andresearch-outline-project(your outline).tools/— the generated runtime: orchestrator, core engine, Linear adapter, bounded web/PDF fetcher.src/— editable source;scripts/builds/verifies/installs;tests/holds the regression suite (npm test).briefs/demo-brief.md— a synthetic brief for an end-to-end demo.
Requirements
- A DSH installation of the tested line (
@deepseek-ai/dsh0.2.1-rc.5). The preset is mounted as a profile bundle whose patch inserts a declarative@deepseek-ai/dsh-agent-presetrow; the composition uses the splitprefix+suffixpersona shape and the shipped@deepseek-ai/dsh-workflow-ptcbackend. The line is tested, not pinned: the bundle records the installed DSH line it was verified against as informationaldsh.testedDsh; there is no peer/engines pin, because no semver prerelease range can express "any 0.2.x prerelease" (and no range can certify the tested surface), so the install-time compatibility gate is the authoritative requirement.scripts/verify-dsh-compat.mjsis the real compatibility check and validates the composition against the INSTALLED runtime's own declarations — every row package imports, every config key exists in that plugin's exportedConfigschema, every custom row module imports and its declaration registers, everyctx.get('<service>')is declared by an installed package's Context augmentation, and every host-service method the preset reaches (for examplesubagents.startActivation) exists in those declarations, with reviewed property reads checked separately. A DSH upgrade that breaks any of that fails at install time with a row/key/expected/actual diagnostic instead of silently disabling the preset. - Node.js 20 or later for build/verify/install scripts.
- Optional:
LINEAR_API_KEYin the DSH credentials store for Linear workflows; local-only projects never call Linear. - A model provider reachable from your deployment; role assignment lives in
roleProfilesinconfig.default.json(local-only; seeded fromconfig.example.json). A per-workspace.research-agent/config.jsoncan override roles for one workspace.
Install
npm run verify:snapshot
npm run install:preset -- "$HOME/.dsh/.agent-presets/research"
The installer first runs the DSH compatibility gate against the installed
runtime (see Requirements) and refuses to copy on any mismatch, naming the
row, config key or service plus expected vs actual. --force-accept is the
explicit override; when used, it is recorded in the install receipt with the
DSH version and structural-surface digest, so an accepted mismatch is never
silent.
The installer then copies runtime assets (composition, roles, skills, tools)
into the target. A config.default.json that already exists at the target
is never touched — re-installing after a code update cannot change your
working configuration. Two explicit flags can write it:
--replace-config— reset the target config to this checkout'sconfig.default.json(use after editing it or runningnpm run init).--clean-target— remove the destination tree first (stale bundles and residue); an existing target config is still preserved unless--replace-configis also passed.
First installs receive the config: the checkout's local config.default.json
when present, otherwise seeded from the public config.example.json template
(a mounted preset cannot run without one). The installer also reports —
never changes — role models outside the recognized list. Run
tests/installed-build-probes.mjs <target> after installing to confirm the
installed runtime.
Verify the build
npm run check— offline snapshot verification (hashes every runtime file against the build manifest; no network, seconds).npm test— the full suite (build, snapshot, schema, migration, capabilities, preflight, transport, blinding, promotion, Linear core/ reducer/reconcile/lifecycle, feedback, causal routing, TeX acceptance, output policy, hardening, and the DSH 0.2.1 integration targets: real harness registration/admission with the exact mounted tool surface, the compatibility gate, session-policy/confinement adapters, and the renderer spawn contract; publish-preflight, close-node, acceptance-scratch, re-acceptance-rule, role-dispatch-rc5 and tex-project-context targets cover the newest lifecycle, closure and role-child-composition work). There is no CI: the repository ships no workflow, and a push runs nothing. The suite is run locally on this host, which HAS the TeX/poppler toolchain — toolchain-dependent paths assert the real tools rather than degrading.npm run release:verify— full suite + local smoke + clean install + installed probes.
Configuration and operation
Precedence: workspace .research-agent/config.json > installed
config.default.json > built-in defaults.
linear.approval: "auto"by default; set a stricter mode if side effects should require confirmation.- Each role may set a provider-supported
reasoningEffort; writing roles ship amodelFallbackschain with a per-workspace rate-limit breaker. - External research performs bounded outbound HTTP(S) fetches and may send context to providers; disable it for unauthorized material. The fetch provider rejects URL credentials, bounds sizes/time, retries transient failures, and refuses cross-origin redirects.
Data handling
Never commit .research-agent/ — it holds plans, drafts, evidence,
transcripts, receipts, and Linear metadata. Credentials, logs, and private
input material are ignored by default; inspect git status before every
commit. Redaction checks on final reports are not a substitute for
reviewing what external systems receive.
Schema discipline
- One canonical, unversioned record shape per kind, defined and validated
in
src/autoresearch-core.mjs;kindis a record type, never a version. - No
schemaVersionfields,v1/v2branches, legacy readers, alternate unions, or policy-version markers. Runtime rejects old shapes with exactly one error:not canonical; run scripts/migrate-workspace.mjs. - Tool parameter schemas are generated from the core definitions; never hand-maintain one.
- Change a core constructor/validator and all consumers atomically — fixtures, docs, bundles, snapshots, and tests in the same change.
scripts/assert-canonical-schema.mjsenforces all of the above in source and generated artifacts.
Development
Make runtime changes in src/, then npm run build:preset (it regenerates
the tools/ bundles, pins agent.cordis.yml, and bumps the generation id).
Never edit generated bundles by hand. After a DSH upgrade, run
node scripts/verify-dsh-compat.mjs (the installer runs it too): it validates
the composition against the installed runtime's own declarations and fails
with the offending row/config key instead of mounting a silently disabled
preset. Run npm test before installation or deployment.
Maintainer-only helper files — AGENTS.md (agent change
discipline) and docs/ (exactly two files: capabilities.md, plans.md) —
are kept locally in the working checkout and intentionally not published.
See CONTRIBUTING.md, SECURITY.md, and NOTICE for the remaining rules.
No comments yet. Be the first to write one.