writbase 0.1.0 → 0.1.2

package/skills/manager/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: manager
+description: Patterns for managing agents, permissions, projects, and departments in WritBase (writbase:manage_agent_keys, writbase:manage_agent_permissions, writbase:manage_projects, writbase:manage_departments, writbase:get_provenance, writbase:subscribe, writbase:discover_agents). Use when connected as a manager-role agent.
+---
+
+# WritBase Manager Patterns
+
+All manager tools require `role: "manager"` on your agent key. Worker keys cannot access these tools.
+
+## Agent Provisioning Flow
+
+The standard sequence for onboarding a new agent:
+
+1. **Create the key** with `writbase:manage_agent_keys` (action: `create`)
+2. **Grant permissions** with `writbase:manage_agent_permissions` (action: `grant`)
+3. **Verify** with `writbase:discover_agents` to confirm the agent appears with correct capabilities
+
+Store the `full_key` from step 1 securely -- it is shown only once.
+
+## Key Management
+
+Use `writbase:manage_agent_keys` with these actions:
+
+| Action | Required Params | Notes |
+|--------|----------------|-------|
+| `list` | -- | Paginated. Optional `limit` (max 50), `cursor` |
+| `create` | `name` | Returns `full_key` (shown once). Optional: `special_prompt`, `project_id`, `department_id` |
+| `update` | `key_id` | Update `name`, `special_prompt`, `is_active`, `project_id`, `department_id` |
+| `deactivate` | `key_id` | Sets `is_active: false`. Immediate effect |
+| `rotate` | `key_id` | Generates new secret. Old secret invalidated immediately. Returns new `full_key` |
+
+Constraints:
+- Managers can only create worker keys (not other managers)
+- You cannot modify your own key (`self_modification_denied`)
+- If `require_human_approval_for_agent_keys` is enabled in workspace settings, new keys start as inactive until an admin activates them
+
+## Permission Management
+
+Use `writbase:manage_agent_permissions` with these actions:
+
+| Action | Required Params | Notes |
+|--------|----------------|-------|
+| `list` | `key_id` | Shows all permission rows for the target agent |
+| `grant` | `key_id`, `permissions` | Upserts permission rows (idempotent on project+department) |
+| `revoke` | `key_id`, `permissions` | Deletes matching permission rows |
+
+Permission flags per row: `can_read`, `can_create`, `can_update`, `can_assign`, `can_comment`, `can_archive`.
+
+### Dominance Rule
+
+You can only grant permissions you yourself have. This is enforced per-row: a single row of your permissions must be a superset of each granted row. Permissions are never combined across your rows.
+
+See [permission-model.md](references/permission-model.md) for detailed rules and examples.
+
+### `can_comment` as Restricted Update
+
+`can_comment` allows changing only `notes` and `status`. It blocks changes to `priority`, `description`, `department`, `due_date`, and `assign_to`. Use this for agents that should report progress but not modify task scope.
+
+## Project and Department Management
+
+### `writbase:manage_projects`
+
+| Action | Required Params | Notes |
+|--------|----------------|-------|
+| `create` | `name` | Creates project, auto-generates slug |
+| `rename` | `project_id`, `name` | Updates display name |
+| `archive` | `project_id` | Archived projects hide from active views, permissions become inert |
+
+### `writbase:manage_departments`
+
+| Action | Required Params | Notes |
+|--------|----------------|-------|
+| `create` | `name` | Creates department, auto-generates slug |
+| `rename` | `department_id`, `name` | Updates display name |
+| `archive` | `department_id` | Archived departments hide from active views |
+
+## Webhook Subscriptions
+
+Use `writbase:subscribe` to register webhooks for task event notifications:
+
+| Action | Required Params | Notes |
+|--------|----------------|-------|
+| `create` | `project`, `url` | HTTPS-only. Optional `event_types` (default: `["task.completed"]`) |
+| `list` | -- | Lists all subscriptions for your agent key |
+| `delete` | `subscription_id` | Removes the subscription |
+
+Valid event types: `task.created`, `task.updated`, `task.completed`, `task.failed`, `task.assigned`, `task.reassigned`.
+
+The `secret` for HMAC-SHA256 signature verification is returned only on creation -- store it securely.
+
+## Provenance and Audit
+
+Use `writbase:get_provenance` to view the event log:
+
+- `project` (required): scopes events to a specific project
+- `target_type` (optional): filter by `task`, `agent_key`, `project`, or `department`
+- `event_category` (optional): filter by `task`, `admin`, or `system`
+- Paginated with `limit` (max 50) and `cursor`
+
+## Agent Discovery
+
+Use `writbase:discover_agents` to list agents with access to a project:
+
+- `project` (required): the project slug
+- `skill` (optional): filter agents by declared skill/capability
+
+## Example: Full Agent Provisioning
+
+```
+# Step 1: Create a worker key
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "deploy-bot",
+  "special_prompt": "You handle deployment tasks. Mark tasks done only after verifying the deployment succeeded."
+}
+# Response includes full_key: "wb_<key_id>_<secret>" -- store this securely
+
+# Step 2: Grant permissions (use project_id UUID from writbase:info)
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "<key_id from step 1>",
+  "permissions": [
+    {
+      "project_id": "<project-uuid>",
+      "department_id": "<ops-dept-uuid>",
+      "can_read": true,
+      "can_create": true,
+      "can_update": true
+    }
+  ]
+}
+
+# Step 3: Verify the agent appears
+writbase:discover_agents { "project": "my-project" }
+# Confirm "deploy-bot" is listed with expected permissions
+```
+
+See [agent-provisioning.md](references/agent-provisioning.md) for more provisioning patterns including cross-department and delegation setups.

package/skills/manager/references/agent-provisioning.md

@@ -0,0 +1,251 @@
+# Agent Provisioning Guides
+
+Step-by-step guides for common agent provisioning patterns. All examples assume you are connected as a manager-role agent.
+
+Before provisioning, call `writbase:info` to get your project and department UUIDs from the `permissions.scopes` array.
+
+---
+
+## 1. Single-Project Worker
+
+A worker that can read, create, and update tasks in one project.
+
+### Step 1: Create the agent key
+
+```
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "build-agent",
+  "special_prompt": "You handle build and CI tasks. Always include build logs in task notes when marking done."
+}
+```
+
+Response:
+```json
+{
+  "key_id": "a1b2c3d4-...",
+  "full_key": "wb_a1b2c3d4-..._secrethere",
+  "name": "build-agent",
+  "role": "worker",
+  "is_active": true,
+  "warning": "Store this key securely. It will NOT be shown again."
+}
+```
+
+### Step 2: Grant permissions
+
+```
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "a1b2c3d4-...",
+  "permissions": [
+    {
+      "project_id": "<your-project-uuid>",
+      "can_read": true,
+      "can_create": true,
+      "can_update": true
+    }
+  ]
+}
+```
+
+This grants project-wide access (no department restriction) with read, create, and update.
+
+### Step 3: Verify
+
+```
+writbase:discover_agents { "project": "my-project" }
+```
+
+Confirm "build-agent" appears in the results with the expected permissions.
+
+---
+
+## 2. Cross-Department Agent
+
+An agent that operates across multiple departments with different permission levels.
+
+### Step 1: Create the agent key
+
+```
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "triage-agent",
+  "special_prompt": "You triage incoming tasks: read from intake, create in the appropriate department."
+}
+```
+
+### Step 2: Grant separate permission rows per department
+
+Each department needs its own permission row. Rows are evaluated independently.
+
+```
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "<triage-agent-key-id>",
+  "permissions": [
+    {
+      "project_id": "<project-uuid>",
+      "department_id": "<intake-dept-uuid>",
+      "can_read": true,
+      "can_update": true
+    },
+    {
+      "project_id": "<project-uuid>",
+      "department_id": "<engineering-dept-uuid>",
+      "can_read": true,
+      "can_create": true
+    },
+    {
+      "project_id": "<project-uuid>",
+      "department_id": "<design-dept-uuid>",
+      "can_read": true,
+      "can_create": true
+    }
+  ]
+}
+```
+
+This agent can:
+- Read and update tasks in the "intake" department (move them through triage statuses)
+- Read tasks and create new tasks in "engineering" and "design" departments
+- Cannot update tasks in engineering/design (intentional -- triage only creates, doesn't modify)
+
+### Step 3: Verify
+
+```
+writbase:manage_agent_permissions {
+  "action": "list",
+  "key_id": "<triage-agent-key-id>"
+}
+```
+
+Confirm all three permission rows are present with correct flags.
+
+---
+
+## 3. Delegation Setup
+
+An agent that can assign tasks to other agents. This requires `can_assign` permission and an understanding of delegation constraints.
+
+### Step 1: Create the coordinating agent
+
+```
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "coordinator-agent",
+  "special_prompt": "You coordinate work across the team. Assign tasks to the most appropriate agent based on their skills."
+}
+```
+
+### Step 2: Grant permissions with `can_assign`
+
+```
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "<coordinator-key-id>",
+  "permissions": [
+    {
+      "project_id": "<project-uuid>",
+      "can_read": true,
+      "can_create": true,
+      "can_update": true,
+      "can_assign": true
+    }
+  ]
+}
+```
+
+### Step 3: Create worker agents that can be assigned to
+
+The workers do not need `can_assign` themselves -- they just need permissions in the same project.
+
+```
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "frontend-agent"
+}
+
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "<frontend-agent-key-id>",
+  "permissions": [
+    {
+      "project_id": "<project-uuid>",
+      "department_id": "<frontend-dept-uuid>",
+      "can_read": true,
+      "can_update": true
+    }
+  ]
+}
+```
+
+### Delegation constraints
+
+WritBase enforces two safety mechanisms on task assignment:
+
+**`delegation_depth` (max 3)**: Each time a task is reassigned, the depth increments. After 3 reassignments, further delegation is blocked with `delegation_depth_exceeded`. The agent must either complete the task directly or create a new task.
+
+**`assignment_chain` (cycle detection)**: The database tracks every agent key ID that has been assigned the task. If an agent appears in the chain already, `circular_delegation` is returned. This prevents A -> B -> A loops.
+
+### How the coordinator assigns work
+
+Once provisioned, the coordinator uses `writbase:update_task` with the `assign_to` param:
+
+```
+writbase:update_task {
+  "task_id": "<task-uuid>",
+  "version": 2,
+  "assign_to": "frontend-agent"
+}
+```
+
+The `assign_to` field accepts either the agent's name or key ID.
+
+To unassign a task (return it to the pool), pass an empty string:
+
+```
+writbase:update_task {
+  "task_id": "<task-uuid>",
+  "version": 3,
+  "assign_to": ""
+}
+```
+
+---
+
+## 4. Comment-Only Observer
+
+An agent that can monitor and report on tasks but cannot change their scope.
+
+### Step 1: Create the key
+
+```
+writbase:manage_agent_keys {
+  "action": "create",
+  "name": "status-reporter",
+  "special_prompt": "You monitor task progress and add status notes. Do not change task priorities or descriptions."
+}
+```
+
+### Step 2: Grant `can_read` + `can_comment`
+
+```
+writbase:manage_agent_permissions {
+  "action": "grant",
+  "key_id": "<reporter-key-id>",
+  "permissions": [
+    {
+      "project_id": "<project-uuid>",
+      "can_read": true,
+      "can_comment": true
+    }
+  ]
+}
+```
+
+This agent can:
+- Read all tasks in the project
+- Change `status` (e.g., mark tasks `in_progress` or `done`)
+- Add/update `notes`
+- Cannot change `priority`, `description`, `department`, `due_date`, or `assign_to`

package/skills/manager/references/permission-model.md

@@ -0,0 +1,156 @@
+# WritBase Permission Model
+
+## Permission Grant Structure
+
+Each permission row contains:
+
+```json
+{
+  "project_id": "<uuid>",
+  "department_id": "<uuid or null>",
+  "can_read": false,
+  "can_create": false,
+  "can_update": false,
+  "can_assign": false,
+  "can_comment": false,
+  "can_archive": false
+}
+```
+
+- `project_id` is always required
+- `department_id` is optional -- when null, the permission applies project-wide
+- All boolean flags default to `false` if omitted
+
+## Dominance Check Rules
+
+When a manager grants permissions to another agent, the system verifies that the manager's own permissions are a superset. This is the **dominance check**.
+
+### Key principle: single-row dominance
+
+A single row of the manager's permissions must fully cover each granted row. Permissions are **never combined across the manager's rows**.
+
+### Rules evaluated per granted row:
+
+1. **Same project**: The manager must have a permission row for the same `project_id`
+2. **Department coverage**: The manager's row must have `department_id = null` (project-wide) or the same `department_id` as the granted row
+3. **Action superset**: Every `true` flag in the granted row must also be `true` in the manager's covering row
+
+### Examples
+
+**Manager has:**
+```
+Row A: { project_id: "P1", department_id: null, can_read: true, can_create: true, can_update: true }
+```
+
+**Granting to worker:**
+```
+CORRECT: { project_id: "P1", department_id: "D1", can_read: true, can_create: true }
+  -- Row A covers this (project-wide includes all departments, read+create are both true)
+
+WRONG: { project_id: "P1", department_id: "D1", can_read: true, can_assign: true }
+  -- Row A does not have can_assign, so dominance check fails
+```
+
+**Manager has two rows:**
+```
+Row A: { project_id: "P1", department_id: "D1", can_read: true, can_create: true }
+Row B: { project_id: "P1", department_id: "D2", can_read: true, can_update: true }
+```
+
+**Granting to worker:**
+```
+WRONG: { project_id: "P1", department_id: "D1", can_read: true, can_update: true }
+  -- Row A has D1 but no can_update. Row B has can_update but is scoped to D2.
+  -- No single row covers both D1 + can_update. Dominance check fails.
+
+CORRECT: { project_id: "P1", department_id: "D1", can_read: true, can_create: true }
+  -- Row A covers this entirely.
+
+CORRECT: { project_id: "P1", department_id: "D2", can_read: true, can_update: true }
+  -- Row B covers this entirely.
+```
+
+## `can_comment` as Restricted Update
+
+`can_comment` is intentionally separate from `can_update`. An agent with only `can_comment`:
+
+- **Can change**: `notes`, `status`
+- **Cannot change**: `priority`, `description`, `department`, `due_date`, `assign_to`
+
+Use `can_comment` for agents that should report progress (e.g., set status to `done` and add completion notes) but should not modify task scope or reassign work.
+
+An agent with `can_update` can change all task fields (except assignment, which requires `can_assign`).
+
+## Department Scoping Per Action
+
+### `writbase:add_task`
+
+- With `department` param: checks `can_create` for that specific department
+- Without `department` param: requires project-wide `can_create` (a permission row with `department_id = null`)
+
+```
+WRONG setup: Agent has can_create only for department "eng"
+  writbase:add_task { "project": "my-project", "description": "New task" }
+  -- Fails: no project-wide can_create
+
+CORRECT: Either specify the department:
+  writbase:add_task { "project": "my-project", "department": "eng", "description": "New task" }
+
+  Or grant project-wide can_create:
+  { "project_id": "P1", "department_id": null, "can_create": true }
+```
+
+### `writbase:update_task`
+
+Permission is checked against the task's **current** department, not the new department being set:
+
+```
+Task is currently in department "eng".
+Agent has can_update for department "eng" only.
+
+CORRECT: writbase:update_task { "task_id": "...", "version": 3, "department": "ops" }
+  -- Allowed because the agent has can_update for the task's current department ("eng")
+
+If the task were in department "ops", the same agent could NOT update it,
+even though they are trying to move it to "eng" where they have permissions.
+```
+
+## Common Permission Mistakes
+
+### Mistake: Granting more than you have
+
+```
+Manager has: { can_read: true, can_create: true }
+Tries to grant: { can_read: true, can_create: true, can_update: true }
+Result: insufficient_manager_scope error
+```
+
+### Mistake: Assuming rows combine
+
+```
+Manager has:
+  Row 1: { project_id: "P1", can_read: true }
+  Row 2: { project_id: "P1", can_create: true }
+
+Tries to grant: { project_id: "P1", can_read: true, can_create: true }
+Result: insufficient_manager_scope error
+  -- Neither row alone covers both can_read AND can_create
+```
+
+### Mistake: Department mismatch
+
+```
+Manager has: { project_id: "P1", department_id: "D1", can_read: true, can_create: true }
+Tries to grant: { project_id: "P1", department_id: "D2", can_read: true }
+Result: insufficient_manager_scope error
+  -- Manager's row is scoped to D1, cannot cover a grant for D2
+```
+
+### Correct: Project-wide covers all departments
+
+```
+Manager has: { project_id: "P1", department_id: null, can_read: true, can_create: true }
+Tries to grant: { project_id: "P1", department_id: "D2", can_read: true }
+Result: Success
+  -- department_id: null means project-wide, which covers any specific department
+```

package/skills/worker/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: worker
+description: Patterns for working with WritBase task management MCP tools (writbase:info, writbase:get_tasks, writbase:get_top_tasks, writbase:add_task, writbase:update_task). Use when connected to a WritBase MCP server.
+---
+
+# WritBase Worker Patterns
+
+## Session Start
+
+Always begin a session by calling `writbase:info`. This returns:
+
+- Your agent name, role, home project, and home department
+- Your permission scopes (which projects/departments you can access and what actions are allowed)
+- A `special_prompt` field with workspace-specific instructions -- follow these if present
+
+Do not skip this step. Your permissions determine which tools will succeed.
+
+## Tool Selection
+
+| Goal | Tool | Notes |
+|------|------|-------|
+| "What should I work on?" | `writbase:get_top_tasks` | Priority-sorted, excludes done/cancelled/failed/blocked by default, max 25 (default 10) |
+| Browse/filter/search tasks | `writbase:get_tasks` | Supports status, priority, department, search, date filters, pagination |
+| Create a task | `writbase:add_task` | Requires `can_create` permission |
+| Update a task | `writbase:update_task` | Requires `can_update` or `can_comment` permission |
+
+## Compact vs Verbose Shape
+
+By default, task queries return a compact 9-field shape:
+
+`id`, `version`, `status`, `priority`, `description`, `due_date`, `department`, `created_at`, `updated_at`
+
+Set `verbose: true` only when you need additional fields: `notes`, `assigned_to_agent_key_id`, `requested_by_agent_key_id`, `delegation_depth`, `assignment_chain`, `project_id`, `is_archived`, or full audit metadata.
+
+## Version Conflict Handling
+
+`writbase:update_task` uses optimistic concurrency. You must pass the `version` number from your last fetch:
+
+1. Fetch the task (via `writbase:get_tasks` or `writbase:get_top_tasks`)
+2. Pass the returned `version` value when calling `writbase:update_task`
+3. On `version_conflict` error, re-fetch the task and retry with the `current_version` from the error response
+4. Retry up to 3 times before reporting a conflict to the user
+
+## Validation Rules
+
+- `description`: minimum 3 characters
+- `priority`: one of `low`, `medium`, `high`, `critical`
+- `status`: one of `todo`, `in_progress`, `blocked`, `done`, `cancelled`, `failed`
+- `due_date`: valid ISO 8601 string (`YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ssZ`)
+
+## Department Scoping
+
+- `writbase:add_task` without a `department` param requires project-wide `can_create` (a permission row with `department_id` = null)
+- `writbase:update_task` checks permissions against the task's current department, not the new one
+- With only `can_comment` permission: you can change `notes` and `status` only -- changes to `priority`, `description`, `department`, `due_date`, or `assign_to` are rejected
+
+## Error Recovery Quick Reference
+
+| Error | Action |
+|-------|--------|
+| `version_conflict` | Re-fetch the task, retry with `current_version` from the error |
+| `rate_limited` | Wait `retry_after` seconds, then retry |
+| `scope_not_allowed` | Check your permissions with `writbase:info` |
+| `invalid_assignee` | Verify the agent name or key ID is correct and active |
+| `validation_error` | Read the `fields` object for per-field error messages |
+| `task_not_found` | Verify the task ID and your read access |
+
+See [error-handling.md](references/error-handling.md) for the full error code reference.
+
+## Example Workflows
+
+### 1. Session start, pick up work, complete a task
+
+```
+# Step 1: Learn your context
+writbase:info {}
+
+# Step 2: Find top priority work
+writbase:get_top_tasks { "project": "my-project" }
+
+# Step 3: Mark a task in progress (use version from step 2)
+writbase:update_task {
+  "task_id": "abc-123",
+  "version": 4,
+  "status": "in_progress"
+}
+
+# Step 4: Complete the task after doing the work
+writbase:update_task {
+  "task_id": "abc-123",
+  "version": 5,
+  "status": "done",
+  "notes": "Implemented the feature and verified tests pass."
+}
+```
+
+### 2. Adding a task with department
+
+```
+writbase:add_task {
+  "project": "my-project",
+  "department": "engineering",
+  "description": "Add rate limiting to the /api/upload endpoint",
+  "priority": "high",
+  "due_date": "2026-03-20"
+}
+```
+
+### 3. Version conflict retry pattern
+
+```
+# First attempt -- fails because another agent updated the task
+writbase:update_task {
+  "task_id": "abc-123",
+  "version": 4,
+  "status": "done"
+}
+# Error: { "code": "version_conflict", "current_version": 5 }
+
+# Re-fetch to see what changed
+writbase:get_tasks { "project": "my-project", "search": "abc-123" }
+# Returns task with version: 5
+
+# Retry with correct version
+writbase:update_task {
+  "task_id": "abc-123",
+  "version": 5,
+  "status": "done"
+}
+```