agent-planner-mcp 0.6.2 → 0.8.0

package/AGENT_GUIDE.md

@@ -5,6 +5,8 @@ This guide is optimized for AI agents using AgentPlanner MCP tools.
 ## Core Workflow
 
 ```
+0. check_coherence_pending() → See if plans/goals need alignment review
+   → If stale items: run_coherence_check(plan_id) on each
 1. suggest_next_tasks(plan_id) → Find ready tasks (dependency-aware)
 2. get_task_context(node_id, depth=2) → Load progressive context
 3. Work on tasks (quick_status to track)
@@ -15,6 +17,16 @@ This guide is optimized for AI agents using AgentPlanner MCP tools.
 
 ## Essential Tools
 
+### Preflight: Alignment Check
+```javascript
+check_coherence_pending()
+// → Returns stale plans/goals that changed since last review
+
+run_coherence_check({ plan_id: "..." })
+// → Evaluates quality (coverage, specificity, ordering, knowledge)
+// → Stamps plan as reviewed, returns score breakdown
+```
+
 ### Before Starting Work
 ```javascript
 get_plan_context({ plan_id: "..." })

package/README.md

@@ -13,6 +13,87 @@ MCP server for [AgentPlanner](https://agentplanner.io) — AI agent orchestratio
 
 ## Setup
 
+## Thin local client (v1)
+
+A lightweight CLI loop for task-driven workflows. No MCP client required — useful when an agent (Claude Code, OpenClaw, a script) just needs to read its current task as files and write status back.
+
+### Mental model
+
+- AgentPlanner (the API) is the source of truth.
+- `.agentplanner/` files are a regeneratable cache, written by the CLI for the agent to read.
+- The agent works in the real repo. Status changes flow back via explicit writeback commands. There is no live sync.
+
+> **Running locally?** See [agent-planner/LOCAL_QUICKSTART.md](https://github.com/TAgents/agent-planner/blob/main/LOCAL_QUICKSTART.md) for the 5-minute path to a full local stack you can point this CLI at. Use `--api-url http://localhost:3000` in the `login` step below.
+
+### The loop
+
+```bash
+# 1. Login — saves credentials and auto-selects a default plan
+#    (pass --plan-id to pick one, or it auto-selects if you have exactly one plan)
+npx agent-planner-mcp login --token <token> --api-url https://agentplanner.io/api [--plan-id <id>]
+#    Localhost variant (after `docker compose -f docker-compose.local.yml up`):
+npx agent-planner-mcp login --token <token> --api-url http://localhost:3000
+
+# 2. See your task queue
+npx agent-planner-mcp tasks [--plan-id <id>]
+
+# 3. Pick the next task and pull context (claims it for 30 minutes)
+npx agent-planner-mcp next [--plan-id <id>]
+#    Force a fresh recommendation even if you have active work:
+npx agent-planner-mcp next --fresh
+
+# 4. Or pull context for a specific plan/node (no claim, no status change)
+npx agent-planner-mcp context --plan-id <plan-id> --node-id <node-id>
+#    If a default plan is set, --plan-id can be omitted:
+npx agent-planner-mcp context --node-id <node-id>
+
+# 5. Explicit writeback. No live sync.
+npx agent-planner-mcp start                          # claim + mark in_progress
+npx agent-planner-mcp blocked --message "Waiting on API decision"
+npx agent-planner-mcp done    --message "Implemented and verified"
+```
+
+### `next` resolution order
+
+`next` is a smart picker. It resolves in this order:
+
+1. **Resume** — if any task in scope is `in_progress`, pick it. (Source: `resume_in_progress`.)
+2. **Recommend** — call `suggest_next_tasks` (dependency- and RPI-aware) for a fresh pick. (Source: `suggest_next_tasks`.)
+3. **Fallback** — first `not_started` task in your queue. (Source: `my_tasks_fallback`.)
+
+`tasks` is the queue view; `next` is the smart picker; `next --fresh` skips step 1 and forces a fresh recommendation even when active work exists.
+
+### What `start`, `blocked`, `done` actually do
+
+| Command | Status | Claim | Log entry | Learning written to Graphiti |
+|---|---|---|---|---|
+| `start` | `in_progress` | claim (30m TTL) | — | — |
+| `blocked --message ...` | `blocked` | release | `challenge` | — |
+| `done --message ...` | `completed` | release | `progress` | yes (entry_type: `learning`) |
+
+All hooks are best-effort: claim/release/learning failures do not block the status update. Claim collisions (another agent already holds the lease) are reported but not fatal.
+
+### What `current-task.md` surfaces
+
+Beyond title, description, agent_instructions, and acceptance criteria, the generated `current-task.md` includes BDI signals from the API responses already being fetched:
+
+- **Plan health** — `quality_score`, rationale, `coherence_checked_at` (or "never")
+- **Coherence warning** — flagged when `node.coherence_status` is `contradiction_detected` or `stale_beliefs`, with concrete next-step pointers (`check_contradictions`, `recall_knowledge`)
+- **Detected contradictions** — listed when present in the node context
+- **Task mode** — shown when not `free` (RPI awareness for `research`/`plan`/`implement`)
+- **Linked goals**, **relevant knowledge** (top 5), **plan progress snapshot**
+
+### When to use CLI vs MCP vs API skill
+
+| You want… | Use |
+|---|---|
+| Zero-setup local task context for any coding agent (Claude Code, OpenClaw, scripts) | **CLI** (this thin client) |
+| Rich, structured tool access from inside an MCP-aware agent (Claude Desktop, Cursor, etc.) | **MCP** (run `npx agent-planner-mcp` as an MCP server) |
+| Direct programmatic integration from your own service | **API** (REST endpoints; same routes the MCP and CLI use) |
+
+The CLI is intentionally thin: it covers the read context + writeback loop and nothing else. For decomposition, dependency creation, knowledge graph queries, RPI chains, coherence runs, and goal management, use the MCP server (or the API directly).
+
+
 ### Claude Desktop
 
 Add to your `claude_desktop_config.json`:
@@ -149,6 +230,10 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 - `claim_task` / `release_task` - Task locking
 - `share_plan` - Collaboration management
 
+### Alignment & Review
+- `check_coherence_pending` - See which plans/goals need alignment review (staleness check)
+- `run_coherence_check` - Evaluate plan quality and stamp as reviewed
+
 ## LLM Skill Reference
 
 See **[SKILL.md](./SKILL.md)** for a complete reference designed to be consumed by LLMs. Include it in system prompts or agent configurations to give any LLM full knowledge of how to use AgentPlanner tools effectively.

package/SKILL.md

@@ -31,12 +31,43 @@ You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative p
 - You need to coordinate with humans on multi-step projects
 - You want to persist findings, decisions, or progress across sessions
 - You are asked to plan, research, or implement something as part of a tracked workflow
+- A user wants help defining or refining a goal
+
+## Goal Coaching
+
+When a user expresses an intent, objective, or want — help them turn it into a well-structured goal. Don't just create a goal from their words. Coach them through it:
+
+```
+1. Listen to the user's intent (however vague)
+2. recall_knowledge()         → Search for related context in the knowledge graph
+3. list_goals()               → Check for overlap with existing goals
+4. list_plans()               → Find related work that might link to this goal
+5. Propose a structured goal:
+   - Clear title
+   - Description explaining why this matters
+   - Success criteria with specific metrics + targets
+   - Linked plans (existing or suggest new ones)
+6. create_goal() + link plans
+7. assess_goal_quality()      → Check quality and get improvement suggestions
+8. Iterate with the user until quality is high
+```
+
+**What makes a good goal:**
+- **Clear** — has a title and description that explain what and why
+- **Measurable** — has success criteria with specific metrics and targets (e.g., "API latency < 100ms p99")
+- **Actionable** — has at least one linked plan with concrete tasks
+- **Knowledge-grounded** — related facts exist in the knowledge graph (if not, suggest researching first)
+- **Committed** — promoted from desire to intention when ready, with a time reference
+
+Use `assess_goal_quality(goal_id)` after creation to check quality and surface suggestions. Share the results with the user and help them address gaps.
 
 ## Workflow
 
 Follow this sequence when working on a plan:
 
 ```
+0. PREFLIGHT → check_coherence_pending to see if anything needs alignment review
+               ↳ If stale plans found, run_coherence_check on each before starting task work
 1. ORIENT    → suggest_next_tasks or get_task_context to understand what needs doing
 2. CLAIM     → quick_status to mark the task in_progress
 3. WORK      → Do the actual work (code, research, analysis, etc.)
@@ -46,6 +77,22 @@ Follow this sequence when working on a plan:
 6. NEXT      → suggest_next_tasks to find the next ready task
 ```
 
+### Preflight: Alignment Check
+
+Before diving into tasks, check if goals, plans, and knowledge are aligned:
+
+```
+check_coherence_pending()
+→ Returns stale plans/goals that changed since last review
+→ If stale items found:
+    run_coherence_check({ plan_id: "<plan_id>" })
+    → Evaluates quality (coverage, specificity, ordering, knowledge)
+    → Stamps the plan as reviewed
+    → Returns quality breakdown + coherence issues
+```
+
+This is a lightweight check (seconds, not minutes). Do it at the start of each work session. Skip if you already checked recently.
+
 ## Loading Context
 
 Always load context before starting work. Use `get_task_context` — it gives you exactly the right amount of information based on depth level.
@@ -205,6 +252,16 @@ Cross-plan dependencies work the same as regular dependencies (`blocks`, `requir
 | `claim_task` | Claim exclusive ownership of a task (prevents agent collisions) |
 | `release_task` | Release a previously claimed task |
 
+### Alignment & Review
+
+Check if goals, plans, and knowledge are aligned. Run as a preflight check before starting work.
+
+| Tool | Purpose |
+|------|---------|
+| `check_coherence_pending` | See what needs review — returns stale plans/goals that changed since last check |
+| `run_coherence_check` | Evaluate a plan's quality (coverage, specificity, ordering, knowledge) and stamp as reviewed |
+| `assess_goal_quality` | Check how well-defined a goal is (clarity, measurability, actionability, knowledge, commitment) |
+
 ### Knowledge (Temporal Knowledge Graph)
 
 All knowledge is stored in the Graphiti temporal knowledge graph, which automatically extracts entities and relationships and enables cross-plan knowledge retrieval. The temporal graph is **cross-plan** and **persists across sessions** — anything recorded is available to all future agents and conversations within the organization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {

package/src/api-client.js

@@ -613,6 +613,11 @@ const goals = {
     const response = await apiClient.get('/goals/dashboard');
     return response.data;
   },
+
+  getQuality: async (goalId) => {
+    const response = await apiClient.get(`/goals/${goalId}/quality`);
+    return response.data;
+  },
 };
 
 /**
@@ -722,6 +727,17 @@ const graphiti = {
   }
 };
 
+// ─── Users (my-tasks queue) ────────────────────────────────────
+const users = {
+  getMyTasks: async (options = {}) => {
+    const params = new URLSearchParams();
+    if (options.plan_id) params.append('plan_id', options.plan_id);
+    const qs = params.toString() ? `?${params.toString()}` : '';
+    const response = await apiClient.get(`/users/my-tasks${qs}`);
+    return response.data;
+  },
+};
+
 // ─── Dependencies (cross-plan & external) ─────────────────────
 const dependencies = {
   /**
@@ -760,10 +776,10 @@ const dependencies = {
  * @param {string} token - API token or JWT
  * @returns {Object} - API client modules (plans, nodes, etc.)
  */
-function createApiClient(token) {
+function createApiClient(token, options = {}) {
   const scheme = getAuthScheme(token);
   const client = axios.create({
-    baseURL: process.env.API_URL || 'http://localhost:3000',
+    baseURL: options.apiUrl || process.env.API_URL || 'http://localhost:3000',
     headers: {
       'Content-Type': 'application/json',
       'Authorization': token ? `${scheme} ${token}` : undefined
@@ -813,6 +829,10 @@ function createApiClient(token) {
       claimTask: async (planId, nodeId, agentId = 'mcp-agent', ttlMinutes = 30) => (await client.post(`/plans/${planId}/nodes/${nodeId}/claim`, { agent_id: agentId, ttl_minutes: ttlMinutes })).data,
       releaseTask: async (planId, nodeId, agentId = 'mcp-agent') => (await client.delete(`/plans/${planId}/nodes/${nodeId}/claim`, { data: { agent_id: agentId } })).data,
       getTaskClaim: async (planId, nodeId) => (await client.get(`/plans/${planId}/nodes/${nodeId}/claim`)).data,
+      suggestNextTasks: async (planId, limit = 5) => {
+        const params = new URLSearchParams({ plan_id: planId, limit: String(limit) });
+        return (await client.get(`/context/suggest?${params.toString()}`)).data;
+      },
     },
     comments: {
       getComments: async (planId, nodeId) => (await client.get(`/plans/${planId}/nodes/${nodeId}/comments`)).data,
@@ -883,6 +903,12 @@ function createApiClient(token) {
       removeAchiever: async (goalId, depId) => (await client.delete(`/goals/${goalId}/achievers/${depId}`)).data,
       getKnowledgeGaps: async (goalId) => (await client.get(`/goals/${goalId}/knowledge-gaps`)).data,
       getDashboard: async () => (await client.get('/goals/dashboard')).data,
+      getQuality: async (goalId) => (await client.get(`/goals/${goalId}/quality`)).data,
+    },
+    coherence: {
+      getPending: async () => (await client.get('/coherence/pending')).data,
+      runCheck: async (planId, goalId) => (await client.post(`/plans/${planId}/coherence/check`, goalId ? { goal_id: goalId } : {})).data,
+      getPlanCoherence: async (planId) => (await client.get(`/plans/${planId}/coherence`)).data,
     },
     context: {
       getNodeContext: async (nodeId, options = {}) => {
@@ -911,6 +937,14 @@ function createApiClient(token) {
       listCrossPlan: async (planIds) => (await client.get('/dependencies/cross-plan', { params: { plan_ids: planIds.join(',') } })).data,
       createExternal: async (data) => (await client.post('/dependencies/external', data)).data,
     },
+    users: {
+      getMyTasks: async (options = {}) => {
+        const params = new URLSearchParams();
+        if (options.plan_id) params.append('plan_id', options.plan_id);
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        return (await client.get(`/users/my-tasks${qs}`)).data;
+      },
+    },
     axiosInstance: client,
   };
 }
@@ -919,6 +953,13 @@ function createApiClient(token) {
 // Export the axios instance for direct use
 const axiosInstance = apiClient;
 
+// ─── Coherence ────────────────────────────────────────────────
+const coherence = {
+  getPending: () => apiClient.get('/coherence/pending').then(r => r.data),
+  runCheck: (planId, goalId) => apiClient.post(`/plans/${planId}/coherence/check`, goalId ? { goal_id: goalId } : {}).then(r => r.data),
+  getPlanCoherence: (planId) => apiClient.get(`/plans/${planId}/coherence`).then(r => r.data),
+};
+
 module.exports = {
   plans,
   nodes,
@@ -932,6 +973,8 @@ module.exports = {
   context,
   graphiti,
   dependencies,
+  coherence,
+  users,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/cli/config.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function getConfigDir() {
+  if (process.env.AGENT_PLANNER_CONFIG_DIR) {
+    return process.env.AGENT_PLANNER_CONFIG_DIR;
+  }
+
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'agent-planner');
+  }
+
+  return path.join(os.homedir(), '.config', 'agent-planner');
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readConfig() {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function writeConfig(config) {
+  const configDir = getConfigDir();
+  ensureDir(configDir);
+  const configPath = getConfigPath();
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  return configPath;
+}
+
+function resolveApiConfig(overrides = {}) {
+  const config = readConfig();
+  return {
+    apiUrl: overrides.apiUrl || process.env.API_URL || config.apiUrl || 'http://localhost:3000',
+    token: overrides.token || process.env.USER_API_TOKEN || process.env.API_TOKEN || config.token || null,
+  };
+}
+
+function mergeConfig(partial) {
+  const existing = readConfig();
+  return writeConfig({ ...existing, ...partial, updatedAt: new Date().toISOString() });
+}
+
+module.exports = {
+  ensureDir,
+  getConfigDir,
+  getConfigPath,
+  readConfig,
+  writeConfig,
+  mergeConfig,
+  resolveApiConfig,
+};

package/src/cli/local-client.js

@@ -0,0 +1,646 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { createApiClient } = require('../api-client');
+const { ensureDir, getConfigPath, mergeConfig, readConfig, resolveApiConfig, writeConfig } = require('./config');
+
+const DEFAULT_AGENT_ID = 'ap-cli';
+const DEFAULT_CLAIM_TTL_MIN = 30;
+
+function parseArgs(args = []) {
+  const positional = [];
+  const options = {};
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const keyValue = arg.slice(2).split('=');
+    const key = keyValue[0].replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (keyValue.length > 1) {
+      options[key] = keyValue.slice(1).join('=');
+      continue;
+    }
+
+    const next = args[i + 1];
+    if (!next || next.startsWith('--')) {
+      options[key] = true;
+      continue;
+    }
+
+    options[key] = next;
+    i += 1;
+  }
+
+  return { positional, options };
+}
+
+async function promptForLogin(options) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const prompt = (question) => new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+
+  const apiUrl = options.apiUrl || await prompt('API URL (default: https://agentplanner.io/api): ') || 'https://agentplanner.io/api';
+  const token = options.token || await prompt('API token: ');
+  rl.close();
+
+  if (!token) {
+    throw new Error('API token is required. Pass --token or run in an interactive terminal.');
+  }
+
+  return { apiUrl, token };
+}
+
+async function login(options = {}) {
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const credentials = (options.token && options.apiUrl)
+    ? { apiUrl: options.apiUrl, token: options.token }
+    : interactive
+      ? await promptForLogin(options)
+      : (() => {
+          if (!options.token) {
+            throw new Error('Missing token. Pass --token for non-interactive login.');
+          }
+          return {
+            apiUrl: options.apiUrl || 'https://agentplanner.io/api',
+            token: options.token,
+          };
+        })();
+
+  const api = createApiClient(credentials.token, { apiUrl: credentials.apiUrl });
+  const plans = await api.plans.getPlans();
+
+  const configData = {
+    apiUrl: credentials.apiUrl,
+    token: credentials.token,
+    updatedAt: new Date().toISOString(),
+  };
+
+  let defaultPlanId = null;
+  if (options.planId) {
+    defaultPlanId = options.planId;
+  } else if (Array.isArray(plans) && plans.length === 1) {
+    defaultPlanId = plans[0].id;
+  }
+  if (defaultPlanId) {
+    configData.defaultPlanId = defaultPlanId;
+  }
+
+  const configPath = writeConfig(configData);
+
+  return {
+    configPath,
+    apiUrl: credentials.apiUrl,
+    defaultPlanId,
+  };
+}
+
+function getWorkspaceStatePath(baseDir = process.cwd()) {
+  return path.join(baseDir, '.agentplanner');
+}
+
+function getWorkspaceContextPath(baseDir = process.cwd()) {
+  return path.join(getWorkspaceStatePath(baseDir), 'context.json');
+}
+
+function readWorkspaceContext(baseDir = process.cwd()) {
+  const contextPath = getWorkspaceContextPath(baseDir);
+  if (!fs.existsSync(contextPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(contextPath, 'utf8'));
+}
+
+function resolveSelection(options = {}, baseDir = process.cwd()) {
+  const workspaceContext = readWorkspaceContext(baseDir) || {};
+  const config = readConfig();
+  return {
+    planId: options.planId || workspaceContext.selection?.planId || config.defaultPlanId || null,
+    nodeId: options.nodeId || workspaceContext.selection?.nodeId || null,
+  };
+}
+
+function renderPlanTree(nodes = []) {
+  const lines = [];
+
+  function walk(node, depth) {
+    const indent = '  '.repeat(depth);
+    const marker = node.node_type === 'phase' ? '▸' : node.node_type === 'milestone' ? '◆' : '•';
+    const status = node.status ? ` [${node.status}]` : '';
+    lines.push(`${indent}${marker} ${node.title}${status}`);
+    for (const child of node.children || []) {
+      walk(child, depth + 1);
+    }
+  }
+
+  for (const node of nodes) {
+    walk(node, 0);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function stringifyJson(data) {
+  return JSON.stringify(data, null, 2) + '\n';
+}
+
+function renderBulletList(items = []) {
+  return items.filter(Boolean).map((item) => `- ${item}`);
+}
+
+function extractAcceptanceCriteria(text = '') {
+  const match = text.match(/Acceptance criteria:\s*([\s\S]*)/i);
+  if (!match) return [];
+
+  return match[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('-'))
+    .map((line) => line.replace(/^-\s*/, '').trim());
+}
+
+function stripAcceptanceCriteria(text = '') {
+  return text.replace(/\n*Acceptance criteria:\s*[\s\S]*/i, '').trim();
+}
+
+function renderPlanHealth(plan) {
+  if (!plan) return [];
+  const hasQuality = plan.quality_score !== null && plan.quality_score !== undefined;
+  const hasChecked = Boolean(plan.coherence_checked_at);
+  if (!hasQuality && !hasChecked) return [];
+
+  const out = ['## Plan health', ''];
+  if (hasQuality) {
+    out.push(`- Quality score: ${plan.quality_score}`);
+    if (plan.quality_rationale) {
+      out.push(`- Rationale: ${plan.quality_rationale}`);
+    }
+  }
+  out.push(`- Last coherence check: ${hasChecked ? plan.coherence_checked_at : 'never'}`);
+  if (!hasChecked) {
+    out.push('- Run `run_coherence_check` (MCP) before acting on stale plans.');
+  }
+  out.push('');
+  return out;
+}
+
+function renderCoherenceWarning(task) {
+  if (!task || !task.coherence_status) return [];
+  const status = task.coherence_status;
+  if (status === 'clean' || status === 'unchecked') return [];
+
+  const out = ['## Coherence warning', ''];
+  out.push(`- Status: ${status}`);
+  if (status === 'contradiction_detected') {
+    out.push('- Supporting knowledge contains contradictions. Run `check_contradictions` (MCP) and re-verify before acting.');
+  } else if (status === 'stale_beliefs') {
+    out.push('- Knowledge backing this task may be outdated. Run `recall_knowledge` (MCP) to refresh before deciding.');
+  }
+  out.push('');
+  return out;
+}
+
+function renderContradictions(nodeContext) {
+  const list = Array.isArray(nodeContext?.contradictions) ? nodeContext.contradictions : [];
+  if (!list.length) return [];
+
+  const out = ['## Detected contradictions', ''];
+  out.push(...renderBulletList(
+    list.slice(0, 5).map((c) => c.summary || c.content || c.message || JSON.stringify(c)),
+  ));
+  out.push('');
+  return out;
+}
+
+function renderCurrentTask(selection, plan, nodeContext, planContext) {
+  const lines = [];
+  lines.push(`# ${selection.nodeId && nodeContext?.node ? nodeContext.node.title : plan.title}`);
+  lines.push('');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- Plan: ${plan.title}`);
+  lines.push(`- Plan ID: ${plan.id}`);
+  if (selection.nodeId && nodeContext?.node) {
+    lines.push(`- Task ID: ${selection.nodeId}`);
+    lines.push(`- Status: ${nodeContext.node.status || 'unknown'}`);
+    if (nodeContext.node.task_mode && nodeContext.node.task_mode !== 'free') {
+      lines.push(`- Task mode: ${nodeContext.node.task_mode}`);
+    }
+  }
+  lines.push(`- Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  lines.push(...renderPlanHealth(plan));
+
+  if (!selection.nodeId || !nodeContext?.node) {
+    lines.push('No node selected. Re-run with --node-id to materialize a task-specific current-task.md.');
+    lines.push('');
+    lines.push('Generated file. Safe to overwrite with `agent-planner-mcp context ...`.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const task = nodeContext.node;
+  const ancestry = Array.isArray(nodeContext.ancestry) ? nodeContext.ancestry : [];
+  const parentPhase = ancestry.find((item) => item.node_type === 'phase');
+  const acceptanceCriteria = extractAcceptanceCriteria(task.description || '');
+  const description = stripAcceptanceCriteria(task.description || '');
+  const knowledge = (nodeContext.knowledge || []).slice(0, 5).map((item) => item.content);
+  const phaseSummaries = (planContext?.phases || []).map((phase) => `${phase.title}: ${phase.completed_tasks}/${phase.total_tasks} complete`);
+
+  lines.push(...renderCoherenceWarning(task));
+  lines.push(...renderContradictions(nodeContext));
+
+  if (parentPhase) {
+    lines.push('## Placement');
+    lines.push('');
+    lines.push(`- Phase: ${parentPhase.title}`);
+    lines.push(`- Phase status: ${parentPhase.status || 'unknown'}`);
+    lines.push('');
+  }
+
+  if (description) {
+    lines.push('## Task');
+    lines.push('');
+    lines.push(description);
+    lines.push('');
+  }
+
+  if (task.context) {
+    lines.push('## Implementation context');
+    lines.push('');
+    lines.push(task.context);
+    lines.push('');
+  }
+
+  if (task.agent_instructions) {
+    lines.push('## Agent instructions');
+    lines.push('');
+    lines.push(task.agent_instructions);
+    lines.push('');
+  }
+
+  if (acceptanceCriteria.length) {
+    lines.push('## Acceptance criteria');
+    lines.push('');
+    lines.push(...renderBulletList(acceptanceCriteria));
+    lines.push('');
+  }
+
+  const goalsData = (nodeContext.goals || []).concat(
+    (planContext?.goals || []).filter(
+      (pg) => !(nodeContext.goals || []).some((ng) => ng.id === pg.id)
+    )
+  );
+  if (goalsData.length) {
+    lines.push('## Linked goals');
+    lines.push('');
+    lines.push(...goalsData.map((g) => `- ${g.title || g.name}${g.status ? ` [${g.status}]` : ''}`));
+    lines.push('');
+  }
+
+  if (knowledge.length) {
+    lines.push('## Relevant knowledge');
+    lines.push('');
+    lines.push(...renderBulletList(knowledge));
+    lines.push('');
+  }
+
+  if (phaseSummaries.length) {
+    lines.push('## Plan progress snapshot');
+    lines.push('');
+    lines.push(...renderBulletList(phaseSummaries));
+    lines.push('');
+  }
+
+  lines.push('## Suggested loop');
+  lines.push('');
+  lines.push('- Run `agent-planner-mcp start` when you begin active work (claims the task for 30 min).');
+  lines.push('- Do the implementation work in the repo, not in `.agentplanner/`.');
+  lines.push('- If blocked, run `agent-planner-mcp blocked --message "why"` (releases the claim).');
+  lines.push('- When complete, run `agent-planner-mcp done --message "what changed"` (logs progress and writes a learning to the temporal graph).');
+  lines.push('- Refresh with `agent-planner-mcp context --plan-id ... --node-id ...` when you need updated context.');
+  lines.push('');
+  lines.push('## Source of truth');
+  lines.push('');
+  lines.push('- AgentPlanner (the API) is the source of truth for this plan and task.');
+  lines.push('- Files under `.agentplanner/` are a regeneratable cache produced by `agent-planner-mcp context`.');
+  lines.push('- Do not hand-edit `.agentplanner/` files; changes here are not synced back. Use the writeback commands above.');
+  lines.push('- Safe to delete `.agentplanner/` at any time — re-run `context` or `next` to repopulate.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function materializeContext(options = {}) {
+  const baseDir = path.resolve(options.dir || process.cwd());
+  const selection = resolveSelection(options, baseDir);
+  if (!selection.planId) {
+    throw new Error('Missing plan id. Pass --plan-id or run context after generating workspace state.');
+  }
+
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const api = createApiClient(token, { apiUrl });
+  const stateDir = getWorkspaceStatePath(baseDir);
+  ensureDir(stateDir);
+
+  const [plan, nodes, planContext, nodeContext] = await Promise.all([
+    api.plans.getPlan(selection.planId),
+    api.nodes.getNodes(selection.planId),
+    api.context.getPlanContext(selection.planId),
+    selection.nodeId ? api.context.getNodeContext(selection.nodeId) : Promise.resolve(null),
+  ]);
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    apiUrl,
+    selection,
+    plan,
+    planContext,
+    nodeContext,
+  };
+
+  fs.writeFileSync(path.join(stateDir, 'context.json'), stringifyJson(payload));
+  fs.writeFileSync(path.join(stateDir, 'plan-tree.md'), renderPlanTree(nodes));
+  fs.writeFileSync(path.join(stateDir, 'current-task.md'), renderCurrentTask(selection, plan, nodeContext, planContext));
+
+  return {
+    stateDir,
+    selection,
+  };
+}
+
+async function tryClaim(api, planId, nodeId, options = {}) {
+  if (typeof api.nodes?.claimTask !== 'function') return false;
+  try {
+    await api.nodes.claimTask(
+      planId,
+      nodeId,
+      options.agentId || DEFAULT_AGENT_ID,
+      Number(options.ttl) || DEFAULT_CLAIM_TTL_MIN,
+    );
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function tryRelease(api, planId, nodeId, options = {}) {
+  if (typeof api.nodes?.releaseTask !== 'function') return false;
+  try {
+    await api.nodes.releaseTask(planId, nodeId, options.agentId || DEFAULT_AGENT_ID);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function tryRecordLearning(api, { planId, nodeId, taskTitle, message }) {
+  if (!message || typeof api.graphiti?.addEpisode !== 'function') return false;
+  try {
+    await api.graphiti.addEpisode({
+      content: message,
+      name: taskTitle ? `[done] ${taskTitle}` : `[done] ${nodeId}`,
+      plan_id: planId,
+      node_id: nodeId,
+      metadata: { entry_type: 'learning', source: DEFAULT_AGENT_ID },
+    });
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function updateStatus(command, options = {}) {
+  const statusMap = {
+    start: 'in_progress',
+    blocked: 'blocked',
+    done: 'completed',
+  };
+  const logTypeMap = {
+    blocked: 'challenge',
+    done: 'progress',
+  };
+
+  const baseDir = path.resolve(options.dir || process.cwd());
+  const selection = resolveSelection(options, baseDir);
+  if (!selection.planId || !selection.nodeId) {
+    throw new Error('Missing plan/node selection. Pass --plan-id and --node-id, or run context with both first.');
+  }
+
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const api = createApiClient(token, { apiUrl });
+  await api.nodes.updateNodeStatus(selection.planId, selection.nodeId, statusMap[command]);
+
+  let logged = false;
+  if (options.message && logTypeMap[command]) {
+    await api.logs.addLogEntry(selection.planId, selection.nodeId, {
+      content: options.message,
+      log_type: logTypeMap[command],
+    });
+    logged = true;
+  }
+
+  let claimed = false;
+  let released = false;
+  let learned = false;
+
+  if (command === 'start') {
+    claimed = await tryClaim(api, selection.planId, selection.nodeId, options);
+  } else if (command === 'blocked' || command === 'done') {
+    released = await tryRelease(api, selection.planId, selection.nodeId, options);
+  }
+
+  if (command === 'done' && options.message) {
+    const workspaceContext = readWorkspaceContext(baseDir);
+    const taskTitle = workspaceContext?.nodeContext?.node?.title;
+    learned = await tryRecordLearning(api, {
+      planId: selection.planId,
+      nodeId: selection.nodeId,
+      taskTitle,
+      message: options.message,
+    });
+  }
+
+  return {
+    planId: selection.planId,
+    nodeId: selection.nodeId,
+    status: statusMap[command],
+    logged,
+    claimed,
+    released,
+    learned,
+  };
+}
+
+async function getMyTasks(options = {}) {
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const config = readConfig();
+  const planId = options.planId || config.defaultPlanId || null;
+  const api = createApiClient(token, { apiUrl });
+  const fetchOptions = {};
+  if (planId) fetchOptions.plan_id = planId;
+
+  const tasks = await api.users.getMyTasks(fetchOptions);
+  if (!planId) {
+    return { tasks, planId };
+  }
+
+  const taskList = Array.isArray(tasks) ? tasks : tasks?.tasks;
+  if (!Array.isArray(taskList)) {
+    return { tasks, planId };
+  }
+
+  const filteredTasks = taskList.filter((task) => task.plan_id === planId);
+  if (Array.isArray(tasks)) {
+    return { tasks: filteredTasks, planId };
+  }
+
+  return {
+    tasks: {
+      ...tasks,
+      tasks: filteredTasks,
+    },
+    planId,
+  };
+}
+
+function normalizeSuggestion(suggestion, planId) {
+  if (!suggestion) return null;
+  const id = suggestion.id || suggestion.node_id;
+  if (!id) return null;
+  return {
+    id,
+    title: suggestion.title,
+    status: suggestion.status,
+    plan_id: suggestion.plan_id || planId,
+    task_mode: suggestion.task_mode,
+    knowledge_ready: suggestion.knowledge_ready,
+    ...suggestion,
+  };
+}
+
+async function pickViaSuggestNextTasks(api, planId, limit) {
+  if (!planId || typeof api.nodes?.suggestNextTasks !== 'function') return null;
+  try {
+    const suggestions = await api.nodes.suggestNextTasks(planId, limit);
+    const list = Array.isArray(suggestions)
+      ? suggestions
+      : (suggestions?.suggestions || suggestions?.tasks || []);
+    if (!list.length) return null;
+    return normalizeSuggestion(list[0], planId);
+  } catch (_err) {
+    return null;
+  }
+}
+
+async function pickFromQueue(options, status) {
+  try {
+    const { tasks, planId: queuePlanId } = await getMyTasks(options);
+    const list = Array.isArray(tasks) ? tasks : tasks?.tasks || [];
+    const match = list.find((t) => t.status === status);
+    if (!match) return null;
+    if (!match.plan_id && queuePlanId) match.plan_id = queuePlanId;
+    return match;
+  } catch (_err) {
+    return null;
+  }
+}
+
+async function getNextTask(options = {}) {
+  const { apiUrl, token } = resolveApiConfig(options);
+  if (!token) {
+    throw new Error(`Not logged in. Run \`agent-planner-mcp login\` first. Config path: ${getConfigPath()}`);
+  }
+
+  const config = readConfig();
+  const planId = options.planId || config.defaultPlanId || null;
+  const api = createApiClient(token, { apiUrl });
+  const fresh = Boolean(options.fresh);
+
+  // Resolution order:
+  //  1. Resume any in_progress task in scope (unless --fresh).
+  //  2. Dependency-aware recommendation via suggest_next_tasks.
+  //  3. Fallback: first not_started task in the my-tasks queue.
+  //
+  // `tasks` is the queue view; `next` is the smart picker. `next --fresh`
+  // forces a fresh recommendation even when active work exists.
+
+  let chosen = null;
+  let source = null;
+
+  if (!fresh) {
+    chosen = await pickFromQueue(options, 'in_progress');
+    if (chosen) source = 'resume_in_progress';
+  }
+
+  if (!chosen) {
+    chosen = await pickViaSuggestNextTasks(api, planId, options.limit ? Number(options.limit) : 5);
+    if (chosen) source = 'suggest_next_tasks';
+  }
+
+  if (!chosen) {
+    chosen = await pickFromQueue(options, 'not_started');
+    if (chosen) source = 'my_tasks_fallback';
+  }
+
+  if (!chosen) {
+    throw new Error('No actionable tasks (in_progress or not_started) found.');
+  }
+
+  const taskPlanId = chosen.plan_id || planId;
+  if (!taskPlanId) {
+    throw new Error('Could not determine plan_id for the selected task. Pass --plan-id explicitly.');
+  }
+
+  const claimed = await tryClaim(api, taskPlanId, chosen.id, options);
+
+  const contextResult = await materializeContext({
+    ...options,
+    planId: taskPlanId,
+    nodeId: chosen.id,
+  });
+
+  return {
+    task: chosen,
+    planId: taskPlanId,
+    stateDir: contextResult.stateDir,
+    claimed,
+    source,
+  };
+}
+
+module.exports = {
+  getMyTasks,
+  getNextTask,
+  getWorkspaceContextPath,
+  getWorkspaceStatePath,
+  login,
+  materializeContext,
+  parseArgs,
+  readWorkspaceContext,
+  renderCurrentTask,
+  renderPlanTree,
+  resolveSelection,
+  updateStatus,
+};

package/src/cli.js

@@ -1,39 +1,57 @@
 #!/usr/bin/env node
 
 /**
- * CLI Entry Point for agent-planner-mcp
- * Routes to different commands or starts the MCP server
+ * CLI entry point for agent-planner-mcp.
+ * Preserves the existing MCP server/setup commands while adding
+ * a thin local-client loop for login/context/status writeback.
  */
 
-const path = require('path');
+const { getMyTasks, getNextTask, materializeContext, login, parseArgs, updateStatus } = require('./cli/local-client');
 
 const args = process.argv.slice(2);
 const command = args[0];
+const { options } = parseArgs(args.slice(1));
 
-// Route to different commands
-switch (command) {
-  case 'setup-claude-code':
-    // Run the setup-claude-code script
-    const setupClaudeCode = require('./setup-claude-code.js');
-    setupClaudeCode.main();
-    break;
-
-  case 'setup':
-    // Run the interactive setup wizard
-    require('./setup.js');
-    break;
-
-  case '--help':
-  case '-h':
-  case 'help':
-    console.log(`
-Agent Planner MCP - Model Context Protocol Server
+function printHelp() {
+  console.log(`
+Agent Planner MCP - MCP server + thin local client
 
 Usage:
-  npx agent-planner-mcp                    Start MCP server (requires USER_API_TOKEN)
-  npx agent-planner-mcp setup-claude-code  Install orchestration commands to .claude/
-  npx agent-planner-mcp setup              Interactive setup wizard
-  npx agent-planner-mcp --help             Show this help message
+  npx agent-planner-mcp                          Start MCP server (requires USER_API_TOKEN)
+  npx agent-planner-mcp setup-claude-code       Install orchestration commands to .claude/
+  npx agent-planner-mcp setup                   Interactive setup wizard
+  npx agent-planner-mcp login --token <token> [--api-url <url>] [--plan-id <id>]
+  npx agent-planner-mcp tasks [--plan-id <id>]
+  npx agent-planner-mcp next [--plan-id <id>] [--fresh]
+  npx agent-planner-mcp context --plan-id <id> [--node-id <id>] [--dir <path>]
+  npx agent-planner-mcp start [--plan-id <id>] [--node-id <id>]
+  npx agent-planner-mcp blocked [--plan-id <id>] [--node-id <id>] [--message "..."]
+  npx agent-planner-mcp done [--plan-id <id>] [--node-id <id>] [--message "..."]
+  npx agent-planner-mcp --help
+
+Commands:
+  login    Authenticate and store credentials. If --plan-id is passed it is
+           saved as the default plan. If exactly one plan is accessible, it is
+           auto-selected as the default.
+  tasks    Queue view: list tasks assigned to you (uses /users/my-tasks).
+           Filters by --plan-id or falls back to the stored default plan.
+  next     Smart picker. Resolution order: (1) resume any in_progress task
+           in scope, (2) dependency-aware recommendation via suggest_next_tasks,
+           (3) fall back to first not_started task in your queue. Claims the
+           picked task for 30 minutes and materializes its context files.
+           Pass --fresh to skip step 1 and force a fresh recommendation
+           even when active work exists.
+  context  Pull context for a specific plan/node and write .agentplanner/ files
+           (a regeneratable cache; AgentPlanner remains the source of truth).
+           Surfaces plan health (quality, coherence) and any contradictions
+           detected on the task. --node-id can be used alone when a default
+           plan is set.
+  start    Mark the current task as in_progress and claim it (30-minute TTL).
+  blocked  Mark the current task as blocked and release the claim. Optional
+           --message is logged as a challenge entry.
+  done     Mark the current task as completed and release the claim. Optional
+           --message is logged as progress AND written to the temporal
+           knowledge graph as a learning episode.
 
 Environment Variables:
   API_URL          - Agent Planner API URL (default: http://localhost:3000)
@@ -44,21 +62,104 @@ Environment Variables:
 Documentation:
   https://github.com/talkingagents/agent-planner-mcp
 `);
-    break;
-
-  case '--version':
-  case '-v':
-    const pkg = require('../package.json');
-    console.log(`agent-planner-mcp v${pkg.version}`);
-    break;
-
-  default:
-    // No command or unknown command - start MCP server
-    if (command && !command.startsWith('-')) {
-      console.error(`Unknown command: ${command}`);
-      console.error('Run "npx agent-planner-mcp --help" for usage information.');
-      process.exit(1);
+}
+
+async function main() {
+  switch (command) {
+    case 'setup-claude-code': {
+      const setupClaudeCode = require('./setup-claude-code.js');
+      setupClaudeCode.main();
+      return;
+    }
+
+    case 'setup':
+      require('./setup.js');
+      return;
+
+    case 'login': {
+      const result = await login(options);
+      console.log(`Saved credentials to ${result.configPath}`);
+      console.log(`API URL: ${result.apiUrl}`);
+      if (result.defaultPlanId) {
+        console.log(`Default plan: ${result.defaultPlanId}`);
+      }
+      return;
+    }
+
+    case 'tasks': {
+      const result = await getMyTasks(options);
+      const taskList = Array.isArray(result.tasks) ? result.tasks : result.tasks?.tasks || [];
+      if (result.planId) {
+        console.log(`Tasks for plan ${result.planId}:`);
+      } else {
+        console.log('All tasks:');
+      }
+      if (!taskList.length) {
+        console.log('  (no tasks)');
+        return;
+      }
+      for (const t of taskList) {
+        const plan = t.plan_id && t.plan_id !== result.planId ? ` (plan: ${t.plan_id})` : '';
+        console.log(`  [${t.status || '?'}] ${t.title || t.id}${plan}`);
+      }
+      return;
+    }
+
+    case 'next': {
+      const result = await getNextTask(options);
+      console.log(`Selected task: ${result.task.title || result.task.id} [${result.task.status}]`);
+      console.log(`Plan: ${result.planId}`);
+      console.log(`Source: ${result.source}`);
+      if (result.claimed) console.log('Claimed task for 30 minutes.');
+      console.log(`Context written to ${result.stateDir}`);
+      return;
     }
-    // Start the MCP server
-    require('./index.js');
+
+    case 'context': {
+      const result = await materializeContext(options);
+      console.log(`Wrote generated context files to ${result.stateDir}`);
+      if (result.selection.nodeId) {
+        console.log(`Selected node: ${result.selection.nodeId}`);
+      }
+      return;
+    }
+
+    case 'start':
+    case 'blocked':
+    case 'done': {
+      const result = await updateStatus(command, options);
+      console.log(`Updated ${result.nodeId} to ${result.status}`);
+      if (result.logged) console.log('Added log entry.');
+      if (result.claimed) console.log('Claimed task.');
+      if (result.released) console.log('Released task claim.');
+      if (result.learned) console.log('Recorded learning to temporal knowledge graph.');
+      return;
+    }
+
+    case '--help':
+    case '-h':
+    case 'help':
+      printHelp();
+      return;
+
+    case '--version':
+    case '-v': {
+      const pkg = require('../package.json');
+      console.log(`agent-planner-mcp v${pkg.version}`);
+      return;
+    }
+
+    default:
+      if (command && !command.startsWith('-')) {
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "npx agent-planner-mcp --help" for usage information.');
+        process.exit(1);
+      }
+      require('./index.js');
+  }
 }
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exit(1);
+});

package/src/tools.js

@@ -178,6 +178,41 @@ function setupTools(server, apiClientOverride) {
           }
         },
 
+        // ========================================
+        // COHERENCE - Check alignment across goals/plans/knowledge
+        // ========================================
+        {
+          name: "check_coherence_pending",
+          description: "Check what needs coherence review. Returns stale plans and goals that have changed since their last coherence check. Call this at the start of a maintenance cycle to discover what needs attention. Uses timestamp comparison (updated_at vs coherence_checked_at) — no expensive processing.",
+          inputSchema: {
+            type: "object",
+            properties: {}
+          }
+        },
+        {
+          name: "run_coherence_check",
+          description: "Run a coherence check on a specific plan. Evaluates quality (coverage, specificity, ordering, knowledge completeness), flags contradictions, and stamps the plan as checked. Returns quality breakdown with sub-scores and rationale.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              plan_id: { type: "string", description: "Plan ID to check" },
+              goal_id: { type: "string", description: "Optional goal ID to evaluate coverage against" }
+            },
+            required: ["plan_id"]
+          }
+        },
+        {
+          name: "assess_goal_quality",
+          description: "Assess how well-defined a goal is. Evaluates 5 dimensions: clarity (title+description), measurability (success criteria), actionability (linked plans), knowledge grounding (related facts), and commitment (desire vs intention, deadline). Returns score, dimension breakdown, and specific improvement suggestions. Use this when helping users define or refine goals.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              goal_id: { type: "string", description: "Goal ID to assess" }
+            },
+            required: ["goal_id"]
+          }
+        },
+
         // ========================================
         // CONTEXT LOADING - Get everything you need
         // Use before starting work on a plan/goal
@@ -2233,12 +2268,14 @@ function setupTools(server, apiClientOverride) {
               "Knowledge - Persistent storage for decisions, context, constraints, and learnings"
             ],
             recommended_workflow: [
-              "1. Check list_goals to understand current objectives",
-              "2. Use list_plans to see existing plans",
-              "3. Before working on a plan, use get_plan_context to get the full picture",
-              "4. Update task statuses as you work (update_node with status)",
-              "5. Store important decisions and learnings using add_learning",
-              "6. Check recall_knowledge before making decisions to see past context"
+              "1. PREFLIGHT: check_coherence_pending to see if any plans/goals need alignment review",
+              "   → If stale items found, run_coherence_check on each before starting task work",
+              "2. Check list_goals to understand current objectives",
+              "3. Use list_plans to see existing plans",
+              "4. Before working on a plan, use get_plan_context to get the full picture",
+              "5. Update task statuses as you work (update_node with status)",
+              "6. Store important decisions and learnings using add_learning",
+              "7. Check recall_knowledge before making decisions to see past context"
             ],
             quick_tips: [
               "Always capture WHY decisions were made, not just WHAT",
@@ -2375,6 +2412,43 @@ function setupTools(server, apiClientOverride) {
         });
       }
 
+      // ===== COHERENCE =====
+      if (name === "check_coherence_pending") {
+        const result = await apiClient.coherence.getPending();
+        const totalStale = (result.stale_plans?.length || 0) + (result.stale_goals?.length || 0);
+        return formatResponse({
+          ...result,
+          tip: totalStale > 0
+            ? "Review stale items. For each stale plan, call run_coherence_check to evaluate quality and stamp as checked."
+            : "Everything is up to date. No coherence review needed."
+        });
+      }
+
+      if (name === "assess_goal_quality") {
+        const { goal_id } = args;
+        const result = await apiClient.goals.getQuality(goal_id);
+        const lowDims = Object.entries(result.dimensions || {})
+          .filter(([, v]) => v.score < 0.5)
+          .map(([k]) => k);
+        return formatResponse({
+          ...result,
+          tip: result.suggestions?.length > 0
+            ? `Goal needs improvement in: ${lowDims.join(', ') || 'minor areas'}. Follow the suggestions to strengthen it.`
+            : 'Goal is well-defined. Ready for agent execution.'
+        });
+      }
+
+      if (name === "run_coherence_check") {
+        const { plan_id, goal_id } = args;
+        const result = await apiClient.coherence.runCheck(plan_id, goal_id);
+        return formatResponse({
+          ...result,
+          tip: result.coherence_issues_count > 0
+            ? `${result.coherence_issues_count} coherence issues found. Review tasks with stale_beliefs or contradiction_detected status.`
+            : "Plan is coherent. Quality score and checked_at timestamp updated."
+        });
+      }
+
       // Tool not found
       throw new Error(`Unknown tool: ${name}`);
     } catch (error) {