@synapse-research/synapse 0.2.12 → 0.2.13

package/dist/public/skill/references/00-common-tools.md

@@ -1,253 +0,0 @@
-# Common Tools (All Roles)
-
-All Agent roles can use the following tools for querying information and collaboration.
-
----
-
-## Checkin
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_checkin` | First call: get Agent persona, role, current assignments, pending work counts, and **unread notification count** |
-
-The checkin response includes **owner/master information** for the agent:
-- `agent.owner`: `{ uuid, name, email }` or `null` — the human user who owns this agent
-- Use the owner info to know who to @mention for confirmations and approvals (e.g., after elaboration, before validating)
-
-### Project Filtering
-
-Results can be filtered by project(s) using optional HTTP headers in your `.mcp.json` configuration:
-
-| Header | Format | Example |
-|--------|--------|---------|
-| `X-Synapse-Project` | Single UUID or comma-separated UUIDs | `project-uuid-1` or `uuid1,uuid2,uuid3` |
-| `X-Synapse-Project-Group` | Group UUID | `group-uuid-here` |
-
-**Behavior**:
-- **No header**: Returns all projects (default, backward compatible)
-- **X-Synapse-Project**: Returns only specified project(s)
-- **X-Synapse-Project-Group**: Returns all projects in the group
-- **Priority**: `X-Synapse-Project-Group` takes precedence if both headers are provided
-
-**Affected tools**: `synapse_checkin`, `synapse_get_my_assignments`
-
-**Example `.mcp.json`**:
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "http://localhost:3000/api/mcp",
-      "headers": {
-        "Authorization": "Bearer syn_xxx",
-        "X-Synapse-Project": "project-uuid-1,project-uuid-2"
-      }
-    }
-  }
-}
-```
-
----
-
----
-
-## Session Lifecycle
-
-MCP sessions implement **sliding window expiration** — sessions expire after 30 minutes of **inactivity**, not from creation time.
-
-**Key points**:
-- Each request automatically renews the session (updates `lastActivity`)
-- Active agents can work indefinitely without timeout
-- Inactive sessions are cleaned up every 5 minutes
-- Server restart clears all sessions (clients should auto-reconnect)
-
-**When you see "Session not found" (HTTP 404)**:
-- The session expired due to inactivity or server restart
-- Your MCP client should automatically reinitialize
-- This is transparent in clients with auto-reconnect support
-
----
-
-## Project Groups
-
-Projects can be organized into **Project Groups** — a single-level grouping for categorizing related projects together (e.g., all projects for the same product). A project belongs to at most one group, or can be ungrouped.
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_project_groups` | List all project groups with project counts |
-| `synapse_get_project_group` | Get a single project group by UUID with its projects list |
-| `synapse_get_group_dashboard` | Get aggregated dashboard stats for a project group |
-
----
-
-## Project & Activity
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_list_projects` | List all projects for the current company (paginated). Returns projects with counts of ideas, documents, tasks, and proposals. |
-| `synapse_get_project` | Get project details and background information |
-| `synapse_get_activity` | Get project activity stream (paginated) |
-
----
-
-## Ideas
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_ideas` | List project Ideas (filterable by status, paginated) |
-| `synapse_get_idea` | Get a single Idea's details |
-| `synapse_get_available_ideas` | Get claimable Ideas (status=open) |
-
----
-
-## Documents
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_documents` | List project documents (filterable by type: prd, tech_design, adr, spec, guide) |
-| `synapse_get_document` | Get a single document's content |
-
----
-
-## Proposals
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_proposals` | List project Proposals (filterable by status: pending, approved, rejected) |
-| `synapse_get_proposal` | Get a single Proposal's details, including documentDrafts and taskDrafts |
-
----
-
-## Tasks
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_list_tasks` | List project Tasks (filterable by status/priority/proposalUuids, paginated) |
-| `synapse_get_task` | Get a single Task's details and context |
-| `synapse_get_available_tasks` | Get claimable Tasks (status=open, optional proposalUuids filter) |
-| `synapse_get_unblocked_tasks` | Get tasks ready to start — all dependencies resolved (done/closed). Optional proposalUuids filter. `to_verify` is NOT considered resolved. |
-
-**Proposal filtering** — `synapse_list_tasks`, `synapse_get_available_tasks`, and `synapse_get_unblocked_tasks` all accept an optional `proposalUuids` parameter (array of proposal UUID strings). When provided, only tasks belonging to those proposals are returned. When omitted, all tasks are returned (backward compatible).
-
-```
-// Example: filter tasks by two proposals
-synapse_list_tasks({ projectUuid: "...", proposalUuids: ["proposal-uuid-1", "proposal-uuid-2"] })
-```
-
----
-
-## Assignments
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_my_assignments` | Get all Ideas and Tasks claimed by you |
-
----
-
-## Comments
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_add_comment` | Add a comment to an idea/proposal/task/document |
-| `synapse_get_comments` | Get the comment list for a target (paginated) |
-
-**Parameters for `synapse_add_comment`:**
-- `targetType`: `"idea"` / `"proposal"` / `"task"` / `"document"`
-- `targetUuid`: Target UUID
-- `content`: Comment content (Markdown)
-
----
-
-## Elaboration
-
-Requirements elaboration tools allow any agent to answer elaboration questions and view elaboration state for Ideas. The PM Agent creates elaboration rounds (via `synapse_pm_start_elaboration`), and any agent or user can answer questions and check status.
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_answer_elaboration` | Submit answers for an elaboration round on an Idea |
-| `synapse_get_elaboration` | Get the full elaboration state for an Idea (rounds, questions, answers, summary) |
-
-**Parameters for `synapse_answer_elaboration`:**
-- `ideaUuid`: Idea UUID
-- `roundUuid`: Elaboration round UUID
-- `answers`: Array of answer objects:
-  - `questionId`: Question ID to answer
-  - `selectedOptionId`: Selected option ID (or `null` if using custom text only)
-  - `customText`: Custom text answer (or `null` if using selected option only)
-
-**Parameters for `synapse_get_elaboration`:**
-- `ideaUuid`: Idea UUID
-
----
-
-## @Mentions
-
-Use @mentions to notify specific users or agents in comments, task descriptions, and idea content. Mention syntax: `@[DisplayName](type:uuid)` where type is `user` or `agent`.
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_search_mentionables` | Search for users and agents that can be @mentioned |
-
-**Parameters for `synapse_search_mentionables`:**
-- `query`: Name or keyword to search
-- `limit`: Max results to return (default: 10)
-
-**Mention workflow:**
-1. Search for mentionable users/agents: `synapse_search_mentionables({ query: "yifei" })`
-2. Use the returned UUID to write mentions in your content: `@[Yifei](user:uuid-here)`
-3. When the content is saved (comment, task update, idea update), mentioned users/agents automatically receive a notification
-
-**Permission scoping:**
-- User caller: can mention all company users + own agents
-- Agent caller: can mention all company users + same-owner agents
-
-**When to @mention (key events):**
-- **Elaboration completion** — After reviewing elaboration answers, @mention the answerer (typically the agent's owner) to confirm your understanding before validating. See [02-pm-workflow.md](02-pm-workflow.md) Step 4 for the full elaboration confirmation flow.
-- **Proposal creation/update** — @mention relevant stakeholders (idea creator, owner) when submitting a proposal for review
-- **Task submission** — @mention the PM or owner when submitting work for verification, especially if the task involved significant decisions or trade-offs
-- **Blocking issues** — @mention the relevant person when you encounter a blocker that requires human input
-
----
-
-## Notifications
-
-Agents receive in-app notifications for events relevant to them (task assignments, proposal approvals, comments, etc.). The `synapse_checkin` response includes an `notifications.unreadCount` field — **check this value after checkin** and review your notifications if the count is non-zero.
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_get_notifications` | Get your notifications (default: unread only, paginated) |
-| `synapse_mark_notification_read` | Mark a single notification or all notifications as read |
-
-**Parameters for `synapse_get_notifications`:**
-- `status`: `"unread"` (default) / `"read"` / `"all"`
-- `limit`: Max results (default: 20)
-- `offset`: Pagination offset (default: 0)
-- `autoMarkRead`: Automatically mark fetched unread notifications as read (default: `true`)
-
-**Parameters for `synapse_mark_notification_read`:**
-- `notificationUuid`: UUID of a single notification to mark as read
-- `all`: Set to `true` to mark all notifications as read (use one or the other)
-
-**Recommended workflow:**
-1. Call `synapse_checkin()` — check `notifications.unreadCount`
-2. If unreadCount > 0, call `synapse_get_notifications()` to review them — notifications are auto-marked as read
-3. To peek without marking read: `synapse_get_notifications({ autoMarkRead: false })`
-4. `synapse_mark_notification_read` is still available for manual control if needed
-
-**Notification types you may receive:**
-- `task_assigned` — A task was assigned to you
-- `task_verified` — Your task was verified by admin
-- `task_reopened` — Your task was reopened
-- `proposal_approved` / `proposal_rejected` — Your proposal was reviewed
-- `comment_added` — Someone commented on your idea/task/proposal
-- `idea_claimed` — Your idea was claimed by another agent
-- `mentioned` — Someone @mentioned you in a comment, task, or idea
-
----
-
-## Usage Tips
-
-- Call `synapse_checkin()` at the start of each conversation to understand your role, pending items, and unread notifications
-- Use `synapse_get_project` + `synapse_get_documents` to understand project background before starting work
-- Use `synapse_get_activity` to see what happened recently and avoid duplicate work
-- Use `synapse_add_comment` to record decision rationale, ask questions, and hold discussions

package/dist/public/skill/references/01-setup.md

@@ -1,251 +0,0 @@
-# Setup: MCP Configuration & Skill Management
-
-## Objective
-
-Configure the Synapse MCP server so your AI Agent can communicate with the Synapse platform, and set up skill download/update.
-
----
-
-## 1. Obtain API Key
-
-API Keys must be created manually by the user in the Synapse Web UI — Agents cannot obtain them on their own.
-
-**Ask the user to complete the following steps:**
-
-1. Open the Synapse settings page in a browser (e.g., `http://localhost:3000/settings`)
-2. Click **Create API Key**
-3. Enter the Agent name
-4. Select the Agent **role** (Developer / PM / Admin)
-5. Optional: Choose a persona preset or customize the persona
-6. Click create and **immediately copy the generated API Key** (shown only once)
-
-If the user does not have an API Key yet, inform them:
-
-> I need a Synapse API Key to connect to the platform. Please create an API Key on the Synapse settings page (Settings > Agents), select the appropriate role, and share the Key with me.
-
-**Security notes:**
-- Each Agent should have its own API Key with the minimum required role
-- Admin Keys have the highest privileges; only use them when management operations are needed
-- API Keys should not be committed to version control
-
----
-
-## 2. MCP Server Configuration
-
-### HTTP Mode
-
-Synapse MCP uses the HTTP transport protocol, with the API Key passed via the `Authorization` header.
-
-Replace `<BASE_URL>` with the Synapse address provided by the user (e.g., `https://synapse.acme.com` or `http://localhost:3000`).
-
-> API Keys are prefixed with `syn_`, e.g., `syn_PXPnHpnmmYk8...`
-
-### Claude Code
-
-Config file location: `.mcp.json` in the project root (or globally at `~/.claude/.mcp.json`).
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "type": "http",
-      "url": "<BASE_URL>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer <your-api-key>"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Code after configuration for MCP to take effect.
-
-### Amazon Kiro
-
-Config file location: `.kiro/settings/mcp.json` in the project root (or globally at `~/.kiro/settings/mcp.json`).
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "url": "<BASE_URL>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer <your-api-key>"
-      }
-    }
-  }
-}
-```
-
-Restart Kiro after configuration for MCP to take effect.
-
-### Cursor
-
-Config file location: `.cursor/mcp.json` in the project root (or globally at `~/.cursor/mcp.json`).
-
-```json
-{
-  "mcpServers": {
-    "synapse": {
-      "url": "<BASE_URL>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer <your-api-key>"
-      }
-    }
-  }
-}
-```
-
-Restart Cursor after configuration for MCP to take effect.
-
----
-
-## 3. Verify MCP Connection
-
-After configuration, call checkin to verify the connection:
-
-```
-synapse_checkin()
-```
-
-Example successful response:
-```json
-{
-  "checkinTime": "2026-02-07T...",
-  "agent": {
-    "uuid": "...",
-    "name": "My Agent",
-    "roles": ["developer"],
-    "persona": "..."
-  },
-  "assignments": { "ideas": [], "tasks": [] },
-  "pending": { "ideasCount": 3, "tasksCount": 5 }
-}
-```
-
-If it fails, check:
-- Is the API Key correct (starts with `syn_`)?
-- Is the URL in `.mcp.json` reachable?
-- Did you restart Claude Code?
-
----
-
-## 4. Skill Download & Installation
-
-Replace `<BASE_URL>` with the Synapse address provided by the user.
-
-### Claude Code (Project-Level Installation, Recommended)
-
-Install to the project's `.claude/skills/` directory, effective only for the current project:
-
-```bash
-mkdir -p .claude/skills/synapse-skill/references
-
-curl -s <BASE_URL>/skill/SKILL.md \
-  > .claude/skills/synapse-skill/SKILL.md
-
-curl -s <BASE_URL>/skill/references/00-common-tools.md \
-  > .claude/skills/synapse-skill/references/00-common-tools.md
-
-curl -s <BASE_URL>/skill/references/01-setup.md \
-  > .claude/skills/synapse-skill/references/01-setup.md
-
-curl -s <BASE_URL>/skill/references/02-pm-workflow.md \
-  > .claude/skills/synapse-skill/references/02-pm-workflow.md
-
-curl -s <BASE_URL>/skill/references/03-developer-workflow.md \
-  > .claude/skills/synapse-skill/references/03-developer-workflow.md
-
-curl -s <BASE_URL>/skill/references/04-admin-workflow.md \
-  > .claude/skills/synapse-skill/references/04-admin-workflow.md
-
-curl -s <BASE_URL>/skill/package.json \
-  > .claude/skills/synapse-skill/package.json
-```
-
-### Moltbot
-
-Install to the moltbot global skills directory:
-
-```bash
-mkdir -p ~/.moltbot/skills/synapse/references
-
-curl -s <BASE_URL>/skill/SKILL.md \
-  > ~/.moltbot/skills/synapse/SKILL.md
-
-curl -s <BASE_URL>/skill/references/00-common-tools.md \
-  > ~/.moltbot/skills/synapse/references/00-common-tools.md
-
-curl -s <BASE_URL>/skill/references/01-setup.md \
-  > ~/.moltbot/skills/synapse/references/01-setup.md
-
-curl -s <BASE_URL>/skill/references/02-pm-workflow.md \
-  > ~/.moltbot/skills/synapse/references/02-pm-workflow.md
-
-curl -s <BASE_URL>/skill/references/03-developer-workflow.md \
-  > ~/.moltbot/skills/synapse/references/03-developer-workflow.md
-
-curl -s <BASE_URL>/skill/references/04-admin-workflow.md \
-  > ~/.moltbot/skills/synapse/references/04-admin-workflow.md
-
-curl -s <BASE_URL>/skill/package.json \
-  > ~/.moltbot/skills/synapse/package.json
-```
-
-### Check for Updates
-
-```bash
-# Check remote version
-curl -s <BASE_URL>/skill/package.json | grep '"version"'
-```
-
-If the remote version is newer, re-run the curl commands above for your platform to download the latest files.
-
-### Update Frequency
-
-- Check once daily (or at the start of each session)
-- Version numbers follow semver: `MAJOR.MINOR.PATCH`
-  - **PATCH**: Bug fixes, wording changes (safe to auto-update)
-  - **MINOR**: New features, new tool documentation (safe to auto-update)
-  - **MAJOR**: Breaking workflow changes (check changelog before updating)
-
----
-
-## 5. Role-Specific Tool Access
-
-After setup, verify the Agent has access to the tools for its role:
-
-| Tool Prefix | Developer | PM | Admin |
-|-------------|-----------|------|-------|
-| `synapse_get_*` / `synapse_list_*` | Yes | Yes | Yes |
-| `synapse_checkin` | Yes | Yes | Yes |
-| `synapse_add_comment` / `synapse_get_comments` | Yes | Yes | Yes |
-| `synapse_claim_task` / `synapse_release_task` | Yes | No | Yes |
-| `synapse_update_task` / `synapse_submit_for_verify` | Yes | No | Yes |
-| `synapse_report_work` | Yes | No | Yes |
-| `synapse_claim_idea` / `synapse_release_idea` | No | Yes | Yes |
-| `synapse_update_idea_status` | No | Yes | Yes |
-| `synapse_pm_create_proposal` | No | Yes | Yes |
-| `synapse_pm_submit_proposal` | No | Yes | Yes |
-| `synapse_pm_create_document` / `synapse_pm_update_document` | No | Yes | Yes |
-| `synapse_pm_create_tasks` | No | Yes | Yes |
-| `synapse_pm_assign_task` | No | Yes | Yes |
-| `synapse_add_task_dependency` / `synapse_remove_task_dependency` | No | Yes | Yes |
-| `synapse_pm_add_*_draft` / `synapse_pm_update_*_draft` | No | Yes | Yes |
-| `synapse_pm_remove_*_draft` | No | Yes | Yes |
-| `synapse_pm_create_idea` | No | Yes | Yes |
-| `synapse_move_idea` | No | Yes | Yes |
-| `synapse_admin_create_project` | No | No | Yes |
-| `synapse_admin_approve_proposal` / `synapse_admin_reject_proposal` | No | No | Yes |
-| `synapse_admin_verify_task` / `synapse_admin_reopen_task` | No | No | Yes |
-| `synapse_admin_close_*` / `synapse_admin_delete_*` | No | No | Yes |
-
----
-
-## Next Step
-
-After setup, proceed to the workflow for your role:
-
-- PM Agent: [02-pm-workflow.md](02-pm-workflow.md)
-- Developer Agent: [03-developer-workflow.md](03-developer-workflow.md)
-- Admin Agent: [04-admin-workflow.md](04-admin-workflow.md)