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.