# Co Research

> Autonomous research agent that reads RESEARCH.md, infers what's needed, dynamically adjusts TODOs, and delegates to the right skill. Supports opt-in BFS mode for autonomous design space search. Respects a configurable supervision policy (presets: manual / checkpointed / autonomous / wild) governing notifications, approval gates, resource limits, and idea-change handling. Proactively surfaces gaps and asks before acting. Trigger phrases: "start research", "continue project", "what's next?", "explore design space", "autoresearch".

- Skill: `zy-ning/co-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zy-ning/co-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zy-ning/co-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zy-ning (https://skillmd.com/u/zy-ning)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zy-ning/co-research

---


# Co-Research

Own `RESEARCH.md`. Use it as the ground truth for project state.

## Session Start

1. If `RESEARCH.md` does not exist, initialize the project:
   - If `templates/RESEARCH.md.template` exists locally, copy it.
   - Otherwise, download it (and `CLAUDE.md`) from the pack's GitHub repo:
      ```bash
      mkdir -p templates
      curl -fsSL https://raw.githubusercontent.com/zy-ning/Oh_My_Co-Researcher/main/templates/RESEARCH.md.template -o templates/RESEARCH.md.template
      curl -fsSL https://raw.githubusercontent.com/zy-ning/Oh_My_Co-Researcher/main/CLAUDE.md -o CLAUDE.md
      cp templates/RESEARCH.md.template RESEARCH.md
      ```
   - Ask the user to fill in `## Goal`, then proceed.
2. If `.co-researcher/skills.yaml` exists, read it before planning so you know the project's preferred skillpacks, subset choices, and supervision defaults.
3. Read **Pipeline Status** first (30-second orient), then **Supervision Policy** if present, then the full document.

## Supervision Policy

4. `## Supervision Policy` in RESEARCH.md is optional. If absent, default to confirmation-first behavior throughout unless `.co-researcher/skills.yaml` specifies project-local supervision defaults.
5. Precedence rule:
   - `RESEARCH.md` `## Supervision Policy` overrides everything when present.
   - `.co-researcher/skills.yaml` provides project-local defaults when RESEARCH.md does not define supervision policy yet.
   - preset values are only the starting recommendation written by `co-customize`.
6. If `.co-researcher/skills.yaml` exists, treat it as the project-local preference layer for preferred presets, enabled packs, selected donor skills, and supervision defaults.
7. If the user asks to configure automation, supervision, or preferred skillpacks, use `co-customize` as the primary flow. Use direct inline RESEARCH.md edits only for lightweight policy adjustments when the user clearly wants that.
8. Policy dimensions:
   - **Notify** — events to surface; if no channel exists, surface in the next user-visible update
   - **Approve** — action types requiring a pause; precedence: approval > notify-only > silent
   - **Stop** — target or limits (`target_reached`, `step_limit`, `time_budget`, `error_threshold`, `blocked`)
   - **Resources** — three classes: Service/API, Compute, Human/Physical; escalation rule is `forbid` / `notify` / `approve`
   - **Idea Changes** — improvements (notify), strategy pivots (notify or approve), compromises (approve by default)
9. Preset behavior:
   - `manual` — always stop for approval
   - `checkpointed` (default) — record approval-required issues in **Pending Approvals**, continue unrelated allowed work; stop only when nothing else remains
   - `autonomous` — notify but do not stop
   - `wild` — never implicit; warn the user about unattended actions, resource use, and plan divergence, then require explicit confirmation before enabling

## Assess Before Acting

10. Before executing any TODO, do a gap analysis:
   - Compare **Goal** against completed **Context** entries. What's missing?
   - Surface stale **Blocked** items immediately.
   - Gaps to catch: experiment done but no result analysis; results done but no paper; paper drafted but no review.

11. If the TODO list is stale or incomplete, apply the supervision policy for `todo-adjustments` (approve → wait; notify → announce and continue; absent → propose and wait), then add/remove/reorder as needed.

## Act

12. Pick the highest-priority unblocked TODO. Announce: `→ Working on: <TODO text>`.

13. Delegate to the right skill:

   | Need | Skill |
   |------|-------|
   | Literature survey | `research-lit` or `arxiv` |
   | Deep paper Q&A / code repo discovery | `alpha-research` (AlphaXiv: `alpha ask`, `alpha repo`) |
   | Paper-to-code reproducibility audit | `audit` |
   | Method / idea refinement | `research-refine` |
   | Experiment planning | `experiment-plan` |
   | Running experiments | `co-experiment` (this pack) or `run-experiment` |
   | Result analysis | `result-to-claim` |
   | Figures | `paper-figure` |
   | Paper drafting | `co-write` (this pack) or `paper-write` |
   | Review / critique | `co-review` (this pack) or `auto-review-loop` |
   | Lesson extraction | `co-evolve` (this pack) |
   | Unclear | Ask the user, or do it directly. |

14. When done: check off TODO, append timestamped **Context** entry, update **State** and **Pipeline Status**, save `RESEARCH.md`.

## Proactive Loop

15. After each completed TODO, surface the result briefly, then apply the supervision policy for the next move:
   - **Ambiguous next step** → describe 2–3 options and ask. Never silently pick among plausible directions.
   - **Approve / stop target reached** → ask before proceeding, or queue and continue unrelated work if `checkpointed`.
   - **Notify only** → announce the next action and continue.
   - **Wild** → continue until completion criteria, a hard safety rule, or a forbidden boundary.
   - **No policy** → announce and ask "Shall I continue?"

## Exploration Modes

**BFS mode — opt-in, off by default**

When the user asks to "explore the design space", "autoresearch", or "find the best config", apply the supervision policy for `bfs-start` (approve → confirm; notify → announce and continue; absent → confirm). In `wild` mode, BFS may proceed without a checkpoint only when target file, metric, budget, and completion criteria are already explicit and within granted resource boundaries.

Before starting, confirm: target file, metric + direction (e.g., minimize `val_bpb`), time budget per run, max experiments. Then delegate to `co-experiment` BFS mode — do not interrupt. When done, update RESEARCH.md Context and Pipeline Status and propose next step.

**DFS — default when direction is confirmed**

Commit each meaningful step. `git stash` before risky moves; note the stash in **Context**.

## Project-local Skill Config

16. `.co-researcher/skills.yaml` is optional. If absent, keep existing behavior.
17. If present, use it to prefer enabled donor packs and selected skills when choosing among overlapping external tools.
18. Do not silently rewrite `.co-researcher/skills.yaml` during normal orchestration. Use `co-customize` when the user wants to change stack or supervision preferences.

## Tone

Concise. No preamble. Show what you are doing, not what you are about to do.

## Example

Input: RESEARCH.md with experiments done in Context, but only a "run baseline" TODO (already checked). No write TODO.
Gap detected: "Results exist but no paper TODO — adding P1: Write paper draft."
Action: Proposes TODO addition, waits for confirmation, then invokes `result-to-claim` to validate claims before writing.