goaltracker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nhat-TheDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# GoalTracker MCP
+
+**Persistent, structured project memory for AI coding agents.** GoalTracker is an MCP server that gives an agent like Claude Code a real plan to work from — `Goal → Spec → Milestone → Task → Note` — stored in a single SQLite file, so a context reset (or a completely different agent picking up the same work) is a 1-tool-call recovery, not a "let me re-read the whole conversation" guessing game.
+
+## Why
+
+Long-running coding work rarely fits in one session. An ad-hoc todo list in chat doesn't survive a context reset, and it definitely doesn't survive a handoff to a different agent. GoalTracker fixes that by being the thing both agents actually read and write, not just describe:
+
+- **A context-reset agent recovers everything in one call.** `goal_get_context` returns the goal, the confirmed spec, every milestone with its task counts, and the last checkpoint — no re-deriving the plan from memory.
+- **A different agent (or a different session, hours or days later) sees the real state**, including *why* something is blocked, not just that it is.
+- **The MCP never guesses on your behalf.** It stores and returns structured data; all planning judgment stays with the agent — and, for the two places that matter most (finalizing a spec, approving a too-small milestone), with you.
+
+## Quick start
+
+```bash
+npm install -g goaltracker
+```
+
+Add it to your MCP client config (Claude Code, Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "goaltracker": {
+      "command": "npx",
+      "args": ["-y", "goaltracker"]
+    }
+  }
+}
+```
+
+(If installed globally, `"command": "goaltracker"` works without `npx`.)
+
+Then install the companion skill, which teaches the agent the correct call sequence — session warm-up, spec confirmation before breaking milestones, the milestone-approval flow, checkpoint habits:
+
+```bash
+npx goaltracker install-skill              # personal — ~/.claude/skills/, every project
+npx goaltracker install-skill --project     # this project only — ./.claude/skills/
+```
+
+That's it. Data lives in a single SQLite file, created automatically on first run at `~/.goaltracker/goaltracker.db` (override with `GOALTRACKER_DB_PATH`). Schema upgrades apply themselves on startup — you never run a migration by hand.
+
+## A worked example
+
+A goal, planned, confirmed with you, worked on at whatever pace you choose, handed off to a second agent, and closed — the way it actually plays out with the skill installed:
+
+![GoalTracker example flow: drafting and confirming a spec, breaking into milestones and tasks, approving an undersized milestone, presenting the final plan, picking a check-in cadence, working, checkpointing, a different agent resuming, and closing the goal](docs/example-flow.svg)
+
+In short: nothing gets broken into milestones until you've confirmed the spec, and nothing starts running until you've confirmed the final plan and picked how often the agent checks in with you. `checkpoint_save` closes every stop. A completely different agent (a different session, hours or days later — even a different Claude) recovers everything with one `goal_get_context` call, including what the previous agent was doing and why, before `status_report` and a final check against the spec close the goal out.
+
+### Zooming in: a second agent finishes the goal
+
+The diagram above shows the handoff as one dashed arrow. Here's what it actually looks like in practice — Session 1 ran out of context partway through; Session 2 is a fresh agent (could be a different Claude entirely) with no memory of any of it:
+
+![A second agent finishing a goal: Agent A's session ends, Agent B calls goal_list and goal_get_context to recover milestones/progress/why a task is blocked, reports status and asks the user for the missing piece, then finishes the remaining tasks and closes the goal](docs/example-flow-handoff.svg)
+
+```
+goal_list({ status: "active" })
+→ [{ id: "g_42", title: "Add notification system", status: "active" }]
+
+goal_get_context({ goal_id: "g_42" })
+→ {
+    goal: { title: "Add notification system", status: "active" },
+    spec: { overview: "...", acceptance_criteria: [ ... ] },
+    milestones: [
+      { milestone: { title: "M1 — Email delivery", status: "completed" }, task_counts: { completed: 3 } },
+      { milestone: { title: "M2 — Push notifications", status: "in_progress" }, task_counts: { completed: 2, in_progress: 1, blocked: 1 } }
+    ],
+    milestones_pending_approval: [],
+    progress: { completion_pct: 62, total_tasks: 8, completed: 5, in_progress: 1, blocked: 1, pending: 1 },
+    last_checkpoint: {
+      current_task_id: "t_17",
+      agent_summary: "M1 done and verified. Started M2 — push service is blocked: which push provider to use hasn't been decided yet.",
+      next_actions: ["Ask the user to pick a push provider", "Once decided, finish t_17 then t_18"]
+    }
+  }
+```
+
+One call, and Agent B already knows exactly what happened — no need to ask the user to recap anything:
+
+```
+Agent B: "Picking up 'Add notification system' — M1 (email) is done. M2 (push notifications) is
+blocked: which push provider do you want — Firebase Cloud Messaging, or a custom service?"
+
+[user picks Firebase Cloud Messaging]
+
+task_add_note({ task_id: "t_17", content: "User chose Firebase Cloud Messaging as the push provider.", type: "decision" })
+task_update_status({ task_id: "t_17", status: "in_progress" })
+  → [does the work] → task_update_status({ task_id: "t_17", status: "completed" })
+
+task_list({ milestone_id: "m_2", status: "pending" })
+→ [{ id: "t_18", title: "Wire up the push notification settings page" }]
+
+task_update_status({ task_id: "t_18", status: "in_progress" })
+  → [does the work] → task_update_status({ task_id: "t_18", status: "completed" })
+
+status_report({ goal_id: "g_42" })
+→ { progress: { completion_pct: 100 }, blocked_tasks: [], acceptance_criteria: [ ... ] }
+
+[Agent B checks acceptance_criteria against the actual task evidence]
+
+goal_update_status({ goal_id: "g_42", status: "completed" })
+```
+
+Agent A never told Agent B about the pending provider decision directly — it was written into `checkpoint_save`'s `agent_summary` / `next_actions` back in Session 1, and `goal_get_context` handed it straight to Agent B. The two agents never "talked"; the second one still finished the goal with full context.
+
+## How it works
+
+- **Data only, no reasoning.** The MCP stores and returns structured data. All planning judgment — how to break down work, when a spec is good enough, whether a small milestone is intentional — stays with the agent (and, via the skill, with you).
+- **One hierarchy, one DB.** `Goal → Spec → Milestone → Task → Note`, all in one SQLite file. The agent only ever needs to remember `goal_id`.
+- **Fast warm-up.** `goal_get_context` is the single call that replaces re-reading everything.
+- **Audit trail.** Every status change carries a timestamp and, for `blocked`/`cancelled`, a required reason.
+- **One real gate.** Milestones with fewer than 2 active tasks require an explicit `milestone_approve` before work can start on them — everywhere else, the MCP never rejects a call.
+
+Full schema, every tool's exact input/output, and the design rationale behind each decision: [docs/design/DESIGN.md](docs/design/DESIGN.md).
+
+## Tools (14 total)
+
+| Group | Tools |
+|---|---|
+| Goal | `goal_create`, `goal_list`, `goal_get_context` ⭐ |
+| Spec | `spec_set` |
+| Milestone | `milestone_create`, `milestone_approve` |
+| Task | `task_create`, `task_get`, `task_list`, `task_update_status`, `task_add_note` |
+| Status | `status_report` ⭐ |
+| Lifecycle | `goal_update_status`, `checkpoint_save` |
+
+⭐ = the two calls you'll use most: warm-up at the start of a session, review before closing one. See [DESIGN.md §3](docs/design/DESIGN.md) for full input/output shapes.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GOALTRACKER_DB_PATH` | `~/.goaltracker/goaltracker.db` | Where the SQLite file lives |
+
+## Development
+
+Building from source instead of installing the published package:
+
+```bash
+git clone <this repo>
+cd GoalTracker
+npm install
+npm run build      # generates the embedded skill content, then compiles
+npm run dev         # run directly from src/ with tsx, no build step
+npm run typecheck   # tsc --noEmit
+npm test             # vitest
+```
+
+To point an MCP client at a local build instead of the published package:
+
+```json
+{
+  "mcpServers": {
+    "goaltracker": {
+      "command": "node",
+      "args": ["/absolute/path/to/GoalTracker/dist/index.js"]
+    }
+  }
+}
+```
+
+The skill source lives at [.claude/skills/goaltracker/SKILL.md](.claude/skills/goaltracker/SKILL.md) — edit it there. Every script above (`build`, `dev`, `typecheck`, `test`) regenerates `src/skillContent.ts` from it automatically before running; that generated file is gitignored, don't edit it directly.

package/dist/db/client.js

@@ -0,0 +1,38 @@
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { migration001Init } from './migrations/001_init.js';
+import { migration002AddMilestoneApproval } from './migrations/002_add_milestone_approval.js';
+// Future schema changes: add a new 00N_description.ts migration module and
+// list it here. It auto-applies (in order, inside a transaction) against
+// every existing user's DB the next time the server starts.
+const migrations = [migration001Init, migration002AddMilestoneApproval];
+const DEFAULT_DB_PATH = path.join(os.homedir(), '.goaltracker', 'goaltracker.db');
+export function openDb(dbPath = process.env.GOALTRACKER_DB_PATH ?? DEFAULT_DB_PATH) {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    runMigrations(db);
+    return db;
+}
+function runMigrations(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      version    INTEGER PRIMARY KEY,
+      name       TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    );
+  `);
+    const applied = new Set(db.prepare('SELECT version FROM _migrations').all().map((row) => row.version));
+    const insertMigration = db.prepare('INSERT INTO _migrations (version, name, applied_at) VALUES (?, ?, ?)');
+    const pending = migrations.filter((m) => !applied.has(m.version)).sort((a, b) => a.version - b.version);
+    for (const migration of pending) {
+        const apply = db.transaction(() => {
+            migration.up(db);
+            insertMigration.run(migration.version, migration.name, new Date().toISOString());
+        });
+        apply();
+    }
+}

package/dist/db/migrations/001_init.js

@@ -0,0 +1,72 @@
+export const migration001Init = {
+    version: 1,
+    name: 'init',
+    up(db) {
+        db.exec(`
+      CREATE TABLE goals (
+        id          TEXT PRIMARY KEY,
+        title       TEXT NOT NULL,
+        description TEXT,
+        status      TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','completed','archived')),
+        status_note TEXT,
+        created_at  TEXT NOT NULL,
+        updated_at  TEXT NOT NULL
+      );
+
+      CREATE TABLE specs (
+        goal_id             TEXT PRIMARY KEY REFERENCES goals(id),
+        overview            TEXT NOT NULL,
+        acceptance_criteria TEXT NOT NULL DEFAULT '[]',
+        constraints         TEXT NOT NULL DEFAULT '[]',
+        out_of_scope        TEXT NOT NULL DEFAULT '[]',
+        updated_at          TEXT NOT NULL
+      );
+
+      CREATE TABLE milestones (
+        id          TEXT PRIMARY KEY,
+        goal_id     TEXT NOT NULL REFERENCES goals(id),
+        title       TEXT NOT NULL,
+        description TEXT,
+        "order"     INTEGER NOT NULL DEFAULT 0,
+        created_at  TEXT NOT NULL
+      );
+
+      CREATE TABLE tasks (
+        id            TEXT PRIMARY KEY,
+        milestone_id  TEXT NOT NULL REFERENCES milestones(id),
+        goal_id       TEXT NOT NULL REFERENCES goals(id),
+        title         TEXT NOT NULL,
+        description   TEXT,
+        status        TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','in_progress','completed','blocked','cancelled')),
+        priority      TEXT NOT NULL DEFAULT 'medium' CHECK (priority IN ('low','medium','high')),
+        status_reason TEXT,
+        created_at    TEXT NOT NULL,
+        updated_at    TEXT NOT NULL
+      );
+
+      CREATE TABLE notes (
+        id         TEXT PRIMARY KEY,
+        task_id    TEXT NOT NULL REFERENCES tasks(id),
+        content    TEXT NOT NULL,
+        type       TEXT NOT NULL DEFAULT 'progress' CHECK (type IN ('progress','blocker','decision','evidence','uncertainty')),
+        created_at TEXT NOT NULL
+      );
+
+      CREATE TABLE checkpoints (
+        id              TEXT PRIMARY KEY,
+        goal_id         TEXT NOT NULL REFERENCES goals(id),
+        current_task_id TEXT REFERENCES tasks(id),
+        agent_summary   TEXT NOT NULL,
+        next_actions    TEXT NOT NULL DEFAULT '[]',
+        saved_at        TEXT NOT NULL
+      );
+
+      CREATE INDEX idx_tasks_goal       ON tasks(goal_id);
+      CREATE INDEX idx_tasks_milestone  ON tasks(milestone_id);
+      CREATE INDEX idx_tasks_status     ON tasks(status);
+      CREATE INDEX idx_milestones_goal  ON milestones(goal_id);
+      CREATE INDEX idx_notes_task       ON notes(task_id);
+      CREATE INDEX idx_checkpoints_goal ON checkpoints(goal_id, saved_at DESC);
+    `);
+    },
+};

package/dist/db/migrations/002_add_milestone_approval.js

@@ -0,0 +1,7 @@
+export const migration002AddMilestoneApproval = {
+    version: 2,
+    name: 'add_milestone_approval',
+    up(db) {
+        db.exec(`ALTER TABLE milestones ADD COLUMN approved_at TEXT;`);
+    },
+};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { openDb } from './db/client.js';
+import { goalTools } from './tools/goal.js';
+import { specTools } from './tools/spec.js';
+import { milestoneTools } from './tools/milestone.js';
+import { taskTools } from './tools/task.js';
+import { statusTools } from './tools/status.js';
+import { checkpointTools } from './tools/checkpoint.js';
+import { installSkill } from './installSkill.js';
+async function runServer() {
+    const db = openDb();
+    const tools = [
+        ...goalTools(db),
+        ...specTools(db),
+        ...milestoneTools(db),
+        ...taskTools(db),
+        ...statusTools(db),
+        ...checkpointTools(db),
+    ];
+    const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
+    const server = new Server({ name: 'GoalTracker', version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: z.toJSONSchema(tool.schema),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = toolsByName.get(request.params.name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Error: unknown tool "${request.params.name}"` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = tool.handler(request.params.arguments ?? {});
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    if (subcommand === 'install-skill') {
+        const target = installSkill(rest);
+        console.log(`Installed GoalTracker skill to ${target}`);
+        return;
+    }
+    await runServer();
+}
+main().catch((error) => {
+    console.error('Fatal error starting GoalTracker MCP server:', error);
+    process.exit(1);
+});

package/dist/installSkill.js

@@ -0,0 +1,18 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SKILL_MD } from './skillContent.js';
+export function resolveSkillTargetDir(args, cwd, homedir) {
+    const scopeDir = args.includes('--project') ? cwd : homedir;
+    return path.join(scopeDir, '.claude', 'skills', 'goaltracker');
+}
+export function writeSkill(targetDir) {
+    mkdirSync(targetDir, { recursive: true });
+    const targetPath = path.join(targetDir, 'SKILL.md');
+    writeFileSync(targetPath, SKILL_MD);
+    return targetPath;
+}
+export function installSkill(args = []) {
+    const targetDir = resolveSkillTargetDir(args, process.cwd(), os.homedir());
+    return writeSkill(targetDir);
+}

package/dist/schemas/index.js

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+// ---------- Enums ----------
+export const GoalStatus = z.enum(['active', 'completed', 'archived']);
+export const MilestoneStatus = z.enum(['pending', 'in_progress', 'completed']);
+export const TaskStatus = z.enum(['pending', 'in_progress', 'completed', 'blocked', 'cancelled']);
+export const TaskPriority = z.enum(['low', 'medium', 'high']);
+export const NoteType = z.enum(['progress', 'blocker', 'decision', 'evidence', 'uncertainty']);
+// ---------- Models ----------
+export const Goal = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    status: GoalStatus,
+    status_note: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+export const Spec = z.object({
+    goal_id: z.string(),
+    overview: z.string(),
+    acceptance_criteria: z.array(z.string()),
+    constraints: z.array(z.string()),
+    out_of_scope: z.array(z.string()),
+    updated_at: z.string(),
+});
+export const Milestone = z.object({
+    id: z.string(),
+    goal_id: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    order: z.number(),
+    status: MilestoneStatus,
+    approved_at: z.string().optional(),
+    created_at: z.string(),
+});
+export const Task = z.object({
+    id: z.string(),
+    milestone_id: z.string(),
+    goal_id: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    status: TaskStatus,
+    priority: TaskPriority,
+    status_reason: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+export const Note = z.object({
+    id: z.string(),
+    task_id: z.string(),
+    content: z.string(),
+    type: NoteType,
+    created_at: z.string(),
+});
+export const Checkpoint = z.object({
+    goal_id: z.string(),
+    current_task_id: z.string().optional(),
+    agent_summary: z.string(),
+    next_actions: z.array(z.string()),
+    saved_at: z.string(),
+});
+// ---------- Tool input schemas ----------
+export const goalCreateInput = z.object({
+    title: z.string().min(1),
+    description: z.string().optional(),
+});
+export const goalListInput = z.object({
+    status: GoalStatus.optional(),
+});
+export const goalGetContextInput = z.object({
+    goal_id: z.string().min(1),
+});
+export const goalUpdateStatusInput = z.object({
+    goal_id: z.string().min(1),
+    status: GoalStatus,
+    note: z.string().optional(),
+});
+export const specSetInput = z.object({
+    goal_id: z.string().min(1),
+    overview: z.string().min(1),
+    acceptance_criteria: z.array(z.string()),
+    constraints: z.array(z.string()).optional(),
+    out_of_scope: z.array(z.string()).optional(),
+});
+export const milestoneCreateInput = z.object({
+    goal_id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional(),
+    order: z.number().int().optional(),
+});
+export const milestoneApproveInput = z.object({
+    milestone_id: z.string().min(1),
+});
+export const taskCreateInput = z.object({
+    milestone_id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional(),
+    priority: TaskPriority.optional(),
+});
+export const taskGetInput = z.object({
+    task_id: z.string().min(1),
+});
+export const taskListInput = z.object({
+    goal_id: z.string().optional(),
+    milestone_id: z.string().optional(),
+    status: TaskStatus.optional(),
+    priority: TaskPriority.optional(),
+});
+export const taskUpdateStatusInput = z
+    .object({
+    task_id: z.string().min(1),
+    status: TaskStatus,
+    reason: z.string().optional(),
+})
+    .refine((data) => !(['blocked', 'cancelled'].includes(data.status) && !data.reason), {
+    message: 'reason is required when status is "blocked" or "cancelled"',
+    path: ['reason'],
+});
+export const taskAddNoteInput = z.object({
+    task_id: z.string().min(1),
+    content: z.string().min(1),
+    type: NoteType,
+});
+export const statusReportInput = z.object({
+    goal_id: z.string().min(1),
+});
+export const checkpointSaveInput = z.object({
+    goal_id: z.string().min(1),
+    current_task_id: z.string().optional(),
+    agent_summary: z.string().min(1),
+    next_actions: z.array(z.string()),
+});
+export function rowToGoal(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        description: row.description ?? undefined,
+        status: row.status,
+        status_note: row.status_note ?? undefined,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+export function rowToSpec(row) {
+    return {
+        goal_id: row.goal_id,
+        overview: row.overview,
+        acceptance_criteria: JSON.parse(row.acceptance_criteria),
+        constraints: JSON.parse(row.constraints),
+        out_of_scope: JSON.parse(row.out_of_scope),
+        updated_at: row.updated_at,
+    };
+}
+export function rowToMilestoneBase(row) {
+    return {
+        id: row.id,
+        goal_id: row.goal_id,
+        title: row.title,
+        description: row.description ?? undefined,
+        order: row.order,
+        approved_at: row.approved_at ?? undefined,
+        created_at: row.created_at,
+    };
+}
+export function rowToTask(row) {
+    return {
+        id: row.id,
+        milestone_id: row.milestone_id,
+        goal_id: row.goal_id,
+        title: row.title,
+        description: row.description ?? undefined,
+        status: row.status,
+        priority: row.priority,
+        status_reason: row.status_reason ?? undefined,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+export function rowToNote(row) {
+    return {
+        id: row.id,
+        task_id: row.task_id,
+        content: row.content,
+        type: row.type,
+        created_at: row.created_at,
+    };
+}
+export function rowToCheckpoint(row) {
+    return {
+        goal_id: row.goal_id,
+        current_task_id: row.current_task_id ?? undefined,
+        agent_summary: row.agent_summary,
+        next_actions: JSON.parse(row.next_actions),
+        saved_at: row.saved_at,
+    };
+}

package/dist/skillContent.js

@@ -0,0 +1,165 @@
+// Auto-generated by scripts/generate-skill-content.mjs from .claude/skills/goaltracker/SKILL.md — do not edit directly.
+export const SKILL_MD = `---
+name: goaltracker
+description: Use when the GoalTracker MCP tools (goal_create, goal_list, goal_get_context, spec_set, milestone_create, milestone_approve, task_create, task_get, task_list, task_update_status, task_add_note, status_report, goal_update_status, checkpoint_save) are connected and the user wants to track progress on a project, write a spec or acceptance criteria, break work into milestones and tasks, decide what order to tackle work in, resume work after a context reset, or check on progress. Also reach for this the moment you notice a requested feature or task is large enough that you need to ask the user several clarifying questions before you can even start (multiple components, missing architecture/tech context, unclear scope) — that need for clarification is itself the signal to set up tracking, not just a reason to ask and move on. Make sure to use this whenever GoalTracker is available and the conversation involves planning, spec-writing, task breakdown, or any feature/task request that clearly needs more than one sitting to finish — even if the user never mentions GoalTracker, planning, or tracking by name. Teaches the correct call sequence, how to write a spec that's actually checkable, how to choose a milestone breakdown strategy, and the schema's conventions so the agent doesn't reinvent bookkeeping the MCP already handles.
+---
+
+# Using GoalTracker
+
+GoalTracker is a data-only MCP: it stores and returns structured state (Goal → Spec → Milestone → Task → Note), but never reasons or suggests — all judgment stays with you, the agent. Follow these conventions so the state you build stays useful across sessions, and so the plans you create are actually good plans, not just a todo dump with extra steps.
+
+## The clarifying-questions moment is the trigger, not just planning requests
+
+A request like "handle this feature for me" reads as an instruction to execute, not to plan — so don't wait for the user to explicitly ask for a plan or say "track this." Watch for the moment instead: if a feature or task is big enough that you need to ask the user several things before you can even start — which repo/path, what stack, what already exists, which pieces are actually in scope — that need for clarification is itself the signal, not just a reason to fire off questions and wait for replies.
+
+When you notice that moment, create the Goal and a first-pass Spec from whatever you already know before (or alongside) asking your questions: put the confirmed scope in \`overview\`, and put the open questions themselves in \`constraints\` or \`out_of_scope\` until they're answered. That way the answers you get back fill in a spec instead of vanishing into a one-off Q&A, and the next session — yours or someone else's — can see the shape of the ask even before every detail is settled.
+
+## Every session starts with one call
+
+Before doing anything else on an existing project, call \`goal_get_context(goal_id)\`. It returns the goal, spec, every milestone with its task counts, a \`milestones_out_of_range\` list, aggregate progress, and the last checkpoint — everything you need to resume, in one call. Don't call \`task_list\` or dig through individual tasks just to "get oriented"; that's what this call replaces.
+
+If the returned \`last_checkpoint\` has a \`current_task_id\`, call \`task_get(current_task_id)\` next to see that task's full detail and notes before you resume it — the checkpoint tells you *what* you were doing, \`task_get\` tells you the specifics you'd otherwise have to reconstruct from memory that no longer exists.
+
+If you don't know the \`goal_id\`, call \`goal_list\` first.
+
+## Setting up a new project
+
+\`\`\`
+goal_create → [draft spec ⇄ confirm with the user] → spec_set
+  → milestone_create (× N) → task_create (× M)
+  → [present final plan, pick a check-in cadence] → start work
+\`\`\`
+
+The step between \`goal_create\` and the point where you actually start breaking milestones is a conversation, not a formality. Treat it like a kickoff discussion you'd have before committing to a plan, not an admin step to clear so you can get to the breakdown.
+
+- **Draft before you commit.** Work out a first-pass \`overview\`, \`acceptance_criteria\`, \`constraints\`, and \`out_of_scope\` from what you already know, then present it to the user in the **spec draft** format below — *before* treating \`spec_set\` as final. Don't silently assume what "done" means and move straight to milestones — state it, in a consistent structure, and let them correct it.
+- Write \`acceptance_criteria\` as a real Definition of Done, not a restatement of the goal: each item should be something you could point at task evidence and tick off as true or false. Cover exception paths and edge cases too, not just the happy path — a criteria list that's all happy-path is a plan waiting to be surprised. If you don't have enough information yet to write a reliable criterion, say so and ask, rather than guessing at one and hoping it holds up.
+- **Ask about what would actually change the breakdown**, not everything: what's explicitly out of scope (the thing people under-specify the most), any constraint that isn't obvious from the request itself (a deadline, a system you can't touch, a stack decision already made elsewhere), and whether the acceptance criteria you drafted match what they'd really accept as "done."
+- **\`spec_set\` is create-or-replace, so use it like a checkpoint while the spec is still taking shape**, not a one-shot commit — call it with your draft, revise based on what the user says, call it again. There's no separate "update" tool and no penalty for calling it more than once.
+- **Don't call \`milestone_create\` until the user has actually confirmed the spec** — a real "yes, that's it" or a correction you've since folded back in, not just silence after you stated it once. This is a behavioral habit, not something the MCP enforces — \`milestone_create\` will not stop you from skipping this, which is exactly why it's worth being deliberate about instead of treating the spec step as a rubber stamp on the way to the real work.
+- Once the spec is actually confirmed: choose a milestone breakdown strategy (below) before calling \`milestone_create\` repeatedly — don't just default to whatever order occurred to you first.
+- Each milestone should end up holding roughly 2–5 active (non-cancelled) tasks — enough to be a meaningful phase, small enough to stay focused. The upper end is still just a nudge, not enforced. The **lower** end now has teeth: \`task_update_status\` will refuse to start (\`"in_progress"\`) any task in a milestone with fewer than 2 active tasks until you call \`milestone_approve\` — see "When a milestone is too small to start on" below.
+- Leave \`order\` unset unless you need a specific sequence — it auto-assigns.
+- **Once every milestone and task exists (and any undersized milestone has already been approved — see below), present the whole plan back to the user** in the **final plan** format below, as one last look at the full shape of the work before any of it starts. Don't call \`task_update_status(..., "in_progress")\` on anything until they've seen it.
+- **With the plan confirmed, ask how they want you to check in while you work**: after every task, after every milestone, or straight through with a report only at the end (or when something blocks you). Whatever they pick applies for the rest of the session — see "Doing the work" below for what each option means in practice.
+
+## Templates for presenting to the user
+
+Use these formats consistently. This costs nothing extra from the MCP — no tool returns formatted text, formatting is entirely your job using data these tools already gave you — and a structured draft is something a user can actually skim and react to, instead of a paragraph they have to parse.
+
+**Spec draft** — after drafting, before calling \`spec_set\` for real:
+
+\`\`\`
+## Spec draft — <goal title>
+
+**Overview:** <what "done" means, in 1-2 sentences>
+
+**Acceptance criteria:**
+- <criterion 1>
+- <criterion 2>
+
+**Constraints:**
+- <constraint, or "none identified yet">
+
+**Out of scope:**
+- <item, or "none identified yet">
+
+Anything to add, cut, or correct before I lock this in?
+\`\`\`
+
+**Final plan** — after milestones and tasks exist and any small-milestone approval is settled, before execution starts:
+
+\`\`\`
+## Plan — <goal title>
+
+**M1 — <title>** (<breakdown strategy>: <one-line why this order>)
+- <task 1>
+- <task 2>
+
+**M2 — <title>**
+- <task 1>
+...
+
+Ready to start? Want me to check in after every task, after every milestone, or run straight through and report at the end?
+\`\`\`
+
+**Completion report** — whenever your check-in cadence says to stop, or when a Goal is closed:
+
+\`\`\`
+## <Task, Milestone, or Goal> complete — <title>
+
+**Done:**
+- <task>: <one-line outcome or evidence>
+
+**Status:** <e.g. "3 of 5 tasks done in this milestone, 1 blocked">
+<mention any blocked task and why, if there is one>
+
+Next: <what you'll do next, or the question you need answered before continuing>
+\`\`\`
+
+## Before you create milestones: choose a breakdown strategy
+
+Pick one primary strategy and let it drive the order you create milestones (and, within a milestone, tasks) in:
+
+- **dependency-first** — order milestones so nothing blocks on work that comes later.
+- **risk-first** — tackle the riskiest unknown first; if it invalidates the plan, better to find out now than after three milestones of unrelated work.
+- **verify-first** — front-load whichever milestone produces real evidence/proof early, when getting confirmation that the approach works is the actual bottleneck.
+- **unblock-first** — if one thing is already blocking multiple other directions, resolve that before anything else.
+- **handoff-first** — if someone else (a teammate, or a future session with no memory of this conversation) needs to pick this up, structure milestones so the plan reads clearly without you there to explain it.
+
+There's no schema field for "strategy" — say which one you picked and why in the milestone's \`description\` (one line is enough). This isn't busywork: it's the difference between a milestone list that's just a todo dump and one that actually reflects a plan, and it costs nothing since \`description\` already exists.
+
+## When a milestone is too small to start on
+
+If \`task_update_status(..., "in_progress")\` comes back with an error about the milestone having fewer than 2 active tasks, that's not a bug to route around — it means this milestone is small enough that it might be an accidental under-breakdown rather than a deliberate one-off. Before calling \`milestone_approve(milestone_id)\`, actually check with the user: is a single-task milestone here intentional, or would this task make more sense folded into a neighboring milestone instead? Only call \`milestone_approve\` once you've gotten a real answer — it exists to catch genuine oversights, not to be rubber-stamped past on your own so you can keep moving. Once approved, the restriction is lifted for that milestone permanently, even if its active task count drops back below 2 later (e.g. a task gets cancelled).
+
+## Doing the work
+
+\`\`\`
+task_list(status="pending") → task_update_status(id, "in_progress") → do the work
+  → task_add_note(type="progress" | "evidence" | "uncertainty") as you go
+  → [if something stops you] task_add_note(type="blocker") → task_update_status(id, "blocked", reason=...)
+  → task_update_status(id, "completed")
+\`\`\`
+
+- If \`task_update_status(id, "in_progress")\` is rejected for being in an unapproved, too-small milestone, see "When a milestone is too small to start on" above — don't just retry or work around it.
+- **Follow the check-in cadence the user picked when you presented the final plan:**
+  - *After every task* — once a task is \`completed\` (or \`blocked\`), stop and report before starting the next one.
+  - *After every milestone* — keep working through a milestone's tasks uninterrupted, then stop and report once every task in it is \`completed\` or \`cancelled\` (or one is \`blocked\`).
+  - *Straight through* — keep going until the whole Goal is done, or until something is \`blocked\` and needs a decision only the user can make.
+  Whichever cadence applies, use the **completion report** format below when you stop — don't just finish a tool call silently and wait for the next instruction.
+- \`reason\` is required by the schema when you set status to \`blocked\` or \`cancelled\` — always explain why.
+- The schema has no dedicated fields for a task's dependencies or how to verify it done — that's intentional (see the closing note), not a gap to work around with extra tools. Put that context straight into the task's \`description\` when you create it (e.g. "depends on: <other task title>" / "verify by: run X, check Y") so it's there when you or a future session reads the task back.
+- \`task_create\`'s response includes \`milestone_active_task_count\`. Watch it: if a milestone is trending past 5 active tasks, consider starting a new milestone for the next chunk of work instead of continuing to pile on. If \`goal_get_context\` / \`status_report\` flag a milestone in \`milestones_out_of_range\`, it's advisory — decide whether to split, merge, or just add more tasks; you won't be blocked either way.
+- Titles and descriptions are immutable once created (by design — corrections are rare enough that they don't need a dedicated tool). If a title or description turns out wrong, record the correction with \`task_add_note(type="decision")\` rather than looking for an edit tool.
+
+## Ending a session
+
+Always call \`checkpoint_save(goal_id, current_task_id?, agent_summary, next_actions)\` before your context resets — even if you didn't finish anything. \`agent_summary\` and \`next_actions\` are what the *next* session's \`goal_get_context\` call will hand back as \`last_checkpoint\`; write them for a future instance of yourself with zero memory of this conversation.
+
+If you changed the plan mid-session — added a milestone that wasn't in the original breakdown, cancelled tasks because an assumption turned out wrong, reprioritized which milestone matters most — say so in \`agent_summary\`. There's no separate "pivot log" in this schema, and no tool reads back checkpoint *history* either — \`goal_get_context\` only ever returns the single latest one. Writing down what changed and why still matters, but think of it as a note for whoever picks this up next, not as building a queryable log: if you need to know what happened three sessions ago, there's no tool call that gets you there.
+
+## Checking status / verifying completion
+
+Call \`status_report(goal_id)\` for a periodic review or before closing a goal. It returns the same progress/milestone aggregates as \`goal_get_context\`, plus \`blocked_tasks\` (each with its latest note) and the goal's \`acceptance_criteria\` as a plain list.
+
+For any \`blocked_tasks\` entry worth acting on, call \`task_get(task_id)\` to read its full note history before deciding anything — the single \`latest_note\` in \`status_report\` is enough to notice a block, not always enough to understand it. Record what you decide with \`task_add_note(type="decision")\` on that task.
+
+There is no per-criterion "checked" flag anywhere in this schema — that was tried and deliberately removed. Verification is your job: cross-check \`acceptance_criteria\` against the actual task evidence yourself, then record what you verified in \`checkpoint_save\`'s \`agent_summary\` / \`next_actions\` (or a \`task_add_note(type="evidence")\` on the relevant task). Don't invent your own tracking field for this.
+
+\`completion_pct\` is \`null\` when there are no tasks yet, or every task has been cancelled — treat \`null\` as "not measurable yet," not zero. When you report a progress number to a human, say what it's counting (e.g. "42% — 5 of 12 non-cancelled tasks" rather than a bare "42%"), so a stale or misleading number is easy to catch instead of taken on faith.
+
+## Closing out
+
+\`\`\`
+status_report(goal_id)   // completion_pct should be 100 (or null if everything was cancelled)
+  → [verify acceptance_criteria yourself against task evidence]
+  → goal_update_status(goal_id, "completed", note?)
+\`\`\`
+
+\`goal_update_status\` also handles archiving (\`"archived"\`) and reactivating an archived goal (\`"active"\`) — there's no separate archive/reactivate tool.
+
+## Why this schema stays this thin
+
+GoalTracker deliberately has no fields for task dependencies, verify-methods, breakdown strategy, or a change/pivot log — richer planning practice (a breakdown strategy, dependency ordering, a real Definition of Done, logging why a plan changed) belongs in *how you use* \`description\`, \`task_add_note\`, and \`checkpoint_save\`, not in new columns. Before treating something as a missing feature, try encoding it in an existing free-text field first — the schema has already had several structured fields proposed and deliberately rejected for exactly this reason (see \`docs/design/DESIGN.md\` §9). If something genuinely can't be expressed this way — not just "would be marginally more convenient as a dedicated field" — that's worth raising as a real schema change instead of a workaround.
+`;

package/dist/tools/checkpoint.js

@@ -0,0 +1,27 @@
+import { randomUUID } from 'node:crypto';
+import { checkpointSaveInput, rowToCheckpoint } from '../schemas/index.js';
+export function checkpointTools(db) {
+    return [
+        {
+            name: 'checkpoint_save',
+            description: "Save the Agent's current context summary before the session ends. Loaded back via goal_get_context as last_checkpoint.",
+            schema: checkpointSaveInput,
+            handler: (args) => {
+                const input = checkpointSaveInput.parse(args);
+                const goalExists = db.prepare('SELECT 1 FROM goals WHERE id = ?').get(input.goal_id);
+                if (!goalExists)
+                    throw new Error(`Goal not found: ${input.goal_id}`);
+                if (input.current_task_id) {
+                    const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(input.current_task_id);
+                    if (!taskExists)
+                        throw new Error(`Task not found: ${input.current_task_id}`);
+                }
+                const now = new Date().toISOString();
+                const id = randomUUID();
+                db.prepare(`INSERT INTO checkpoints (id, goal_id, current_task_id, agent_summary, next_actions, saved_at)
+           VALUES (?, ?, ?, ?, ?, ?)`).run(id, input.goal_id, input.current_task_id ?? null, input.agent_summary, JSON.stringify(input.next_actions), now);
+                return rowToCheckpoint(db.prepare('SELECT * FROM checkpoints WHERE id = ?').get(id));
+            },
+        },
+    ];
+}

package/dist/tools/goal.js

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+import { goalCreateInput, goalListInput, goalGetContextInput, goalUpdateStatusInput, rowToGoal, rowToSpec, rowToMilestoneBase, rowToCheckpoint, } from '../schemas/index.js';
+import { buildMilestonesSummary, buildProgress } from '../utils/computed.js';
+export function goalTools(db) {
+    return [
+        {
+            name: 'goal_create',
+            description: 'Create a new Goal. Called once when starting a new project.',
+            schema: goalCreateInput,
+            handler: (args) => {
+                const input = goalCreateInput.parse(args);
+                const now = new Date().toISOString();
+                const goal = {
+                    id: randomUUID(),
+                    title: input.title,
+                    description: input.description,
+                    status: 'active',
+                    created_at: now,
+                    updated_at: now,
+                };
+                db.prepare(`INSERT INTO goals (id, title, description, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)`).run(goal.id, goal.title, goal.description ?? null, goal.status, goal.created_at, goal.updated_at);
+                return goal;
+            },
+        },
+        {
+            name: 'goal_list',
+            description: 'List Goals, optionally filtered by status. Use to find a goal_id or get an overview of all projects.',
+            schema: goalListInput,
+            handler: (args) => {
+                const input = goalListInput.parse(args);
+                const rows = input.status
+                    ? db.prepare('SELECT * FROM goals WHERE status = ? ORDER BY created_at DESC').all(input.status)
+                    : db.prepare('SELECT * FROM goals ORDER BY created_at DESC').all();
+                return rows.map((r) => rowToGoal(r));
+            },
+        },
+        {
+            name: 'goal_get_context',
+            description: 'The single warm-up call for a context-reset Agent: returns the goal, spec, milestones with task counts, out-of-range milestones, aggregate progress, and the last checkpoint. Call this at the start of every session.',
+            schema: goalGetContextInput,
+            handler: (args) => {
+                const { goal_id } = goalGetContextInput.parse(args);
+                const goalRow = db.prepare('SELECT * FROM goals WHERE id = ?').get(goal_id);
+                if (!goalRow)
+                    throw new Error(`Goal not found: ${goal_id}`);
+                const goal = rowToGoal(goalRow);
+                const specRow = db.prepare('SELECT * FROM specs WHERE goal_id = ?').get(goal_id);
+                const spec = specRow ? rowToSpec(specRow) : null;
+                const milestoneRows = db
+                    .prepare('SELECT * FROM milestones WHERE goal_id = ? ORDER BY "order" ASC')
+                    .all(goal_id);
+                const taskStatusRows = db
+                    .prepare('SELECT milestone_id, status FROM tasks WHERE goal_id = ?')
+                    .all(goal_id);
+                const tasksByMilestone = new Map();
+                const allStatuses = [];
+                for (const row of taskStatusRows) {
+                    allStatuses.push(row.status);
+                    const list = tasksByMilestone.get(row.milestone_id) ?? [];
+                    list.push(row.status);
+                    tasksByMilestone.set(row.milestone_id, list);
+                }
+                const { milestones, outOfRange, pendingApproval } = buildMilestonesSummary(milestoneRows.map((r) => rowToMilestoneBase(r)), tasksByMilestone);
+                const progress = buildProgress(allStatuses);
+                const checkpointRow = db
+                    .prepare('SELECT * FROM checkpoints WHERE goal_id = ? ORDER BY saved_at DESC LIMIT 1')
+                    .get(goal_id);
+                const last_checkpoint = checkpointRow ? rowToCheckpoint(checkpointRow) : null;
+                return {
+                    goal,
+                    spec,
+                    milestones,
+                    milestones_out_of_range: outOfRange,
+                    milestones_pending_approval: pendingApproval,
+                    progress,
+                    last_checkpoint,
+                };
+            },
+        },
+        {
+            name: 'goal_update_status',
+            description: 'Close a finished Goal, archive an inactive one, or reactivate an archived Goal. Merges goal_complete + goal_archive + goal_reactivate.',
+            schema: goalUpdateStatusInput,
+            handler: (args) => {
+                const input = goalUpdateStatusInput.parse(args);
+                const existing = db.prepare('SELECT 1 FROM goals WHERE id = ?').get(input.goal_id);
+                if (!existing)
+                    throw new Error(`Goal not found: ${input.goal_id}`);
+                const now = new Date().toISOString();
+                db.prepare(`UPDATE goals SET status = ?, status_note = COALESCE(?, status_note), updated_at = ? WHERE id = ?`).run(input.status, input.note ?? null, now, input.goal_id);
+                return rowToGoal(db.prepare('SELECT * FROM goals WHERE id = ?').get(input.goal_id));
+            },
+        },
+    ];
+}

package/dist/tools/milestone.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { milestoneCreateInput, milestoneApproveInput, rowToMilestoneBase, } from '../schemas/index.js';
+import { computeMilestoneStatus } from '../utils/computed.js';
+export function milestoneTools(db) {
+    return [
+        {
+            name: 'milestone_create',
+            description: 'Break a Goal into a major phase. Status is auto-computed from its tasks. When order is omitted, it auto-assigns to max(order in this goal) + 1.',
+            schema: milestoneCreateInput,
+            handler: (args) => {
+                const input = milestoneCreateInput.parse(args);
+                const goalExists = db.prepare('SELECT 1 FROM goals WHERE id = ?').get(input.goal_id);
+                if (!goalExists)
+                    throw new Error(`Goal not found: ${input.goal_id}`);
+                let order = input.order;
+                if (order === undefined) {
+                    const row = db
+                        .prepare('SELECT MAX("order") as maxOrder FROM milestones WHERE goal_id = ?')
+                        .get(input.goal_id);
+                    order = (row.maxOrder ?? -1) + 1;
+                }
+                const now = new Date().toISOString();
+                const id = randomUUID();
+                db.prepare(`INSERT INTO milestones (id, goal_id, title, description, "order", created_at) VALUES (?, ?, ?, ?, ?, ?)`).run(id, input.goal_id, input.title, input.description ?? null, order, now);
+                const row = db.prepare('SELECT * FROM milestones WHERE id = ?').get(id);
+                return { ...rowToMilestoneBase(row), status: computeMilestoneStatus([], undefined) };
+            },
+        },
+        {
+            name: 'milestone_approve',
+            description: 'Explicitly approve a Milestone that has fewer than 2 active tasks, lifting the restriction that blocks task_update_status from starting work on its tasks. Only call this after actually confirming with the user that a small Milestone is intentional — not as a shortcut to unblock yourself.',
+            schema: milestoneApproveInput,
+            handler: (args) => {
+                const { milestone_id } = milestoneApproveInput.parse(args);
+                const existing = db.prepare('SELECT 1 FROM milestones WHERE id = ?').get(milestone_id);
+                if (!existing)
+                    throw new Error(`Milestone not found: ${milestone_id}`);
+                db.prepare('UPDATE milestones SET approved_at = ? WHERE id = ?').run(new Date().toISOString(), milestone_id);
+                const row = db.prepare('SELECT * FROM milestones WHERE id = ?').get(milestone_id);
+                const statuses = db.prepare('SELECT status FROM tasks WHERE milestone_id = ?').all(milestone_id).map((r) => r.status);
+                const base = rowToMilestoneBase(row);
+                return { ...base, status: computeMilestoneStatus(statuses, base.approved_at) };
+            },
+        },
+    ];
+}

package/dist/tools/spec.js

@@ -0,0 +1,33 @@
+import { specSetInput, rowToSpec } from '../schemas/index.js';
+export function specTools(db) {
+    return [
+        {
+            name: 'spec_set',
+            description: 'Create or overwrite the Spec for a Goal (overview, acceptance criteria, constraints, out of scope). Create-or-replace semantics — call again any time the spec changes.',
+            schema: specSetInput,
+            handler: (args) => {
+                const input = specSetInput.parse(args);
+                const goalExists = db.prepare('SELECT 1 FROM goals WHERE id = ?').get(input.goal_id);
+                if (!goalExists)
+                    throw new Error(`Goal not found: ${input.goal_id}`);
+                const now = new Date().toISOString();
+                db.prepare(`INSERT INTO specs (goal_id, overview, acceptance_criteria, constraints, out_of_scope, updated_at)
+           VALUES (@goal_id, @overview, @acceptance_criteria, @constraints, @out_of_scope, @updated_at)
+           ON CONFLICT(goal_id) DO UPDATE SET
+             overview = excluded.overview,
+             acceptance_criteria = excluded.acceptance_criteria,
+             constraints = excluded.constraints,
+             out_of_scope = excluded.out_of_scope,
+             updated_at = excluded.updated_at`).run({
+                    goal_id: input.goal_id,
+                    overview: input.overview,
+                    acceptance_criteria: JSON.stringify(input.acceptance_criteria),
+                    constraints: JSON.stringify(input.constraints ?? []),
+                    out_of_scope: JSON.stringify(input.out_of_scope ?? []),
+                    updated_at: now,
+                });
+                return rowToSpec(db.prepare('SELECT * FROM specs WHERE goal_id = ?').get(input.goal_id));
+            },
+        },
+    ];
+}

package/dist/tools/status.js

@@ -0,0 +1,56 @@
+import { statusReportInput, rowToGoal, rowToMilestoneBase, rowToTask, rowToNote, } from '../schemas/index.js';
+import { buildMilestonesSummary, buildProgress } from '../utils/computed.js';
+export function statusTools(db) {
+    return [
+        {
+            name: 'status_report',
+            description: 'Periodic review / pre-closure check. Returns aggregate progress, milestones with task counts, blocked tasks, and the acceptance criteria list. Data only — no suggestions.',
+            schema: statusReportInput,
+            handler: (args) => {
+                const { goal_id } = statusReportInput.parse(args);
+                const goalRow = db.prepare('SELECT * FROM goals WHERE id = ?').get(goal_id);
+                if (!goalRow)
+                    throw new Error(`Goal not found: ${goal_id}`);
+                const goal = rowToGoal(goalRow);
+                const milestoneRows = db
+                    .prepare('SELECT * FROM milestones WHERE goal_id = ? ORDER BY "order" ASC')
+                    .all(goal_id);
+                const taskRows = db
+                    .prepare('SELECT * FROM tasks WHERE goal_id = ?')
+                    .all(goal_id)
+                    .map((r) => rowToTask(r));
+                const tasksByMilestone = new Map();
+                for (const t of taskRows) {
+                    const list = tasksByMilestone.get(t.milestone_id) ?? [];
+                    list.push(t.status);
+                    tasksByMilestone.set(t.milestone_id, list);
+                }
+                const { milestones, outOfRange, pendingApproval } = buildMilestonesSummary(milestoneRows.map((r) => rowToMilestoneBase(r)), tasksByMilestone);
+                const progress = buildProgress(taskRows.map((t) => t.status));
+                const blocked_tasks = taskRows
+                    .filter((t) => t.status === 'blocked')
+                    .map((t) => {
+                    const latestNoteRow = db
+                        .prepare('SELECT * FROM notes WHERE task_id = ? ORDER BY created_at DESC LIMIT 1')
+                        .get(t.id);
+                    return {
+                        task: t,
+                        blocked_reason: t.status_reason ?? '',
+                        latest_note: latestNoteRow ? rowToNote(latestNoteRow) : undefined,
+                    };
+                });
+                const specRow = db.prepare('SELECT acceptance_criteria FROM specs WHERE goal_id = ?').get(goal_id);
+                const acceptance_criteria = specRow ? JSON.parse(specRow.acceptance_criteria) : [];
+                return {
+                    goal,
+                    progress,
+                    milestones,
+                    milestones_out_of_range: outOfRange,
+                    milestones_pending_approval: pendingApproval,
+                    blocked_tasks,
+                    acceptance_criteria,
+                };
+            },
+        },
+    ];
+}

package/dist/tools/task.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { taskCreateInput, taskGetInput, taskListInput, taskUpdateStatusInput, taskAddNoteInput, rowToTask, rowToNote, } from '../schemas/index.js';
+import { activeTaskCount, needsApproval } from '../utils/computed.js';
+export function taskTools(db) {
+    return [
+        {
+            name: 'task_create',
+            description: 'Create a task within a milestone. No hard cap — the response includes milestone_active_task_count so the Agent can judge against the 2-5 active-task guideline.',
+            schema: taskCreateInput,
+            handler: (args) => {
+                const input = taskCreateInput.parse(args);
+                const milestoneRow = db
+                    .prepare('SELECT goal_id FROM milestones WHERE id = ?')
+                    .get(input.milestone_id);
+                if (!milestoneRow)
+                    throw new Error(`Milestone not found: ${input.milestone_id}`);
+                const now = new Date().toISOString();
+                const id = randomUUID();
+                db.prepare(`INSERT INTO tasks (id, milestone_id, goal_id, title, description, priority, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.milestone_id, milestoneRow.goal_id, input.title, input.description ?? null, input.priority ?? 'medium', now, now);
+                const statuses = db.prepare('SELECT status FROM tasks WHERE milestone_id = ?').all(input.milestone_id).map((r) => r.status);
+                const task = rowToTask(db.prepare('SELECT * FROM tasks WHERE id = ?').get(id));
+                return { ...task, milestone_active_task_count: activeTaskCount(statuses) };
+            },
+        },
+        {
+            name: 'task_get',
+            description: "Inspect a task's full detail, including all its notes.",
+            schema: taskGetInput,
+            handler: (args) => {
+                const { task_id } = taskGetInput.parse(args);
+                const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(task_id);
+                if (!row)
+                    throw new Error(`Task not found: ${task_id}`);
+                const notes = db
+                    .prepare('SELECT * FROM notes WHERE task_id = ? ORDER BY created_at ASC')
+                    .all(task_id)
+                    .map((r) => rowToNote(r));
+                return { ...rowToTask(row), notes };
+            },
+        },
+        {
+            name: 'task_list',
+            description: 'Find tasks to work on or review, filtered by goal, milestone, status, and/or priority.',
+            schema: taskListInput,
+            handler: (args) => {
+                const input = taskListInput.parse(args);
+                const clauses = [];
+                const params = [];
+                if (input.goal_id) {
+                    clauses.push('goal_id = ?');
+                    params.push(input.goal_id);
+                }
+                if (input.milestone_id) {
+                    clauses.push('milestone_id = ?');
+                    params.push(input.milestone_id);
+                }
+                if (input.status) {
+                    clauses.push('status = ?');
+                    params.push(input.status);
+                }
+                if (input.priority) {
+                    clauses.push('priority = ?');
+                    params.push(input.priority);
+                }
+                const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+                const rows = db.prepare(`SELECT * FROM tasks ${where} ORDER BY created_at ASC`).all(...params);
+                return rows.map((r) => rowToTask(r));
+            },
+        },
+        {
+            name: 'task_update_status',
+            description: "Update a task's status (pending, in_progress, completed, blocked, cancelled). reason is required for blocked and cancelled.",
+            schema: taskUpdateStatusInput,
+            handler: (args) => {
+                const input = taskUpdateStatusInput.parse(args);
+                const existing = db.prepare('SELECT milestone_id FROM tasks WHERE id = ?').get(input.task_id);
+                if (!existing)
+                    throw new Error(`Task not found: ${input.task_id}`);
+                if (input.status === 'in_progress') {
+                    const milestoneRow = db
+                        .prepare('SELECT title, approved_at FROM milestones WHERE id = ?')
+                        .get(existing.milestone_id);
+                    const statuses = db.prepare('SELECT status FROM tasks WHERE milestone_id = ?').all(existing.milestone_id).map((r) => r.status);
+                    if (needsApproval(statuses, milestoneRow.approved_at ?? undefined)) {
+                        throw new Error(`Milestone "${milestoneRow.title}" has fewer than 2 active tasks and has not been approved yet. ` +
+                            `Confirm with the user that this small milestone is intentional, then call milestone_approve(milestone_id) before starting work on its tasks.`);
+                    }
+                }
+                const now = new Date().toISOString();
+                db.prepare(`UPDATE tasks SET status = ?, status_reason = ?, updated_at = ? WHERE id = ?`).run(input.status, input.reason ?? null, now, input.task_id);
+                return rowToTask(db.prepare('SELECT * FROM tasks WHERE id = ?').get(input.task_id));
+            },
+        },
+        {
+            name: 'task_add_note',
+            description: 'Record a progress update, blocker, technical decision, evidence, or uncertainty on a task.',
+            schema: taskAddNoteInput,
+            handler: (args) => {
+                const input = taskAddNoteInput.parse(args);
+                const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(input.task_id);
+                if (!taskExists)
+                    throw new Error(`Task not found: ${input.task_id}`);
+                const now = new Date().toISOString();
+                const id = randomUUID();
+                db.prepare(`INSERT INTO notes (id, task_id, content, type, created_at) VALUES (?, ?, ?, ?, ?)`).run(id, input.task_id, input.content, input.type, now);
+                return rowToNote(db.prepare('SELECT * FROM notes WHERE id = ?').get(id));
+            },
+        },
+    ];
+}

package/dist/utils/computed.js

@@ -0,0 +1,85 @@
+export function emptyTaskStatusCounts() {
+    return { pending: 0, in_progress: 0, completed: 0, blocked: 0, cancelled: 0 };
+}
+export function activeTaskCount(taskStatuses) {
+    return taskStatuses.filter((s) => s !== 'cancelled').length;
+}
+export function isMilestoneOutOfRange(taskStatuses) {
+    const count = activeTaskCount(taskStatuses);
+    return count < 2 || count > 5;
+}
+/**
+ * The 5-active-task upper bound stays advisory only (see DESIGN.md §9,
+ * "Rejected: hard cap on Milestone task count"). The 2-active-task lower
+ * bound is enforced instead: a Milestone below it needs an explicit
+ * milestone_approve before task_update_status will allow starting work on
+ * its tasks. This checks that lower-bound gate.
+ */
+export function needsApproval(taskStatuses, approvedAt) {
+    return approvedAt === undefined && activeTaskCount(taskStatuses) < 2;
+}
+/**
+ * "All tasks completed/cancelled" is checked before the approval-gate rule,
+ * so a Milestone whose only task(s) are already done always reads
+ * "completed" — even if that leaves it under the 2-active-task minimum.
+ * Without this order, a 1-task Milestone whose sole task is completed would
+ * be stuck reading "pending" forever, since the <2-active-tasks check would
+ * always match first. (This is also why an empty Milestone needs its own
+ * check first: `[].every(...)` is vacuously true and would otherwise read
+ * as "completed" before it has any tasks at all.)
+ *
+ * Note "pending" still covers two different situations that this field
+ * alone doesn't distinguish: a Milestone below the 2-active-task minimum
+ * and not yet approved (in effect "pending approval" — see needsApproval)
+ * versus one at/above that minimum, or already approved, where no task has
+ * started yet ("pending start"). Callers that need to tell them apart
+ * should check approved_at / needsApproval too.
+ */
+export function computeMilestoneStatus(taskStatuses, approvedAt) {
+    if (taskStatuses.length === 0)
+        return 'pending';
+    if (taskStatuses.every((s) => s === 'completed' || s === 'cancelled'))
+        return 'completed';
+    if (needsApproval(taskStatuses, approvedAt))
+        return 'pending';
+    if (taskStatuses.every((s) => s === 'pending'))
+        return 'pending';
+    return 'in_progress';
+}
+export function completionPct(counts) {
+    const total = Object.values(counts).reduce((sum, n) => sum + n, 0);
+    const denom = total - counts.cancelled;
+    if (denom === 0)
+        return null;
+    return (counts.completed / denom) * 100;
+}
+export function buildMilestonesSummary(milestones, tasksByMilestone) {
+    const result = [];
+    const outOfRange = [];
+    const pendingApproval = [];
+    for (const m of milestones) {
+        const statuses = tasksByMilestone.get(m.id) ?? [];
+        const status = computeMilestoneStatus(statuses, m.approved_at);
+        const counts = emptyTaskStatusCounts();
+        for (const s of statuses)
+            counts[s]++;
+        result.push({ milestone: { ...m, status }, task_counts: counts });
+        if (status !== 'completed' && isMilestoneOutOfRange(statuses)) {
+            outOfRange.push(m.id);
+        }
+        if (status !== 'completed' && needsApproval(statuses, m.approved_at)) {
+            pendingApproval.push(m.id);
+        }
+    }
+    return { milestones: result, outOfRange, pendingApproval };
+}
+export function buildProgress(taskStatuses) {
+    const counts = emptyTaskStatusCounts();
+    for (const s of taskStatuses)
+        counts[s]++;
+    return {
+        total_tasks: taskStatuses.length,
+        ...counts,
+        completion_pct: completionPct(counts),
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "goaltracker",
+  "version": "1.0.0",
+  "description": "MCP server that helps AI Agents track progress, manage Goals and Tasks in a hierarchical model, and maintain context across sessions.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "goaltracker": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "generate:skill": "node scripts/generate-skill-content.mjs",
+    "prebuild": "npm run generate:skill",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "predev": "npm run generate:skill",
+    "dev": "tsx src/index.ts",
+    "pretypecheck": "npm run generate:skill",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run generate:skill",
+    "test": "vitest run"
+  },
+  "license": "MIT",
+  "author": "Nhat-TheDev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nhat-TheDev/GoalTracker.git"
+  },
+  "homepage": "https://github.com/Nhat-TheDev/GoalTracker#readme",
+  "bugs": {
+    "url": "https://github.com/Nhat-TheDev/GoalTracker/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.11.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}