project-router

What this skill does

# project-router

This skill is Safa’s **canonical project management + context switching control plane**.

Core idea:
- **Canonical PM is local + queryable (SQLite)**: projects, tasks, context packs.
- **Trello is a tracking backend/UI**: cards mirror canonical tasks; lists mirror status; labels mirror priority.
- The “killer feature” is **context switching**: load the right docs/code/index for a project/task quickly and deterministically.

It provides:
- CLI: `project <verb> ...`
- MCP server: `mcp-project-router` (tools mirror the CLI)
- Per-project bundle stored in `.project/` (brief, targets, artifact index)
- A canonical task store (SQLite) + Trello sync adapter

## Project bundle layout (v1)

The `.project/` bundle is the **project-local** context nucleus. The canonical PM DB points at these bundles.

Inside a project root:
- `.project/project.json` — structured manifest
- `.project/PROJECT.md` — living brief
- `.project/targets.json` — target definitions (commands)
- `.project/index/artifacts.json` — artifact index
- `.project/history/plans/*.json` — plans
- `.project/history/applies/*.json` — apply receipts

## CLI quick start

### Baseline / existing commands

From anywhere inside a repo/workspace:
- `project detect`
- `project context`
- `project target list`
- `project target run <name>`

Initialize a bundle (dry-run plan + apply):
- `project init` (prints plan)
- `project apply <planId>`

Artifacts:
- `project artifact add <path|url> [--tags a,b,c]` (plan + apply)

### Canonical PM + context switching (new)

> Note: these verbs are the target UX. Implementations should remain idempotent and safe.

Project registration:
- `project pm project add <slug> --name "..." --root <path>`
- `project pm project list`

Task management:
- `project pm task add <slug> "<title>" --priority P0|P1|P2|P3 [--status inbox|next|doing|blocked|waiting|done]`
- `project pm task list [--project <slug>] [--status ...]`
- `project pm task set-status <taskId> <status>`

Context switching:
- `project pm switch <slug>`
  - prints pinned docs + top targets + active tasks
- `project pm focus <taskId>`
  - loads task-linked files/artifacts and updates the task activity log

Trello sync:
- `project pm trello sync [--project <slug>]`
  - ensures the single "Safa — PM" Trello board exists
  - ensures lists exist (Inbox/Next/Doing/Blocked/Waiting/Done)
  - upserts cards for canonical tasks
  - moves cards to match status
  - applies priority labels (P0..P3)

## MCP quick start (via mcporter)

- `mcporter list mcp-project-router --schema --timeout 120000 --json`

Examples:
- Detect:
  - `mcporter call --server mcp-project-router --tool project_detect --args '{}'`
- Read context:
  - `mcporter call --server mcp-project-router --tool project_context_read --args '{}'`
- Run target:
  - `mcporter call --server mcp-project-router --tool project_target_run --args '{"target":"test"}'`

## Trello backend conventions

Single-board setup:
- Board name: `Safa — PM` (or configurable)
- Lists == canonical statuses:
  - `Inbox`, `Next`, `Doing`, `Blocked`, `Waiting`, `Done`
- Card title: `[<project_slug>] <task_title>`
- Card description begins with a machine block for idempotency:
  ```yaml
  --- pm ---
  task_id: <stable-id>
  project: <slug>
  status: <status>
  priority: P0|P1|P2|P3
  ---
  ```
- Labels (priority, color-coded):
  - `P0` = red
  - `P1` = orange
  - `P2` = yellow
  - `P3` = blue

## Canonical PM storage (SQLite)

Recommended DB location (in workspace):
- `/home/safa/clawd/data/pm/pm.sqlite`

Minimum tables (v0):
- `projects(slug PRIMARY KEY, name, root_path, created_at, updated_at)`
- `tasks(task_id PRIMARY KEY, project_slug, title, status, priority, created_at, updated_at)`
- `task_refs(task_id, kind, ref)` (file paths / urls / artifacts)
- `external_refs(task_id, system, external_id, meta_json)` (e.g., Trello card_id/list_id)

## Safety

- Project bundle writes remain **plan/apply**.
- Canonical PM writes should be idempotent and auditable (timestamps + activity log).
- Trello sync should be safe to re-run repeatedly (upsert by `task_id` marker; never duplicate cards).
- `project_target_run` executes commands defined in `.project/targets.json`.