Co Scientist Start

co-scientist-start

Goal:

• Start one Co-Scientist run from Claude Code using a natural-language goal or an imported brief.

Expected input:

• either a natural-language research goal
• or a brief path such as notes/drug_resistance_brief.md
• or no explicit arguments, which should trigger a short guided intake

Guided intake:

• If the user only says /co-scientist-start, ask at most four short questions:
  1. What is the research goal?
  2. Should the run favor exploration or grounded progress?
  3. Should the run use a completion-driven search or a capped low-cost iteration budget?
  4. Is there an existing brief, paper note, or other file to import?
• Do not ask for low-level mechanics settings such as num_debaters, elo_k_factor, or ucb_exploration_constant.
• If the user explicitly asks for stricter or lighter review, capture that as a high-level review override for critique depth without replacing the iteration-strategy question or disabling any review stage.
• After collecting the answers, render a confirmation summary before you create any files.

Execution steps:

1. If the user supplied a natural-language goal, convert it into --goal "<goal>".

2. If the user supplied a brief file, convert it into --brief <path>.

3. When the user also specified high-level controls such as exploration, iteration strategy, or review rigor, pass them through as:

   --exploration <value> --generation-bias <value> --review <value> --budget <value> --evolution <value> --stop-policy <value> --iteration-policy <value> --iteration-band <value> --human-checkpoint <value>
   

   Convert Claude-style key: value controls into real CLI flags before execution. For example:

   • exploration: aggressive -> --exploration aggressive
   • review: strict -> --review strict
   • iteration policy: capped -> --iteration-policy capped
   • iteration band: 6 10 -> --iteration-band 6_10
   • human checkpoint: before overview -> --human-checkpoint before_overview

4. Before creating the run, render a summary with:

   python -m tools.host.claude_project_cli start --goal "<goal>" --skill co-scientist-pipeline --summary-only
   

   or the equivalent brief-based variant.

5. Show the returned summary to the user and wait for confirmation.

   • When you present the summary, also tell the user that the run-local dashboard receipt will be written to:
     • runs/<run_id>/dashboard/LINKS.md
     • runs/<run_id>/dashboard/LINKS.json
   • Tell the user that /co-scientist-dashboard <run-dir> is the ready-link follow-up when the background bootstrap has not finished yet.

6. After confirmation, run:

   python -m tools.host.claude_project_cli start --goal "<goal>" --skill co-scientist-pipeline
   

   or the equivalent brief-based variant.

7. Read the emitted handoff artifact:

   • runs/<run_id>/state/HOST_AGENT_HANDOFF.json

8. Read the CLI JSON result and the run-local dashboard receipt artifacts:

   • runs/<run_id>/dashboard/LINKS.md
   • runs/<run_id>/dashboard/LINKS.json

9. If the CLI JSON contains dashboardLinks:

   • If dashboard.status is running, return dashboardLinks.dashboard as the primary dashboard URL and include the deep links.
   • If dashboard.status is starting, immediately run:

   python -m tools.host.claude_project_cli dashboard <run-dir>
   

   • Read the refreshed CLI JSON result plus runs/<run_id>/dashboard/LINKS.md.
   • If runtime.status is now running, return the refreshed links.dashboard URL as the primary dashboard URL and include the deep links.
   • If runtime.status is still starting, tell the user that the dashboard is still booting, point them to runs/<run_id>/dashboard/LINKS.md, and include the retry command:

   /co-scientist-dashboard <run-dir>
   

10. Open the canonical workflow and shared contracts:

• skills/co-scientist-pipeline/SKILL.md
• skills/shared-references/artifact-contract.md
• skills/shared-references/state-contract.md
• skills/shared-references/integration-contract.md
• skills/shared-references/execution-modes.md

11. Continue execution from the canonical repository-local skills tree instead of inventing a parallel flow. If the first refreshed routing plan returns run_configuration, execute research-config before any generation work.
12. After each major phase write, run:

python -m tools.validation.contract_validation runs/<run_id> --skill co-scientist-pipeline

Rules:

• Use co-scientist-start when the user wants the system to create the run directory, input.md, and the canonical start artifacts.
• If the user first asks what can be configured, route them to co-scientist-params or summarize ../../shared-references/start-parameters.md.
• Use co-scientist-run only when the user already has a run directory or a compatibility config.yaml.
• Prefer --interaction-mode guided when the run came from a question-driven intake.
• Prefer --interaction-mode brief_import when the run is anchored by an imported brief without a separate free-form goal.
• Fresh runs normally pass through the explicit Configuration stage first so research-config can materialize research_plan/RESEARCH_PLAN.json.
• Once the user confirms the start summary, do not ask again after each evolution round when the effective policy is iteration_policy = completion_driven and human_checkpoint = auto.
• Under completion_driven + auto, keep running until the routing plan reaches overview or inspect_state, or a validator/safety stop requires intervention. Final complete comes from the completion verifier after overview work.
• If you must stop before convergence or a terminal route, tell the user the run is paused, current convergence has not been reached, persisted state is resumable, and the next recommended action is continue evolution through resume or an explicit continue request.
• Never pass Claude-style key: value text straight into claude_project_cli; convert it to explicit flags first.
• Read execution semantics from repository-local SKILL.md files and dynamic context from canonical artifacts.
• Treat skills/ as canonical and .claude/skills/ as the Claude Code entry surface.
• Treat runs/<run_id>/dashboard/LINKS.md as the human-readable dashboard receipt and runs/<run_id>/dashboard/LINKS.json as the machine-readable receipt.