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:

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