@synapse-research/synapse 0.2.12 → 0.2.13

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

@@ -1,176 +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. If this is the assigned autonomous-loop
-# agent, propose follow-ups; otherwise use synapse_create_experiment for
-# user-directed terminal work.
-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,108 +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. Set `SYNAPSE_URL` and `SYNAPSE_API_KEY` **in one place** (see "Where the credentials live" below).
-3. Restart Claude Code so it reloads MCP config and re-evaluates env.
-4. Call `synapse_checkin()` and confirm expected roles/tools are visible.
-
-The plugin already ships its own `.mcp.json` (at `public/synapse-plugin/.mcp.json` inside the plugin bundle), so you do **not** need to copy a `.mcp.json` into your project. Installing the plugin makes the MCP server available; the only thing you supply is the env values.
-
-## Where The Credentials Live (Important)
-
-The plugin's bundled `.mcp.json` carries `${SYNAPSE_URL}` and `${SYNAPSE_API_KEY}` placeholders. Claude Code substitutes them at MCP-server-startup time from your env. You only put the real values in **one** location:
-
-- **User-level Claude Code settings** — `~/.claude/settings.json`'s `env` block. Best for personal use across projects.
-  ```json
-  {
-    "env": {
-      "SYNAPSE_URL": "http://localhost:3000",
-      "SYNAPSE_API_KEY": "syn_..."
-    }
-  }
-  ```
-- **Project-level Claude Code settings** — `<project>/.claude/settings.json`'s `env` block. Best when several teammates share a project but each needs their own key (use `.claude/settings.local.json` for personal values; never commit the key).
-- **Shell environment** — `export SYNAPSE_URL=...; export SYNAPSE_API_KEY=...` in your shell rc, before launching Claude Code. Ad-hoc only.
-
-The plugin's bash hooks (`SessionStart`, `PostToolUse`, etc.) also read the same two env variables, so a single env source covers both the MCP server and the hook scripts.
-
-## Plugin's Own `.mcp.json` (For Reference)
-
-You don't need to edit or copy this file — the plugin ships and loads it automatically:
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "${SYNAPSE_URL}/api/mcp",
-      "headers": {
-        "Authorization": "Bearer ${SYNAPSE_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-If you have a strong reason to override (e.g. add `X-Synapse-Project` filter headers for one project), you can add a `.mcp.json` at your project root that defines a different `synapse` server entry — Claude Code project-level config takes precedence.
-
-## Roles That Matter
-
-Set the agent's roles on the **Agents** page based on what you expect Claude Code to do:
-
-- `pre_research` — paper search, literature reading.
-- `research` — research-question CRUD.
-- `experiment` — create/start/report/submit experiments, compute tools.
-- `report` — document and synthesis tools.
-- `admin` / `pi_agent` — needed if Claude Code should call `synapse_review_experiment` to carry the user's verbal approve / reject from the terminal into Synapse. Without one of these, `/api/experiments/<uuid>/review` returns 403.
-
-If the same Claude Code agent should both execute experiments and verbally-approve them, give it both `experiment` and `admin` (or `pi_agent`).
-
-## 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 env variables actually reach the MCP server process (`echo $SYNAPSE_URL` from the same shell that launches Claude Code)
-- 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)**

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

@@ -1,145 +0,0 @@
----
-name: synapse
-description: Synapse platform overview and router skill. Use it to orient on projects and then hand off to the stage-specific Synapse skills.
-license: AGPL-3.0
-metadata:
-  author: Vincentwei1021
-  version: "0.6.1"
-  category: research
-  mcp_server: 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
-
-| Skill | When to use it |
-|------|-----------------|
-| **[setup](../setup/SKILL.md)** | Configure MCP, API keys, and project-level `.mcp.json` |
-| **[research](../research/SKILL.md)** | Research questions, literature search, related works, deep research |
-| **[experiments](../experiments/SKILL.md)** | Experiment planning, revision, execution, compute, and result submission |
-| **[autonomy](../autonomy/SKILL.md)** | Autonomous loop and next-experiment proposal work |
-| **[sessions](../sessions/SKILL.md)** | Plugin hooks, session lifecycle, and multi-agent parallel execution |
-
-## Core Workflow
-
-```text
-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](../setup/SKILL.md)**, then call:
-
-```text
-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](../research/SKILL.md)**.
-2. **Question-first** — draft one or more `ResearchQuestion` records with `synapse_create_research_question` to frame the project. Switch to **[research](../research/SKILL.md)**.
-3. **Experiment-first** — skip ahead and create the foundational experiment (data preparation + baseline + evaluation script) with `synapse_create_experiment`. Switch to **[experiments](../experiments/SKILL.md)**.
-4. **Autonomous** — hand the project to the CC-client autonomous loop so the agent proposes and runs experiments on its own. Switch to **[autonomy](../autonomy/SKILL.md)**.
-
-Each stage skill repeats this onboarding prompt from its own perspective when entered with empty state.
-
-### Step 3: Choose the right stage skill
-
-| Current work | Skill to use |
-|--------------|---------------|
-| Understanding project context and project state | Stay here, then call `synapse_get_project_full_context()` |
-| Research questions, literature, deep research | **[research](../research/SKILL.md)** |
-| Experiment drafting, revision, execution, compute, reporting | **[experiments](../experiments/SKILL.md)** |
-| Autonomous next-step proposal, queue-empty behavior, driving the CC-client autonomous loop | **[autonomy](../autonomy/SKILL.md)** |
-| Plugin hook behavior, session tracking, multi-agent parallel dispatch in Claude Code | **[sessions](../sessions/SKILL.md)** |
-
-## Active Trigger Routing
-
-| Trigger or hook context | First action | Then use |
-|-------------------------|--------------|----------|
-| Experiment assignment or assigned experiment UUID | `synapse_get_experiment({ experimentUuid })` | **[experiments](../experiments/SKILL.md)** to start, run, report progress, and submit results |
-| Experiment plan requested | `synapse_get_experiment()` plus `synapse_get_project_full_context()` | **[experiments](../experiments/SKILL.md)** to update the plan |
-| Experiment revision requested | `synapse_get_experiment()` and read relevant comments if needed | **[experiments](../experiments/SKILL.md)** to revise and resubmit/update |
-| Experiment report requested | `synapse_get_experiment()` and inspect completed results | **[experiments](../experiments/SKILL.md)** to write the report/result document |
-| Research question claimed | `synapse_get_research_question()` and `synapse_get_project_full_context()` | **[research](../research/SKILL.md)** |
-| Deep research requested | `synapse_get_project_full_context()`, `synapse_get_related_works()`, then existing report via `synapse_get_deep_research_report()` | **[research](../research/SKILL.md)**; call `synapse_complete_task({ taskType: "deep_research" })` when done |
-| Auto search triggered | `synapse_get_project_full_context()` and inspect existing related works | **[research](../research/SKILL.md)** to search, add related works, and complete the task if required |
-| Synthesis refresh requested | `synapse_get_project_full_context()`, `synapse_get_documents({ type: "project_synthesis" })`, then `synapse_get_document()` if one exists | Save only if new results need analysis; `synapse_save_project_synthesis()` clears the active synthesis task |
-| Autonomous loop or empty queue | `synapse_get_project_full_context()` and `synapse_list_compute_nodes({ researchProjectUuid })` | **[autonomy](../autonomy/SKILL.md)** to drive the CC-client loop |
-| @mention or comment notification | `synapse_get_comments()` for the target when available | Reply with `synapse_add_comment()` using the `@[name](actorType:uuid)` format |
-| Sub-agent start/session context | Use the injected experiment UUID, then `synapse_get_experiment()` | **[sessions](../sessions/SKILL.md)** for hook behavior and **[experiments](../experiments/SKILL.md)** for work execution |
-
-## Minimum Tool Map
-
-| Need | Tools |
-|------|-------|
-| Identity, assignments, notifications | `synapse_checkin`, `synapse_get_notifications`, `synapse_mark_notification_read` |
-| Project context | `synapse_get_research_project`, `synapse_get_project_full_context` |
-| Documents and synthesis | `synapse_get_documents`, `synapse_get_document`, `synapse_save_project_synthesis` |
-| Literature and deep research | `synapse_search_papers`, `synapse_add_related_work`, `synapse_get_related_works`, `synapse_get_deep_research_report` |
-| Research questions | `synapse_get_research_question` and research-question mutation tools when roles allow |
-| Experiments | `synapse_get_assigned_experiments`, `synapse_get_experiment`, `synapse_create_experiment`, `synapse_start_experiment`, `synapse_report_experiment_progress`, `synapse_submit_experiment_results`, `synapse_propose_experiment` (autonomous loop only) |
-| PI/Admin review | `synapse_review_experiment` |
-| Compute | `synapse_list_compute_nodes`, `synapse_reserve_gpus`, `synapse_get_node_access_bundle` |
-| Collaboration | `synapse_add_comment`, `synapse_get_comments`, `synapse_search_mentionables` |
-| Task cleanup | `synapse_complete_task` except where a task-specific save/submit tool already clears state |
-
-## 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](references/00-common-tools.md)** -- full tool inventory by category
-- **[references/01-setup.md](references/01-setup.md)** -- setup reference used by the `setup` skill
-- **[references/02-research-workflow.md](references/02-research-workflow.md)** -- research reference used by the `research` skill
-- **[references/03-experiment-workflow.md](references/03-experiment-workflow.md)** -- experiment reference used by the `experiments` skill
-- **[references/04-autonomous-loop.md](references/04-autonomous-loop.md)** -- autonomy reference used by the `autonomy` skill
-- **[references/05-session-sub-agent.md](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
-```text
-draft --> pending_review --> pending_start --> in_progress --> completed
-```
-
-### Research Question Status Flow
-```text
-open --> elaborating --> proposal_created --> completed
-  \                                            /
-   \--> closed <------------------------------/
-```

package/dist/public/synapse-plugin/skills/synapse/package.json

@@ -1,49 +0,0 @@
-{
-  "name": "synapse",
-  "version": "0.7.0",
-  "description": "Synapse research orchestration platform skill for Claude Code. Manage research projects, experiments, literature, and compute resources via MCP tools.",
-  "author": "Vincentwei1021",
-  "license": "AGPL-3.0",
-  "keywords": [
-    "synapse",
-    "skill",
-    "research",
-    "ai-agent",
-    "mcp",
-    "experiments",
-    "compute",
-    "collaboration",
-    "claude-code"
-  ],
-  "synapse": {
-    "category": "research",
-    "mcp_server": "synapse",
-    "files": {
-      "SKILL.md": "SKILL.md",
-      "references/00-common-tools.md": "references/00-common-tools.md",
-      "references/01-setup.md": "references/01-setup.md",
-      "references/02-research-workflow.md": "references/02-research-workflow.md",
-      "references/03-experiment-workflow.md": "references/03-experiment-workflow.md",
-      "references/04-autonomous-loop.md": "references/04-autonomous-loop.md",
-      "references/05-session-sub-agent.md": "references/05-session-sub-agent.md"
-    },
-    "requires": {
-      "mcp": ["synapse"]
-    },
-    "triggers": [
-      "synapse",
-      "checkin",
-      "research project",
-      "experiment",
-      "research question",
-      "compute",
-      "literature",
-      "propose experiment",
-      "session",
-      "sub-agent",
-      "plugin hook",
-      "deep research",
-      "autonomous loop"
-    ]
-  }
-}

package/dist/public/synapse-plugin/skills/synapse/references/00-common-tools.md

@@ -1,144 +0,0 @@
-# MCP Tools Reference
-
-Endpoint: `POST /api/mcp` (HTTP Streamable transport)
-
-Auth: `Authorization: Bearer syn_...`
-
-Tool availability is enforced server-side by the agent's Synapse roles. Public read/comment/notification/session tools are broadly available; literature tools usually require `pre_research`; experiment execution and compute tools require `experiment`; question / project mutation tools depend on `research`, `report`, or `admin`.
-
----
-
-## Public Context
-
-| Tool | Description |
-|------|-------------|
-| `synapse_checkin` | Agent check-in. Returns identity, roles, assignments, notifications, and project summaries. |
-| `synapse_list_research_projects` | List visible research projects. |
-| `synapse_get_research_project` | Get project details. |
-| `synapse_get_project_full_context` | Get the canonical project context snapshot: questions, experiments with UUIDs, related-work paper titles, document references, synthesis hints, and compute availability summary. |
-| `synapse_get_activity` | Get the project activity stream. |
-| `synapse_get_documents` | List project documents. |
-| `synapse_get_document` | Read a document in full. |
-| `synapse_add_comment` | Add a durable comment. Prefer `research_question`, `experiment`, or `document` targets. |
-| `synapse_get_comments` | Read the full discussion thread for an entity. |
-| `synapse_get_notifications` | Fetch notifications. Unread notifications auto-mark as read unless `autoMarkRead: false`. |
-| `synapse_mark_notification_read` | Explicitly mark a notification read when needed. Usually optional because `synapse_get_notifications` handles unread notifications by default. |
-| `synapse_search_mentionables` | Search people / agents before composing an `@mention`. |
-| `synapse_get_project_groups` | List project groups and summary metrics. |
-| `synapse_get_project_group` | Read a single project group with its projects. |
-| `synapse_get_group_dashboard` | Get aggregated project-group dashboard data. |
-
----
-
-## Research Questions
-
-Usually requires a research-oriented role.
-
-| Tool | Description |
-|------|-------------|
-| `synapse_get_research_questions` | List research questions for a project. |
-| `synapse_get_research_question` | Read one research question in detail. |
-| `synapse_get_available_research_questions` | List claimable questions (`status=open`). |
-| `synapse_claim_research_question` | Claim a question for elaboration. |
-| `synapse_release_research_question` | Release a previously claimed question. |
-| `synapse_update_research_question_status` | Move a question through `open -> elaborating -> proposal_created -> completed` as appropriate. |
-
----
-
-## Experiments And Compute
-
-Requires the `experiment` tool family.
-
-| Tool | Description |
-|------|-------------|
-| `synapse_get_assigned_experiments` | List experiments assigned to the current agent. |
-| `synapse_get_experiment` | Read one experiment in full. |
-| `synapse_create_experiment` | Create a new experiment outside autonomous loop. Defaults to `pending_review`; can also create a `draft` for further refinement. |
-| `synapse_update_experiment_status` | Move an experiment between `draft`, `pending_review`, and `pending_start` during planning or revision. Can also set `liveStatus` / `liveMessage`. |
-| `synapse_update_experiment_plan` | Flesh out or revise an experiment plan: title, description, linked research question, priority. |
-| `synapse_start_experiment` | Move an experiment into execution. Optionally reserve GPUs inline. |
-| `synapse_reserve_gpus` | Reserve GPUs before starting when you want explicit control over allocation. |
-| `synapse_report_experiment_progress` | Report live progress to the experiment card and timeline. Supports `liveStatus` such as `queuing`, `checking_resources`, or `running`. |
-| `synapse_submit_experiment_results` | Finish an experiment and submit structured results. |
-| `synapse_save_experiment_report` | Create or update the dedicated experiment result document after completion. |
-| `synapse_propose_experiment` | Autonomous-loop only: propose the next experiment when the caller is the assigned loop agent. Human-review mode creates `pending_review`; full-auto mode creates `pending_start` and auto-assigns it back to the agent. Use `synapse_create_experiment` for user-directed terminal work. |
-| `synapse_list_compute_nodes` | List pools, nodes, GPUs, and access details. |
-| `synapse_get_node_access_bundle` | Get managed SSH access details and `privateKeyPemBase64`. |
-| `synapse_sync_node_inventory` | Sync node instance metadata and GPU inventory. |
-| `synapse_report_gpu_status` | Report GPU lifecycle or telemetry updates. |
-| `synapse_get_repo_access` | Get repository credentials and the experiment's base branch when a project is repo-backed. |
-
----
-
-## PI / Admin Review
-
-Requires `admin`, `pi`, or `pi_agent`.
-
-| Tool | Description |
-|------|-------------|
-| `synapse_review_experiment` | Approve a pending experiment into `pending_start` or reject it back to `draft`. Use this for Claude Code terminal review flows. |
-
-### `reviewNote` Formatting
-
-`synapse_review_experiment` records `reviewNote` in:
-- the activity entry,
-- the recipient notification,
-- and (on reject) a comment authored by the actor.
-
-The wording matters because the actor is the agent — `reviewNote` is what makes the human voice visible in audit. Use these formats:
-
-- **Verbal approve (Claude Code terminal):**
-  ```
-  reviewNote: 'User verbally approved in terminal: "<exact words from the user>"'
-  ```
-- **Verbal reject (Claude Code terminal):** summarize the user's revision request in second-person Chinese, including a quoted phrase. Example:
-  ```
-  reviewNote: '用户口头要求修改：把 batch size 改回 32（原话："那个 batch size 改回 32 试试"）'
-  ```
-  The tool writes the comment and emits `experiment_revision_requested` automatically — **do not** also call `synapse_add_comment`.
-- **Claude Code full-auto auto-approve:**
-  ```
-  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'
-  ```
-  Or, if self-review failed:
-  ```
-  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review skipped: <reason>.'
-  ```
-
----
-
-## Literature And Related Works
-
-Usually requires `pre_research`.
-
-| Tool | Description |
-|------|-------------|
-| `synapse_search_papers` | Search papers via DeepXiv hybrid search with arXiv fallback. |
-| `synapse_read_paper_brief` | Fast paper summary. |
-| `synapse_read_paper_head` | Section map plus section TLDRs. |
-| `synapse_read_paper_section` | Read a single section in full. |
-| `synapse_read_paper_full` | Read the full paper as Markdown. Use sparingly. |
-| `synapse_add_related_work` | Add a paper to a project's related works. Duplicate adds are skipped. |
-| `synapse_get_related_works` | List all papers already collected for a project. |
-| `synapse_get_deep_research_report` | Load the current literature-review document, if one exists. |
-| `synapse_save_deep_research_report` | Create or update the literature-review document and increment its version on update. |
-| `synapse_complete_task` | Clear the active `auto_search` or `deep_research` task after a Synapse-triggered run finishes. |
-
----
-
-## Sessions
-
-| Tool | Description |
-|------|-------------|
-| `synapse_list_sessions` | List sessions for the current agent. |
-| `synapse_get_session` | Read one session. |
-| `synapse_create_session` | Create a session for direct work. For Claude sub-agents, let the plugin hooks manage sessions automatically. |
-| `synapse_close_session` | Close a session. |
-| `synapse_reopen_session` | Reopen a closed session instead of creating a duplicate. |
-| `synapse_session_heartbeat` | Keep a session active. |
-
----
-
-## Compatibility Note
-
-Legacy `ExperimentDesign` / `ExperimentRun` surfaces still exist in the repository for compatibility, but this Claude plugin intentionally centers the current `ResearchQuestion -> Experiment` workflow.