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: INLINECODE0
- 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 - INLINECODE5 — living brief
- INLINECODE6 — target definitions (commands)
- INLINECODE7 — artifact index
- INLINECODE8 — plans
- INLINECODE9 — apply receipts
CLI quick start
Baseline / existing commands
From anywhere inside a repo/workspace:
- - INLINECODE10
- INLINECODE11
- INLINECODE12
- INLINECODE13
Initialize a bundle (dry-run plan + apply):
- -
project init (prints plan) - INLINECODE15
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:
- - INLINECODE17
- INLINECODE18
Task management:
- - INLINECODE19
- INLINECODE20
- INLINECODE21
Context switching:
- prints pinned docs + top targets + active tasks
- loads task-linked files/artifacts and updates the task activity log
Trello sync:
- 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)
Examples:
-
mcporter call --server mcp-project-router --tool project_detect --args '{}'
-
mcporter call --server mcp-project-router --tool project_context_read --args '{}'
- INLINECODE28
Trello backend conventions
Single-board setup:
- - Board name:
Safa — PM (or configurable) - Lists == canonical statuses:
-
Inbox,
Next,
Doing,
Blocked,
Waiting,
Done
- - Card title: INLINECODE36
- 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):
Minimum tables (v0):
- - INLINECODE42
- INLINECODE43
- INLINECODE44 (file paths / urls / artifacts)
- INLINECODE45 (e.g., Trello cardid/listid)
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). - INLINECODE47 executes commands defined in
.project/targets.json.
project-router
该技能是Safa的标准项目管理+上下文切换控制平面。
核心理念:
- - 标准PM是本地+可查询的(SQLite):项目、任务、上下文包。
- Trello是跟踪后端/UI:卡片镜像标准任务;列表镜像状态;标签镜像优先级。
- “杀手级功能”是上下文切换:快速且确定性地加载项目/任务的正确文档/代码/索引。
它提供:
- - CLI:project ...
- MCP服务器:mcp-project-router(工具镜像CLI)
- 存储在.project/中的每个项目包(简介、目标、工件索引)
- 标准任务存储(SQLite)+ Trello同步适配器
项目包布局(v1)
.project/包是项目本地上下文核心。标准PM数据库指向这些包。
在项目根目录内:
- - .project/project.json — 结构化清单
- .project/PROJECT.md — 动态简介
- .project/targets.json — 目标定义(命令)
- .project/index/artifacts.json — 工件索引
- .project/history/plans/.json — 计划
- .project/history/applies/.json — 应用收据
CLI快速入门
基础/现有命令
从仓库/工作区的任何位置:
- - project detect
- project context
- project target list
- project target run
初始化包(预演计划+应用):
- - project init(打印计划)
- project apply
工件:
- - project artifact add [--tags a,b,c](计划+应用)
标准PM+上下文切换(新)
注意:这些动词是目标用户体验。实现应保持幂等性和安全性。
项目注册:
- - project pm project add --name ... --root
- project pm project list
任务管理:
- - project pm task add --priority P0|P1|P2|P3 [--status inbox|next|doing|blocked|waiting|done]
- project pm task list [--project ] [--status ...]
- project pm task set-status
上下文切换:
- 打印固定文档+顶部目标+活跃任务
- 加载任务关联的文件/工件并更新任务活动日志
Trello同步:
- - project pm trello sync [--project ]
- 确保存在单个“Safa — PM”Trello看板
- 确保列表存在(收件箱/下一步/进行中/阻塞/等待/完成)
- 为标准任务更新或插入卡片
- 移动卡片以匹配状态
- 应用优先级标签(P0..P3)
MCP快速入门(通过mcporter)
- - mcporter list mcp-project-router --schema --timeout 120000 --json
示例:
- mcporter call --server mcp-project-router --tool project_detect --args {}
- mcporter call --server mcp-project-router --tool project
contextread --args {}
- mcporter call --server mcp-project-router --tool project
targetrun --args {target:test}
Trello后端约定
单看板设置:
- - 看板名称:Safa — PM(或可配置)
- 列表 == 标准状态:
- 收件箱、下一步、进行中、阻塞、等待、完成
- - 卡片标题:[slug>] title>
- 卡片描述以机器块开头,确保幂等性:
yaml
--- pm ---
task_id: <稳定ID>
project:
status: <状态>
priority: P0|P1|P2|P3
- P0 = 红色
- P1 = 橙色
- P2 = 黄色
- P3 = 蓝色
标准PM存储(SQLite)
推荐的数据库位置(在工作区中):
- - /home/safa/clawd/data/pm/pm.sqlite
最小表(v0):
- - projects(slug PRIMARY KEY, name, rootpath, createdat, updatedat)
- tasks(taskid PRIMARY KEY, projectslug, title, status, priority, createdat, updatedat)
- taskrefs(taskid, kind, ref)(文件路径/URL/工件)
- externalrefs(taskid, system, externalid, metajson)(例如,Trello cardid/list_id)
安全性
- - 项目包写入保持计划/应用模式。
- 标准PM写入应幂等且可审计(时间戳+活动日志)。
- Trello同步应可安全重复运行(通过taskid标记更新或插入;绝不重复卡片)。
- projecttarget_run执行在.project/targets.json中定义的命令。