Research os

Research OS Skill

When to use

Use this skill when the working directory contains a Research OS workspace or when the user asks to create, continue, review, or maintain a long-running research program.

The skill is the reusable operating package. Active research files live in the user's external workspace, not inside the skill package.

Package layout

This repository is the skill package root:

• SKILL.md contains the operating instructions.
• scripts/researchos.py contains deterministic helper commands.
• templates/ contains workspace, program, task, scoping task, lead, source, card, and log templates.
• docs/schema-notes.md records intended object shapes; helper validation stays lightweight.
• policies/ contains heartbeat, human intake, controlled exploration, validation, and publishing rules.

Generated research workspaces should live outside this skill package. A workspace created by the helper will contain content/, program folders, generated indexes, and optional site/ output.

The Skill package repository and research workspace repositories are separate. The package page introduces Research OS; a workspace site/ is a separate research-project page generated from that workspace only.

Initialize a workspace

First use should create a new external workspace. Do not initialize inside this Skill package repository or any of its subdirectories.

Use the helper script from the skill root:

python3 scripts/researchos.py init /path/to/workspace --program my-program --title "My Program"
python3 scripts/researchos.py validate /path/to/workspace
python3 scripts/researchos.py heartbeat-plan /path/to/workspace
python3 scripts/researchos.py next-direction-plan /path/to/workspace
python3 scripts/researchos.py maintain /path/to/workspace
python3 scripts/researchos.py add-lead /path/to/workspace my-program "Explore adjacent source landscape"

Do not create active research files in the skill package root. Initialize or operate an external file-native workspace.

First-use sequence:

1. Choose or create an external workspace path.
2. Run init for that path.
3. Run validate immediately.
4. Run heartbeat-plan and complete the seed task-0001 before broader research.
5. Keep generated content/ and site/ in the workspace repository, not in this package repository.

Helper command surface

Use helper commands when they preserve structure or reduce repeated file edits:

• init: create the external workspace scaffold; it must refuse the skill package root or any subdirectory under it.
• validate: check required state, task references, lead references, and required frontmatter before continuing.
• heartbeat-plan: print the next selected work; if any human inbox has real content, this must select human-intake; if the queue is empty and continuation mode is auto-scoping, this must select next-direction-review.
• next-direction-plan: when ordinary work and active leads are exhausted, print candidate sources, continuation limits, and the bounded next-direction review action.
• inject: append human input to a program inbox, classify it, update human_interrupts, and create a human-origin lead when the route is controlled exploration.
• add-lead: create a controlled exploration lead from agent, map-gap, evidence-gap, claim, source, or human signals.
• lead-plan: list active proposed, review-needed, or accepted leads that need triage.
• generate-manifest: regenerate program-manifest.json for low-token navigation.
• refresh-index: regenerate leads.md, program-manifest.json, and program-index.md.
• build-site: generate only reviewed Markdown marked publish: true; keep inboxes, logs, leads, lead catalogs, and internal program indexes out of site/.
• maintain: run validation first, add missing default continuation policy for older workspaces, then refresh navigation and build the reviewed site unless --no-site is set; if validation fails, do not regenerate outputs.

Core rule

Do not improvise the next step from conversation alone. Read state first.

Continuation policy

New workspaces default to this policy in the active program state.json:

continuation_mode: auto-scoping
max_candidate_leads_per_heartbeat: 3
max_promoted_tasks_per_heartbeat: 1
allow_scoping_task_when_method_missing: true
require_human_review_for_scope_change: true

Older workspaces may be missing continuation_policy. Run maintain to add the default policy before relying on continuation behavior; validate warns when the policy is absent or incomplete.

When ordinary queue work is exhausted, auto-scoping means queue empty is not done. It triggers next-direction-review after human input, active tasks, queued tasks, and active leads are ruled out.

In next-direction-review, use next-direction-plan to review the research map, lead catalog, evidence gaps, unresolved claims, open uncertainties, parked leads, and recent decisions. Create at most the configured number of candidate leads and promote at most the configured number of accepted leads into bounded tasks.

If the best in-envelope direction lacks a runnable method, command, or artifact contract, create a bounded scoping task from templates/scoping-task.md when allow_scoping_task_when_method_missing is true.

Branch park and program park are separate states. Parking a branch means a lead or candidate direction is out of the active queue; it must not set the program to parked, select none, or stop continuation. After parking one branch, return to the remaining candidate sources. Park the program only when a human explicitly asks to pause/stop, or when next-direction-review exhausts every defensible bounded next task and records the reason for human review.

Require human review for scope changes, private data, credentials, publishing, irreversible actions, and paper/live execution.

Required read order

1. content/os-state.json
2. Active program state.json
3. Active program research-map.md
4. Active program program-manifest.json if present
5. Active program program-index.md if present
6. Active program leads.md and active leads/lead-*.md if present
7. Human inboxes
8. Active task file
9. Relevant policies, especially human intake and controlled exploration
10. Recent heartbeat logs

If program-manifest.json or program-index.md is missing in an initialized workspace, create or refresh it during the next maintenance step.

Heartbeat behavior

A heartbeat advances one bounded slice of work. It must:

• triage human input before ordinary queue work
• resume an active task before creating new work
• derive leads from research-map.md when the queue is empty or research gaps appear
• triage leads before promoting them to bounded tasks
• run next-direction-review instead of stopping when the queue is empty and continuation mode is auto-scoping
• create source notes for external sources
• connect claims to evidence
• write a heartbeat log
• update program state
• regenerate leads.md when leads change
• regenerate program-manifest.json
• update program-index.md
• generate selected HTML pages when useful for human review
• leave a precise next_action

Human intervention

If human input exists, classify it as one of:

• stop or pause
• priority change
• scope change
• new question
• source suggestion
• correction
• publish request
• direct task request
• adjacent lead

Then route it before ordinary work:

• stop, correction, priority, scope, direct task, and publish requests are human-intake overrides
• source suggestions, new questions, and adjacent ideas become human-origin leads unless the user explicitly asks for direct execution
• scope changes update the research map or create review-required items before work continues

Do not silently ignore human input. Humans can change the research direction; they are not just another evidence source.

Controlled exploration

Use controlled exploration for agent-discovered leads and human-suggested adjacent research.

Every lead must record:

• origin: human, agent, map gap, evidence gap, claim, or source
• relationship to the research map or exploration envelope
• expected output
• cost and risk
• decision: accept, reject, park, or needs human review

Promote only accepted leads to tasks. Rejected or parked leads remain visible so future agents do not rediscover the same branch without new evidence. A parked lead is branch-level state only; it does not park the program or end auto-scoping continuation.

Index and site maintenance

Every heartbeat that changes tasks, sources, claims, artifacts, logs, or state should update the program navigation layer:

• program-manifest.json for agent and helper navigation
• program-index.md for human-readable program overview
• leads.md for pending and decided exploratory branches
• selected site/ HTML pages for human review, when the changed content is useful to publish or inspect

Prefer python3 scripts/researchos.py maintain /path/to/workspace after content changes. The command validates first, blocks on structural errors, refreshes navigation files, and builds only reviewed publish: true HTML pages. When continuing a workspace, inspect validation output, program-manifest.json, and program-index.md before opening full Markdown bodies; treat the manifest and exception list as the low-token routing layer.

Do not convert every internal file to HTML by default. The default site builder is allowlist-based: only reviewed Markdown marked publish: true is published, and inboxes, logs, leads, lead catalogs, and internal program indexes stay internal. Reports, research cards, validation memos, source catalogs, and claim catalogs should be marked publishable only after review.

Output discipline

When reporting to the user, include:

• what changed
• what was found
• what remains uncertain
• what the next heartbeat should do

Avoid turning every heartbeat into a long report. Report only when there is a decision, finding, blocker, or useful artifact.

Safety and integrity

• For current factual claims, refresh sources before publishing.
• Mark unsupported claims as low confidence.
• Preserve contradictions; do not smooth them away.
• Do not publish private inbox content unless policy permits it.