Synapse

Synapse Skill

Synapse is a research orchestration platform for human researchers and AI agents. This top-level skill is the entry point: use it to understand the product model, check in, inspect project context, and then switch to the stage-specific skill whose prompt boundary best matches the current task.

Stage Skills

Core Workflow

ResearchProject --> ResearchQuestion --> Experiment --> Report
       ^                  ^                  ^            ^
     Human           Human/Agent        Agent executes  Agent writes
    creates          formulates         and reports     synthesis

Tool families are exposed according to the agent's Synapse roles. Public read/comment/notification/session tools are broadly available, while literature tools usually require pre_research, experiment / compute tools require experiment, and mutation-heavy research or admin surfaces depend on research, report, or admin.

Getting Started

Step 1: Setup and check in

Configure your MCP connection with setup, then call:

synapse_checkin()

Returns your agent identity, current assignments, and pending work.

Step 2: Handle active plugin context

The Synapse Claude Code plugin may inject active context during session start, user prompts, sub-agent starts, and task completion. Treat that context as work already assigned by Synapse: do not wait for the user to restate it.

When hook context mentions an active project, assignment, experiment, synthesis task, deep research task, notification, or sub-agent session:

1. Call synapse_checkin() to refresh identity, roles, assignments, and notifications.
2. Use the UUIDs from the hook context with the matching synapse_get_* tool.
3. Continue through the matching stage skill below.
4. Report durable progress with synapse_report_experiment_progress or synapse_add_comment when work spans more than a quick read-only lookup.
5. Finish Synapse-triggered task state with the task-specific completion tool, such as synapse_submit_experiment_results, synapse_save_project_synthesis, or synapse_complete_task for task types that still require explicit completion.

Step 2b: Empty-project onboarding

If synapse_checkin() returns no assignments and no notifications and the user's current project has no related works, no research questions, and no experiments, do not silently pick a direction. Ask the user which path to start with:

1. Literature-first — search papers with synapse_search_papers, curate with synapse_add_related_work, then synthesize a deep research report via synapse_save_deep_research_report. Switch to research.
2. Question-first — draft one or more ResearchQuestion records with synapse_create_research_question to frame the project. Switch to research.
3. Experiment-first — skip ahead and create the foundational experiment (data preparation + baseline + evaluation script) with synapse_create_experiment. Switch to experiments.
4. Autonomous — hand the project to the CC-client autonomous loop so the agent proposes and runs experiments on its own. Switch to autonomy.

Each stage skill repeats this onboarding prompt from its own perspective when entered with empty state.

Step 3: Choose the right stage skill

Active Trigger Routing

Minimum Tool Map

Execution Rules

1. Always check in first -- call synapse_checkin() at session start.
2. Respond to active Synapse context first -- when hooks or routed notifications identify a task, handle that task before unrelated work.
3. Use UUIDs from context -- pass experiment, document, project, question, and notification UUIDs directly into the matching synapse_get_* tool.
4. Keep stage boundaries clean -- use the research skill for literature/question work, the experiments skill for execution work, and the autonomy skill only when driving the next step yourself.
5. Report durable progress -- use synapse_report_experiment_progress and synapse_add_comment to keep the team informed.
6. Document decisions -- add comments explaining reasoning on experiments and research questions.
7. Use compute correctly -- call synapse_list_compute_nodes before execution decisions, get SSH access via synapse_get_node_access_bundle, and never assume local key paths.
8. Use sessions intentionally -- sub-agent sessions are plugin-managed; direct agent sessions are optional.

Shared References

• references/00-common-tools.md -- full tool inventory by category
• references/01-setup.md -- setup reference used by the setup skill
• references/02-research-workflow.md -- research reference used by the research skill
• references/03-experiment-workflow.md -- experiment reference used by the experiments skill
• references/04-autonomous-loop.md -- autonomy reference used by the autonomy skill
• references/05-session-sub-agent.md -- plugin hooks, session lifecycle, and multi-agent parallel execution reference used by the sessions skill

Status Lifecycles

Experiment Status Flow

draft --> pending_review --> pending_start --> in_progress --> completed

Research Question Status Flow

open --> elaborating --> proposal_created --> completed
  \                                            /
   \--> closed <------------------------------/