home / skills / cdeistopened / opened-vault / todos

todos skill

safe

This skill helps you manage project todos via a REST API, enabling create, view, update, delete and project-wide listings.

npx playbooks add skill cdeistopened/opened-vault --skill todos

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.1 KB

---
name: todos
description: Manages project todos via REST API. Use when the user asks to create, view, update, or delete todos, list tasks by project, check task status, or filter by due date. Requires the Nomendex app to be running.
version: 2
---

# Todos Management

## Overview

Manages todos via the Nomendex REST API. The API handles all validation, ID generation, timestamps, and ordering automatically.

Todos are displayed in a kanban board UI with columns for each status. Users can drag and drop todos between columns to change their status, or use the API to update status programmatically.

## Todo Status

Each todo has a status field that controls which kanban column it appears in. The available statuses are:

| Status | Description |
|--------|-------------|
| `todo` | Not started - the default status for new todos |
| `in_progress` | Currently being worked on |
| `done` | Completed |
| `later` | Deferred or backlogged for future consideration |

When creating a todo, status defaults to `todo` if not specified. When updating a todo's status, the system automatically assigns a new order position at the end of the target column.

## Port Discovery

The server writes its port to a discoverable location. Extract it with:

```bash
PORT=$(cat ~/Library/Application\ Support/com.firstloop.nomendex/serverport.json | grep -o '"port":[0-9]*' | cut -d: -f2)
```

## API Endpoints

All endpoints use POST with JSON body at `http://localhost:$PORT`:

| Endpoint | Description |
|----------|-------------|
| `/api/todos/create` | Create a new todo |
| `/api/todos/list` | List todos (with optional project filter) |
| `/api/todos/get` | Get a single todo by ID |
| `/api/todos/update` | Update a todo |
| `/api/todos/delete` | Delete a todo |
| `/api/todos/projects` | List all projects |
| `/api/todos/tags` | List all tags |
| `/api/todos/archive` | Archive a todo |
| `/api/todos/unarchive` | Unarchive a todo |
| `/api/todos/archived` | List archived todos |

## Create Todo

```bash
curl -s -X POST "http://localhost:$PORT/api/todos/create" \
  -H "Content-Type: application/json" \
  -d '{"title": "My todo", "project": "work"}'

# With explicit status
curl -s -X POST "http://localhost:$PORT/api/todos/create" \
  -H "Content-Type: application/json" \
  -d '{"title": "My todo", "status": "in_progress", "project": "work"}'
```

## List Todos

```bash
# All active todos
curl -s -X POST "http://localhost:$PORT/api/todos/list" \
  -H "Content-Type: application/json" \
  -d '{}'

# Todos for a specific project
curl -s -X POST "http://localhost:$PORT/api/todos/list" \
  -H "Content-Type: application/json" \
  -d '{"project": "work"}'
```

## Update Todo

```bash
# Update status
curl -s -X POST "http://localhost:$PORT/api/todos/update" \
  -H "Content-Type: application/json" \
  -d '{"todoId": "todo-123", "updates": {"status": "done"}}'

# Update multiple fields
curl -s -X POST "http://localhost:$PORT/api/todos/update" \
  -H "Content-Type: application/json" \
  -d '{"todoId": "todo-123", "updates": {"title": "New title", "status": "in_progress"}}'
```

## How Claude Should Use This Skill

Always start by getting the server port, then use the appropriate endpoint.

Overview

This skill manages project todos via the Nomendex REST API so you can create, view, update, delete, and filter tasks programmatically. It expects the Nomendex app to be running and automatically handles validation, ID generation, timestamps, and ordering on the server side. Use it to drive a kanban-style workflow or to script bulk updates and queries.

How this skill works

The skill discovers the running Nomendex server port from a well-known file, then issues POST requests with JSON bodies to localhost endpoints. It supports endpoints for creating, listing (optionally by project), getting, updating, deleting, archiving, and listing tags or projects. Status changes are reflected in kanban columns and the server assigns ordering automatically.

When to use it

Create a new todo or set its initial status and project.
List active todos or list todos filtered by project.
Update a todo’s status, title, project, or other fields programmatically.
Delete, archive, or unarchive todos from scripts or automation.
Query available projects or tags to populate UIs or filters.

Best practices

Always read the server port from the discoverable file before calling endpoints to avoid hardcoding ports.
Send JSON POST bodies and set Content-Type: application/json for every request.
Use the list endpoints with a project filter to reduce payload size when you only need one project.
When changing status, rely on the server to set ordering; only submit the status field unless you need other updates.
Respect archived vs active lists: use /api/todos/archived to inspect archived items and /api/todos/archive to move items out of active lists.

Example use cases

Create a quick task for a project: create a todo with title and project via /api/todos/create.
Build a dashboard: call /api/todos/list and /api/todos/projects to render a project-filtered kanban board.
Automate sprint cleanup: list todos by project and archive or delete completed items in bulk.
Status workflows: move items between todo, in_progress, done, and later by updating the status field.
Reporting: pull todos filtered by due date or status for progress reports.

FAQ

What must be running for this skill to work?

The Nomendex app must be running because the skill reads the server port and sends requests to the local REST API.

How do I discover the server port?

Read the port from the discoverable JSON file the app writes (the skill uses that file path to set PORT before calling endpoints).