goaltracker 1.0.0 → 1.1.0

package/README.md

@@ -112,7 +112,7 @@ Agent A never told Agent B about the pending provider decision directly — it w
 - **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).
+Full schema, every tool's exact input/output, and the design rationale behind each decision: [docs/design/DESIGN.md](docs/design/DESIGN.md) (index — links out to the data model, tool reference, and decision log).
 
 ## Tools (14 total)
 
@@ -125,7 +125,7 @@ Full schema, every tool's exact input/output, and the design rationale behind ea
 | 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.
+⭐ = the two calls you'll use most: warm-up at the start of a session, review before closing one. See [docs/design/02-tools.md](docs/design/02-tools.md) for full input/output shapes.
 
 ## Configuration
 

package/dist/schemas/index.js

@@ -62,7 +62,7 @@ export const Checkpoint = z.object({
 // ---------- Tool input schemas ----------
 export const goalCreateInput = z.object({
     title: z.string().min(1),
-    description: z.string().optional(),
+    description: z.string().min(1),
 });
 export const goalListInput = z.object({
     status: GoalStatus.optional(),

package/dist/skillContent.js

@@ -1,7 +1,7 @@
 // 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.
+description: Use when the GoalTracker MCP tools (goal_create, spec_set, milestone_create, task_create, status_report, etc.) 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 after a context reset, or check on progress. Also reach for this the moment a requested feature or task is large enough that you need several clarifying questions before you can even start (multiple components, missing architecture/tech context, unclear scope) — that need is itself the signal to set up tracking, 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
@@ -34,12 +34,16 @@ The step between \`goal_create\` and the point where you actually start breaking
 
 - **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.
+  Before presenting the draft, re-read each criterion and ask yourself: could I mark this true or false today with zero ambiguity? If not, it's not done yet — sharpen it or flag it as an open question instead of shipping it vague.
+  - Not checkable (just restates the goal): "Icon system uses Lucide icons"
+  - Checkable (real DoD): "All 40 icon keys in \`util.js\` map to a lucide-static SVG; zero call sites fall back to an empty string"
 - **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.
+- **Before presenting the final plan, re-read every task description you just wrote as a self-audit pass.** Does each one say what actually changes and how you'd verify it's done, or is it a bare title restated as a sentence (e.g. "Fix the bug")? This is your one real chance to catch that — the final plan template below only surfaces a short verify clause per task, not the full description, so a thin description is otherwise invisible to the user at review time. Tighten anything that fails this check before moving on.
 - **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.
 
@@ -73,11 +77,11 @@ Anything to add, cut, or correct before I lock this in?
 ## Plan — <goal title>
 
 **M1 — <title>** (<breakdown strategy>: <one-line why this order>)
-- <task 1>
-- <task 2>
+- <task 1 title> — verify: <short clause pulled from that task's description>
+- <task 2 title> — verify: <short clause pulled from that task's description>
 
 **M2 — <title>**
-- <task 1>
+- <task 1 title> — verify: <short clause>
 ...
 
 Ready to start? Want me to check in after every task, after every milestone, or run straight through and report at the end?
@@ -130,6 +134,9 @@ task_list(status="pending") → task_update_status(id, "in_progress") → do the
   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.
+  Before calling \`task_create\`, ask yourself: if a future session with zero memory of this conversation read only this description, would they know what to change and how to confirm it's done — without asking you? A description shorter than a sentence almost never clears that bar.
+  - Not enough: "Fix the bug"
+  - Enough: "Fix the pagination cursor resetting to page 1 after a filter change — depends on: task 'add filter state to URL params' / verify by: apply a filter, click next page, filter should stay applied"
 - \`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.
 
@@ -161,5 +168,5 @@ status_report(goal_id)   // completion_pct should be 100 (or null if everything
 
 ## 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.
+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/05-decisions.md\`). 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/goal.js

@@ -5,7 +5,7 @@ export function goalTools(db) {
     return [
         {
             name: 'goal_create',
-            description: 'Create a new Goal. Called once when starting a new project.',
+            description: 'Create a new Goal. Called once when starting a new project. description is required — a 1-2 sentence summary of what this goal is about, for anyone (or any future session) scanning goal_list later.',
             schema: goalCreateInput,
             handler: (args) => {
                 const input = goalCreateInput.parse(args);

package/dist/tools/milestone.js

@@ -5,7 +5,7 @@ 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.',
+            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. description is not required by this tool, but use it to state which breakdown strategy this milestone follows and why — not just a restated title.',
             schema: milestoneCreateInput,
             handler: (args) => {
                 const input = milestoneCreateInput.parse(args);

package/dist/tools/task.js

@@ -5,7 +5,7 @@ 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.',
+            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. description is not required by this tool, but write one substantial enough that a future session with zero memory of this conversation could act on it — a bare restated title is not enough.',
             schema: taskCreateInput,
             handler: (args) => {
                 const input = taskCreateInput.parse(args);

package/dist/utils/computed.js

@@ -9,7 +9,7 @@ export function isMilestoneOutOfRange(taskStatuses) {
     return count < 2 || count > 5;
 }
 /**
- * The 5-active-task upper bound stays advisory only (see DESIGN.md §9,
+ * The 5-active-task upper bound stays advisory only (see docs/design/05-decisions.md,
  * "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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goaltracker",
-  "version": "1.0.0",
+  "version": "1.1.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",