handoff-mcp-server 0.8.1 → 0.11.0

package/skills/handoff-import/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: handoff-import
+description: "Import existing handoff documents into .handoff/ management. Reads the specified file, structures its content into tasks/decisions/blockers/notes, and calls handoff_import_context in one shot. Triggers on '/handoff-import <path>', 'import handoff', 'take this into handoff'."
+user-invocable: true
+---
+
+# Handoff Import
+
+Import an existing handoff document (Markdown, JSON, or free-text) into
+structured `.handoff/` management via a single `handoff_import_context` call.
+
+## Usage
+
+```
+/handoff-import tmp/260601-sprint-handoff.md
+/handoff-import path/to/any-document.md
+```
+
+If called without arguments, ask the user for a file path.
+
+## Procedure
+
+1. **Init check**: Verify `.handoff/` exists. If not, run `handoff_init` first.
+
+2. **Read the source**: Read the specified file with the Read tool.
+
+3. **Analyze and structure**: Decompose the content into the categories below.
+
+4. **Import**: Call `handoff_import_context` once with all extracted data.
+
+5. **Report**: Show how many tasks were created, whether a session was saved,
+   and whether raw_notes captured anything.
+
+6. **Verify**: Call `handoff_list_tasks` to display the import result and
+   ask the user to confirm correctness.
+
+## Field Mapping Guide
+
+### tasks — Extracting Structured Tasks
+
+Every actionable item in the source document becomes a task.
+Always populate these fields:
+
+| Field | How to extract |
+|---|---|
+| `title` | Short imperative phrase (e.g. "Add retry logic to USB reconnect") |
+| `status` | Map from source: "done"/"completed" -> `done`, "WIP"/"in progress" -> `in_progress`, "blocked" -> `blocked`, else `todo` |
+| `priority` | See priority rules below. Must be `low`, `medium`, or `high` |
+| `notes` | Context that doesn't fit elsewhere: root cause, constraints, approach taken |
+| `labels` | Category tags from the source (e.g. `["auth", "security"]`, `["pio", "dma"]`) |
+| `links` | Related file paths, issue URLs, MR URLs, wiki pages |
+| `done_criteria` | Verifiable checklist items extracted from prose (see below) |
+| `children` | Sub-tasks nested under a parent |
+| `schedule.estimate_hours` | If effort estimates are mentioned (e.g. "~2h", "half a day") |
+| `schedule.due_date` | If deadlines are mentioned (ISO format) |
+| `schedule.milestone` | If milestone names are mentioned |
+| `dependencies` | Task IDs this task depends on (e.g. "after t1", "once X is done") |
+| `order` | Display ordering hints (e.g. P0→P1→P2 maps to 0, 1, 2) |
+
+### done_criteria — Converting Prose to Checkable Items
+
+Transform vague descriptions into specific, testable criteria:
+
+**Before** (raw handoff prose):
+> USB reconnect needs to handle the case where the host doesn't re-enumerate.
+> Also make sure the pattern engine restarts cleanly.
+
+**After** (structured done_criteria):
+```json
+[
+  {"item": "Host non-enumeration triggers fallback reset after 3s timeout", "checked": false},
+  {"item": "Pattern engine SM_RESTART executes on reconnect", "checked": false},
+  {"item": "cargo test passes for reconnect scenarios", "checked": false}
+]
+```
+
+Each criterion should be:
+- **Observable**: can be verified by running code, reading output, or checking state
+- **Specific**: names the function, file, behavior, or metric
+- **Independent**: can be checked without knowing other criteria
+
+**done_criteria must cover the full verification chain** — not just implementation:
+
+| Category | Example criteria |
+|---|---|
+| Implementation | "Add validation logic to signup form" |
+| Automated checks | "All tests pass, linter clean" |
+| **Real-run verification** | "App runs and the feature works as expected in the actual environment" |
+
+A task is not done until verified end-to-end by running the real artifact.
+Passing automated checks alone is insufficient.
+
+### links — What to Reference
+
+```json
+[
+  "src/usb/reconnect.rs",
+  "https://gitlab.com/group/project/-/issues/42",
+  "https://gitlab.com/group/project/-/merge_requests/18",
+  "wiki/30-usb-protocol.md"
+]
+```
+
+Include paths to:
+- Source files being modified
+- Issues or MRs related to the task
+- Wiki pages or docs that provide context
+- External references (datasheets, specs)
+
+### priority — Estimation Rules
+
+| Priority | When to use |
+|---|---|
+| `high` | Blocks other work, causes failures, user explicitly flagged as urgent, safety/security |
+| `medium` | Improves existing functionality, needed for the current milestone, moderate impact |
+| `low` | Nice-to-have, cosmetic, future consideration, no immediate impact |
+
+Signals in source text:
+- "must", "critical", "blocker", "breaks", "urgent" -> `high`
+- "should", "improve", "enhance", "needed" -> `medium`
+- "could", "maybe", "eventually", "nice to have", "low priority" -> `low`
+
+When ambiguous, default to `medium`.
+
+### session — Decisions, Blockers, Notes
+
+| Field | What to extract |
+|---|---|
+| `summary` | One-line overview with `[import]` prefix |
+| `decisions` | Technical choices with `reason` and `confidence` (`confirmed`/`estimated`/`unverified`) |
+| `blockers` | Anything preventing progress (dependencies, missing info, hardware) |
+| `handoff_notes` | `caution`: risks and warnings. `context`: background info. `suggestion`: concrete next actions |
+| `references` | Documents, issues, MRs, wikis relevant to the import |
+| `context_pointers` | Files the next session should read first, with line ranges if known |
+
+### raw_notes — The Safety Net
+
+Anything that doesn't fit the structured fields goes into `raw_notes`.
+Never discard information from the source — if it can't be structured,
+preserve it as raw text.
+
+## source Field
+
+```json
+{
+  "description": "Import from <filepath>",
+  "format": "markdown"
+}
+```
+
+Detect format from file extension: `.md` -> `markdown`, `.json` -> `json`,
+`.txt` -> `text`, other -> `other`.
+
+## Structuring Guidelines
+
+- **When in doubt, make it a task**: Register borderline items as tasks with
+  context in notes. They can be `skipped` later.
+- **Never discard info**: Everything from the source must land somewhere —
+  tasks, session, or raw_notes.
+- **Always reference the source**: Include the source file path in `references`.
+- **Mark estimates**: When status or priority is inferred, note "(estimated)"
+  in the task's notes.
+
+## Full Example
+
+**Source document** (`tmp/260610-sprint-handoff.md`):
+> ## Current work
+> Auth module rewrite is 80% done. Decided on OAuth2+PKCE for mobile support.
+> Token refresh tests still failing — need to mock the expiry clock.
+>
+> ## Tasks
+> - [x] Session migration script (deployed to prod)
+> - [ ] PKCE flow (frontend + backend)
+> - [ ] CI pipeline takes 12min, target is 5min
+>
+> ## Blockers
+> - DB migration window not scheduled yet
+
+**Structured call**:
+```json
+{
+  "source": {"description": "tmp/260610-sprint-handoff.md", "format": "markdown"},
+  "tasks": [
+    {
+      "title": "Auth module rewrite",
+      "status": "in_progress",
+      "priority": "high",
+      "notes": "80% done. Token refresh tests failing due to clock mocking.",
+      "labels": ["auth", "security"],
+      "links": ["src/auth/oauth.rs", "src/auth/token.rs"],
+      "done_criteria": [
+        {"item": "Token refresh test passes with mocked expiry clock", "checked": false},
+        {"item": "OAuth2 PKCE flow works on mobile client", "checked": false}
+      ],
+      "children": [
+        {"title": "Session migration script", "status": "done", "notes": "Deployed to prod"},
+        {
+          "title": "PKCE flow implementation",
+          "status": "in_progress",
+          "priority": "high",
+          "children": [
+            {"title": "Frontend PKCE integration", "status": "todo"},
+            {"title": "Backend PKCE endpoints", "status": "todo"}
+          ]
+        }
+      ]
+    },
+    {
+      "title": "CI pipeline optimization",
+      "status": "todo",
+      "priority": "medium",
+      "labels": ["ci"],
+      "done_criteria": [
+        {"item": "CI build time under 5 minutes", "checked": false}
+      ]
+    }
+  ],
+  "session": {
+    "summary": "[import] Sprint handoff migration from tmp/260610",
+    "decisions": [
+      {"decision": "OAuth2 + PKCE for auth", "reason": "Mobile app needs PKCE; implicit flow not viable", "confidence": "confirmed"}
+    ],
+    "blockers": ["DB migration window not scheduled"],
+    "references": [
+      {"label": "Source handoff doc", "uri": "tmp/260610-sprint-handoff.md", "type": "doc"}
+    ]
+  }
+}
+```
+
+## Common Mistakes
+
+- **Empty done_criteria**: Every `todo`/`in_progress` task should have at least one criterion.
+- **Missing links**: If the source mentions files or issues, capture them in `links`.
+- **Generic priority**: Don't leave priority empty. Apply the rules above.
+- **Flat structure**: If tasks have natural parent-child relationships, use `children`.
+- **Discarding info**: Use `raw_notes` for anything that doesn't fit structured fields.
+- **Missing schedule fields**: If the source mentions estimates, deadlines, or milestones, capture them.

package/skills/handoff-load/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: handoff-load
+description: "Load handoff context for the current project. Calls handoff_load_context, summarizes tasks/decisions/blockers, and shows what to work on next. Triggers on '/handoff-load', 'コンテキスト読み込み', 'what was I working on', 'resume work'."
+user-invocable: true
+---
+
+# Handoff Load
+
+セッション開始時にプロジェクトの引き継ぎコンテキストを読み込み、現状を把握する。
+
+## 手順
+
+1. `handoff_load_context` を呼ぶ（引数なし — cwd を使用）
+2. `not_initialized` が返った場合:
+   - ディレクトリ名からプロジェクト名を推測
+   - `handoff_init` で初期化
+   - 初期化完了を報告して終了
+3. **paused セッション**がある場合:
+   - `paused_sessions` をユーザーに表示（ID, summary, branch）
+   - 再開したい場合: `handoff_load_context(session_id: "s-...")` で paused → active に遷移
+   - 不要な場合: `handoff_save_context(close_session_id: "s-...")` で paused → closed に直接遷移
+4. **`session_guidance` がある場合（アクティブセッション未確立）**:
+   - 作業開始前に `handoff_save_context` を `session_status: "active"` で呼んでセッションを確立する
+   - `session_guidance.suggested_fields` の内容（summary, decisions, context_pointers, references, related_task_ids）を引き継いで含める
+   - `handoff_notes` に最低1つ `suggestion`（これから何をするか）を含める
+   - これにより中断時にも「何をしようとしていたか」が `.handoff/` に残る
+5. 返されたコンテキストを以下の順で確認・要約:
+   - **前回セッション / previous_session**: summary, branch, commit, ended_at。引き継ぎ情報（decisions, handoff_notes, context_pointers）を確認
+   - **タスク**: `blocked` → `in_progress` → `todo` の優先順で表示
+   - **工数サマリー**: total_estimate_hours, total_actual_hours, completion_rate, overdue_count を報告
+   - **期限超過**: overdue_count > 0 なら該当タスクを強調
+   - **ブロッカー**: あれば強調表示
+   - **決定事項**: confidence が `unverified` のものを警告
+   - **申し送り**: `caution` を最初に、`context` → `suggestion` の順
+   - **コンテキストポインタ**: 次に読むべきファイル一覧
+6. ユーザーに現状サマリーを日本語で報告
+7. 次のアクションを提案（「何から始めますか？」）

package/skills/handoff-refer/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: handoff-refer
+description: "Send a cross-project referral to another project's .handoff/. Triggers on 'send referral', 'refer to <project>', 'cross-project', 'notify other project', or when work in one project reveals an issue/improvement needed in another."
+---
+
+# Handoff Refer Skill
+
+Send a structured referral (improvement request, bug report, work request)
+from the current project to another project that uses handoff-mcp.
+
+## When to Use
+
+- You discover a bug in a dependency project during work
+- You identify an improvement needed in another project
+- You want to request work from another team/project
+- Cross-project coordination is needed
+
+## Procedure
+
+1. Identify the target project (by name or path).
+2. Determine the referral type: `improvement`, `bug`, `request`, or `info`.
+3. Call `handoff_refer` with **all required fields**:
+   - `summary`: one-line description
+   - `referral_type`: category
+   - `priority`: `low`, `medium`, or `high`
+   - `target_project` (name) or `target_project_dir` (path)
+   - `details`: what changed, its impact, and what the target needs to do
+   - `tasks`: concrete work items with `done_criteria`
+   - `context`: source references (branch, commit, spec docs, MR links)
+4. If warnings are returned, fix them before proceeding. The server
+   validates completeness — omitting `details`, `tasks`, `context`, or
+   `priority` triggers warnings. Tasks without `done_criteria` also warn.
+5. Report confirmation to the user.
+
+## Target Resolution
+
+- **By name**: `target_project: "pochi-dio"` — resolved via `scan_dirs` in config
+- **By path**: `target_project_dir: "/home/user/pro/pochi-dio"` — direct path
+
+Use name when the project is in a scan_dirs directory.
+Use path when targeting a project outside scan_dirs.
+
+## Managing Received Referrals
+
+When `handoff_load_context` shows incoming referrals:
+
+1. Review each referral's summary and priority.
+2. Acknowledge with `handoff_update_referral` (status: `acknowledged`).
+3. Create tasks based on the referral if appropriate.
+4. Resolve with `handoff_update_referral` (status: `resolved`) when done.
+
+## Example
+
+```json
+{
+  "target_project": "handoff-mcp",
+  "summary": "Import skill needs better task structuring guidance",
+  "referral_type": "improvement",
+  "priority": "medium",
+  "details": "When importing 20 tasks from pochi-dio, done_criteria and links were mostly empty.",
+  "tasks": [
+    {
+      "title": "Add before/after examples to import skill",
+      "priority": "medium",
+      "done_criteria": [
+        {"item": "Skill includes concrete field mapping examples"}
+      ]
+    }
+  ]
+}
+```

package/src/mcp/handlers/assignees.rs

@@ -0,0 +1,254 @@
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use serde_json::{json, Value};
+use toml_edit::{DocumentMut, Item, Table};
+
+use super::config_crud::{
+    load_doc, require_str, save_doc, set_opt_f64, set_opt_str, set_string_array,
+};
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::tasks::{build_task_index, TaskIndex};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let config_path = handoff.join("config.toml");
+    let tasks_dir = handoff.join("tasks");
+
+    let raw = std::fs::read_to_string(&config_path)
+        .with_context(|| format!("Failed to read config: {}", config_path.display()))?;
+    let doc: DocumentMut = raw.parse().with_context(|| "Failed to parse config.toml")?;
+
+    let assignees_table = doc.get("assignees").and_then(|v| v.as_table());
+
+    let mut result: HashMap<String, Value> = HashMap::new();
+
+    if let Some(table) = assignees_table {
+        for (key, item) in table.iter() {
+            let sub = match item.as_table() {
+                Some(t) => t,
+                None => continue,
+            };
+
+            let display_name = sub
+                .get("display_name")
+                .and_then(|v| v.as_str())
+                .unwrap_or(key);
+            let color = sub.get("color").and_then(|v| v.as_str()).unwrap_or("");
+            let work_hours = sub
+                .get("work_hours_per_day")
+                .and_then(|v| v.as_integer().or_else(|| v.as_float().map(|f| f as i64)))
+                .unwrap_or(8);
+            let closed_weekdays: Vec<Value> = sub
+                .get("closed_weekdays")
+                .and_then(|v| v.as_array())
+                .map(|arr| {
+                    arr.iter()
+                        .filter_map(|v| {
+                            v.as_str()
+                                .map(|s| json!(s))
+                                .or_else(|| v.as_integer().map(|n| json!(n)))
+                        })
+                        .collect()
+                })
+                .unwrap_or_default();
+
+            result.insert(
+                key.to_string(),
+                json!({
+                    "display_name": display_name,
+                    "color": color,
+                    "work_hours_per_day": work_hours,
+                    "closed_weekdays": closed_weekdays,
+                    "task_count": 0,
+                    "active_task_count": 0,
+                    "total_estimate_hours": 0.0,
+                    "total_actual_hours": 0.0,
+                }),
+            );
+        }
+    }
+
+    // Count tasks per assignee
+    if tasks_dir.exists() {
+        let (tree, _) = build_task_index(&tasks_dir, u32::MAX)?;
+        count_assignee_tasks(&tree, &mut result);
+    }
+
+    let output = json!({ "assignees": result });
+    serde_json::to_string_pretty(&output).map_err(Into::into)
+}
+
+fn count_assignee_tasks(tree: &[TaskIndex], result: &mut HashMap<String, Value>) {
+    for node in tree {
+        if let Some(ref assignee) = node.assignee {
+            if let Some(entry) = result.get_mut(assignee) {
+                if let Some(obj) = entry.as_object_mut() {
+                    let tc = obj.get("task_count").and_then(|v| v.as_u64()).unwrap_or(0);
+                    obj.insert("task_count".to_string(), json!(tc + 1));
+
+                    if node.status == "in_progress" || node.status == "review" {
+                        let ac = obj
+                            .get("active_task_count")
+                            .and_then(|v| v.as_u64())
+                            .unwrap_or(0);
+                        obj.insert("active_task_count".to_string(), json!(ac + 1));
+                    }
+
+                    if let Some(ref sched) = node.schedule {
+                        if let Some(est) = sched.estimate_hours {
+                            let cur = obj
+                                .get("total_estimate_hours")
+                                .and_then(|v| v.as_f64())
+                                .unwrap_or(0.0);
+                            obj.insert("total_estimate_hours".to_string(), json!(cur + est));
+                        }
+                        if let Some(act) = sched.actual_hours {
+                            let cur = obj
+                                .get("total_actual_hours")
+                                .and_then(|v| v.as_f64())
+                                .unwrap_or(0.0);
+                            obj.insert("total_actual_hours".to_string(), json!(cur + act));
+                        }
+                    }
+                }
+            }
+        }
+
+        count_assignee_tasks(&node.children, result);
+    }
+}
+
+/// handoff_add_assignee — create a new `[assignees.<key>]` entry. Fails if the
+/// key already exists.
+pub fn handle_add(arguments: &Value) -> Result<String> {
+    let path = super::config_crud::config_path(arguments)?;
+    let key = require_str(arguments, "key")?;
+    let mut doc = load_doc(&path)?;
+
+    let assignees = super::config_crud::ensure_table(&mut doc, "assignees")?;
+    assignees.set_implicit(true);
+    if assignees.contains_key(key) {
+        anyhow::bail!("Assignee '{key}' already exists. Use handoff_update_assignee to modify it.");
+    }
+    let mut sub = Table::new();
+    apply_assignee_fields(&mut sub, arguments);
+    doc["assignees"][key] = Item::Table(sub);
+
+    save_doc(&path, &doc)?;
+    Ok(format!("Added assignee '{key}'"))
+}
+
+/// handoff_update_assignee — patch an existing `[assignees.<key>]` entry.
+pub fn handle_update(arguments: &Value) -> Result<String> {
+    let path = super::config_crud::config_path(arguments)?;
+    let key = require_str(arguments, "key")?;
+    let mut doc = load_doc(&path)?;
+
+    let exists = doc
+        .get("assignees")
+        .and_then(|v| v.as_table())
+        .map(|t| t.contains_key(key))
+        .unwrap_or(false);
+    if !exists {
+        anyhow::bail!("Assignee '{key}' not found. Use handoff_add_assignee to create it.");
+    }
+    let sub = super::config_crud::ensure_subtable(&mut doc, "assignees", key)?;
+    apply_assignee_fields(sub, arguments);
+
+    save_doc(&path, &doc)?;
+    Ok(format!("Updated assignee '{key}'"))
+}
+
+/// handoff_remove_assignee — delete a `[assignees.<key>]` entry and unassign it
+/// from every task (matches the VSCode extension's removeAssignee behaviour).
+pub fn handle_remove(arguments: &Value) -> Result<String> {
+    let path = super::config_crud::config_path(arguments)?;
+    let key = require_str(arguments, "key")?;
+    let mut doc = load_doc(&path)?;
+
+    let removed = doc
+        .get_mut("assignees")
+        .and_then(|v| v.as_table_mut())
+        .map(|t| t.remove(key).is_some())
+        .unwrap_or(false);
+    if !removed {
+        anyhow::bail!("Assignee '{key}' not found.");
+    }
+    save_doc(&path, &doc)?;
+
+    // Unassign from tasks.
+    let tasks_dir = path
+        .parent()
+        .map(|p| p.join("tasks"))
+        .ok_or_else(|| anyhow::anyhow!("Cannot locate tasks dir"))?;
+    let unassigned = unassign_all(&tasks_dir, key)?;
+
+    Ok(format!(
+        "Removed assignee '{key}' and unassigned it from {unassigned} task(s)"
+    ))
+}
+
+/// Apply the optional assignee fields from `arguments` onto a TOML table.
+fn apply_assignee_fields(table: &mut Table, arguments: &Value) {
+    table.set_implicit(false);
+    set_opt_str(table, "display_name", arguments.get("display_name"));
+    set_opt_str(table, "color", arguments.get("color"));
+    set_opt_f64(
+        table,
+        "work_hours_per_day",
+        arguments.get("work_hours_per_day"),
+    );
+    super::config_crud::set_mixed_array(table, "closed_weekdays", arguments.get("closed_weekdays"));
+    set_string_array(table, "closed_dates", arguments.get("closed_dates"));
+    set_string_array(table, "open_dates", arguments.get("open_dates"));
+    super::config_crud::set_f64_map(table, "day_hours", arguments.get("day_hours"));
+}
+
+/// Clear `assignee` on every task currently assigned to `key`. Returns the count.
+fn unassign_all(tasks_dir: &Path, key: &str) -> Result<usize> {
+    use crate::storage::tasks::{read_task, write_task};
+    use chrono::Utc;
+
+    let mut count = 0;
+    let dirs = collect_task_dirs(tasks_dir)?;
+    for dir in dirs {
+        if let Some((mut data, status)) = read_task(&dir)? {
+            if data.assignee.as_deref() == Some(key) {
+                data.assignee = None;
+                data.updated_at = Some(Utc::now().to_rfc3339());
+                write_task(&dir, &status, &data)?;
+                count += 1;
+            }
+        }
+    }
+    Ok(count)
+}
+
+/// Recursively collect every task directory under `tasks_dir`.
+fn collect_task_dirs(dir: &Path) -> Result<Vec<PathBuf>> {
+    let mut out = Vec::new();
+    collect_task_dirs_into(dir, &mut out)?;
+    Ok(out)
+}
+
+fn collect_task_dirs_into(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
+    if !dir.exists() {
+        return Ok(());
+    }
+    for entry in std::fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if path.is_dir() {
+            // A task directory contains a `_task.<status>.json` file.
+            if crate::storage::tasks::find_task_file(&path)?.is_some() {
+                out.push(path.clone());
+            }
+            collect_task_dirs_into(&path, out)?;
+        }
+    }
+    Ok(())
+}