@synapse-research/synapse 0.2.11 → 0.2.13

package/dist/public/synapse-plugin/skills/autonomy/SKILL.md

@@ -1,140 +0,0 @@
----
-name: autonomy
-description: Drive the Claude Code-client autonomous research loop — analyze project state, propose the next experiment, dispatch sub-agents to execute it, and iterate.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: synapse
----
-
-# Autonomy Skill
-
-Use this skill when the user asks the Claude Code agent to drive research autonomously on a Synapse project: propose the next experiment, dispatch it, analyze the result, and repeat.
-
-This is the **CC-client autonomous loop**. It does not depend on the server-side `autonomousLoopEnabled` flag (that flag is for realtime-transport agents). The loop runs entirely inside the current Claude Code session: the main agent is the orchestrator, and sub-agents spawned via the Task tool are auto-enrolled by the plugin's `SubagentStart` hook.
-
-## Default Mode
-
-**Full auto** by default. When the user says "turn on autonomous loop", "run until done", or similar, assume full auto unless they say otherwise:
-
-- New experiment proposals are created as `pending_start` and immediately dispatched to sub-agents for execution.
-- The main agent does not wait for human approval between iterations.
-- The user can stop the loop at any time by interrupting the session; the main agent should also stop voluntarily once stop conditions (below) are met.
-
-If the user explicitly asks for "human review before each experiment", switch to **review mode**: proposals land as `pending_review` and the loop pauses until they are approved externally.
-
-## Prompt Boundary
-
-Stay inside this skill when the work is about:
-- reviewing the project state after experiments finish
-- deciding whether to propose the next experiment or wait for in-flight work
-- dispatching sub-agents to execute `pending_start` experiments
-- maintaining a rolling synthesis via `synapse_save_project_synthesis`
-- detecting stop conditions and exiting cleanly
-
-Hand off to:
-- **[experiments](../experiments/SKILL.md)** for the inner execution logic of one experiment (the sub-agent operates there)
-- **[research](../research/SKILL.md)** when the loop decides it needs new literature before the next experiment
-- **[sessions](../sessions/SKILL.md)** for how sub-agent sessions and heartbeats are auto-managed
-
-## Before Starting The Loop
-
-1. `synapse_checkin()` to refresh identity and current assignments.
-2. `synapse_get_project_full_context({ researchProjectUuid })` to load brief, evaluation methods, past experiments, latest synthesis, and compute availability.
-3. Confirm with the user:
-   - target project UUID
-   - mode (`full_auto` default, or `review`)
-   - optional budgets: `maxIterations`, `maxExperimentsProposed`, `maxComputeHours`
-4. If the project has no completed experiments, do not enter the loop cold. Offer the foundational path first (data prep + baseline + eval script — see **[experiments](../experiments/SKILL.md)**), then start the loop once the baseline is in place.
-
-## Iteration Procedure
-
-Each iteration of the loop follows the same shape. The main agent runs this until a stop condition triggers.
-
-1. **Refresh project state**
-   - `synapse_get_project_full_context({ researchProjectUuid })`
-   - `synapse_get_assigned_experiments({ researchProjectUuid, statuses: ["pending_start", "in_progress"] })`
-
-2. **Decide what this iteration should do**
-   - If any experiment is `in_progress`, the loop should **monitor**, not propose. Poll `synapse_get_experiment` for each running experiment, write a progress note to the user, and yield back so the next user turn re-enters the loop.
-   - If any experiment is `pending_start` (and mode is `full_auto`), **dispatch** it: spawn a Task-tool sub-agent with the experiment UUID in its prompt. The `SubagentStart` hook auto-injects the session UUID and execution workflow; the main agent does not need to call `synapse_create_session`.
-   - If the queue is empty and there are completed experiments to digest, **synthesize** first: read the current `project_synthesis` document via `synapse_get_documents({ type: "project_synthesis" })` + `synapse_get_document`, and update it with `synapse_save_project_synthesis` only if new results add something the existing synthesis does not already cover.
-   - If the queue is empty and synthesis is current, **propose** the next experiment with `synapse_propose_experiment`. One independent run per proposal — split comparisons, ablations, and parameter sweeps into separate proposals.
-
-3. **Respect compute reality**
-   - Before proposing, check availability with `synapse_list_compute_nodes({ researchProjectUuid, onlyAvailable: true })`. Do not over-propose concurrent experiments beyond what available GPUs can run.
-   - If the project has a `computePoolUuid`, reservations must stay inside that pool.
-
-4. **Log the decision**
-   - Add a short `synapse_add_comment({ targetType: "research_project", ... })` summarizing what this iteration decided and why. This gives the human a readable audit trail in the UI.
-
-5. **Check stop conditions**, then either return control to the user (normal case) or immediately re-run step 1 if the user asked for tight, unattended iteration within a single turn.
-
-## Monitor-Not-Executor
-
-The main agent does **not** SSH into GPU nodes, does **not** run training loops, and does **not** call `synapse_start_experiment` itself (unless the user explicitly tells it to run an experiment inline with no sub-agent). Its job is:
-
-- read state → decide → dispatch → monitor → synthesize → propose → repeat.
-
-All execution work — `synapse_start_experiment`, `synapse_get_node_access_bundle`, SSH, training, `synapse_report_experiment_progress`, `synapse_submit_experiment_results` — happens inside sub-agents. Spawn one Task sub-agent per `pending_start` experiment. Each sub-agent receives its session UUID and the full experiment workflow automatically via the `SubagentStart` hook.
-
-## Proposal Quality
-
-A good proposal includes:
-- **Motivation** — what previous result or gap this addresses
-- **Hypothesis** — what you expect to learn
-- **Method** — enough detail that a sub-agent can execute without further prompting
-- **Success criteria** — how the result will be judged against the project's evaluation method
-- **Compute fit** — realistic given current availability
-
-Bad proposals to avoid:
-- bundling multiple runs into one card
-- re-running something already completed
-- ignoring the project's stated evaluation methods
-- proposing work the available compute pool cannot support
-
-## Stop Conditions
-
-Exit the loop and report back to the user when any of these hold:
-
-- `maxIterations` reached (default: ask the user up front)
-- `maxExperimentsProposed` reached
-- `maxComputeHours` used across this loop's runs
-- synthesis has not materially changed for K consecutive iterations (no-progress detection)
-- the user interrupts or explicitly says "stop"
-- all research questions are `completed` and there is no promising direction left
-- compute pool is exhausted and no experiment is making forward progress
-
-On exit, summarize what was run, what was learned, the current state of the synthesis document, and any recommended follow-ups for a human.
-
-## Mutual Exclusion With The Server-Side Loop
-
-If `synapse_get_research_project` shows the project already has `autonomousLoopEnabled = true` and a loop agent assigned on the realtime side, do not also run the CC-client loop against it. Warn the user and either defer, or ask them to disable the server-side loop first — running both will double-dispatch proposals and reservations.
-
-## Typical Turn
-
-```
-synapse_checkin()
-synapse_get_project_full_context({ researchProjectUuid })
-synapse_get_assigned_experiments({ researchProjectUuid, statuses: ["pending_start", "in_progress"] })
-
-# Monitor in-flight experiments if any
-# Else dispatch pending_start via Task sub-agents
-# Else synthesize if new results need analysis
-# Else propose next experiment
-
-synapse_add_comment({
-  targetType: "research_project",
-  targetUuid: "<projectUuid>",
-  content: "Iteration N — dispatched experiment <uuid> / proposed <title> / no-op (synthesis current)"
-})
-```
-
-## Reference
-
-- **[Autonomous loop reference](../synapse/references/04-autonomous-loop.md)**
-- **[Experiments skill](../experiments/SKILL.md)**
-- **[Sessions skill](../sessions/SKILL.md)**
-- **[Common tools](../synapse/references/00-common-tools.md)**

package/dist/public/synapse-plugin/skills/experiments/SKILL.md

@@ -1,87 +0,0 @@
----
-name: experiments
-description: Plan, revise, execute, and report Synapse experiments, including compute access and result submission.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: synapse
----
-
-# Experiments Skill
-
-Use this skill for the experiment stage: drafting plans, revising returned experiments, running approved work, using compute, and submitting results.
-
-## Prompt Boundary
-
-Stay inside this skill when the work is about:
-- creating a brand-new experiment from scratch
-- `draft`, `pending_review`, `pending_start`, `in_progress`, or `completed` experiments
-- plan authoring or revision based on reviewer feedback
-- reserving GPUs and starting workloads
-- reporting progress and saving results
-- writing experiment result reports
-
-Hand off to:
-- **[research](../research/SKILL.md)** for literature and deep research
-- **[autonomy](../autonomy/SKILL.md)** to drive the CC-client autonomous loop when there is nothing to execute and you need to propose the next experiment
-- **[sessions](../sessions/SKILL.md)** when running multiple experiments in parallel via sub-agents
-
-## Empty-Assignment Onboarding
-
-If `synapse_get_assigned_experiments` returns empty, do not idle. Ask the user which path:
-
-1. **Execute an approved experiment** — list `pending_start` experiments in the project with `synapse_get_project_full_context` and ask which to start.
-2. **Flesh out a quick idea** — call `synapse_get_project_full_context`, then draft a plan with `synapse_create_experiment` (defaults to `pending_review`, or pass `status: "draft"` to keep refining).
-3. **Create the foundational experiment** — if the project has no completed experiments, offer the foundational template below.
-4. **Enter the autonomous loop** — hand off to **[autonomy](../autonomy/SKILL.md)** to propose and auto-dispatch the next experiment.
-
-## Foundational First Experiment
-
-If the project has no completed experiments yet, the first experiment is not a normal research run — it is the project's baseline infrastructure. Drive it through three bundled deliverables before any comparison work:
-
-1. **Data preparation** — normalize the raw dataset into a single canonical format every future experiment will consume. Keep the prep scripts under the project's repo (if one is configured via `synapse_get_repo_access`).
-2. **Baseline run** — execute the simplest reasonable approach end-to-end and record its metrics with `synapse_submit_experiment_results`, so subsequent experiments have something to beat.
-3. **Evaluation script** — implement the canonical eval harness future experiments will call. Commit alongside data prep.
-
-If the project has a repo, commit all three onto the base branch (or a per-experiment branch merged back). Every subsequent experiment branches from that base so it inherits prep + eval automatically.
-
-## Typical Flow
-
-1. `synapse_checkin()` — refresh identity and assignments
-2. Author or fetch the experiment
-   - New plan: `synapse_create_experiment(...)` (defaults to `pending_review`, or `status: "draft"` to keep editing)
-   - Existing assignment: `synapse_get_assigned_experiments()` then `synapse_get_experiment({ experimentUuid })`
-3. If drafting or revising: `synapse_update_experiment_status({ status: "draft", liveStatus: "writing" })` + `synapse_update_experiment_plan(...)`, then `synapse_update_experiment_status({ status: "pending_review" })`
-4. Before execution: `synapse_list_compute_nodes({ onlyAvailable: true, researchProjectUuid })`
-5. Reserve compute: optional `synapse_reserve_gpus(...)` or inline via `synapse_start_experiment({ gpuUuids })`
-6. `synapse_start_experiment({ experimentUuid, workingNotes })` — moves to `in_progress`
-7. If remote compute: `synapse_get_node_access_bundle({ experimentUuid, nodeUuid })`, write the returned `privateKeyPemBase64` to a local PEM, `chmod 600`, SSH with the returned host/user/port
-8. If repo-backed: `synapse_get_repo_access` → clone → branch from the experiment's base branch
-9. Run the workload in a persistent remote shell (`tmux`/`screen`) with unbuffered output (`python -u …` or `PYTHONUNBUFFERED=1`) so logs never stall a tool call
-10. Report progress with `synapse_report_experiment_progress` at milestones — `phase` ∈ `setup` | `training` | `evaluation` | `analysis`; `liveStatus` ∈ `checking_resources` | `queuing` | `running`
-11. For long runs (>30 min), schedule periodic progress updates (cron on the remote node, or the main agent polling and calling `synapse_report_experiment_progress` on a timer) so the card never looks dead
-12. Commit code/artifacts to the experiment branch or base branch; capture the commit SHA
-13. Finish with `synapse_submit_experiment_results({ outcome, experimentResults, branch, commitSha })` — `outcome` ∈ `success` | `failure` | `inconclusive`; on failure include the error and partial results
-14. If the flow asks for a dedicated report document: `synapse_save_experiment_report({ experimentUuid, title, content })` — do **not** post a full report as a comment
-15. If revising per reviewer feedback, read the full thread first with `synapse_get_comments({ targetType: "experiment", targetUuid })` before editing the plan
-
-## Core Rules
-
-- **Never assume a server-local SSH key path exists.** Always fetch the access bundle and write the PEM locally.
-- **One independent run per experiment card.** Do not bundle comparison runs, ablations, or parameter sweeps into a single experiment — create multiple cards.
-- **Match the project description's language.** If the project brief is in Chinese, write the plan, progress, and report in Chinese.
-- **Split plan / execution / report tools.** Use `synapse_update_experiment_plan` for plan edits, `synapse_report_experiment_progress` for live status, `synapse_submit_experiment_results` for completion, and `synapse_save_experiment_report` for the dedicated report. Do not substitute with comments.
-- **Revision stays durable.** When a reviewer sends an experiment back, flip to `draft`, revise, then move it back to `pending_review`; leave a reply via `synapse_add_comment` using `@[name](actorType:uuid)` format to notify the reviewer.
-- **Failures are data.** An experiment that crashes or shows a regression is still a valid submission: set `outcome: "failure"` (or `"inconclusive"`) and write up what happened in `experimentResults` and the report.
-
-## Running Multiple Experiments In Parallel
-
-When the user wants to execute several `pending_start` experiments at the same time, the main agent should monitor and dispatch rather than run workloads itself. Spawn one Task-tool sub-agent per experiment UUID — the plugin's `SubagentStart` hook auto-creates a Synapse session and injects the full execution workflow. The main agent then polls with `synapse_get_assigned_experiments({ statuses: ["in_progress", "completed"] })` and `synapse_get_experiment` to track progress. See **[sessions](../sessions/SKILL.md)** for the full pattern.
-
-## Reference
-
-- **[Experiment workflow reference](../synapse/references/03-experiment-workflow.md)**
-- **[Common tools](../synapse/references/00-common-tools.md)**
-- **[Plugin hooks and parallel execution](../synapse/references/05-session-sub-agent.md)**

package/dist/public/synapse-plugin/skills/research/SKILL.md

@@ -1,58 +0,0 @@
----
-name: research
-description: Work on Synapse pre-experiment research: project context, research questions, literature search, related works, and deep research reports.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: synapse
----
-
-# Research Skill
-
-Use this skill for the pre-experiment stage: understanding project context, developing research questions, grounding work in literature, and producing deep research outputs.
-
-## Prompt Boundary
-
-Stay inside this skill when the work is about:
-- reading project context and framing the problem
-- creating or progressing research questions
-- searching papers and reading them progressively
-- curating `RelatedWork`
-- writing or updating a deep research report
-
-Hand off to:
-- **[experiments](../experiments/SKILL.md)** once the work becomes experiment planning or execution
-- **[autonomy](../autonomy/SKILL.md)** to drive the CC-client autonomous loop when you are choosing the next experiment yourself
-
-## Empty-Project Onboarding
-
-If `synapse_get_research_questions` and `synapse_get_related_works` both return empty for the active project, do not guess a direction. Ask the user:
-
-1. **List existing literature** — does the user already have related works elsewhere that should be imported first?
-2. **Search new literature** — run `synapse_search_papers` against an initial topic phrase supplied by the user, and curate results with `synapse_add_related_work`.
-3. **Draft a research question** — create the first `ResearchQuestion` with `synapse_create_research_question` so later experiments have a framing to attach to.
-4. **Generate a deep research report** — once some related works exist, run the progressive-read flow below and save the synthesis with `synapse_save_deep_research_report`.
-
-Offer example invocations (with the project UUID filled in) so the user can pick one. Do not skip ahead to experiment planning from this skill.
-
-## Typical Flow
-
-1. `synapse_checkin()`
-2. `synapse_get_research_project()` or `synapse_get_project_full_context()`
-3. `synapse_get_research_questions()` or create/claim a question
-4. `synapse_search_papers()` and inspect papers with `brief` / `head` / `section` / `full`
-5. `synapse_add_related_work()` for durable project memory
-6. `synapse_save_deep_research_report()` when synthesizing findings (organize thematically, not paper-by-paper; cite specific methods/results; match the project description's language)
-7. `synapse_add_comment()` on the research question or project artifacts when reasoning should be durable
-8. If the task originated from a Synapse-triggered deep research or auto search, finish with `synapse_complete_task({ taskType: "deep_research" | "auto_search" })`
-
-## Core Rule
-
-Do not drift into experiment execution from this skill. Once you are drafting a runnable experiment plan, switch to **[experiments](../experiments/SKILL.md)**.
-
-## Reference
-
-- **[Research workflow reference](../synapse/references/02-research-workflow.md)**
-- **[Common tools](../synapse/references/00-common-tools.md)**

package/dist/public/synapse-plugin/skills/sessions/SKILL.md

@@ -1,174 +0,0 @@
----
-name: sessions
-description: Understand the Synapse Claude Code plugin hooks, session lifecycle, and multi-agent parallel execution. Covers what each hook does, where plugin state lives, and how to run multiple experiments in parallel via Task sub-agents.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: synapse
----
-
-# Sessions Skill
-
-Use this skill when the task is about how the Synapse plugin itself behaves inside Claude Code: which hooks fire, what they inject into context, how sub-agent sessions are managed, and how to dispatch multiple experiments in parallel to Task sub-agents.
-
-## Prompt Boundary
-
-Stay inside this skill when the work is about:
-- understanding why Synapse context appeared in the session (which hook injected it)
-- debugging a sub-agent that is not behaving as expected (session, heartbeat, or teardown issue)
-- deciding how a main agent should dispatch parallel experiment work across sub-agents
-- deciding when to call `synapse_create_session` / `synapse_close_session` directly instead of relying on hooks
-
-Hand off to:
-- **[experiments](../experiments/SKILL.md)** for the actual work inside one experiment
-- **[autonomy](../autonomy/SKILL.md)** for the CC-client autonomous loop
-
-## Core Rule
-
-For sub-agents spawned through the Task tool, sessions are fully automatic. Do not manually call `synapse_create_session` or `synapse_close_session` for a sub-agent unless you are debugging the lifecycle itself. The `SubagentStart` and `SubagentStop` hooks already do it.
-
-## Plugin Hooks At A Glance
-
-The plugin ships ten hooks wired up in `hooks/hooks.json`. Each reads/writes local state under `.synapse/` in the project and, when needed, calls Synapse MCP tools via the bundled `synapse-api.sh` wrapper.
-
-| Hook script | Claude Code event | What it does | State touched | MCP calls |
-|---|---|---|---|---|
-| `on-session-start.sh` | `SessionStart` (`startup` \| `resume` \| `compact`) | Calls `synapse_checkin`, caches owner / roles / project UUID into `state.json`, scans for pre-assigned sub-agent session files, and builds the rich `additionalContext` block that orients the agent on assignments, projects, and workflow. | `state.json`, reads `sessions/*.json` | `synapse_checkin`, optional `synapse_session_heartbeat` |
-| `on-user-prompt.sh` | `UserPromptSubmit` | Fast local-only check on every user turn. Scans `.synapse/sessions/` and injects a brief reminder that sub-agent sessions are auto-managed. No network calls (stays under 100 ms). | reads `sessions/` | none |
-| `on-pre-enter-plan.sh` | `PreToolUse` (`EnterPlanMode`) | Injects planning-mode guidance: prefer the current Experiment pipeline (`draft → pending_review → pending_start → in_progress → completed`), plan one independent run per experiment card, do not plan to create sessions manually. | none | none |
-| `on-pre-exit-plan.sh` | `PreToolUse` (`ExitPlanMode`) | Reminds the agent to verify that the plan is expressed as Experiment records before executing. | none | none |
-| `on-pre-spawn-agent.sh` | `PreToolUse` (`Task`) | Before a sub-agent is spawned, atomically writes `.synapse/pending/{name}` with the agent name and type so the `SubagentStart` hook can claim it. Skips read-only sub-agent types. | writes `pending/{name}` | none |
-| `on-subagent-start.sh` | `SubagentStart` | Atomically claims the pending file via `mv`, then either reuses an active session, reopens a closed one, or creates a new one via `synapse_list_sessions` / `synapse_reopen_session` / `synapse_create_session`. Writes `sessions/{name}.json`, stores the mapping in `state.json`, and injects the session UUID plus the execution workflow directly into the sub-agent's context. | `state.json`, `sessions/{name}.json`, `claimed/{agent_id}` | `synapse_list_sessions`, `synapse_create_session`, `synapse_reopen_session`, `synapse_session_heartbeat` |
-| `on-teammate-idle.sh` | `TeammateIdle` | When a teammate sub-agent idles between turns, sends a heartbeat so its Synapse session does not auto-time-out after 1 hour. Output suppressed — this fires too often to notify the user. | reads `state.json` | `synapse_session_heartbeat` |
-| `on-subagent-stop.sh` | `SubagentStop` | Looks up the session UUID, calls `synapse_close_session`, and cleans up `state.json`, `sessions/{name}.json`, and `claimed/{agent_id}`. | deletes state entries, `sessions/{name}.json`, `claimed/{agent_id}` | `synapse_close_session` |
-| `on-task-completed.sh` | `TaskCompleted` | Scans the completed task description/subject for a `synapse:experiment:<uuid>` marker. If found, injects a reminder to finalize the experiment with `synapse_submit_experiment_results` (or report progress if still running). | reads task metadata only | none |
-| `on-session-end.sh` | `SessionEnd` | Safety-checked cleanup. Removes `.synapse/` only when all sub-agent sessions are closed and `state.json` has no meaningful content left. | deletes `.synapse/` if safe | none |
-
-## Local State Layout
-
-The plugin keeps per-project state under `.synapse/` in the project working directory:
-
-- `state.json` — flock-guarded key/value store. Holds owner info cached from `synapse_checkin`, agent roles, the primary project UUID, and the `session_{…}` / `agent_for_session_{…}` / `name_for_agent_{…}` mappings used by the start/stop hooks.
-- `pending/{name}` — written by `on-pre-spawn-agent.sh`, atomically claimed by `on-subagent-start.sh` via `mv`.
-- `claimed/{agent_id}` — marker file showing which pending entry was claimed.
-- `sessions/{name}.json` — per-sub-agent session metadata: `sessionUuid`, `agentId`, `agentName`, `agentType`, `sessionAction`, `createdAt`. Other hooks (idle, stop, user-prompt) read from here to locate the session.
-
-`on-session-end.sh` removes `.synapse/` only when it is safe; otherwise state is preserved across sessions so resumed work reconnects to the same Synapse sessions.
-
-## MCP Connection Session vs Synapse Agent Session
-
-These are two different things — do not confuse them.
-
-- **MCP connection session** — the HTTP-streamable session on `/api/mcp`. Identified by the `mcp-session-id` header, auto-renewed on every request, expires after 30 minutes of inactivity. The plugin handles this transparently.
-- **Synapse agent session** — a durable record in Synapse of which agent is working on what (the green / yellow / grey indicators on the Settings page). Created/closed by the plugin hooks above, or explicitly by `synapse_create_session` / `synapse_close_session`.
-
-## Session Status Lifecycle
-
-```
-active ——(no heartbeat 1h)——> inactive ——(heartbeat)——> active
-  \                                 \
-   \—— close ——> closed ——(reopen)——> active
-```
-
-| Status | Meaning |
-|---|---|
-| `active` | Agent is working. Green indicator. |
-| `inactive` | No heartbeat in over an hour. Yellow indicator. |
-| `closed` | Session ended. Grey indicator. Can be reopened. |
-
-## Session Tools
-
-| Tool | Purpose |
-|---|---|
-| `synapse_list_sessions` | List sessions for the current agent. |
-| `synapse_get_session` | Read one session's details. |
-| `synapse_create_session` | Create a named session — usually only needed for direct (non-sub-agent) work. |
-| `synapse_close_session` | Close a session. |
-| `synapse_reopen_session` | Reopen a closed session instead of creating a duplicate with the same name. |
-| `synapse_session_heartbeat` | Keep a session active. Hooks already send heartbeats automatically. |
-
-## Running Multiple Experiments In Parallel
-
-When the main agent needs to execute several `pending_start` experiments concurrently, it should **orchestrate, not execute**. The plugin does the heavy lifting for session bookkeeping; the main agent only needs to spawn sub-agents and monitor.
-
-### Main agent: dispatch
-
-```text
-# 1. Refresh and list what needs to run
-synapse_checkin()
-synapse_get_assigned_experiments({ researchProjectUuid, statuses: ["pending_start"] })
-
-# 2. Inspect each candidate
-synapse_get_experiment({ experimentUuid })
-
-# 3. For each experiment, spawn a Task sub-agent with the experiment UUID in the prompt.
-#    The SubagentStart hook auto-creates/reuses a Synapse session and injects the
-#    execution workflow. The main agent does not need to call synapse_create_session.
-Task({
-  subagent_type: "general-purpose",
-  name: "training-worker-<short>",
-  prompt: "Your Synapse experiment UUID: <experiment-uuid>. Run the experiment end to end."
-})
-```
-
-### Sub-agent: execute
-
-Each sub-agent follows the full execution checklist in **[experiments](../experiments/SKILL.md)**: `synapse_start_experiment` → `synapse_list_compute_nodes` / `synapse_reserve_gpus` → `synapse_get_node_access_bundle` → run remotely (tmux + unbuffered) → `synapse_report_experiment_progress` at milestones → `synapse_submit_experiment_results` → optional `synapse_save_experiment_report`.
-
-### Main agent: monitor
-
-The main agent polls for completion rather than blocking on any one sub-agent:
-
-```text
-synapse_get_assigned_experiments({
-  researchProjectUuid,
-  statuses: ["in_progress", "completed"]
-})
-
-# For any experiment still in_progress, read its latest state
-synapse_get_experiment({ experimentUuid })
-
-# Once all have completed, synthesize / propose follow-ups
-synapse_propose_experiment({ researchProjectUuid, title, description })
-```
-
-### Sequential multi-experiment sub-agent
-
-A single sub-agent can also handle multiple experiments in order when dependencies matter:
-
-```text
-Task({
-  subagent_type: "general-purpose",
-  name: "sequential-worker",
-  prompt: """
-    Synapse experiments, in order (each depends on the previous):
-      1. <experiment-uuid-1> — baseline evaluation
-      2. <experiment-uuid-2> — ablation built on #1's results
-
-    For each: start_experiment → run → report_progress → submit_results.
-  """
-})
-```
-
-## Project-Level MCP For Sub-Agents
-
-Sub-agents only inherit Synapse MCP access if the MCP server is configured at the project level. Put the config in `.mcp.json` at the project root (the plugin bundle ships the template at `public/synapse-plugin/.mcp.json`). User-level-only MCP configs will not reach sub-agents.
-
-## Troubleshooting
-
-| Symptom | Likely cause / fix |
-|---|---|
-| Sub-agent cannot see Synapse tools | MCP is user-level only. Move `.mcp.json` to the project root. |
-| Sub-agent session shown as `inactive` | Heartbeat has not fired for 1 h. Usually the sub-agent crashed; respawn with the same name — `SubagentStart` will reopen the existing session instead of making a duplicate. |
-| Duplicate sessions appear with similar names | A previous sub-agent stopped without the `SubagentStop` hook firing (hard crash). Close stale sessions with `synapse_close_session`, then respawn. |
-| Main agent did not receive checkin context | `SessionStart` hook failed (check `SYNAPSE_URL`, `SYNAPSE_API_KEY`). Call `synapse_checkin()` manually to recover. |
-| Experiment stuck in `in_progress` | The sub-agent died before `synapse_submit_experiment_results`. Either resume by respawning the sub-agent with the same experiment UUID, or the main agent calls `synapse_report_experiment_progress` and then `synapse_submit_experiment_results({ outcome: "failure", experimentResults: { error: "..." } })` to close it out. |
-
-## Reference
-
-- **[Session and sub-agent reference](../synapse/references/05-session-sub-agent.md)**
-- **[Experiments skill](../experiments/SKILL.md)**
-- **[Autonomy skill](../autonomy/SKILL.md)**
-- **[Common tools](../synapse/references/00-common-tools.md)**

package/dist/public/synapse-plugin/skills/setup/SKILL.md

@@ -1,73 +0,0 @@
----
-name: setup
-description: Configure Synapse MCP access for Claude Code with project-level .mcp.json and verify the connection.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: synapse
----
-
-# Setup Skill
-
-Use this skill when the task is about getting Synapse connected inside Claude Code: API keys, MCP configuration, project-level `.mcp.json`, or connection debugging.
-
-## Scope
-
-This skill covers:
-- creating or locating a Synapse API key
-- configuring MCP with `SYNAPSE_URL` and `SYNAPSE_API_KEY`
-- preferring project-level `.mcp.json` so sub-agents inherit access
-- verifying access with `synapse_checkin()`
-
-This skill does not cover day-to-day research or experiment execution. Hand off to:
-- **[research](../research/SKILL.md)** for literature and research-question work
-- **[experiments](../experiments/SKILL.md)** for experiment planning and execution
-- **[sessions](../sessions/SKILL.md)** for plugin hook behavior and multi-agent parallel execution
-- **[autonomy](../autonomy/SKILL.md)** to drive the CC-client autonomous research loop
-
-## Recommended Flow
-
-1. Get an API key from the Synapse **Agents** page.
-2. Put Synapse MCP config at project level in `.mcp.json`.
-3. Restart Claude Code if needed.
-4. Call `synapse_checkin()` and confirm expected roles/tools are visible.
-
-## Project-Level MCP Template
-
-The plugin ships a project-level template at `public/synapse-plugin/.mcp.json`. The expected content is:
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "${SYNAPSE_URL}/api/mcp",
-      "headers": {
-        "Authorization": "Bearer ${SYNAPSE_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-## Verification
-
-Use:
-
-```text
-synapse_checkin()
-```
-
-If the connection is wrong, check:
-- the key starts with `syn_`
-- `SYNAPSE_URL` is reachable
-- Claude Code has reloaded the MCP config
-- the agent has the roles needed for the tools you expect to use
-
-## Reference
-
-- **[Synapse overview](../synapse/SKILL.md)**
-- **[Setup reference](../synapse/references/01-setup.md)**
-- **[Common tools](../synapse/references/00-common-tools.md)**