project-router

# 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`.