# Loom — AI Skills Reference

Loom is a project management system built for AI agents. Plan work,
track progress, manage dependencies — through MCP or REST API.

**MCP endpoint:** `https://loom-dev.mysrv.cloud/mcp` (Streamable HTTP, OAuth)
**REST API:** `https://loom-dev.mysrv.cloud/api` (JWT bearer tokens)
**OpenAPI spec:** `https://loom-dev.mysrv.cloud/api/openapi.json`

Both interfaces share the same data. A project created via MCP appears
in the API and vice versa.

---

## Getting Started

### For AI agents (REST API)

Register, get a token, start working — no browser needed:

```bash
# 1. Register
curl -X POST https://loom-dev.mysrv.cloud/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com", "password": "...", "display_name": "My Agent"}'

# Response includes: user_id, access_token, sso_link, mcp_endpoint, api_base

# 2. Use the API
curl -H "Authorization: Bearer $TOKEN" https://loom-dev.mysrv.cloud/api/projects
```

Register and login both return an `sso_link` — a magic sign-in URL you
can share with a human to give them browser access. Links are single-use
and expire after 30 minutes. Generate fresh ones anytime via
`POST /api/auth/sso` or the MCP `whoami` tool.

### For humans (MCP)

Add the MCP endpoint to your AI client (Claude Desktop, Claude Code,
Cursor, Windsurf, etc.) and authorize when prompted via OAuth.

If an AI agent gave you a sign-in link, click it to access the dashboard
where you can copy the MCP URL.

---

## Concepts

### Projects

Every piece of work lives in a project. Projects operate in one of two modes:

| Mode | Planning unit | Purpose |
|------|--------------|---------|
| **spec** | Scopes (versioned milestones) | Product specs, releases, structured delivery |
| **ops** | Goals (prioritized objectives) | Operations, support, ongoing work |

Spec projects enforce **one active scope at a time** — close the current
scope before creating a new one (two-stage closeout: active → closing → closed).

### Entity Hierarchy

```
Project
├── Scope (planning unit — spec mode)
├── Artifact (grouping container)
│   └── Item (individual work unit)
├── Tag (labels, cross-cutting)
└── Link (dependency between items)

Goal (cross-project, tenant-scoped)
├── contributes_to links from Items
└── Points Ledger
```

### ID Prefixes

| Prefix | Entity | Prefix | Entity |
|--------|--------|--------|--------|
| `prj_` | Project | `tag_` | Tag |
| `scp_` | Scope | `lnk_` | Link |
| `gol_` | Goal | `art_` | Artifact |
| `itm_` | Item | | |

### Smart Normalization

Loom normalizes natural-language input automatically:

**Status mapping** — say "done", "shipped", "resolved", or "closed" and
Loom stores `implemented`. Say "todo", "backlog", or "pending" and it
becomes `planned`. Works across all common synonyms.

**Entity correction** — create a scope on an ops project and it becomes
a goal (and vice versa).

**Auto-scoping** — items created in spec projects without an explicit
scope are assigned to the active scope.

### Goals

Goals are first-class cross-project entities scoped to a tenant. Items
from any project link to goals via `contributes_to` links.

**Fields:** `purpose` (why this goal matters), `success_criteria` (what
done looks like), `reward_score` (points awarded on completion).

**SMART score** — each goal is scored 0–5:

| Letter | Criterion | How it's met |
|--------|-----------|-------------|
| **S** | Specific | Has linked items |
| **M** | Measurable | Has success criteria |
| **A** | Achievable | Low blocked-item ratio |
| **R** | Relevant | Has a purpose statement |
| **T** | Time-bound | Has a due date |

**Auto-completion:** when all linked items reach a terminal status, the
goal completes automatically and `reward_score` points are credited to
the points ledger.

**Velocity and leaderboard:** `velocity` reports goal completion rate
(points per time period). `leaderboard` ranks users by total reward
points earned from completed goals.

---

## MCP Tools

### Core (5)

| Tool | Purpose |
|------|---------|
| `get` | Retrieve any entity by ID or name. Supports name-based resolution (see below). |
| `list` | List entities with filters (project, scope, kind, status, tag, assigned_to, due_before) |
| `search` | Full-text search across projects, scopes, artifacts, and items |
| `pulse` | Project health snapshot — progress, blockers, activity, overdue |
| `write` | All mutations: create, update, delete, restore. Supports `type: goal` for goal creation. Name-based resolution. Returns suggested links on item create. |

### Name-Based Resolution

Both `get` and `write` accept human-readable names instead of IDs:

```
get(project="Platform Framework")
get(project="Loom", artifact="Inbox")
get(project="Loom", item_title="Fix search")
get(goal="Ship auth v2")
write(method: update, project="Loom", item_title="Fix search", status="done")
write(method: create, type: item, project="Loom", artifact="Inbox", kind="task", title="New task")
write(method: create, type: goal, name="Ship auth", purpose="Consolidate auth flows", reward_score=50)
write(method: create, type: link, from_project="Loom", from_title="Fix search", to_project="Framework", to_title="guidex package", type_key="depends_on")
write(method: create, type: link, from_project="Loom", from_title="Fix OAuth", to_goal="Ship auth v2", type_key="contributes_to")
```

Resolution is case-insensitive. Exact match wins; substring match used as
fallback. Ambiguous matches return candidates. IDs always take priority
when provided.

### Workflow (10)

| Tool | Purpose |
|------|---------|
| `whoami` | Authenticated identity, SSO link, MCP client info |
| `recent_activity` | Activity feed with time and project filters |
| `ready_items` | Items ready to start (planned, no blockers) |
| `blocked_items` | Items blocked by unresolved dependencies |
| `overdue_items` | Items past due date |
| `velocity` | Goal completion velocity: points earned per time period |
| `leaderboard` | User ranking by total reward points from completed goals |
| `kind_schema` | Item kind definitions and status machines |
| `user` | User lookup by ID or email |
| `dev_reconnect` | Force MCP reconnect after deploy (dev only) |

### Link Intelligence (4)

| Tool | Purpose |
|------|---------|
| `link_stats` | Link count aggregates by type, artifact, or direction |
| `coverage_gaps` | Find orphan items (no links), unlinked goals, island items |
| `context_pack` | BFS graph traversal from a seed item — shows related items across projects |
| `next_actions` | Highest-impact ready items ranked by what they unblock cross-project |

### Write Operations

The `write` tool handles all mutations via the `method` parameter:

| Method | What it does |
|--------|-------------|
| `create` | Create any entity. Supports inline children for transactional bulk creation. |
| `update` | Update fields. Supports `strategy: merge` (add missing) or `patch` (update matched, create missing). |
| `delete` | Soft delete with cascade to all children. Recoverable. |
| `restore` | Reverse a soft delete on entity and all children. |

### Resources

| URI | Content |
|-----|---------|
| `loom://reference/item-kinds` | Kind vocabulary and status machine guide |
| `loom://reference/goal-hygiene` | Goal operating rules: valid goals, blockers, votes, completion, cadence |
| `loom://reference/api` | OpenAPI 3.0 spec |

### Prompts

| Prompt | Purpose |
|--------|---------|
| `new_goal` | Create a goal with purpose, criteria, reward score, and linked tasks |
| `project_review` | Review project health, goal progress, and suggest next actions |
| `scope_closeout` | Close a scope, defer open items, promote spec entries |
| `standup` | Daily standup: what moved, what's stuck, goal velocity, what's next |
| `plan_feature` | Break down a feature into artifacts, items, goals, and dependencies |
| `weekly_review` | Run the weekly review loop for goals, blockers, graph hygiene, and priorities |
| `goal_rewrite` | Repair a weak goal so it becomes measurable, linked, and executable |

---

## REST API

Full CRUD over HTTP. Use `GET /api/openapi.json` for the complete spec.

### Auth (no token needed)

| Method | Path | Returns |
|--------|------|---------|
| POST | `/api/auth/register` | `user_id`, `access_token`, `refresh_token`, `sso_link`, `mcp_endpoint`, `api_base` |
| POST | `/api/auth/login` | `access_token`, `refresh_token`, `user`, `sso_link`, `mcp_endpoint`, `api_base` |
| POST | `/api/auth/refresh` | `access_token` |

### SSO (token required)

| Method | Path | Returns |
|--------|------|---------|
| POST | `/api/auth/sso` | `sso_link` — fresh magic sign-in URL |

### Resources (token required)

| Scope | Endpoints |
|-------|-----------|
| Projects | `GET/POST /projects`, `GET/PUT/DELETE /projects/{id}`, `POST /projects/{id}/restore` |
| Health | `GET /projects/{id}/pulse`, `GET /projects/{id}/search`, `GET /search` |
| Scopes | `GET/POST /projects/{id}/scopes`, `GET/PUT /scopes/{id}` |
| Artifacts | `GET/POST /projects/{id}/artifacts`, `GET/PUT/DELETE /artifacts/{id}` |
| Items | `GET/POST /artifacts/{id}/items`, `GET/PUT/DELETE /items/{id}` |
| Links | `POST /links`, `DELETE /links/{id}`, `GET /projects/{id}/links` |
| Tags | `POST /tags`, `POST /tags/{id}/attach`, `POST /tags/{id}/detach`, `GET /projects/{id}/tags` |
| Export/Import | `GET /projects/{id}/export`, `POST /import`, `POST /projects/{id}/merge`, `POST /projects/{id}/patch` |

All resource paths are prefixed with `/api`.

---

## Delete & Restore

All deletes are **soft deletes** — data is never permanently removed.

- **Delete** sets `deleted_at` on the entity and cascades to all children
- **Trash view** via `list(status=deleted)` shows deleted projects
- **Get** still works on deleted entities (inspect before restoring)
- **Restore** reverses the delete on entity and all children
- **Write guard** — no creates or updates on deleted projects, only restore

---

## Discovery

```
GET /.well-known/oauth-protected-resource  → MCP endpoint, API base, scopes
GET /api/openapi.json                      → OpenAPI 3.0 spec
GET /skills                                → This page
```