@vibescope/mcp-server 0.0.1 → 0.1.0

package/src/knowledge.ts

@@ -21,12 +21,40 @@ export const KNOWLEDGE_BASE: Record<string, string> = {
 - Priority: 1=highest, 5=lowest`,
 
 	validation: `# Task Validation
-Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
-1. Check: get_tasks_awaiting_validation(project_id)
-2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
-3. Review code changes and run tests
-4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
-Self-validation allowed when single-agent or to unblock deployment.`,
+Completed tasks need validation before PR merge. PRIORITIZE validation over new tasks.
+
+## Validator Workflow
+
+### 1. Claim Task
+claim_validation(task_id) → Returns worktree_setup with existing branch
+
+### 2. Set Up Worktree (EXISTING branch)
+git fetch origin feature/task-branch
+git worktree add ../PROJECT-task-ID feature/task-branch
+cd ../PROJECT-task-ID
+
+### 3. Run Tests Locally
+pnpm install && pnpm test && pnpm build
+
+### 4. Approve or Reject
+
+**APPROVE** → Validator merges PR:
+validate_task(task_id, approved: true, validation_notes: "...")
+# Response includes merge instructions with PR URL
+gh pr merge <NUMBER> --squash
+git worktree remove ../PROJECT-task-ID
+
+**REJECT** → Create fix task:
+validate_task(task_id, approved: false, validation_notes: "Issues...", create_fix_task: true)
+# Creates fix task with SAME branch/PR
+# Fix agent picks up, pushes fixes to same PR
+git worktree remove ../PROJECT-task-ID
+
+## Key Rules
+- Validators check out EXISTING branches
+- On approval: validator merges immediately
+- On rejection: use create_fix_task: true
+- Always clean up worktree after validation`,
 
 	deployment: `# Deployment Workflow
 1. Ensure all completed tasks are validated first
@@ -73,11 +101,53 @@ When validate_task(approved: true) is called, the response includes:
 - **cleanup**: Branch deletion commands
 - **note**: Confirmation it's safe to merge
 
+## Multi-Agent Worktrees (CRITICAL)
+
+When multiple agents share a repository, you MUST use git worktrees to prevent conflicts.
+
+### Why Worktrees?
+- Branch switching in shared repos causes file conflicts between agents
+- Uncommitted changes from one agent block another's work
+- Worktrees provide isolated working directories with shared .git
+
+### Setup (Once Per Task)
+\`\`\`bash
+# From main repo, create worktree for your task
+git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
+
+# Work in the worktree directory
+cd ../worktree-<task-short-id>
+\`\`\`
+
+### Cleanup (After Task Merged)
+\`\`\`bash
+# Remove worktree after PR merged
+git worktree remove ../worktree-<task-short-id>
+git branch -d feature/<task-id>-<title>
+\`\`\`
+
+### Worktree Rules
+- ALWAYS create a worktree before starting work on a task
+- Each agent works in their own worktree directory
+- Never switch branches in the main repo when other agents are active
+- Commit and push frequently to avoid losing work
+
+## Handling Merge Conflicts
+
+When claim_validation detects conflicts (via GitHub API):
+1. Response includes merge_conflict with rebase_instructions
+2. Checkout the feature branch locally
+3. Rebase onto target branch: \`git rebase origin/<target>\`
+4. Resolve conflicts, then: \`git add . && git rebase --continue\`
+5. Force push: \`git push origin <branch> --force-with-lease\`
+6. Re-claim validation to verify PR is now mergeable
+
 ## Key Rules
-- Create branch when starting task (github-flow/git-flow)
+- Create worktree + branch when starting task (multi-agent environments)
 - Push and create PR when completing task
 - Wait for validation before merging
-- Clean up branch after successful merge`,
+- Resolve merge conflicts via rebase before approval
+- Clean up worktree and branch after successful merge`,
 
 	blockers: `# Working with Blockers
 When stuck and need human input:
@@ -118,6 +188,33 @@ Be mindful of token costs - every tool call has a cost.
 - Batch related updates when possible
 - Trust lite mode; only use full mode for initial exploration`,
 
+	sprints: `# Sprints
+Sprints are time-bounded bodies of work with velocity tracking.
+
+## Lifecycle
+1. **planning**: Create sprint, add tasks with story points
+2. **active**: Sprint in progress, working on tasks
+3. **in_review**: Sprint ended, reviewing completion
+4. **retrospective**: Post-sprint reflection
+5. **completed**: Final state, velocity recorded
+
+## Workflow
+1. create_sprint(project_id, title, start_date, end_date, goal)
+2. get_sprint_backlog(project_id) - view available tasks
+3. add_task_to_sprint(sprint_id, task_id, story_points) - add tasks
+4. start_sprint(sprint_id) - locks committed_points
+5. Work on tasks normally (they're assigned to the sprint)
+6. complete_sprint(sprint_id) - calculates final velocity
+
+## Velocity Tracking
+- committed_points: Total story points at sprint start
+- velocity_points: Story points completed by sprint end
+- get_sprint_velocity(project_id) - shows history and average velocity
+
+## Auto-Deployment
+Set auto_deploy_on_completion: true when creating sprint.
+Triggers deployment when sprint completes.`,
+
 	topics: `# Available Help Topics
 - getting_started: Basic workflow overview
 - tasks: Working on tasks, progress tracking
@@ -128,5 +225,6 @@ Be mindful of token costs - every tool call has a cost.
 - milestones: Breaking down complex tasks
 - fallback: Background activities when idle
 - session: Session management
-- tokens: Token efficiency tips`,
+- tokens: Token efficiency tips
+- sprints: Time-bounded task groupings with velocity tracking`,
 };