WritBase Recipes Reference

Consolidated reference for all WritBase MCP tools. This skill is invoked by /writbase-router for complex operations and serves as an API cookbook.

1. Session Start: writbase:info

Call with no parameters. Returns:

{
  "agent": { "name": "...", "role": "worker|manager", "is_active": true, "project": "slug|null", "department": "slug|null" },
  "permissions": {
    "department_required": false,
    "scopes": [
      { "project": "my-proj", "department": "eng", "can_read": true, "can_create": true, "can_update": true, "can_assign": false, "can_comment": false, "can_archive": false }
    ]
  },
  "special_prompt": "Follow these instructions..."
}

Interpreting the response:

• agent.role determines tool access: worker gets 6 tools, manager gets all 12
• agent.project / agent.department are defaults -- use these when the user does not specify
• permissions.scopes lists every project/department grant. A scope with department: null is project-wide
• permissions.department_required -- if true, add_task requires a department parameter
• special_prompt -- if present, follow these instructions for the entire session

2. Task Retrieval

writbase:get_tasks -- browse/filter/search

Compact shape (default): id, version, status, priority, description, due_date, department, created_at, updated_at

Verbose shape adds: notes, project_id, is_archived, full audit metadata

Pagination: When next_cursor is present in the response, pass it as cursor to get the next page.

writbase:get_tasks { "project": "my-proj", "status": "todo", "priority": "high" }
writbase:get_tasks { "project": "my-proj", "search": "rate limiting", "limit": 5 }
writbase:get_tasks { "project": "my-proj", "cursor": "<next_cursor from prev>" }

writbase:get_top_tasks -- priority-sorted actionable tasks

By default excludes done, cancelled, failed, blocked. Set status to override.

writbase:get_top_tasks { "project": "my-proj" }
writbase:get_top_tasks { "project": "my-proj", "department": "eng", "limit": 5 }

3. Task Creation: writbase:add_task

Permission check:

• With department param: requires can_create for that department scope
• Without department param: requires project-wide can_create (a permission row with department_id = null)

writbase:add_task {
  "project": "my-proj",
  "department": "eng",
  "description": "Add rate limiting to /api/upload",
  "priority": "high",
  "due_date": "2026-04-01"
}

4. Task Updates: writbase:update_task

Permission check:

• can_update allows changing all fields (except is_archived which needs can_archive)
• can_comment restricts to notes and status only -- attempting other fields returns scope_not_allowed
• Permission is checked against the task's current department, not the target department

Version conflict retry pattern

# Attempt 1: update with version from earlier fetch
writbase:update_task { "task_id": "abc-123", "version": 4, "status": "done" }
# Error: { "code": "version_conflict", "current_version": 6 }

# Re-fetch to see current state
writbase:get_tasks { "project": "my-proj", "search": "abc-123" }
# Returns version: 6

# Attempt 2: retry with fresh version
writbase:update_task { "task_id": "abc-123", "version": 6, "status": "done" }

Retry up to 3 times. If still conflicting, report to the user -- another agent is actively modifying the task.

5. Task Assignment: writbase:assign_task

Creates a task in another team's queue. Separate from add_task.

Permission check: Requires can_assign (not can_create) for the target department scope.

writbase:assign_task {
  "project": "my-proj",
  "department": "frontend",
  "description": "Fix responsive layout on settings page",
  "priority": "high"
}

6. Manager Operations

All manager tools require role: "manager". Worker keys receive insufficient_manager_scope.

writbase:manage_agent_keys

Constraints:

• Cannot modify your own key (self_modification_denied)
• If require_human_approval_for_agent_keys is enabled, new keys start inactive

# Create a worker key
writbase:manage_agent_keys {
  "action": "create",
  "name": "deploy-bot",
  "special_prompt": "You handle deployment tasks."
}
# Response: { "key_id": "...", "full_key": "wb_<key_id>_<secret>", ... }
# Store full_key securely -- shown only once

writbase:manage_agent_permissions

Permission flags per row: can_read, can_create, can_update, can_assign, can_comment, can_archive

Dominance rule: A single row of your permissions must be a superset of each granted row. Permissions are never combined across your rows.

# Grant read + create for a specific department
writbase:manage_agent_permissions {
  "action": "grant",
  "key_id": "<target-key-id>",
  "permissions": [{
    "project_id": "<uuid>",
    "department_id": "<uuid>",
    "can_read": true,
    "can_create": true
  }]
}

writbase:manage_projects

writbase:manage_departments

7. Webhooks: writbase:subscribe

Manager only. HMAC-SHA256 signed payloads.

Valid event types: task.created, task.updated, task.completed, task.failed

writbase:subscribe {
  "action": "create",
  "project": "my-proj",
  "url": "https://example.com/webhook",
  "event_types": ["task.created", "task.completed"]
}
# Response includes `secret` for HMAC verification -- store securely, shown only once

8. Provenance: writbase:get_provenance

Manager only. Queries the append-only event log.

# All task events in a project
writbase:get_provenance { "project": "my-proj", "target_type": "task" }

# Admin events only (key/permission changes)
writbase:get_provenance { "project": "my-proj", "event_category": "admin" }

# Paginate through history
writbase:get_provenance { "project": "my-proj", "cursor": "<next_cursor>" }

9. Agent Discovery: writbase:discover_agents

Manager only. Lists active agents with access to a project.

writbase:discover_agents { "project": "my-proj" }
writbase:discover_agents { "project": "my-proj", "skill": "coding" }

Returns agent name, role, last_used_at, and capabilities (skills, description, accepts_tasks).

10. Agent Provisioning Cookbook

Single-project worker

# 1. Create key
writbase:manage_agent_keys { "action": "create", "name": "build-agent", "special_prompt": "Handle CI tasks." }

# 2. Grant permissions (use project UUID from info)
writbase:manage_agent_permissions {
  "action": "grant",
  "key_id": "<key_id>",
  "permissions": [{ "project_id": "<uuid>", "can_read": true, "can_create": true, "can_update": true }]
}

# 3. Verify
writbase:discover_agents { "project": "my-proj" }

Cross-department agent

Grant separate rows per department -- each row is evaluated independently:

writbase:manage_agent_permissions {
  "action": "grant",
  "key_id": "<key_id>",
  "permissions": [
    { "project_id": "<uuid>", "department_id": "<intake-uuid>", "can_read": true, "can_update": true },
    { "project_id": "<uuid>", "department_id": "<eng-uuid>", "can_read": true, "can_create": true }
  ]
}

Comment-only observer

Grant can_read + can_comment (no can_update). Agent can change notes and status but nothing else:

writbase:manage_agent_permissions {
  "action": "grant",
  "key_id": "<key_id>",
  "permissions": [{ "project_id": "<uuid>", "can_read": true, "can_comment": true }]
}

Delegation coordinator

Grant can_assign for cross-department task creation via assign_task:

writbase:manage_agent_permissions {
  "action": "grant",
  "key_id": "<key_id>",
  "permissions": [{ "project_id": "<uuid>", "can_read": true, "can_create": true, "can_update": true, "can_assign": true }]
}

11. Error Recovery

See error-codes.md for the complete error reference.

Quick recovery table:

12. Validation Quick Reference

See permission-model.md for permission scoping rules.