stack/packages/skills/tasks/SKILL.md

---
name: mosaic-plugin-tasks
description: Integration with Mosaic Stack's Tasks API for task management. Use when the user wants to create, list, update, complete, or delete tasks, including queries like "add task", "create task", "what's in progress", "high priority tasks", "mark task as done", "overdue tasks", "show my tasks", or "delete task".
homepage: https://git.mosaicstack.dev/mosaic/stack
metadata:
  {
    "clawdbot":
      {
        "emoji": "✅",
        "requires": { "bins": ["node"], "env": ["MOSAIC_API_TOKEN", "MOSAIC_WORKSPACE_ID"] },
        "primaryEnv": "MOSAIC_API_TOKEN",
      },
  }
---

# Mosaic Tasks

Integration with Mosaic Stack's Tasks API for comprehensive task management and tracking.

## Quick Start

Use `scripts/tasks.cjs` for all task operations. The script handles authentication and API communication automatically.

### Creating Tasks

```bash
node scripts/tasks.cjs create \
  --title "Review PR #123" \
  --description "Review the authentication refactor" \
  --priority HIGH \
  --status NOT_STARTED \
  --due "2024-02-01T17:00:00Z"
```

Natural language examples:

- "Add task: review PR #123"
- "Create a high priority task to fix the login bug"
- "Add a task to update documentation, due Friday"
- "Create task 'deploy to staging' assigned to Sarah"

### Listing Tasks

```bash
# List all tasks
node scripts/tasks.cjs list

# Filter by status
node scripts/tasks.cjs list --status IN_PROGRESS

# Filter by priority
node scripts/tasks.cjs list --priority HIGH

# Filter by project
node scripts/tasks.cjs list --project-id "uuid-here"

# Combine filters
node scripts/tasks.cjs list --status IN_PROGRESS --priority HIGH

# Query overdue tasks
node scripts/tasks.cjs list --overdue
```

Natural language examples:

- "What tasks are in progress?"
- "Show me high priority tasks"
- "What do I need to do today?"
- "List overdue tasks"
- "What tasks are assigned to me?"
- "Show completed tasks from last week"

### Getting a Specific Task

```bash
node scripts/tasks.cjs get TASK_ID
```

Natural language examples:

- "Show me task details for abc-123"
- "What's the status of the deployment task?"

### Updating Tasks

```bash
# Update status
node scripts/tasks.cjs update TASK_ID --status COMPLETED

# Update priority
node scripts/tasks.cjs update TASK_ID --priority HIGH

# Update multiple fields
node scripts/tasks.cjs update TASK_ID \
  --title "Updated Title" \
  --status IN_PROGRESS \
  --priority MEDIUM
```

Natural language examples:

- "Mark task abc-123 as done"
- "Set PR review task to in progress"
- "Change priority of deployment task to high"
- "Update the description of task xyz-456"
- "Move task to completed"

### Deleting Tasks

```bash
node scripts/tasks.cjs delete TASK_ID
```

Natural language examples:

- "Delete task abc-123"
- "Remove the duplicate deployment task"
- "Delete all completed tasks from last month"

## Task Fields

### Required Fields

- **title** (string, 1-255 characters): Task title or summary

### Optional Fields

- **description** (string, max 10,000 characters): Detailed task description
- **status** (enum): Task status
  - `NOT_STARTED` - Task not yet started (default)
  - `IN_PROGRESS` - Task is being worked on
  - `PAUSED` - Task temporarily paused
  - `COMPLETED` - Task finished
  - `ARCHIVED` - Task archived for historical reference
- **priority** (enum): Task priority level
  - `LOW` - Low priority
  - `MEDIUM` - Medium priority (default)
  - `HIGH` - High priority
- **dueDate** (string): ISO 8601 date string when task is due
- **assigneeId** (UUID): User ID of assigned team member
- **projectId** (UUID): Project this task belongs to
- **parentId** (UUID): Parent task ID for subtasks
- **sortOrder** (integer, min 0): Custom sort order within project/list
- **metadata** (object): Custom key-value data for extensions

## Date Handling

When processing natural language date/time requests:

1. Convert to ISO 8601 format (e.g., "2024-01-30T17:00:00Z")
2. Handle relative dates ("tomorrow", "next week", "Friday", "end of month")
3. Default to end of business day (17:00) if time not specified
4. Use user's timezone (America/Chicago) unless specified otherwise
5. For "today", use current date at 17:00 local time
6. For "overdue", query tasks where `dueDate < now()`

## Querying Overdue Tasks

Overdue tasks are those with a due date in the past that aren't completed or archived:

```bash
node scripts/tasks.cjs list --overdue
```

This filters to:

- `dueDate < current_datetime`
- `status NOT IN (COMPLETED, ARCHIVED)`

Natural language examples:

- "What tasks are overdue?"
- "Show me late tasks"
- "Which tasks missed their deadline?"

## Response Format

Single task operations return a task object:

```json
{
  "id": "uuid",
  "title": "Review PR #123",
  "description": "Review the authentication refactor",
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "dueDate": "2024-02-01T17:00:00Z",
  "assigneeId": "uuid",
  "projectId": "uuid",
  "parentId": null,
  "sortOrder": 0,
  "metadata": {},
  "workspaceId": "uuid",
  "createdBy": "uuid",
  "createdAt": "2024-01-29T10:00:00Z",
  "updatedAt": "2024-01-29T15:30:00Z"
}
```

List queries return paginated results:

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "totalPages": 2
  }
}
```

## Task Status Workflow

Typical task lifecycle:

1. **NOT_STARTED** → Initial state when created
2. **IN_PROGRESS** → Work begins on task
3. **PAUSED** → Temporarily blocked or on hold
4. **IN_PROGRESS** → Resume work
5. **COMPLETED** → Task finished
6. **ARCHIVED** → Move to historical archive

Tasks can transition to any status at any time based on needs.

## Environment

The script reads configuration from:

- `MOSAIC_API_URL` (default: http://localhost:3001)
- `MOSAIC_WORKSPACE_ID` (required)
- `MOSAIC_API_TOKEN` (required for authentication)

Ensure these are set in the environment or `.env` file.

## Error Handling

Common errors:

- **401 Unauthorized**: Missing or invalid API token
- **403 Forbidden**: Insufficient workspace permissions (tasks require MEMBER role to create/update, ADMIN to delete)
- **404 Not Found**: Task ID doesn't exist in this workspace
- **400 Bad Request**: Invalid status/priority value, missing required fields, or invalid UUID format

When operations fail, the script outputs clear error messages with guidance on resolution.

## Permission Requirements

Task operations require different permission levels:

- **List/Get**: Any workspace member (including GUEST)
- **Create/Update**: MEMBER role or higher
- **Delete**: ADMIN role or higher

## Integration with Projects

Tasks can be linked to projects via `projectId`. This enables:

- Filtering tasks by project
- Project-based task organization
- Tracking project progress through task completion
- Sorting tasks within project context using `sortOrder`

When creating tasks for a project, include the `--project-id` flag.

## Subtasks

Tasks support hierarchical organization via `parentId`:

```bash
# Create parent task
node scripts/tasks.cjs create --title "Deploy v2.0"

# Create subtask
node scripts/tasks.cjs create \
  --title "Run tests" \
  --parent-id PARENT_TASK_ID
```

Subtasks inherit project context from parent but can have independent status, priority, and due dates.