@nolto/cli 0.5.0 → 0.6.0

package/dist/skill/roadmap-progress/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: roadmap-progress
+description: Maintain a local project's `.roadmap/roadmap.json` as work starts, completes, becomes blocked, or is replanned. Use when Codex or Claude plans project phases and tasks, begins or finishes an implementation task, reports project progress, records a blocker, or needs to keep the Roadmap Viewer current. Do not mark work done without verification. Attach plan documents to tasks with the plan command.
+---
+
+# Roadmap Progress
+
+Keep `.roadmap/roadmap.json` synchronized with verified repository work. Treat the file as the source of truth for progress reporting.
+
+## Resolve the roadmap
+
+1. Use the roadmap named by the user when provided.
+2. Otherwise locate `.roadmap/roadmap.json` from the current directory upward.
+3. If no roadmap exists and the user asked to plan or initialize the project, create one using [references/schema.md](references/schema.md). Otherwise report that it is missing; do not invent project scope.
+4. Read [references/schema.md](references/schema.md) before creating phases or tasks, changing IDs, or repairing validation errors.
+
+## Choose the workflow
+
+### Report status
+
+Read without modifying. Summarize overall completed/total tasks, current task, blocked tasks, and the next actionable todo whose dependencies are done. Run the bundled CLI `status` command when practical.
+
+### Start work
+
+Before implementation, set the selected task to `in-progress`, set `startedAt` when absent, set `currentTaskId`, update its phase status, refresh `summary`, and update `updatedAt`.
+
+### Complete work
+
+Run relevant verification first. Only after verification succeeds, set the task to `done`, set `completedAt`, clear `currentTaskId` when it points to that task, recompute the phase status, refresh `summary`, and update `updatedAt`. If verification fails, keep the task `in-progress` or mark it `blocked` with a concrete note.
+
+### Record a blocker
+
+Set the task to `blocked` and add a note that states the blocking condition and the next action or required input. Clear `currentTaskId` when it points to that task. Do not mark dependent tasks as blocked unless they have independently started; their `dependsOn` already represents the constraint.
+
+### Replan
+
+Edit phases and tasks directly while preserving stable IDs. Add dependencies only when they are real prerequisites. Keep the two-level `phases[] -> tasks[]` hierarchy; do not add epics, subtasks, or percentage fields. Progress is computed from done tasks.
+
+### Attach a plan document
+
+When an implementation plan exists as a markdown file in the repository,
+link it to its task: `roadmap.mjs plan <task-id> --path docs/plans/feature.md`.
+Paths are repository-relative (the repository root is the parent of `.roadmap/`).
+The command warns if the file does not exist yet; create the plan file first
+when possible.
+
+## Use the bundled CLI
+
+Resolve the script relative to this `SKILL.md`. Common repository installs are:
+
+- Codex: `node .agents/skills/roadmap-progress/scripts/roadmap.mjs ...`
+- Claude Code: `node .claude/skills/roadmap-progress/scripts/roadmap.mjs ...`
+
+Supported commands:
+
+```text
+roadmap.mjs [--file path] status
+roadmap.mjs [--file path] validate
+roadmap.mjs [--file path] start <task-id> [--note text] [--summary text]
+roadmap.mjs [--file path] done <task-id> [--note text] [--summary text]
+roadmap.mjs [--file path] block <task-id> --note text [--summary text]
+roadmap.mjs [--file path] todo <task-id> [--note text] [--summary text]
+roadmap.mjs [--file path] summary --text text
+roadmap.mjs [--file path] plan <task-id> --path <repo-relative-md>
+```
+
+Use direct JSON edits to add, remove, rename, or reorder phases and tasks, then run `validate`. The CLI writes atomically and maintains timestamps and phase status for task state changes.
+
+## Guardrails
+
+- `schemaVersion` is 2. Files at version 1 still validate (with a warning) and
+  are migrated to 2 automatically by any mutation command. Never edit
+  `schemaVersion` by hand.
+- This skill only writes local files. It never sends anything to a server —
+  syncing to Nolto is handled separately by `nolto watch` / `nolto sync`.
+- Use only `todo`, `in-progress`, `done`, and `blocked`. Convert legacy `in_progress` when touching that entry.
+- Keep all phase and task IDs unique across the file.
+- Preserve task IDs across title changes so `dependsOn` remains stable.
+- Keep exactly one `currentTaskId`; it must point to an `in-progress` task. Use `null` when nothing is active.
+- Require `completedAt` for done tasks and `startedAt` for in-progress tasks.
+- Keep notes factual and current; replace stale implementation notes instead of accumulating a log.
+- Never rewrite repository history or source code solely to make the roadmap appear complete.
+- Finish every mutation by running `validate` and reporting the task status changed.

package/dist/skill/roadmap-progress/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Roadmap Progress"
+  short_description: "Keep local project roadmaps accurate and current"
+  default_prompt: "Use $roadmap-progress to update this project roadmap after completing the current task."

package/dist/skill/roadmap-progress/references/schema.md

@@ -0,0 +1,81 @@
+# Roadmap schema
+
+Use this reference when creating or structurally editing `.roadmap/roadmap.json`.
+
+## Shape
+
+```json
+{
+  "schemaVersion": 2,
+  "project": {
+    "id": "my-api",
+    "name": "My API",
+    "repository": "/absolute/path/to/my-api"
+  },
+  "updatedAt": "2026-07-20T14:30:00+09:00",
+  "currentTaskId": "task-004",
+  "summary": "セッション管理を実装中。",
+  "phases": [
+    {
+      "id": "phase-auth",
+      "title": "認証",
+      "status": "in-progress",
+      "plan": "docs/plans/auth.md",
+      "tasks": [
+        {
+          "id": "task-003",
+          "title": "ログインAPI",
+          "status": "done",
+          "completedAt": "2026-07-19T18:40:00+09:00"
+        },
+        {
+          "id": "task-004",
+          "title": "セッション管理",
+          "status": "in-progress",
+          "startedAt": "2026-07-20T11:00:00+09:00",
+          "plan": "docs/plans/session-management.md",
+          "note": "Redisへの保存処理まで完了。期限切れ処理が未実装。"
+        },
+        {
+          "id": "task-005",
+          "title": "ログアウトAPI",
+          "status": "todo",
+          "dependsOn": ["task-004"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Fields
+
+- `schemaVersion`: Always `2`.
+- `project.id`: Stable lowercase identifier matching `^[a-z0-9][a-z0-9._-]*$`.
+- `project.name`: Display name.
+- `project.repository`: Absolute repository path when known.
+- `updatedAt`: Date-time of the last meaningful roadmap mutation.
+- `currentTaskId`: One active task ID or `null`.
+- `summary`: One or two current sentences; do not use as a changelog.
+- `phases`: Ordered delivery phases.
+- `phase.status`: `todo`, `in-progress`, `done`, or `blocked`.
+- `phase.plan`: Optional repository-relative path to a markdown plan document.
+- `tasks`: Ordered work items. Each must be small enough to verify clearly.
+- `task.status`: `todo`, `in-progress`, `done`, or `blocked`.
+- `task.plan`: Optional repository-relative path to a markdown plan document.
+- `startedAt`: Required in practice for `in-progress` tasks.
+- `completedAt`: Required in practice for `done` tasks.
+- `note`: Current implementation detail or blocker. Omit when it adds no value.
+- `dependsOn`: IDs of prerequisite tasks in the same roadmap.
+
+## Phase status derivation
+
+After a task mutation, derive phase status in this order:
+
+1. `done` when the phase has tasks and all are done.
+2. `in-progress` when any task is in progress.
+3. `blocked` when no task is in progress and any task is blocked.
+4. `in-progress` when some tasks are done and work remains.
+5. `todo` otherwise.
+
+Overall and phase progress are computed as `done task count / total task count`. Do not store progress percentages in JSON.

package/dist/skill/roadmap-progress/scripts/roadmap.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { access, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const STATUSES = new Set(["todo", "in-progress", "done", "blocked"]);
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const ALLOWED_KEYS = {
+  roadmap: new Set(["schemaVersion", "project", "updatedAt", "currentTaskId", "summary", "phases"]),
+  project: new Set(["id", "name", "repository"]),
+  phase: new Set(["id", "title", "status", "plan", "tasks"]),
+  task: new Set(["id", "title", "status", "startedAt", "completedAt", "note", "dependsOn", "plan"])
+};
+
+function parseArguments(argv) {
+  const options = { file: null, note: undefined, summary: undefined, text: undefined, path: undefined, positional: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--file") options.file = argv[++index];
+    else if (value === "--note") options.note = argv[++index];
+    else if (value === "--summary") options.summary = argv[++index];
+    else if (value === "--text") options.text = argv[++index];
+    else if (value === "--path") options.path = argv[++index];
+    else options.positional.push(value);
+  }
+  return options;
+}
+
+async function findRoadmap(explicitPath) {
+  if (explicitPath) return path.resolve(explicitPath);
+  let directory = process.cwd();
+  while (true) {
+    const candidate = path.join(directory, ".roadmap", "roadmap.json");
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  throw new Error("No .roadmap/roadmap.json found. Pass --file <path>.");
+}
+
+function localIsoNow() {
+  const date = new Date();
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const pad = (value) => String(Math.abs(value)).padStart(2, "0");
+  const local = new Date(date.getTime() + offsetMinutes * 60_000).toISOString().slice(0, -1);
+  return `${local}${sign}${pad(Math.trunc(offsetMinutes / 60))}:${pad(offsetMinutes % 60)}`;
+}
+
+function checkKeys(value, allowed, at, errors) {
+  for (const key of Object.keys(value ?? {})) {
+    if (!allowed.has(key)) errors.push(`${at} contains unsupported property "${key}".`);
+  }
+}
+
+function validate(roadmap) {
+  const errors = [];
+  const warnings = [];
+  if (!roadmap || typeof roadmap !== "object" || Array.isArray(roadmap)) return { errors: ["Root must be an object."], warnings };
+  checkKeys(roadmap, ALLOWED_KEYS.roadmap, "roadmap", errors);
+  if (roadmap.schemaVersion !== 1 && roadmap.schemaVersion !== 2) {
+    errors.push("schemaVersion must be 1 or 2.");
+  } else if (roadmap.schemaVersion === 1) {
+    warnings.push("schemaVersion 1 is legacy; the next mutation migrates this file to 2.");
+  }
+  checkKeys(roadmap.project, ALLOWED_KEYS.project, "project", errors);
+  if (!roadmap.project || !ID_PATTERN.test(roadmap.project.id ?? "")) errors.push("project.id is invalid.");
+  if (!roadmap.project?.name) errors.push("project.name is required.");
+  if (!roadmap.project?.repository) errors.push("project.repository is required.");
+  if (Number.isNaN(Date.parse(roadmap.updatedAt))) errors.push("updatedAt must be a valid date-time.");
+  if (typeof roadmap.summary !== "string") errors.push("summary must be a string.");
+  if (!Array.isArray(roadmap.phases)) errors.push("phases must be an array.");
+
+  const allIds = new Set();
+  const tasks = new Map();
+  for (const [phaseIndex, phase] of (Array.isArray(roadmap.phases) ? roadmap.phases : []).entries()) {
+    checkKeys(phase, ALLOWED_KEYS.phase, `phases[${phaseIndex}]`, errors);
+    if (!ID_PATTERN.test(phase.id ?? "")) errors.push(`phases[${phaseIndex}].id is invalid.`);
+    if (allIds.has(phase.id)) errors.push(`Duplicate id "${phase.id}".`);
+    allIds.add(phase.id);
+    if (!phase.title) errors.push(`phases[${phaseIndex}].title is required.`);
+    if (!STATUSES.has(phase.status)) errors.push(`phases[${phaseIndex}].status is invalid.`);
+    if (phase.plan !== undefined && (typeof phase.plan !== "string" || phase.plan.length === 0)) {
+      errors.push(`phases[${phaseIndex}].plan must be a non-empty string.`);
+    }
+    if (!Array.isArray(phase.tasks)) errors.push(`phases[${phaseIndex}].tasks must be an array.`);
+    for (const [taskIndex, task] of (Array.isArray(phase.tasks) ? phase.tasks : []).entries()) {
+      const at = `phases[${phaseIndex}].tasks[${taskIndex}]`;
+      checkKeys(task, ALLOWED_KEYS.task, at, errors);
+      if (!ID_PATTERN.test(task.id ?? "")) errors.push(`${at}.id is invalid.`);
+      if (allIds.has(task.id)) errors.push(`Duplicate id "${task.id}".`);
+      allIds.add(task.id);
+      tasks.set(task.id, task);
+      if (!task.title) errors.push(`${at}.title is required.`);
+      if (!STATUSES.has(task.status)) errors.push(`${at}.status is invalid.`);
+      if (task.status === "done" && !task.completedAt) warnings.push(`${task.id} is done without completedAt.`);
+      if (task.status === "in-progress" && !task.startedAt) warnings.push(`${task.id} is in-progress without startedAt.`);
+      if (task.plan !== undefined && (typeof task.plan !== "string" || task.plan.length === 0)) {
+        errors.push(`${at}.plan must be a non-empty string.`);
+      }
+      if (task.dependsOn !== undefined && !Array.isArray(task.dependsOn)) errors.push(`${at}.dependsOn must be an array.`);
+    }
+    if (Array.isArray(phase.tasks) && STATUSES.has(phase.status)) {
+      const expected = derivePhaseStatus(phase);
+      if (phase.status !== expected) warnings.push(`${phase.id} status is ${phase.status}; task states derive ${expected}.`);
+    }
+  }
+  for (const task of tasks.values()) {
+    for (const dependency of task.dependsOn ?? []) {
+      if (!tasks.has(dependency)) warnings.push(`${task.id} depends on unknown task ${dependency}.`);
+      if (task.id === dependency) errors.push(`${task.id} cannot depend on itself.`);
+    }
+  }
+  if (roadmap.currentTaskId !== null && roadmap.currentTaskId !== undefined) {
+    const current = tasks.get(roadmap.currentTaskId);
+    if (!current) errors.push(`currentTaskId ${roadmap.currentTaskId} does not exist.`);
+    else if (current.status !== "in-progress") warnings.push(`currentTaskId ${roadmap.currentTaskId} is not in-progress.`);
+  }
+  return { errors, warnings };
+}
+
+function derivePhaseStatus(phase) {
+  if (phase.tasks.length > 0 && phase.tasks.every((task) => task.status === "done")) return "done";
+  if (phase.tasks.some((task) => task.status === "in-progress")) return "in-progress";
+  if (phase.tasks.some((task) => task.status === "blocked")) return "blocked";
+  if (phase.tasks.some((task) => task.status === "done")) return "in-progress";
+  return "todo";
+}
+
+function findTask(roadmap, taskId) {
+  for (const phase of roadmap.phases) {
+    const task = phase.tasks.find((item) => item.id === taskId);
+    if (task) return { task, phase };
+  }
+  throw new Error(`Task "${taskId}" not found.`);
+}
+
+function stats(roadmap) {
+  const counts = { todo: 0, "in-progress": 0, done: 0, blocked: 0 };
+  for (const phase of roadmap.phases) for (const task of phase.tasks) counts[task.status] += 1;
+  const total = Object.values(counts).reduce((sum, value) => sum + value, 0);
+  return { counts, total, progress: total ? Math.round((counts.done / total) * 100) : 0 };
+}
+
+async function atomicWrite(filePath, roadmap) {
+  const temporary = `${filePath}.tmp-${process.pid}`;
+  await writeFile(temporary, `${JSON.stringify(roadmap, null, 2)}\n`, "utf8");
+  await rename(temporary, filePath);
+}
+
+function printStatus(roadmap) {
+  const result = stats(roadmap);
+  const current = roadmap.currentTaskId ? findTask(roadmap, roadmap.currentTaskId).task : null;
+  console.log(`${roadmap.project.name}: ${result.counts.done}/${result.total} done (${result.progress}%)`);
+  console.log(`Current: ${current ? `${current.id} — ${current.title}` : "none"}`);
+  const blocked = roadmap.phases.flatMap((phase) => phase.tasks).filter((task) => task.status === "blocked");
+  console.log(`Blocked: ${blocked.length ? blocked.map((task) => `${task.id} — ${task.title}`).join(", ") : "none"}`);
+  if (roadmap.summary) console.log(`Summary: ${roadmap.summary}`);
+}
+
+const options = parseArguments(process.argv.slice(2));
+const [command = "status", taskId] = options.positional;
+
+try {
+  const filePath = await findRoadmap(options.file);
+  const roadmap = JSON.parse(await readFile(filePath, "utf8"));
+
+  if (command === "status") {
+    printStatus(roadmap);
+  } else if (command === "validate") {
+    const result = validate(roadmap);
+    for (const warning of result.warnings) console.warn(`WARN ${warning}`);
+    if (result.errors.length) {
+      for (const error of result.errors) console.error(`ERROR ${error}`);
+      process.exitCode = 1;
+    } else {
+      console.log(`OK ${filePath}`);
+    }
+  } else if (command === "summary") {
+    if (options.text === undefined) throw new Error("summary requires --text.");
+    roadmap.summary = options.text;
+    roadmap.updatedAt = localIsoNow();
+    roadmap.schemaVersion = 2;
+    await atomicWrite(filePath, roadmap);
+    console.log(`Updated summary in ${filePath}`);
+  } else if (["start", "done", "block", "todo"].includes(command)) {
+    if (!taskId) throw new Error(`${command} requires a task id.`);
+    if (command === "block" && !options.note) throw new Error("block requires a non-empty --note.");
+    const { task, phase } = findTask(roadmap, taskId);
+    const now = localIsoNow();
+    if (command === "start") {
+      task.status = "in-progress";
+      task.startedAt ??= now;
+      delete task.completedAt;
+      roadmap.currentTaskId = task.id;
+    } else if (command === "done") {
+      task.status = "done";
+      task.completedAt = now;
+      if (roadmap.currentTaskId === task.id) roadmap.currentTaskId = null;
+    } else if (command === "block") {
+      task.status = "blocked";
+      delete task.completedAt;
+      if (roadmap.currentTaskId === task.id) roadmap.currentTaskId = null;
+    } else {
+      task.status = "todo";
+      delete task.startedAt;
+      delete task.completedAt;
+      if (roadmap.currentTaskId === task.id) roadmap.currentTaskId = null;
+    }
+    if (options.note !== undefined) task.note = options.note;
+    if (options.summary !== undefined) roadmap.summary = options.summary;
+    phase.status = derivePhaseStatus(phase);
+    roadmap.updatedAt = now;
+    roadmap.schemaVersion = 2;
+    const result = validate(roadmap);
+    if (result.errors.length) throw new Error(`Mutation failed validation: ${result.errors.join(" ")}`);
+    await atomicWrite(filePath, roadmap);
+    console.log(`${task.id} -> ${task.status}`);
+    for (const warning of result.warnings) console.warn(`WARN ${warning}`);
+  } else if (command === "plan") {
+    if (!taskId) throw new Error("plan requires a task id.");
+    if (!options.path) throw new Error("plan requires --path <repo-relative-md-path>.");
+    const { task } = findTask(roadmap, taskId);
+    task.plan = options.path;
+    roadmap.schemaVersion = 2;
+    roadmap.updatedAt = localIsoNow();
+    const repoRoot = path.dirname(path.dirname(filePath));
+    try {
+      await access(path.join(repoRoot, options.path));
+    } catch {
+      console.warn(`WARN plan file not found at ${path.join(repoRoot, options.path)}`);
+    }
+    const result = validate(roadmap);
+    if (result.errors.length) throw new Error(`Mutation failed validation: ${result.errors.join(" ")}`);
+    await atomicWrite(filePath, roadmap);
+    console.log(`${task.id} plan -> ${options.path}`);
+  } else {
+    throw new Error(`Unknown command "${command}".`);
+  }
+} catch (error) {
+  console.error(`roadmap-progress: ${error.message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nolto/cli",
-  "version": "0.5.0",
-  "description": "CLI for Nolto — register plans and update progress from your terminal.",
+  "version": "0.6.0",
+  "description": "CLI for syncing repository roadmaps with Nolto.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -25,19 +25,19 @@
   "homepage": "https://nolto.app",
   "keywords": [
     "nolto",
-    "mcp",
     "cli",
-    "plan",
-    "claude"
+    "roadmap",
+    "sync"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/copy-skill.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --coverage",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@nolto/roadmap-schema": "0.1.0",
+    "chokidar": "^4.0.3",
     "commander": "^14.0.0",
     "zod": "^3.24.1"
   },