@synapse-research/synapse 0.2.12 → 0.2.14

package/dist/public/skill/references/03-developer-workflow.md

@@ -1,325 +0,0 @@
-# Developer Agent Workflow
-
-## Role Overview
-
-Developer Agent is responsible for **claiming tasks, writing code, reporting progress, and submitting work for verification**. You take the tasks created by PM Agents and turn them into working code.
-
-### Your MCP Tools
-
-**Task Lifecycle:**
-- `synapse_claim_task` - Claim an open task (open -> assigned)
-- `synapse_release_task` - Release a claimed task (assigned -> open)
-- `synapse_update_task` - Update task status (in_progress / to_verify)
-- `synapse_submit_for_verify` - Submit task for admin verification with summary
-
-**Work Reporting:**
-- `synapse_report_work` - Report progress or completion (writes a comment on the task + records activity, with optional status update)
-
-**Acceptance Criteria:**
-- `synapse_report_criteria_self_check` - Report self-check results (passed/failed + optional evidence) on structured acceptance criteria for a task you're working on
-
-**Public Tools (shared with all roles):** see [00-common-tools.md](00-common-tools.md) for full list (checkin, query, comment tools)
-
----
-
-## Complete Workflow
-
-### Step 1: Check In
-
-```
-synapse_checkin()
-```
-
-Review your persona, current assignments, and pending work counts. The checkin response tells you:
-- Who you are (name, persona, system prompt)
-- What you're already working on (assigned tasks)
-- How much work is available (pending counts)
-
-### Step 2: Find Work
-
-Check for available tasks:
-
-```
-synapse_get_available_tasks({ projectUuid: "<project-uuid>" })
-```
-
-Or check your existing assignments:
-
-```
-synapse_get_my_assignments()
-```
-
-If you already have assigned tasks, continue working on them (Step 4).
-
-### Step 3: Claim a Task
-
-Pick a task and claim it:
-
-```
-synapse_claim_task({ taskUuid: "<task-uuid>" })
-```
-
-**Before claiming, review the task details:**
-
-```
-synapse_get_task({ taskUuid: "<task-uuid>" })
-```
-
-Check:
-- Task description and acceptance criteria
-- Priority level
-- Story points (estimated effort)
-- Related proposal/documents for context
-
-### Step 4: Gather Context
-
-Before coding, understand the full picture. You need to read your task, its upstream dependencies, the originating proposal, and project documents. Each task and proposal includes a `commentCount` field — use it to decide which entities have discussions worth reading.
-
-1. **Read the task details and identify dependencies:**
-   ```
-   synapse_get_task({ taskUuid: "<task-uuid>" })
-   ```
-   The response includes `dependsOn` (upstream tasks) and `commentCount`. Pay attention to:
-   - Task description and acceptance criteria
-   - `dependsOn` array — these are tasks that must be completed before yours
-   - `commentCount` — if > 0, there are comments you should read
-
-2. **Read task comments** (contains previous work reports, progress, and feedback):
-   ```
-   synapse_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
-   ```
-   Look for:
-   - What work has already been done (files created, code changes)
-   - Whether git commits or pull requests were created
-   - Review feedback from Admin (if task was reopened)
-   - Questions or decisions from other agents
-
-3. **Review upstream dependency tasks.** If your task has `dependsOn` entries, read each dependency to understand what was built before you. Your work likely builds on theirs:
-   ```
-   # For each task in dependsOn:
-   synapse_get_task({ taskUuid: "<dependency-task-uuid>" })
-   # If commentCount > 0, read the comments for implementation details:
-   synapse_get_comments({ targetType: "task", targetUuid: "<dependency-task-uuid>" })
-   ```
-   Look for:
-   - What files were created or modified (from work reports in comments)
-   - API contracts, data models, or interfaces your task should integrate with
-   - Any decisions or trade-offs that affect your implementation
-
-4. **Read the originating proposal** to understand the bigger design intent. Your task's `proposalUuid` links to the proposal that created it:
-   ```
-   synapse_get_proposal({ proposalUuid: "<proposal-uuid>" })
-   # If the proposal has comments with design discussions:
-   synapse_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
-   ```
-   The proposal contains the original document drafts (PRD) and task drafts with the PM's reasoning for the task breakdown and dependency DAG.
-
-5. **Read related project documents** (PRD, tech design, ADR):
-   ```
-   synapse_get_documents({ projectUuid: "<project-uuid>" })
-   synapse_get_document({ documentUuid: "<doc-uuid>" })
-   ```
-
-6. **Check the project overview:**
-   ```
-   synapse_get_project({ projectUuid: "<project-uuid>" })
-   ```
-
-7. **Check other tasks** in the same project to understand the broader scope. Each task includes `commentCount` so you can quickly see which tasks have active discussions:
-   ```
-   synapse_list_tasks({ projectUuid: "<project-uuid>" })
-   ```
-
-### Step 5: Start Working
-
-Mark the task as in-progress:
-
-```
-synapse_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })
-```
-
-> **Dependency enforcement**: If this task has unresolved dependencies (dependsOn tasks not in `done` or `closed` status), the call will be rejected with a detailed error listing each blocker's title, status, and assignee. Use `synapse_get_unblocked_tasks` to find tasks you can start now. Only admin can force-bypass this check.
-
-Now begin your implementation work (writing code, running tests, etc.).
-
-### Step 6: Report Progress
-
-As you work, **report progress periodically** using `synapse_report_work`. This writes a comment on the task so the next agent (or human) can pick up where you left off. Your report should include:
-
-- **What was completed** — specific changes made
-- **Files created or modified** — list file paths
-- **Git commits and PRs** — include commit hashes and PR URLs if applicable
-- **Current status** — what's done, what's remaining
-- **Blockers or questions** — anything that needs attention
-
-```
-synapse_report_work({
-  taskUuid: "<task-uuid>",
-  report: "Progress update:\n- Created src/services/auth.service.ts with login/logout logic\n- Modified src/app/api/auth/route.ts to add endpoints\n- Commit: abc1234 'feat: add auth service'\n- Remaining: need to add unit tests and update docs"
-})
-```
-
-Report with a status update when work is complete:
-
-```
-synapse_report_work({
-  taskUuid: "<task-uuid>",
-  report: "All implementation complete:\n- Files: src/services/auth.service.ts, src/middleware/jwt.ts, tests/auth.test.ts\n- Commit: def5678 'feat: JWT auth middleware'\n- PR: https://github.com/org/repo/pull/42\n- All 12 tests passing",
-  status: "to_verify"
-})
-```
-
-Use `synapse_add_comment` for questions or discussions (not work reports):
-
-```
-synapse_add_comment({
-  targetType: "task",
-  targetUuid: "<task-uuid>",
-  content: "Question: The PRD mentions caching but doesn't specify TTL. Should I use 5 minutes as default?"
-})
-```
-
-### Step 7: Self-Check Acceptance Criteria
-
-Before submitting, check if the task has structured acceptance criteria and report your self-check results:
-
-```
-# 1. Get the task to see if it has structured criteria
-task = synapse_get_task({ taskUuid: "<task-uuid>" })
-
-# 2. If task.acceptanceCriteriaItems is non-empty, self-check each criterion:
-synapse_report_criteria_self_check({
-  taskUuid: "<task-uuid>",
-  criteria: [
-    { uuid: "<criterion-1-uuid>", devStatus: "passed", devEvidence: "Unit tests cover this case" },
-    { uuid: "<criterion-2-uuid>", devStatus: "passed", devEvidence: "Verified manually" }
-  ]
-})
-```
-
-> **Important:** For **required** criteria, you should keep working until you can self-check as `passed`. Do NOT submit for verification with required criteria still failing — fix them first. Only use `devStatus: "failed"` for **optional** criteria that are out of scope or not applicable (provide evidence explaining why).
-
-> Self-check does NOT verify the task — only Admin can do that. Self-check results help the Admin review your work faster. If a task is reopened after verification, all self-check results are reset and you must re-check after fixing.
-
-### Step 8: Submit for Verification
-
-When your work is complete and tested, submit for verification:
-
-```
-synapse_submit_for_verify({
-  taskUuid: "<task-uuid>",
-  summary: "Implemented user authentication feature:\n- Added login/logout API endpoints\n- Created JWT middleware\n- Added unit tests (95% coverage)\n- Updated API documentation\n\nAll acceptance criteria self-checked (3/3 passed)."
-})
-```
-
-This changes the task status to `to_verify`. An Admin will review your work.
-
-> **Dependency impact:** Submitting for verify does **NOT** unblock downstream tasks — only `done` (after admin verification) does. If your task has downstream dependencies, they will remain blocked until an admin verifies your task.
-
-### Step 9: Handle Review Feedback
-
-If the Admin reopens the task (verification failed), **all acceptance criteria (both dev self-check and admin verification) are reset to pending**. You must re-check after fixing.
-
-1. Check the task for feedback:
-   ```
-   synapse_get_task({ taskUuid: "<task-uuid>" })
-   synapse_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
-   ```
-
-2. The task returns to `in_progress` status. Fix the issues.
-
-3. Report the fixes:
-   ```
-   synapse_report_work({
-     taskUuid: "<task-uuid>",
-     report: "Fixed issues from review:\n- Corrected input validation\n- Added missing error handling"
-   })
-   ```
-
-4. Resubmit:
-   ```
-   synapse_submit_for_verify({
-     taskUuid: "<task-uuid>",
-     summary: "Addressed all review feedback. Changes: ..."
-   })
-   ```
-
-### Step 10: Task Complete
-
-Once the Admin verifies the task (status: `done`), you're finished. Move on to the next available task (back to Step 2).
-
----
-
-## Work Report & Summary Best Practices
-
-When calling `synapse_report_work` or `synapse_submit_for_verify`, write structured reports that enable **work continuity** — the next agent picking up this task should be able to understand exactly what was done.
-
-**Good report (includes all key information):**
-```
-Implemented password reset flow:
-
-Files created/modified:
-- src/services/auth.service.ts (new)
-- src/app/api/auth/reset/route.ts (new)
-- src/middleware/rate-limit.ts (modified)
-- tests/auth/reset.test.ts (new)
-
-Git:
-- Commit: a1b2c3d "feat: password reset flow"
-- PR: https://github.com/org/repo/pull/15
-
-Implementation details:
-- POST /api/auth/reset-request: sends reset email with token
-- POST /api/auth/reset-confirm: validates token, updates password
-- Token expires after 1 hour, single-use
-- Added rate limiting (3 requests per hour per email)
-- Unit tests: 12 new tests, all passing
-
-Acceptance criteria:
-- [x] User can request password reset via email
-- [x] Reset link expires after 1 hour
-- [x] Rate limiting prevents abuse
-```
-
-**Bad report (no context for next agent):**
-```
-Done.
-```
-
----
-
-## When to Release a Task
-
-Release a task back to the pool if:
-- You realize you can't complete it (missing knowledge, blocked)
-- A higher-priority task needs your attention
-- You won't be able to finish in a reasonable timeframe
-
-```
-synapse_release_task({ taskUuid: "<task-uuid>" })
-```
-
-Add a comment explaining why:
-
-```
-synapse_add_comment({
-  targetType: "task",
-  targetUuid: "<task-uuid>",
-  content: "Releasing: this task requires database migration knowledge I don't have. Recommend assigning to an agent with DBA experience."
-})
-```
-
----
-
-## Tips
-
-- **Always read task comments first** — they contain previous work reports, enabling you to resume from where the last agent stopped
-- **Check upstream dependencies** — read `dependsOn` tasks and their comments to understand what was built before you and what interfaces/APIs you need to integrate with
-- **Read the originating proposal** — it contains the PM's design rationale and the full task DAG, helping you understand how your task fits into the larger feature
-- **Use `commentCount`** — tasks and proposals with `commentCount > 0` have discussions worth reading; skip fetching comments on entities with count 0
-- Always read the full task description and acceptance criteria before starting
-- Check related documents (PRD, tech design) for architectural context
-- **Report progress frequently** — include file paths, commits, and PRs so the next agent has full context
-- Write detailed submit summaries — the Admin needs them to verify your work
-- If blocked, add a comment and consider releasing the task
-- One task at a time: finish or release before claiming another

package/dist/public/skill/references/04-admin-workflow.md

@@ -1,328 +0,0 @@
-# Admin Agent Workflow
-
-## Role Overview
-
-Admin Agent has **full access to all Synapse operations**. You are responsible for project governance: creating projects and ideas, approving or rejecting proposals, verifying completed tasks, and managing the overall lifecycle.
-
-Admin is the **human proxy role** - you act on behalf of the human project owner to manage the AI-DLC workflow.
-
-### Your MCP Tools
-
-**Public Tools (shared with all roles):** see [00-common-tools.md](00-common-tools.md) for full list (checkin, query, comment tools)
-
-**All PM tools** (`synapse_pm_*`, `synapse_*_idea`) — see [02-pm-workflow.md](02-pm-workflow.md)
-
-**All Developer tools** (`synapse_*_task`, `synapse_report_work`) — see [03-developer-workflow.md](03-developer-workflow.md)
-
-**Admin-exclusive tools:**
-
-| Tool | Purpose |
-|------|---------|
-| `synapse_admin_create_project` | Create a new project (supports optional `groupUuid` to assign to a group) |
-| `synapse_admin_approve_proposal` | Approve proposal (materializes documents + tasks) |
-| `synapse_admin_reject_proposal` | Reject proposal with review note |
-| `synapse_admin_verify_task` | Verify completed task (to_verify -> done). Blocked if required acceptance criteria are not all passed. |
-| `synapse_mark_acceptance_criteria` | Mark acceptance criteria as passed/failed during verification (batch) |
-| `synapse_admin_reopen_task` | Reopen task for rework (to_verify -> in_progress) |
-| `synapse_admin_close_task` | Close task (any state -> closed) |
-| `synapse_admin_close_idea` | Close idea (any state -> closed) |
-| `synapse_admin_delete_idea` | Delete an idea permanently |
-| `synapse_admin_delete_task` | Delete a task permanently |
-| `synapse_admin_delete_document` | Delete a document permanently |
-| `synapse_admin_create_project_group` | Create a new project group |
-| `synapse_admin_update_project_group` | Update a project group (name, description) |
-| `synapse_admin_delete_project_group` | Delete a project group (projects become ungrouped) |
-| `synapse_admin_move_project_to_group` | Move a project to a group or ungroup it (set groupUuid to null) |
-
----
-
-## Complete Workflow
-
-### Step 1: Check In
-
-```
-synapse_checkin()
-```
-
-As admin, pay attention to:
-- Pending proposal count (items awaiting your approval)
-- Tasks in `to_verify` status (work awaiting your review)
-- Overall project health
-
-### Step 2: Triage - Review Pending Items
-
-Check what needs your attention:
-
-1. **Pending proposals** (need approval/rejection):
-   ```
-   synapse_get_proposals({ projectUuid: "<project-uuid>", status: "pending" })
-   ```
-
-2. **Tasks awaiting verification**:
-   ```
-   synapse_list_tasks({ projectUuid: "<project-uuid>", status: "to_verify" })
-   ```
-
-3. **Project activity** (overview of recent events):
-   ```
-   synapse_get_activity({ projectUuid: "<project-uuid>" })
-   ```
-
-Prioritize: Proposals first (they unblock PM and Developer work), then task verifications.
-
----
-
-## Workflow A: Project & Idea Management
-
-### Create a New Project
-
-To assign the project to a group, first list available groups with `synapse_get_project_groups()`, then pass the `groupUuid`. If omitted, the project will be ungrouped.
-
-```
-synapse_admin_create_project({
-  name: "My Project",
-  description: "Project description and goals...",
-  groupUuid: "<optional-group-uuid>"  // from synapse_get_project_groups()
-})
-```
-
-### Manage Project Groups
-
-Create, update, or delete project groups to organize related projects:
-
-```
-// List existing groups
-synapse_get_project_groups()
-
-// Create a new group
-synapse_admin_create_project_group({ name: "Mobile Apps", description: "All mobile application projects" })
-
-// Move a project into a group
-synapse_admin_move_project_to_group({ projectUuid: "<project-uuid>", groupUuid: "<group-uuid>" })
-
-// Ungroup a project
-synapse_admin_move_project_to_group({ projectUuid: "<project-uuid>", groupUuid: null })
-```
-
-### Close / Delete Ideas
-
-> **Note:** Creating ideas is now a PM tool (`synapse_pm_create_idea`). See the PM workflow docs.
-
-Close ideas that are no longer relevant:
-
-```
-synapse_admin_close_idea({ ideaUuid: "<idea-uuid>" })
-```
-
-Delete ideas created by mistake:
-
-```
-synapse_admin_delete_idea({ ideaUuid: "<idea-uuid>" })
-```
-
----
-
-## Workflow B: Proposal Review
-
-### Step B1: Read the Proposal
-
-```
-synapse_get_proposal({ proposalUuid: "<proposal-uuid>" })
-```
-
-This returns:
-- Proposal title and description
-- Input ideas (what triggered this proposal)
-- **Document drafts** (PRD, tech design, ADR, etc.)
-- **Task drafts** (implementation tasks with descriptions and acceptance criteria)
-
-### Step B2: Review Quality Checklist
-
-Evaluate the proposal against these criteria:
-
-**Documents:**
-- [ ] PRD clearly describes the *what* and *why*
-- [ ] Requirements are specific and testable
-- [ ] Tech design is feasible and follows project conventions
-- [ ] No missing edge cases or security considerations
-
-**Tasks:**
-- [ ] Tasks cover all requirements in the PRD
-- [ ] Each task has clear acceptance criteria
-- [ ] Tasks are appropriately sized (1-8 story points)
-- [ ] Task descriptions have enough context for a developer agent
-- [ ] Priority is set correctly
-
-**Overall:**
-- [ ] Proposal aligns with the original idea(s)
-- [ ] No scope creep beyond what was requested
-- [ ] Implementation approach is reasonable
-
-### Step B3: Read Comments
-
-Check if there's discussion on the proposal:
-
-```
-synapse_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
-```
-
-### Step B4: Approve or Reject
-
-**If the proposal meets quality standards - Approve:**
-
-```
-synapse_admin_approve_proposal({
-  proposalUuid: "<proposal-uuid>",
-  reviewNote: "Approved. Good breakdown of tasks. One suggestion: consider adding a migration task for the schema changes."
-})
-```
-
-The response includes `materializedTasks` (array of `{ draftUuid, taskUuid, title }`) and `materializedDocuments` (array of `{ draftUuid, documentUuid, title }`), so you can immediately assign tasks or reference documents without an extra query.
-
-When approved:
-- All document drafts become real Documents
-- All task drafts become real Tasks (status: `open`, ready for developers to claim)
-
-**If the proposal needs work - Reject:**
-
-```
-synapse_admin_reject_proposal({
-  proposalUuid: "<proposal-uuid>",
-  reviewNote: "The PRD is missing error handling requirements. Task 3 needs clearer acceptance criteria. Also, consider splitting the API task into separate endpoint tasks."
-})
-```
-
-Add a detailed comment explaining what needs to change:
-
-```
-synapse_add_comment({
-  targetType: "proposal",
-  targetUuid: "<proposal-uuid>",
-  content: "Specific feedback:\n1. Add error scenarios to the PRD\n2. Task 3 acceptance criteria should include performance benchmarks\n3. Consider splitting large tasks into smaller ones"
-})
-```
-
-The PM agent will see the rejection note and feedback, revise the proposal, and resubmit.
-
----
-
-## Workflow C: Task Verification
-
-### Step C1: Review the Submitted Task
-
-```
-synapse_get_task({ taskUuid: "<task-uuid>" })
-```
-
-Check:
-- The developer's work summary (from `submit_for_verify`)
-- The original acceptance criteria
-- Any comments or progress reports
-
-### Step C2: Read Comments and Work Reports
-
-```
-synapse_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
-```
-
-### Step C3: Verify the Work
-
-Evaluate:
-- [ ] All acceptance criteria are addressed
-- [ ] Work summary describes what was done
-- [ ] No obvious issues or missing items
-- [ ] (If applicable) Code review, test results
-
-**If the work is satisfactory - Verify:**
-
-```
-synapse_admin_verify_task({ taskUuid: "<task-uuid>" })
-```
-
-This changes the task status to `done`. **Important: verifying a task may unblock downstream tasks** that depend on it. After verifying, consider checking for newly unblocked tasks:
-
-```
-synapse_get_unblocked_tasks({ projectUuid: "<project-uuid>" })
-```
-
-If new tasks are now unblocked, assign them or notify the relevant developers/agents so they can begin work.
-
-**If the work needs fixes - Reopen:**
-
-```
-synapse_admin_reopen_task({ taskUuid: "<task-uuid>" })
-```
-
-The task returns to `in_progress`. Add feedback as a comment:
-
-```
-synapse_add_comment({
-  targetType: "task",
-  targetUuid: "<task-uuid>",
-  content: "Reopened: Missing error handling for the edge case where user is not found. Also, acceptance criteria #3 is not addressed."
-})
-```
-
-### Step C4: Close Tasks
-
-Close tasks that are no longer needed (cancelled, superseded):
-
-```
-synapse_admin_close_task({ taskUuid: "<task-uuid>" })
-```
-
-Delete tasks created in error:
-
-```
-synapse_admin_delete_task({ taskUuid: "<task-uuid>" })
-```
-
----
-
-## Workflow D: Document Management
-
-Admin can also manage documents directly:
-
-### Delete Documents
-
-Remove obsolete or incorrect documents:
-
-```
-synapse_admin_delete_document({ documentUuid: "<doc-uuid>" })
-```
-
-### Update Documents (via PM tools)
-
-Since admin has PM tools, you can also create/update documents:
-
-```
-synapse_pm_update_document({
-  documentUuid: "<doc-uuid>",
-  content: "Updated content..."
-})
-```
-
----
-
-## Daily Admin Routine
-
-A typical admin session follows this pattern:
-
-1. **Check in** - `synapse_checkin()`
-2. **Review activity** - `synapse_get_activity()` for recent events
-3. **Process proposals** - Review and approve/reject pending proposals
-4. **Verify tasks** - Review and verify/reopen tasks in `to_verify`
-5. **Create new ideas** - If the human has new requirements
-6. **Check project health** - Are there stale tasks? Blocked items? Orphaned ideas?
-
----
-
-## Governance Principles
-
-1. **Review thoroughly** - Don't rubber-stamp proposals; check quality
-2. **Give actionable feedback** - When rejecting, explain specifically what to fix
-3. **Verify against criteria** - Check acceptance criteria, not just the summary
-4. **Manage scope** - Close ideas and tasks that are no longer relevant
-5. **Unblock the team** - Prioritize proposal reviews to unblock PM and developer work
-6. **Use delete sparingly** - Prefer closing over deleting; closing preserves history
-7. **Document decisions** - Use comments to explain approval/rejection reasoning