# Replace with your actual token
curl -s "https://api.gqueues.com/v0?action=getQueues&scope=personal" \
  -H "Authorization: Bearer gq_your_token_here" | python3 -m json.tool

curl -s -X POST "https://api.gqueues.com/v0" \
  -H "Authorization: Bearer gq_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-task-001" \
  -d '{
    "action": "createTask",
    "instructions": [
      {"text": "Try the GQueues API"}
    ]
  }' | python3 -m json.tool

---
name: list-queues
description: List queues from GQueues via the API
user_invocable: true
arguments:
  - name: scope
    description: "Queue categories to list: personal, team, shared (comma-separated). Defaults to all."
    required: false
---

# List Queues in GQueues

List available queues from GQueues using the API endpoint.

## Configuration

Read the GQueues settings from `.claude/settings.local.json` under the `gqueues` key:
- `gqueues.accessToken` — Bearer token for authentication
- `gqueues.apiEndpoint` — Base URL for the GQueues API

The API endpoint is `GET /v0` on the GQueues server.

**If the `gqueues` key is missing or either setting is absent**, prompt the user using AskUserQuestion:
1. `apiEndpoint` — ask the user, default: `https://api.gqueues.com`
2. `accessToken` — ask the user, no default (required)

Save the values to `.claude/settings.local.json` under the `gqueues` key (preserve all other keys in the file). After saving, print the absolute path to the settings file.

## Instructions

1. Read `.claude/settings.local.json` to get the access token and endpoint.
2. Determine the scope from the user's input. Valid values: `personal`, `team`, `shared`. If not specified, default to all three.
3. Call the API using curl:

```bash
curl -s -X GET "<base_url>/v0?action=getQueues&scope=<scope>" \
  -H "Authorization: Bearer <access_token>"
```

4. Parse the JSON response and display results to the user in a readable format.

## Query Parameters

- `action` (required): `getQueues`
- `scope` (optional): Comma-separated list of queue categories. Valid values: `personal`, `team`, `shared`. Defaults to `personal,team,shared`.

## Response Format

Response groups queues by category. Only requested scopes are included in the response.

```json
{
  "personal": [
    {
      "key": "<queue key>",
      "name": "My Queue",
      "notes": "",
      "numOpen": 5,
      "numCompleted": 12,
      "isInbox": false,
      "dateCreated": "2024-01-15T10:30:00",
      "lastModified": "2024-03-20T14:00:00",
      "permission": {"view": true, "update": true, "manage": true, "publish": true}
    }
  ],
  "team": [
    {
      "key": "<queue key>",
      "name": "Team Queue",
      "notes": "",
      "numOpen": 3,
      "numCompleted": 8,
      "isInbox": false,
      "isTeamInbox": true,
      "dateCreated": "2024-02-01T09:00:00",
      "lastModified": "2024-03-18T11:00:00",
      "teamName": "Engineering",
      "permission": {"view": true, "update": true, "manage": true, "publish": false}
    }
  ],
  "shared": [
    {
      "key": "<queue key>",
      "name": "Shared Queue",
      "notes": "",
      "numOpen": 2,
      "numCompleted": 4,
      "isInbox": false,
      "dateCreated": "2024-01-20T08:00:00",
      "lastModified": "2024-03-15T16:00:00",
      "permission": {"view": true, "update": false, "manage": false, "publish": false}
    }
  ]
}
```

## Response Handling

- Display queues grouped by category (personal, team, shared).
- For each queue show: name, open/completed counts, and whether it's an inbox.
- For team queues, also show the team name.
- If the HTTP response is an error (401, 403, 404, 429), report the error clearly.

## Examples

User: `/list-queues`
Lists all queues across personal, team, and shared.

User: `/list-queues personal`
Lists only the user's personal queues.

User: `/list-queues team,shared`
Lists team and shared queues only.

---
name: list-tasks
description: List tasks in a given GQueues queue via the API
user_invocable: true
arguments:
  - name: queue_name_or_id
    description: "Queue name or queue key ID to list tasks from"
    required: true
  - name: options
    description: "Optional flags: --limit <n> (1-200, default 200), --no-snoozed (exclude snoozed), --cursor <n> (pagination offset)"
    required: false
---

# List Tasks in a GQueues Queue

List active tasks in a specific queue using the GQueues API.

## Configuration

Read the GQueues settings from `.claude/settings.local.json` under the `gqueues` key:
- `gqueues.accessToken` — Bearer token for authentication
- `gqueues.apiEndpoint` — Base URL for the GQueues API

The API endpoint is `GET /v0` on the GQueues server.

**If the `gqueues` key is missing or either setting is absent**, prompt the user using AskUserQuestion:
1. `apiEndpoint` — ask the user, default: `https://api.gqueues.com`
2. `accessToken` — ask the user, no default (required)

Save the values to `.claude/settings.local.json` under the `gqueues` key (preserve all other keys in the file). After saving, print the absolute path to the settings file.

## Instructions

1. Read `.claude/settings.local.json` to get the access token and endpoint.
2. Determine the queue. If the user provided a queue key (long alphanumeric string), use it directly. If the user provided a queue name, first call `/list-queues` to find the matching queue key.
3. Parse optional flags from the user's input:
   - `--limit <n>` — number of tasks to return (1-200, default 200)
   - `--no-snoozed` — exclude snoozed tasks (default: include snoozed)
   - `--cursor <n>` — pagination offset for fetching next page
4. Call the API using curl:

```bash
curl -s -X GET "<base_url>/v0?action=getActiveTasks&queueKey=<queue_key>&includeSnoozed=<true|false>&limit=<limit>&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"
```

5. Parse the JSON response and display results to the user in a readable format.

## Query Parameters

- `action` (required): `getActiveTasks`
- `queueKey` (required): Datastore key string for the queue
- `includeSnoozed` (optional): `true` or `false`. Default: `true`
- `limit` (optional): Number of tasks to return, 1-200. Default: `200`. Out-of-range values return 400.
- `cursor` (optional): Numeric string for pagination offset. Default: `0`

## Response Format

```json
{
  "items": [
    {
      "key": "<task key>",
      "title": "Task title",
      "notes": "Task notes",
      "completed": false,
      "tags": ["tag1", "tag2"],
      "assignments": [
        {
          "key": "<assignment key>",
          "email": "user@example.com",
          "name": "User Name",
          "profile": "",
          "comment": "",
          "dateCompleted": "",
          "completed": false
        }
      ],
      "creationDate": {
        "text": "Mon, Mar 25, 2024 @ 10:30 AM",
        "raw": "2024-03-25 10:30"
      },
      "dueDate": {
        "dueDate": "Tue, March 26, 2024",
        "duration": null,
        "rawDate": "2024-03-26",
        "title": "Tue, March 26, 2024 @ 3:00 PM",
        "text": "Mar 26 @ 3:00 PM",
        "reminder": {
          "type": "minutes",
          "amount": 30
        },
        "repeats": false
      },
      "subitems": []
    }
  ],
  "sections": [
    {
      "key": "<section key>",
      "name": "Section Name",
      "color": "gq-queue-bkgnd-8",
      "notes": "Section notes",
      "position": "00000000",
      "items": ["<task key>"]
    }
  ],
  "topLevelCount": 10,
  "nextCursor": "5",
  "limit": 200
}
```

## Auto-Pagination

When the user's intent requires seeing **all** tasks (e.g., searching for a task by name, counting tasks, or listing everything), automatically paginate through all pages:

1. Fetch the first page (use the default limit or omit it — the server decides).
2. Read the `limit` field from the response to know the actual page size the server used (it may differ from what you requested due to server-side validation/clamping).
3. If `nextCursor` is not null, fetch the next page using that cursor value.
4. Repeat until `nextCursor` is null (all tasks retrieved).
5. Accumulate all items across pages before processing/displaying results.

This is especially important when the user asks "does task X exist" or "find task Y" — you must check all pages before concluding a task does or doesn't exist.

When the user just wants a quick listing (e.g., `/list-tasks My Queue --limit 10`), respect the explicit limit and do **not** auto-paginate. Only auto-paginate when no explicit `--limit` or `--cursor` is provided and the user's intent requires completeness.

## Response Handling

- Display tasks in a readable list format.
- For each task show: title, due date (if any), tags, assignments, and completion status.
- If the task has subitems, show them indented beneath the parent task.
- Show the total count of top-level items (`topLevelCount`).
- If auto-pagination was not used and `nextCursor` is not null, inform the user that more tasks are available and they can use `--cursor <nextCursor>` to fetch the next page.
- If the HTTP response is an error (400, 401, 403, 404, 429), report the error clearly.

## Examples

User: `/list-tasks My Queue`
Lists all active tasks in the queue named "My Queue".

User: `/list-tasks ahNzfmdxdWV1ZXMtaHJkLWRldnI --limit 10`
Lists 10 tasks from the queue with the given key.

User: `/list-tasks Shopping --no-snoozed`
Lists active non-snoozed tasks in the "Shopping" queue.

User: `/list-tasks Work --cursor 200`
Fetches the next page of tasks starting at offset 200.

---
name: create-task
description: Create task(s) in GQueues via the API
user_invocable: true
arguments:
  - name: task_text
    description: "Task description(s) to create. Supports GQueues quick-add syntax."
    required: true
---

# Create Task in GQueues

Create one or more tasks in GQueues using the API endpoint.

## Configuration

Read the GQueues settings from `.claude/settings.local.json` under the `gqueues` key:
- `gqueues.accessToken` — Bearer token for authentication
- `gqueues.apiEndpoint` — Base URL for the GQueues API

The API endpoint is `POST /v0` on the GQueues server.

**If the `gqueues` key is missing or either setting is absent**, prompt the user using AskUserQuestion:
1. `apiEndpoint` — ask the user, default: `https://api.gqueues.com`
2. `accessToken` — ask the user, no default (required)

Save the values to `.claude/settings.local.json` under the `gqueues` key (preserve all other keys in the file). After saving, print the absolute path to the settings file.

## Idempotency

Every `createTask` request requires an `Idempotency-Key` header. The key determines whether the API treats the request as new or as a retry of a previous one.

**Default behavior — duplicate avoidance:** Generate a **deterministic key** from the task text using a SHA-256 hash. This way, repeating the same command within 24 hours replays the cached response instead of creating a duplicate task.

```bash
IDEM_KEY=$(python3 -c "import hashlib; print('create-task-' + hashlib.sha256('''<task_text>'''.encode()).hexdigest()[:32])")
```

If the user explicitly asks to create a duplicate (e.g., "create another", "create again even if duplicate"), generate a random UUID v4 instead:

```bash
IDEM_KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
```

**Key rules:** allowed characters `a-z`, `A-Z`, `0-9`, `_`, `-`, `.` — max 128 chars.

## Instructions

1. Read `.claude/settings.local.json` to get the access token and endpoint.
2. Parse the user's input into one or more task instructions. If the user provides multiple tasks (separated by newlines or clearly distinct items), create multiple instructions. Maximum 25 per request.
3. Generate the idempotency key (see strategy above).
4. Call the API using curl. Because this skill accepts natural-language input, set `parseQuickAddSyntax: true` on each instruction so the server extracts due dates, tags, queue, assignments, and notes out of the text:

```bash
curl -s -X POST <base_url>/v0 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM_KEY" \
  -d '{
    "action": "createTask",
    "instructions": [
      { "text": "<task_text>", "parseQuickAddSyntax": true }
    ]
  }'
```

5. Handle the response (see Response Handling below).

## Quick-Add Syntax Reference

Quick-add parsing is **opt-in** on the GQueues API — each instruction must set `"parseQuickAddSyntax": true` (as shown in the curl example above). Without that flag, the server stores `text` verbatim and ignores any of the markers below.

With parsing enabled, the task text supports:

- **Queue assignment:** `Task [Queue Name]` — assigns to named queue (auto-creates if needed)
- **Tags:** `Task #tag1 #tag2` — adds tags
- **Due dates:** `Task due tomorrow`, `Task Friday at 3pm`, `Task in 2 hours`
- **Notes:** `Task :: These are the notes`
- **Assignments:** Include email addresses to assign, e.g. `Task user@example.com`

To store a task's text literally (no parsing), omit `parseQuickAddSyntax` (or set it to `false`) and pass the subject via `text`. You can optionally include `queueKey` (from `/list-queues`) and `notes` as top-level instruction fields in that mode.

## Response Handling

**Success (200):**
- Each result has `status: "created"` with a `task` object containing `key`, `title`, `notes`, `tags`, `assignments`, `queueName`, `queueKey`, `creationDate`, and — if set — `dueDate`.
- Check for the `Idempotent-Replayed: true` response header. If present, the task was NOT created again — the API returned a cached response from a previous identical request. Tell the user the task already exists (no duplicate was created).
- If the header is absent, the task was freshly created. Report it normally.

**Idempotency errors:**
- **409 (Conflict):** A duplicate request is still in flight. Wait 1 second (per the `Retry-After` header) and retry with the **same** idempotency key. Retry up to 3 times.
- **422 (Unprocessable Entity):** The idempotency key was already used with a different request body. Generate a **new random key** and retry once.

**Other errors:**
- **400:** Bad request (missing header, invalid key, malformed JSON). Report the error message.
- **401/403:** Authentication or permission failure.
- **404:** API not enabled for this account.
- **413:** Request body exceeds 64 KB. Split the batch into smaller requests.
- **415:** Wrong Content-Type.

## Example

User: `/create-task Buy groceries tomorrow #personal [Shopping]`

Creates a task "Buy groceries" with due date tomorrow, tag "personal", in queue "Shopping" (with `parseQuickAddSyntax: true` so the due date, tag, and queue are extracted from the text).

you: What queues do I have?

claude: Here are your queues:

  Personal
  - Inbox (5 open, 23 completed)
  - Shopping (3 open, 12 completed)
  - Reading List (8 open, 4 completed)

  Team — Engineering
  - Sprint Backlog (12 open, 45 completed)
  - Bug Triage (7 open, 31 completed)

you: Create a task to review the API docs by Friday in Sprint Backlog

claude: Created: "Review the API docs" in Sprint Backlog
  Due: Friday, Apr 11, 2025