@ai-setting/roy-task-plugin 0.4.2 → 0.5.0

package/dist/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "roy-task",
+  "version": "0.5.0",
+  "description": "Roy — task-as-first-class-citizen harness for Claude Code. Ships the roy agent, slash commands for the task lifecycle, and an MCP server exposing the task tools natively.",
+  "author": {
+    "name": "dongzhaokun",
+    "email": "gddzhaokun@gmail.com"
+  },
+  "license": "MIT",
+  "keywords": [
+    "task",
+    "task-management",
+    "roy",
+    "mcp",
+    "feishu",
+    "agent",
+    "productivity"
+  ]
+}

package/dist/claude-plugin/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "roy-task": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/roy-task-mcp-server.mjs"]
+  }
+}

package/dist/claude-plugin/agents/roy.md

@@ -0,0 +1,115 @@
+---
+name: roy
+description: Roy — task-as-first-class-citizen agent. Uses the roy-agent task lifecycle (task_tree → task_create → task_update → task_operation_create → task_complete) so every piece of work is tracked in the local task store.
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, WebFetch, WebSearch
+model: inherit
+---
+
+# Roy — task-first-class-citizen agent
+
+You are **Roy**, an agent whose defining rule is simple:
+
+> **Task is a first-class citizen. No task, no work.**
+
+You are not a chat assistant that occasionally writes notes. You are a worker
+whose output is a *visible, trackable* stream of tasks. Every non-trivial
+request (more than one tool call / more than a couple of minutes of work) MUST
+become a tracked task before you start doing it, and MUST be closed out
+explicitly when you finish.
+
+## The lifecycle (non-negotiable)
+
+### 1. Orient — `task_tree(depth=1)` (or `depth=2` for bigger trees)
+Before creating anything, look at the existing tree. Decide:
+- does this work belong to an existing root (attach via `parent_task_id`)?
+- or is it genuinely new?
+
+Keep **root tasks ≤ 10**. Prefer attaching to an existing thematic root over
+spawning a new root. Never hardcode ids — read them from `task_tree`.
+
+### 2. Create — `task_create`
+Create the task **before** doing the work. Pass:
+- `title` (imperative, specific), `description`, `goals_and_expected_deliverables`
+- `priority` (low / medium / high), `type` (normal / cycle / longterm)
+- `project_path`, `context` (JSON string: worktree_path / branch / type …)
+- `parent_task_id` when the tree said so
+
+The tool returns a **numeric task id** — that number is your handle for the
+rest of the conversation.
+
+### 3. Track — `task_update`
+Report progress as you go, not only at the end:
+- `status`: todo → active → (paused / cancelled) → completed
+- `progress`: 0–100
+- `current_status`: one human sentence about where you are right now
+
+If the scope changes, `task_update` the description/goals instead of silently
+doing something else.
+
+### 4. Record milestones — `task_operation_create`
+This tool has **two orthogonal dimensions** and you must keep them distinct:
+- **state / milestone dimension** — `milestone_type` + `milestone_title` +
+  `milestone_description`: *what* was reached (e.g. "GREEN: all tests pass").
+- **process dimension** — `process_description`: *how* you got there —
+  strategy + tool steps, strictly **100–150 characters**.
+  Too short = rejected (no value); too long = rejected (use the session log).
+
+Rules: do **not** use the process field to restate the milestone, and do not
+use milestones as a substitute for progress. Milestones mark *state
+transitions*: RED→GREEN, blocker found, decision made, review passed.
+
+### 5. Close — `task_complete`
+Before completing:
+1. `task_get(task_id)` and re-read goal + delivery.
+2. Verify the goal and delivery actually match what you delivered. If they do
+   not, either extend the task (`task_update`) or say so honestly.
+3. Call `task_complete` with `deliverable_storage_path` — a locator for the
+   work product: a file path, a git branch/worktree, a doc URL, a commit URL.
+   The path is persisted into the task context and as an operation record.
+
+`task_complete` cannot be used on `cycle` tasks (they are periodic by
+design) — use `task_update` to reset those.
+
+## Other tools
+
+- `task_get(task_id, include_operations)` — full detail; use it before
+  resuming or completing a task.
+- `task_list(...)` — flat listing with filters (status / priority / type).
+- `task_search(keywords)` — find by title / description / goals / tags.
+  **Search before creating**, to avoid duplicates.
+
+## Where tasks live
+
+All tasks and operations are persisted by the roy-task-plugin in the
+**single** project store — locally that is SQLite at
+`~/.roy-task-plugin/tasks.db` (or the remote service when the plugin is
+configured with `persistence: "remote"`). Do not create side databases, do
+not maintain your own to-do list in files, and do not track work in chat only:
+if it is not in the task store, it is not tracked.
+
+## Tool surface on Claude Code
+
+The lifecycle above is expressed through the `roy-agent tasks` CLI (run it with
+the `Bash` tool), because Claude Code does not yet expose the `task_*` tools
+natively. The mapping is 1:1 — same store, same ids, same semantics:
+
+| lifecycle step | Claude Code command |
+|---|---|
+| `task_tree(depth=1)` | `roy-agent tasks tree` |
+| `task_create` | `roy-agent tasks create "<title>" -d "<description>" -g "<goals>" -p high --project-path "<path>"` |
+| `task_update` | `roy-agent tasks update <id> --status active --progress 50 --current-status "…"` |
+| `task_operation_create` | `roy-agent tasks operations <id>` to read; record milestones via the CLI's update/ops surface |
+| `task_complete` | `roy-agent tasks complete <id> --deliverable "<path>"` |
+| `task_get` | `roy-agent tasks get <id>` |
+| `task_list` | `roy-agent tasks list` |
+| `task_search` | `roy-agent tasks search <keywords>` |
+
+Prefer `--json` (`-j`) when you need to parse ids. The task id printed by
+`create` is your handle for the rest of the turn.
+
+## Style
+
+- Be direct and concrete; the user is reading task titles and milestones.
+- Report the task id and its state whenever you finish a step.
+- If a task is blocked, mark it (`task_update(status="paused")`) and record a
+  `problem` milestone explaining the blocker instead of going silent.

package/dist/claude-plugin/commands/task-complete.md

@@ -0,0 +1,25 @@
+---
+description: Complete a task with its deliverable path
+allowed-tools: Bash(roy-agent tasks:*)
+argument-hint: "<task-id> [deliverable path]"
+---
+
+Complete a task.
+
+**Arguments**: `$ARGUMENTS`
+
+Parse as: `<task-id> [deliverable path]`. If `$ARGUMENTS` is empty, ask the
+user for the task id.
+
+The deliverable path is where the work product lives — a file path, a URL, a
+git branch, a worktree path. It is what makes the outcome traceable, so ask
+for it if the user did not give one.
+
+Run `roy-agent tasks complete <task-id> --deliverable "<path>" --json`.
+
+Before completing, confirm the task's goals are actually met: run
+`roy-agent tasks get <task-id> --json` and check the goals against what was
+delivered. If they are not met, say so instead of completing it.
+
+If the `roy-task` MCP server is available in this session, prefer the
+`task_complete` tool over the CLI.

package/dist/claude-plugin/commands/task-create.md

@@ -0,0 +1,19 @@
+---
+description: Create a tracked task (task is a first-class citizen)
+allowed-tools: Bash(roy-agent tasks:*), Read, Write, Edit
+argument-hint: "<title> [description] [priority]"
+---
+
+Create a task in the roy task store.
+
+**Arguments**: `$ARGUMENTS`
+
+If `$ARGUMENTS` is empty, ask the user for a one-line title first, then create the task.
+
+Steps:
+
+1. Look at the existing task tree first — the new task may belong under an existing root. If it does, use that root's id as `parent_task_id`.
+2. Create the task with `roy-agent tasks create "<title>" --description "<what and why>" --priority <low|medium|high> --type <normal|cycle|longterm> --json`.
+3. Report the new task id back to the user — that number is the handle for every later operation (`/task-update`, `/task-milestone`, `/task-complete`).
+
+If the `roy-task` MCP server is available in this session, prefer the `task_create` tool over the CLI; both write to the same store.

package/dist/claude-plugin/commands/task-list.md

@@ -0,0 +1,17 @@
+---
+description: List tasks, optionally filtered by status
+allowed-tools: Bash(roy-agent tasks:*)
+argument-hint: "[status]"
+---
+
+List tasks.
+
+**Arguments**: `$ARGUMENTS` — an optional status filter (`todo`, `active`,
+`completed`, `paused`, `cancelled`, `archived`). With no argument, list active
+and todo tasks.
+
+Run `roy-agent tasks list --json` (adding `--status <status>` when given) and
+render a compact table: id, status, progress, title.
+
+If the `roy-task` MCP server is available in this session, prefer the
+`task_list` tool over the CLI.

package/dist/claude-plugin/commands/task-milestone.md

@@ -0,0 +1,39 @@
+---
+description: Record a milestone on a task (what was reached)
+allowed-tools: Bash(roy-agent tasks:*)
+argument-hint: "<task-id> <milestone title> [description]"
+---
+
+Record a milestone on a task.
+
+**Arguments**: `$ARGUMENTS`
+
+Parse as: `<task-id> <milestone title> [description]`. If `$ARGUMENTS` is
+empty, ask the user for the task id and the milestone title.
+
+A milestone records **state**: "RED reproduced", "GREEN: 21/21 pass", "blocker
+found", "decision made". It is not a log line of what you did.
+
+Record it with the `task_operation_create` tool when the `roy-task` MCP server
+is available. Otherwise fall back to the CLI:
+
+```
+roy-agent tasks operations <task-id> --json
+```
+
+…is read-only, so for the CLI path use the `roy-task` MCP server or record the
+milestone through the task's update surface and note the limitation to the
+user.
+
+If you do have the MCP server, call `task_operation_create` with:
+
+- `task_id` — the task id
+- `milestone_type` — one of `create`, `progress`, `milestone`, `problem`,
+  `solution`, `decision`, `review`, `completed`
+- `milestone_title` — one line
+- `milestone_description` — what was reached
+- `process_description` — **how** you got there, strictly 100–150 characters
+  (this is enforced; too short or too long is rejected)
+
+Keep the two dimensions distinct: the milestone says *what* was reached, the
+process description says *how*.

package/dist/claude-plugin/commands/task-tree.md

@@ -0,0 +1,20 @@
+---
+description: Show the task tree (roots, children, status)
+allowed-tools: Bash(roy-agent tasks:*)
+---
+
+Show the current task tree.
+
+Run `roy-agent tasks tree --json` and render it as an indented outline:
+
+```
+#1234  [active]  Title here                     (3 children)
+  #1240  [todo]   Child task
+```
+
+Include the task id, status, progress and title for every node. Highlight
+which nodes are roots (no parent) so the user can tell at a glance whether a
+new task should be attached to one of them.
+
+If the `roy-task` MCP server is available in this session, prefer the
+`task_tree` tool over the CLI.

package/dist/claude-plugin/commands/task-update.md

@@ -0,0 +1,26 @@
+---
+description: Update a task's status, progress or current status
+allowed-tools: Bash(roy-agent tasks:*)
+argument-hint: "<task-id> [status] [progress] [current-status]"
+---
+
+Update a task.
+
+**Arguments**: `$ARGUMENTS`
+
+Parse the arguments as: `<task-id> [status] [progress] [current-status]`.
+If `$ARGUMENTS` is empty, ask the user for the task id and what to change.
+
+Run:
+
+```
+roy-agent tasks update <task-id> --status <status> --progress <0-100> --current-status "<one sentence>" --json
+```
+
+Only pass the flags the user actually specified. Status must be one of
+`todo`, `active`, `completed`, `paused`, `cancelled`, `archived`.
+
+Report the resulting task back, including its id and new status.
+
+If the `roy-task` MCP server is available in this session, prefer the
+`task_update` tool over the CLI.

package/dist/claude-plugin/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "description": "roy-task lifecycle hooks: surface the task discipline to Claude and keep the store's state honest.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop-check.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/claude-plugin/hooks/session-start.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * `SessionStart` hook — tell Claude that task tracking is available.
+ *
+ * ## What it does
+ *
+ * Prints one short line on stdout telling Claude that the roy task tools are
+ * wired up, and nothing else. On `SessionStart`, stdout is injected into the
+ * model's context, so this is a cheap way to make the task discipline
+ * discoverable without the user having to remember the slash commands.
+ *
+ * ## Why it does NOT touch the progress card
+ *
+ * The Feishu progress card is sent by the **roy-task daemon**, which is
+ * runtime-agnostic and already issues `startTask` / `updateTask` / `finishTask`
+ * around every dispatch. A Claude hook that also patched the card would be a
+ * second writer for the same card — and Claude Code hooks have no channel back
+ * to the daemon (no shared session id, no card id). The daemon is the only
+ * component that knows which card belongs to which Feishu message.
+ *
+ * So: hooks give Claude *context*, the daemon owns the *card*. That split is
+ * the reason this hook is a one-liner instead of a card driver.
+ *
+ * ## Contract
+ *
+ * - stdout: one context line (this is the hook's output channel).
+ * - stderr: diagnostics only.
+ * - exit 0 always: a hook that fails must never block the session.
+ */
+
+function main() {
+  const dbPath = process.env.ROY_TASK_DB_PATH || "(roy-agent default)";
+  process.stdout.write(
+    [
+      "roy-task plugin active.",
+      "Task tracking is available two ways:",
+      "  - native MCP tools (the task_* family: tree, create, get, list, update,",
+      "    milestone, complete, search)",
+      "  - CLI bridge: `roy-agent tasks …`",
+      "Task is a first-class citizen: create the task before doing the work, update it",
+      "as you go, record milestones, and complete it with a deliverable path.",
+      `Task store: ${dbPath}`,
+      "",
+    ].join("\n"),
+  );
+  process.exit(0);
+}
+
+main();

package/dist/claude-plugin/hooks/stop-check.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * `Stop` hook — check that the work left a task behind.
+ *
+ * ## What it does
+ *
+ * When Claude Code decides to stop, this hook looks for a task that is still
+ * `active` (or `todo`) and was touched during this session. If it finds one,
+ * it **blocks** the stop with a short reason: "task #1234 is still active —
+ * complete it or say why not".
+ *
+ * If there is no open task, it approves and exits silently.
+ *
+ * ## Why this is safe to auto-block on
+ *
+ * The check is deliberately narrow:
+ *
+ * - it only looks at tasks in `active` / `todo` state — a completed task never
+ *   blocks anything;
+ * - it only blocks when the session actually **used** a task tool, which we
+ *   detect from the transcript the hook is given on stdin. A session that never
+ *   touched a task is never blocked, so an ordinary conversation is unaffected;
+ * - it never blocks on the *first* stop — a task the user just created is
+ *   legitimately still open. It only blocks once the work looks finished.
+ *
+ * ## Why it does NOT drive the progress card
+ *
+ * Same reason as `session-start.mjs`: the progress card belongs to the
+ * roy-task daemon, which is the only component that knows the Feishu message
+ * and card ids. See the "Why it does NOT touch the progress card" section of
+ * that file.
+ *
+ * ## Contract
+ *
+ * - stdin: the hook payload (JSON) — we read it, we never block on it.
+ * - stdout: the decision JSON.
+ * - stderr: diagnostics only.
+ * - exit 0 always: a hook that throws must not wedge the session.
+ */
+
+import { openStore, defaultTaskDbPath, BridgeError } from "../mcp/bridge.mjs";
+
+/** Read stdin fully, with a hard cap so a huge transcript cannot stall us. */
+async function readStdin(limitBytes = 2 * 1024 * 1024) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > limitBytes) break;
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Did this session actually *call* a task tool?
+ *
+ * The hook payload carries `tool_input` / `transcript_path`. The transcript is
+ * the reliable signal — but it is a JSONL transcript of *messages*, and it
+ * contains far more than tool calls: the SessionStart hook's own context
+ * banner mentions `task_create` by name, and so does this file's own
+ * documentation. A naive substring search over the whole transcript therefore
+ * matches a session that never touched a task at all.
+ *
+ * So we do not search the raw text. We parse the transcript as JSONL and look
+ * specifically at **tool_use blocks** — the structured representation of "the
+ * model invoked a tool named X". Only that counts.
+ */
+function sessionUsedTaskTools(payload, transcriptEntries) {
+  const TASK_TOOLS = new Set([
+    "task_create",
+    "task_update",
+    "task_complete",
+    "task_operation_create",
+    "task_list",
+    "task_tree",
+    "task_get",
+    "task_search",
+  ]);
+
+  for (const entry of transcriptEntries) {
+    const blocks = collectToolUseBlocks(entry);
+    for (const name of blocks) {
+      if (TASK_TOOLS.has(name)) return true;
+    }
+  }
+
+  // Fallback for payloads that carry the tool name directly (no transcript).
+  if (!transcriptEntries.length) {
+    const direct = payload && payload.tool_name;
+    if (typeof direct === "string" && TASK_TOOLS.has(direct)) return true;
+  }
+  return false;
+}
+
+/** Pull every `tool_use` block name out of one transcript entry. */
+function collectToolUseBlocks(entry) {
+  const names = [];
+  if (!entry || typeof entry !== "object") return names;
+
+  const message = entry.message ?? entry;
+  const content = message && message.content;
+
+  const pushBlock = (block) => {
+    if (!block || typeof block !== "object") return;
+    if (block.type === "tool_use" && typeof block.name === "string") {
+      names.push(block.name);
+    }
+  };
+
+  if (Array.isArray(content)) {
+    for (const block of content) pushBlock(block);
+  } else if (content && typeof content === "object") {
+    pushBlock(content);
+  }
+  return names;
+}
+
+/** Parse a JSONL transcript into entries, skipping unparseable lines. */
+function parseTranscript(raw) {
+  const entries = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      // A transcript can contain non-JSON lines; skip them.
+    }
+  }
+  return entries;
+}
+
+/** The most recently updated task that is still open. */
+function findOpenTask(db) {
+  const row = db
+    .prepare(
+      `SELECT id, title, status FROM task
+       WHERE status IN ('todo', 'active')
+       ORDER BY updated_at DESC LIMIT 1`,
+    )
+    .get();
+  return row ?? null;
+}
+
+function approve() {
+  process.stdout.write(JSON.stringify({ decision: "approve" }));
+  process.exit(0);
+}
+
+function block(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      decision: "block",
+      reason,
+      systemMessage: "roy-task: an open task must be closed out before stopping.",
+    }),
+  );
+  process.exit(0);
+}
+
+async function main() {
+  let payload = {};
+  let transcriptEntries = [];
+  try {
+    const raw = await readStdin();
+    if (raw.trim().length > 0) payload = JSON.parse(raw);
+  } catch {
+    payload = {};
+  }
+
+  try {
+    const transcriptPath = payload && payload.transcript_path;
+    if (typeof transcriptPath === "string" && transcriptPath.length > 0) {
+      const { readFileSync } = await import("node:fs");
+      transcriptEntries = parseTranscript(readFileSync(transcriptPath, "utf8"));
+    }
+  } catch {
+    transcriptEntries = [];
+  }
+
+  // No task tool was actually *called* in this session -> nothing to enforce.
+  if (!sessionUsedTaskTools(payload, transcriptEntries)) {
+    approve();
+    return;
+  }
+
+  let db;
+  try {
+    db = openStore(process.env.ROY_TASK_DB_PATH || defaultTaskDbPath());
+  } catch (err) {
+    // A store we cannot open is not a reason to block the user.
+    approve();
+    return;
+  }
+
+  try {
+    const open = findOpenTask(db);
+    if (!open) {
+      approve();
+      return;
+    }
+    block(
+      `Task #${open.id} ("${open.title}") is still ${open.status}. ` +
+        `Complete it with a deliverable path, or update it to reflect that it stays open.`,
+    );
+  } catch (err) {
+    if (err instanceof BridgeError) {
+      approve();
+      return;
+    }
+    approve();
+  } finally {
+    try {
+      db.close();
+    } catch {
+      // already closed
+    }
+  }
+}
+
+main().catch(() => approve());