roadmap-skill 0.2.9 → 0.2.10

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.10] - 2026-02-27
+
+### Added
+- **Contributing Section**: Added Contributing section to README (en/zh)
+
+### Changed
+- **README**: Revamped copy for both en/zh versions, improved clarity and tone
+- **Tag ID Workflow**: Unified tag-id handling with deterministic color fallback
+
+
+## [0.2.9] - 2026-02-26
+
+### Added
+- **Development Scripts**: Added `dev:web`, `dev:server`, `dev:full`, and `inspector` npm scripts
+- **Vite Proxy**: Frontend dev server now proxies API requests to backend automatically
+- **Verbose Parameter**: Tools now support `verbose` parameter for compact vs full data responses
+- **Summary Types**: Added `TaskSummary` and `ProjectSummary` types for lightweight responses
+- **MCP Inspector**: Added `npm run inspector` command for debugging MCP server
+
+### Changed
+- **UI Layout**: Moved filter bar to header alongside title for better space usage
+- **Compact Mode**: Optimized spacing, removed tags, reduced margins and padding
+- **Hover Animation**: Reduced card hover displacement from `-translate-y-1` to `-translate-y-0.5`
+- **Create Button**: Changed task creation button color to project theme green
+
+### Fixed
+- **Completed Tasks**: Fixed "All" filter to properly include completed tasks via `includeCompleted` parameter
+
+## [0.2.8] - 2026-02-26
+
+### Fixed
+- **MCP Transport**: Resolved stdio transport issues for better CLI compatibility
+- **Tag System**: Improved tag management and display in task cards
+
+### Changed
+- Updated README with latest features and improvements
+
+## [0.2.7] - 2026-02-26
+
+### Fixed
+- **Static Files Path**: Corrected bundled static files path for npx environment execution
+
+### Added
+- **Release Documentation**: Added release workflow documentation to AGENTS.md
+
+## [0.2.6] - 2026-02-26
+
+### Fixed
+- **Static Files Path**: Resolved static files path resolution for npx execution environment
+
+## [0.2.5] - 2026-02-26
+
+### Added
+- **NovaBoard UI**: Integrated tag system with NovaBoard-style dashboard design
+- **Tag System**: Full tag management with color coding and filtering
+
+### Fixed
+- **Server Path**: Use `__dirname` instead of `process.cwd()` for reliable static files path resolution
+
 ## [0.2.0] - 2026-02-10
 
 ### Added

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <strong>Let AI manage your projects, keep Kanban simple</strong><br>
-  Zero-config startup, local data, Agent-native support
+  <strong>Shared roadmap for humans and AI Agents</strong><br>
+  Visual kanban for you. MCP server for Agents. Local-first.
 </p>
 
 <p align="center">
@@ -26,15 +26,15 @@
 
 ---
 
-## Why Roadmap Skill?
+## What Makes It Different
 
-| Your Pain Point | How Roadmap Skill Solves It |
-|----------------|----------------------------|
-| Project data scattered in third-party clouds | **Local-first** — All data stored on your machine, full control, works offline |
-| Copy-pasting task lists when chatting with AI | **Agent-native** — AI reads/writes tasks directly, zero friction in conversation |
-| Text-only management lacks visuals, but traditional tools are bloated | **Beautiful Kanban** — Open browser when needed, drag and drop, doesn't interrupt coding flow |
-| Ideas and bugs from Vibe Coding get forgotten | **Collection Box** — Let Agent capture scattered thoughts, auto-organize todos |
-| Too many tasks, don't know where to start | **Smart Recommendations** — Agent analyzes context, proactively suggests next steps |
+**Shared context** — Chat with your Agent to plan tasks, or edit directly in the Kanban — both stay in sync. Your Agent always sees the latest state.
+
+**Agent-native** — Built as an MCP server. Your AI can create, update, and query tasks directly in conversation.
+
+**Lightweight Kanban** — Open `localhost:7860` when you feel like it, or ask your Agent to open it with `open_web_interface`. Or just stay in chat. All three work.
+
+**Local-first** — Your data lives on your machine. No accounts, no cloud sync, no vendor lock-in.
 
 ---
 
@@ -282,69 +282,35 @@ The AI will immediately create the project and tasks, saving them to local stora
 
 ## Who Is This For?
 
-| Scenario | What Roadmap Skill Does For You |
-|---------|--------------------------------|
-| **Solo Developers** | Manage personal projects through conversation, avoid getting lost in complex tools |
-| **AI Power Users** | Let Agent directly read/write tasks, goodbye to copy-pasting hassle |
-| **Vibe Coders** | Capture inspirations on the fly, automatically save to collection box |
-| **Small Teams** | Simple task assignment and progress tracking, zero learning curve |
-| **Privacy-conscious Users** | Data stored completely locally, never uploaded to any cloud service |
+Solo developers, AI power users, and vibe coders who want their Agent to be a real collaborator — not just a code generator.
 
 ---
 
 ## Typical Use Cases
 
-### 1. Capture Inspiration During Vibe Coding
-
-When discussing new features with AI, suddenly think of an optimization:
-
-> "Add this to my collection: Refactor user auth module using JWT + Refresh Token scheme"
-
-AI automatically creates the task, and you'll see it in the Kanban later.
-
-### 2. Let AI Plan Project Structure
-
-Starting a new project? Just ask AI to break it down:
-
-> "Create an e-commerce admin dashboard project with product management, order processing, and user permissions modules, broken down into specific development tasks"
-
-AI auto-creates the project structure. Just open the Kanban in browser and drag tasks to start working.
+### 1. Capture Ideas Without Breaking Flow
 
-### 3. Progress Tracking and Status Updates
+Mid-session, something comes to mind:
 
-Check progress anytime during coding:
+> "Note this down: switch the auth module to JWT + refresh token rotation"
 
-> "What's the completion percentage of my current project? What high-priority tasks haven't started yet?"
+Your Agent creates the task. You stay in flow. Open the Kanban later to review.
 
-> "Mark the user login feature as completed and create corresponding test tasks"
+### 2. Let AI Bootstrap Your Project Plan
 
-### 4. Team Collaboration and Assignment
+Starting something new:
 
-Quickly assign in conversation:
+> "Set up a project for the admin dashboard — product management, orders, and user permissions. Break each into tasks."
 
-> "Assign frontend page tasks to @zhangsan, deadline this Friday, priority high"
+Agent scaffolds the whole structure. You open the board and start dragging.
 
-Team members can view their task list in the Kanban.
+### 3. Check In Without Leaving the Chat
 
----
-
-## Installation
-
-### Requirements
-
-- Node.js 18+ (recommended 20+)
-
-### Global Install
+> "What's left on the current project? Anything high priority I haven't touched?"
 
-```bash
-npm install -g roadmap-skill
-```
-
-### Use Without Installing
+> "Mark the login feature done and add a task for writing tests."
 
-```bash
-npx roadmap-skill          # Full MCP server
-```
+No tab switching. No copy-pasting. Just ask.
 
 ---
 

package/README.zh.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <strong>让 AI 帮你管理项目，让看板回归简洁</strong><br>
-  零配置启动，本地数据，Agent 原生支持
+  <strong>人类与 AI Agent 共享的项目看板</strong><br>
+  你看到的，Agent 也看到。对话里规划，看板里审阅。或者相反。
 </p>
 
 <p align="center">
@@ -26,15 +26,15 @@
 
 ---
 
-## 为什么选择 Roadmap Skill？
+## 这个 MCP 有什么不同？
 
-| 你的困扰 | Roadmap Skill 的解决方式 |
-|---------|-------------------------|
-| 项目数据散落在第三方云端，缺乏安全感 | **本地优先** — 所有数据存储在你的电脑，完全掌控，离线可用 |
-| 和 AI 对话时需要来回粘贴任务列表 | **Agent 原生** — AI 直接读写任务，对话中自然管理，零摩擦 |
-| 纯文本管理缺乏直观性，但传统工具太重 | **美观看板** — 需要时打开浏览器，拖拽即可，不打扰编码流 |
-| Vibe Coding 中的灵感、Bug 随手记在某处就忘了 | **收集箱** — 让 Agent 帮你沉淀零散想法，自动整理待办 |
-| 任务太多不知从何开始，优先级全靠猜 | **智能推荐** — Agent 分析项目上下文，主动建议下一步工作 |
+**人机共享视图** — 在对话里和 Agent 一起规划任务，也可以直接在看板上手动编辑，两种方式实时互通。你和Agent 始终能获取到最新状态。
+
+**Agent 原生** — 以 MCP 服务器形式运行。AI 可以在对话中直接创建、更新、查询任务。
+
+**轻量看板** — 你想看的时候打开 `localhost:7860`。懒得开浏览器？直接让 Agent `/open-web-ui` 也行。
+
+**本地优先** — 数据存在你的机器上。无需账号，无云同步，不依赖任何第三方服务。
 
 ---
 
@@ -279,69 +279,33 @@ AI 会立即为你创建项目和任务，并自动写入本地存储。你可
 
 ## 适合谁使用
 
-| 场景 | Roadmap Skill 能为你做什么 |
-|------|---------------------------|
-| **独立开发者** | 用对话管理个人项目，避免在复杂工具中迷失 |
-| **AI 重度用户** | 让 Agent 直接读写任务，告别来回粘贴的繁琐 |
-| **Vibe Coder** | 随手让 AI 记录灵感，自动沉淀到收集箱 |
-| **小团队协作** | 简单的任务分配与进度追踪，无需学习成本 |
-| **隐私敏感者** | 数据完全本地存储，不上传任何云端服务 |
-
----
+独立开发者、AI 重度用户、Vibe Coder — 想让 Agent 真正参与项目协作，而不只是写代码的人。
 
 ## 典型使用场景
 
-### 1. Vibe Coding 中的灵感收集
-
-正在和 AI 讨论新功能时，突然想到一个优化点：
-
-> "帮我把这个想法记到收集箱：重构用户认证模块，使用 JWT + Refresh Token 方案"
-
-AI 自动创建任务，稍后你打开看板就能看到待整理的想法。
-
-### 2. 让 AI 规划项目结构
-
-开始一个新项目时，直接让 AI 帮你分解：
-
-> "创建一个电商后台管理项目，包含商品管理、订单处理、用户权限三个模块，每个模块分解为具体的开发任务"
+### 1. 不打断流地记录想法
 
-AI 自动创建项目结构，你只需要在浏览器中打开看板，拖拽任务开始工作。
+编着编着突然想到一个优化点：
 
-### 3. 进度追踪与状态更新
+> "记一下：把认证模块改成 JWT + refresh token 方案"
 
-编码过程中随时询问：
+Agent 创建任务。你继续写代码。稍后打开看板再回顾。
 
-> "我当前项目完成了多少百分比？有哪些高优先级任务还没开始？"
+### 2. 让 AI 帮你搭建项目结构
 
-> "把用户登录功能的状态改为已完成，并创建对应的测试任务"
+开始一个新项目：
 
-### 4. 团队协作分配
+> "创建一个电商后台项目，包含商品管理、订单处理、用户权限三个模块，每个模块拆分为具体任务"
 
-在对话中快速分配：
+Agent 直接搭好整个结构。你打开看板开始拖拽。
 
-> "把前端页面的任务分配给 @张三，截止日期设为本周五，优先级设为高"
+### 3. 不离开对话窗口就能检查进度
 
-团队成员可以在看板中查看自己的任务列表。
+> "当前项目还剩什么？有没有高优先级的任务还没动？"
 
----
-
-## 安装
-
-### 环境要求
+> "把登录功能标为已完成，再加一个写测试的任务"
 
-- Node.js 18+ (推荐 20+)
-
-### 全局安装
-
-```bash
-npm install -g roadmap-skill
-```
-
-### 免安装使用
-
-```bash
-npx roadmap-skill          # 完整 MCP 服务器
-```
+不用切换标签页，不用复制粘贴。直接问就行。
 
 ---
 
@@ -359,11 +323,9 @@ npx roadmap-skill          # 完整 MCP 服务器
 
 ## 支持平台
 
-- ✅ **Claude Code** — 命令行 AI 助手
-- ✅ **Claude Desktop** — 完整 MCP 集成
-- ✅ **Cursor** — AI 驱动的 IDE
-- ✅ **VS Code** — 通过 Cline 或 Roo Code 扩展
-- ✅ **任意 MCP 客户端** — 标准 MCP 协议支持
+- ✅ **Claude Code, Codex, OpenCode** — 命令行 AI 助手
+- ✅ **Cursor, VS Code** — AI 驱动的 IDE
+- ✅ **任意支持 MCP 的客户端** — 标准 MCP 协议支持
 
 ---
 

package/dist/index.js

@@ -345,14 +345,15 @@ var storage = new ProjectStorage();
 // src/tools/project-tools.ts
 var ProjectTypeEnum = z.enum(["roadmap", "skill-tree", "kanban"]);
 var ProjectStatusEnum = z.enum(["active", "completed", "archived"]);
-function toProjectSummary(project, taskCount) {
+function toProjectSummary(project, taskCount, tags) {
   return {
     id: project.id,
     name: project.name,
     projectType: project.projectType,
     status: project.status,
     targetDate: project.targetDate,
-    taskCount
+    taskCount,
+    ...tags ? { tags } : {}
   };
 }
 function toTaskSummary(task) {
@@ -401,16 +402,33 @@ var createProjectTool = {
 };
 var listProjectsTool = {
   name: "list_projects",
-  description: "List all projects. Returns summaries by default; set verbose=true for full project data.",
+  description: "List all projects. Summary mode includes current project tags for Agent reuse. Set verbose=true for full project data.",
   inputSchema: z.object({
     verbose: z.boolean().optional()
   }),
   async execute(input) {
     try {
       const projects = await storage.listProjects();
+      if (input.verbose) {
+        return {
+          success: true,
+          data: projects
+        };
+      }
+      const summaries = await Promise.all(
+        projects.map(async (projectSummary) => {
+          const projectData = await storage.readProject(projectSummary.project.id);
+          const tags = (projectData?.tags ?? []).map((tag) => ({
+            id: tag.id,
+            name: tag.name,
+            color: tag.color
+          }));
+          return toProjectSummary(projectSummary.project, projectSummary.taskCount, tags);
+        })
+      );
       return {
         success: true,
-        data: input.verbose ? projects : projects.map((p) => toProjectSummary(p.project, p.taskCount))
+        data: summaries
       };
     } catch (error) {
       return {
@@ -533,6 +551,39 @@ init_esm_shims();
 function generateTagId() {
   return `tag_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 }
+var HEX_COLOR_PATTERN = /^#[0-9A-Fa-f]{6}$/;
+var TAG_COLOR_PALETTE = [
+  "#FF6B6B",
+  "#FF9F43",
+  "#FDCB6E",
+  "#6C5CE7",
+  "#74B9FF",
+  "#00B894",
+  "#00CEC9",
+  "#E17055",
+  "#FAB1A0",
+  "#55A3FF",
+  "#A29BFE",
+  "#FD79A8"
+];
+function hashTagName(value) {
+  let hash = 5381;
+  for (const char of value.toLowerCase()) {
+    hash = hash * 33 ^ char.charCodeAt(0);
+  }
+  return Math.abs(hash >>> 0);
+}
+function resolveTagColor(tagName, inputColor) {
+  if (inputColor) {
+    return inputColor;
+  }
+  const normalizedTagName = tagName.trim();
+  if (normalizedTagName.length === 0) {
+    return TAG_COLOR_PALETTE[0];
+  }
+  const colorIndex = hashTagName(normalizedTagName) % TAG_COLOR_PALETTE.length;
+  return TAG_COLOR_PALETTE[colorIndex];
+}
 var TagService = class {
   storage;
   constructor(storage2) {
@@ -564,11 +615,19 @@ var TagService = class {
           code: "DUPLICATE_ERROR"
         };
       }
+      const resolvedColor = resolveTagColor(data.name, data.color);
+      if (!HEX_COLOR_PATTERN.test(resolvedColor)) {
+        return {
+          success: false,
+          error: `Color must be a valid hex code (e.g., #FF5733), received '${resolvedColor}'`,
+          code: "VALIDATION_ERROR"
+        };
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const tag = {
         id: generateTagId(),
         name: data.name,
-        color: data.color,
+        color: resolvedColor,
         description: data.description || "",
         createdAt: now
       };
@@ -667,6 +726,13 @@ var TagService = class {
           };
         }
       }
+      if (data.color && !HEX_COLOR_PATTERN.test(data.color)) {
+        return {
+          success: false,
+          error: `Color must be a valid hex code (e.g., #FF5733), received '${data.color}'`,
+          code: "VALIDATION_ERROR"
+        };
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const existingTag = projectData.tags[tagIndex];
       const updatedTag = {
@@ -818,6 +884,10 @@ function calculateCompletedAt(currentStatus, newStatus, existingCompletedAt, now
   }
   return existingCompletedAt;
 }
+function findInvalidTagIds(projectData, tagIds) {
+  const validTagIds = new Set(projectData.tags.map((tag) => tag.id));
+  return tagIds.filter((tagId) => !validTagIds.has(tagId));
+}
 var TaskService = {
   /**
    * Create a new task in a project
@@ -835,6 +905,15 @@ var TaskService = {
           code: "NOT_FOUND"
         };
       }
+      const incomingTagIds = data.tags ?? [];
+      const invalidTagIds = findInvalidTagIds(projectData, incomingTagIds);
+      if (invalidTagIds.length > 0) {
+        return {
+          success: false,
+          error: `Invalid tag IDs for project '${projectId}': ${invalidTagIds.join(", ")}`,
+          code: "VALIDATION_ERROR"
+        };
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const task = {
         id: generateTaskId(),
@@ -843,7 +922,7 @@ var TaskService = {
         description: data.description,
         status: "todo",
         priority: data.priority ?? "medium",
-        tags: data.tags ?? [],
+        tags: incomingTagIds,
         dueDate: data.dueDate ?? null,
         assignee: data.assignee ?? null,
         createdAt: now,
@@ -936,6 +1015,16 @@ var TaskService = {
           code: "VALIDATION_ERROR"
         };
       }
+      if (data.tags) {
+        const invalidTagIds = findInvalidTagIds(projectData, data.tags);
+        if (invalidTagIds.length > 0) {
+          return {
+            success: false,
+            error: `Invalid tag IDs for project '${projectId}': ${invalidTagIds.join(", ")}`,
+            code: "VALIDATION_ERROR"
+          };
+        }
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const existingTask = projectData.tasks[taskIndex];
       const completedAt = calculateCompletedAt(
@@ -1067,9 +1156,19 @@ var TaskService = {
           continue;
         }
         const existingTask = projectData.tasks[taskIndex];
-        let updatedTags = existingTask.tags;
-        if (data.tags && data.tags.length > 0) {
-          const existingTags = existingTask.tags || [];
+        let updatedTags = existingTask.tags ?? [];
+        if (data.tags) {
+          const invalidTagIds = findInvalidTagIds(projectData, data.tags);
+          if (invalidTagIds.length > 0) {
+            return {
+              success: false,
+              error: `Invalid tag IDs for project '${projectId}': ${invalidTagIds.join(", ")}`,
+              code: "VALIDATION_ERROR"
+            };
+          }
+        }
+        if (data.tags) {
+          const existingTags = existingTask.tags ?? [];
           switch (data.tagOperation) {
             case "add":
               updatedTags = [.../* @__PURE__ */ new Set([...existingTags, ...data.tags])];
@@ -1147,7 +1246,7 @@ function toTaskSummary2(task) {
 }
 var createTaskTool = {
   name: "create_task",
-  description: "Create a new task in a project. Returns summary by default; set verbose=true for full data.",
+  description: "Create a new task in a project. tags must be existing tag IDs from the same project. Returns summary by default; set verbose=true for full data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     title: z2.string().min(1, "Task title is required"),
@@ -1227,7 +1326,7 @@ var getTaskTool = {
 };
 var updateTaskTool = {
   name: "update_task",
-  description: "Update an existing task. Returns summary by default; set verbose=true for full data.",
+  description: "Update an existing task. tags must be existing tag IDs from the same project. Returns summary by default; set verbose=true for full data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     taskId: z2.string().min(1, "Task ID is required"),
@@ -1270,7 +1369,7 @@ var deleteTaskTool = {
 };
 var batchUpdateTasksTool = {
   name: "batch_update_tasks",
-  description: "Update multiple tasks at once. Returns summaries by default; set verbose=true for full task data.",
+  description: "Update multiple tasks at once. tags must be existing tag IDs from the same project. Returns summaries by default; set verbose=true for full task data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     taskIds: z2.array(z2.string()).min(1, "At least one task ID is required"),
@@ -1304,11 +1403,11 @@ import { z as z3 } from "zod";
 var tagService = new TagService(storage);
 var createTagTool = {
   name: "create_tag",
-  description: "Create a new tag in a project",
+  description: "Create a new tag in a project. If color is omitted, it is generated deterministically from tag name.",
   inputSchema: z3.object({
     projectId: z3.string().min(1, "Project ID is required"),
     name: z3.string().min(1, "Tag name is required"),
-    color: z3.string().regex(/^#[0-9A-Fa-f]{6}$/, "Color must be a valid hex code (e.g., #FF5733)"),
+    color: z3.string().regex(/^#[0-9A-Fa-f]{6}$/, "Color must be a valid hex code (e.g., #FF5733)").optional(),
     description: z3.string().default("")
   }),
   async execute(input) {
@@ -2462,8 +2561,18 @@ Suggest relevant tags:
 - Priority tags: urgent, important
 - Domain tags: frontend, backend, design, testing (if applicable)
 
+Tag consistency rules:
+- list_tags first, then prefer reusing existing tags in that project
+- If no suitable tag exists, create_tag first (color optional, system can auto-generate) and then use the returned tag ID
+- create_task.tags must contain tag IDs only (not tag names)
+
 ### 4. Create Task
 Use create_task to create the task immediately \u2014 no confirmation needed.
+Before create_task:
+1. Call list_tags(projectId)
+2. Match suggested tags to existing tags by name (case-insensitive)
+3. For missing tags, call create_tag(projectId, name, color?)
+4. Build create_task.tags from tag IDs only
 
 ### 5. Status
 After creating, if work starts immediately, use update_task to set status to in-progress.
@@ -2478,6 +2587,7 @@ After creating, if work starts immediately, use update_task to set status to in-
 - Type: Bug
 - Priority: High (affects user experience)
 - Suggested Tags: bug, frontend, mobile
+- create_task.tags: [existing_or_new_tag_ids]
 - Recommended Project: [Recommend if there's a web project]
 
 ## Current Idea: