agent-planner-mcp 1.5.17 → 1.6.0

package/AGENT_GUIDE.md

@@ -83,11 +83,11 @@ The single most important decision when calling a creation tool.
 
 | Origin | Default | Why |
 |---|---|---|
-| **Human said so in chat** | `status='active'` (omit) | User already approved by asking. Don't bury their request in drafts. |
-| **You're acting autonomously** | `status='draft'` (pass explicitly) | Let the human review before it activates. Drafts surface in the dashboard pending queue. |
+| **Human said so in chat** | `status='active'` (pass explicitly) | User already approved by asking. Don't bury their request in drafts. |
+| **You're acting autonomously** | `status='draft'` (the default — just omit) | Let the human review before it activates. Drafts surface in the dashboard pending queue. |
 | **You're uncertain** | use `queue_decision` instead | Drafts are for "I'm proposing structure"; the queue is for "I need an answer." |
 
-Drafts auto-promote to active when work begins on any node (transitions to `in_progress`, `completed`, `blocked`, `plan_ready`). Promote explicitly via `update_plan({status: 'active'})` or `update_goal({status: 'active'})`.
+Draft plans are a hard gate: task status changes and claims on a draft are rejected (409) until the plan is activated. **You can activate it yourself** — `update_plan({status: 'active'})` — whenever a human directed the work (in chat, in the task's instructions, or by assigning it to you). The gate exists to make activation an explicit, auditable step, not to route everything through the UI. Only when you're acting autonomously with no human direction should you leave it draft and `queue_decision` to request activation. Plan completion is derived: a plan reads as `completed` automatically when its work hits 100%; it cannot be set directly.
 
 ## Workflow templates
 

package/README.md

@@ -232,8 +232,8 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 
 ## Key Features
 
-- **24 BDI-aligned tools** for state, goals, and committed actions — no CRUD shapes, every tool answers a whole agentic question
-- **Full mutation surface (v1.0)** — agents and humans-via-agents can manage every plan/node/org property without leaving the conversation; UI is optional inspection
+- **39 BDI-aligned tools** for state, goals, committed actions, and workspace/blueprint management — no CRUD shapes, every tool answers a whole agentic question
+- **Full mutation surface** — agents and humans-via-agents can manage every plan/node/org property, plus workspaces and reusable blueprints, without leaving the conversation; UI is optional inspection
 - **Draft-status seam** — autonomous agent creation lands as drafts surfacing in the dashboard pending queue; human-directed creation defaults to active
 - **Dependency graph** — cycle detection, impact analysis, critical path
 - **Progressive context** — 4-layer context assembly with token budgeting
@@ -242,10 +242,11 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 - **Task claims** — TTL-based locking for multi-agent coordination
 - **Organizations** — multi-tenant isolation with member management
 
-## Available Tools (v1.0.0)
+## Available Tools (v1.5)
 
 ### Beliefs (read state)
 - `briefing` — bundled mission control state in one call
+- `list_plans` — list plans with optional status/visibility/text filters; returns ids, status, last update, and link counts so you can pick a plan without round-tripping `briefing`
 - `task_context` — single task at progressive depth 1-4
 - `goal_state` — single goal deep-dive (details + quality + progress + bottlenecks + gaps)
 - `recall_knowledge` — knowledge graph query (facts, entities, episodes, contradictions)
@@ -256,7 +257,8 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 - `list_goals` — goals with health rollup
 - `update_goal` — atomic goal update (subsumes link/unlink/achievers)
 - `create_goal` — create a new top-level goal (no parent)
-- `derive_subgoal` *(v1.0)* — create a sub-goal under an existing parent
+- `derive_subgoal` — create a sub-goal under an existing parent
+- `record_criterion_progress` — record the latest observed value of a goal's success criterion (e.g. a metric moved 40→72); the write that makes goal attainment real
 
 ### Intentions — execution
 - `claim_next_task` — pick + claim + load context (one call)
@@ -266,24 +268,32 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 - `resolve_decision` — pick up human's answer (atomically materializes any `proposed_subtasks`)
 - `add_learning` — record knowledge episode
 
-### Intentions — creation *(v1.0)*
+### Intentions — creation
 - `form_intention` — create plan + initial tree under a goal, atomically
 - `extend_intention` — add children under an existing parent (lightweight)
 - `propose_research_chain` — RPI triple with 2 blocking edges, in one call
 
-### Intentions — structural mutation *(v1.0)*
+### Intentions — structural mutation
 - `update_plan` — edit any plan property
 - `update_node` — edit any node property except status
 - `move_node` — reparent within plan; cycle-safe
 - `link_intentions` / `unlink_intentions` — manage dependency edges
 - `delete_plan` / `delete_node` — soft-delete via `status='archived'` (recoverable)
 
-### Intentions — sharing & collaboration *(v1.0)*
+### Intentions — sharing & collaboration
 - `share_plan` — atomic visibility + add/remove collaborators
 - `invite_member` — add user to org (by user_id or email)
 - `update_member_role` — owner-only role change
 - `remove_member` — owner/admin removes non-owner member
 
+### Workspaces & Blueprints
+- `list_workspaces` — list workspaces (goal/plan folders) in an organization
+- `create_workspace` — create a new workspace inside an organization (slug auto-generated and de-duped)
+- `list_blueprints` — list blueprints visible to you (owned + public/unlisted), filterable by scope/visibility
+- `save_as_blueprint` — snapshot a live plan as a reusable plan-scope blueprint (structure + agent_instructions + dependencies; excludes run-state)
+- `fork_blueprint` — fork a plan-scope blueprint into a target workspace as a new plan (statuses reset, lineage recorded)
+- `delete_blueprint` — hard-delete a blueprint you own (already-forked plans are unaffected)
+
 ### Utility
 - `get_started` — dynamic reference for new agents
 
@@ -307,12 +317,10 @@ npx agent-planner-mcp
 For remote access (ChatGPT, cloud deployments, multi-agent systems):
 ```bash
 MCP_TRANSPORT=http npx agent-planner-mcp
-# Listens on http://127.0.0.1:3100
+# Listens on http://127.0.0.1:3100 (override with PORT)
 ```
 
-Production endpoint: `https://agentplanner.io/mcp`
-
-See [HTTP_MODE.md](./HTTP_MODE.md) for details.
+Transport is Streamable HTTP (MCP 2025-03-26); auth via `Authorization: ApiKey <your-token>`. Production endpoint: `https://agentplanner.io/mcp` (discovery at `https://agentplanner.io/.well-known/mcp.json`).
 
 ## Local Development
 
@@ -341,5 +349,4 @@ MIT License - see [LICENSE](./LICENSE) for details.
 ## Support
 
 - [GitHub Issues](https://github.com/TAgents/agent-planner-mcp/issues)
-- [CHANGELOG.md](./CHANGELOG.md) for version history
-- [PDR.md](./PDR.md) for technical design
+- [GitHub Releases](https://github.com/TAgents/agent-planner-mcp/releases) for version history and release notes

package/SKILL.md

@@ -173,15 +173,16 @@ v1.0 closes the creation gap. There are three distinct flows depending on who in
 
 ### Scenario A: Human directs you in conversation
 
-User says "create a plan to ship the new auth flow under the security goal" or "mark the BSL launch plan completed."
+User says "create a plan to ship the new auth flow under the security goal."
 
-Default to **`status='active'`** — the human asked for it, just do it.
+Pass **`status='active'` explicitly** — the human asked for it, just do it. (The default is `draft`: omitting status creates a proposal that waits for human activation.)
 
 ```
 form_intention({
   goal_id: '<security-goal-id>',
   title: 'Ship new auth flow',
   rationale: 'User-requested plan to migrate auth to passkeys',
+  status: 'active', // human-directed — omit for autonomous proposals (draft)
   tree: [
     { node_type: 'phase', title: 'Discovery', children: [
       { ref: 'research', title: 'Research passkey libraries', task_mode: 'research' },
@@ -196,10 +197,9 @@ form_intention({
 // return created_without_dependencies + a warning instead.
 ```
 
-```
-update_plan({ plan_id: '<bsl-plan>', status: 'completed' })
-// Done. No queue, no UI trip.
-```
+Completion is not a write: a plan reads as `completed` automatically once its
+work hits 100% (`update_plan({status: 'completed'})` is rejected). To close out
+a plan that won't be finished, archive it: `update_plan({ plan_id, status: 'archived' })`.
 
 ### Scenario B: You're acting autonomously (scheduled loop, etc.)
 
@@ -215,7 +215,10 @@ derive_subgoal({
   status: 'draft',
 })
 // Surfaces in dashboard pending. Human approves via update_goal({status: 'active'})
-// or in the UI. Plans auto-promote to active when first task moves to in_progress.
+// or in the UI. Draft plans reject task execution and claims (409) until activated.
+// If the human later directs you to proceed, activate it yourself:
+// update_plan({status: 'active'}) — the gate makes activation explicit, not human-only.
+// Completion is derived — a plan reads as completed when its work hits 100%.
 ```
 
 ### Scenario C: You're uncertain and want explicit input
@@ -337,6 +340,26 @@ recall_knowledge({
 - **v0.8.x → v0.9.0** — clean break. 63 legacy CRUD tools collapsed into 15 BDI-aligned tools. See [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping.
 - **v0.9.x → v1.0.0** — additive. v0.9 read/update tools unchanged. Adds the full mutation surface (creation, structural edits, sharing, collaboration) so humans can steer entirely through agent conversation. The previously planned `ap_admin_*` namespace is no longer needed — those operations are now first-class BDI tools, with the draft-status seam keeping autonomous agent creation reviewable. See [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
+## UI vocabulary → data model → tools
+
+The web UI (agentplanner.io) and these tools are the same system in two languages. When a human refers to something they see on a screen, map it here:
+
+| UI term | What it is | Tools |
+|---|---|---|
+| **Workspace** | Org-scoped folder that owns goals + plans | `list_workspaces`, `create_workspace` |
+| **Blueprint** | Dehydrated, reusable plan shape; forks into a workspace | `list_blueprints`, `save_as_blueprint`, `fork_blueprint`, `delete_blueprint` |
+| **Mission / Mission Control** | Home overview: goal health, decision queue, activity | `briefing` |
+| **Goal** (a *Desire*) | What you're pursuing | `create_goal`, `derive_subgoal`, `list_goals`, `goal_state`, `update_goal` |
+| **Plan** (an *Intention*) | Committed plan of action that achieves a goal | `form_intention` (create), `extend_intention` (add nodes), `update_plan`, `update_node`, `move_node` |
+| **Knowledge / episode** (a *Belief*) | Facts the agents have learned | `add_learning`, `recall_knowledge` |
+| **Health** | Per-goal `on_track` / `at_risk` / `stale` | `briefing`, `list_goals`, `goal_state` |
+| **Tension / Contradiction** | A coherence conflict — new knowledge contradicts existing facts or tasks (UI "Tensions" card) | `plan_analysis` (coherence), `recall_knowledge` (current vs superseded facts) |
+| **Decision queue / "Awaiting you"** | Human approvals pending | `queue_decision`, `resolve_decision` |
+| **Committed vs Proposed** | A goal is *committed* once promoted (`promoted_at` set), *proposed* before | `update_goal({ committed })` |
+| **Attainment vs Execution** | *Attainment* = success criteria met; *Execution* = tasks completed. Distinct numbers. | `record_criterion_progress` (attainment), `update_task` (execution) |
+| **Critical path / Bottlenecks** | Longest blocking chain / high-fan-out incomplete tasks | `plan_analysis` |
+| **RPI chain** | Research → Plan → Implement decomposition | `propose_research_chain` |
+
 ## Principles
 
 - Tools are intent-shaped, not CRUD-shaped — name what you want to accomplish, not which row to mutate

package/package.json

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

package/src/index.js

@@ -3,6 +3,7 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { MCPHTTPServer } = require('./server-http');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { version } = require('../package.json');
 require('dotenv').config();
 
@@ -77,7 +78,10 @@ async function main() {
       }, {
         capabilities: {
           tools: {}
-        }
+        },
+        // Shown to the model on connect — the no-skill safety net mapping plain
+        // intents to the BDI tool names + pointing at get_started.
+        instructions: SERVER_INSTRUCTIONS
       });
 
       console.error('MCP Server created');

package/src/server-http.js

@@ -15,6 +15,7 @@
 const express = require('express');
 const { SessionManager } = require('./session-manager');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { createApiClient } = require('./api-client');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { createOAuthMetadata, mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } = require('@modelcontextprotocol/sdk/server/auth/router.js');
@@ -522,7 +523,9 @@ class MCPHTTPServer {
     }, {
       capabilities: {
         tools: {}
-      }
+      },
+      // Shown to the model on connect — the no-skill safety net (see index.js).
+      instructions: SERVER_INSTRUCTIONS
     });
 
     // Get per-session API client (bound to user's token), or create one for initialize requests

package/src/server-instructions.js

@@ -0,0 +1,26 @@
+/**
+ * Server-level MCP instructions — surfaced to the model the moment the server
+ * connects, independent of any externally-loaded skill. This is the safety net
+ * for agents that do NOT have the AgentPlanner SKILL.md: it maps plain intents
+ * to the BDI tool names (which were renamed at v0.9, e.g. "create a plan" is
+ * `form_intention`, not `create_plan`) and points to `get_started` for the rest.
+ *
+ * Keep this short — it's read on every connect. Deeper guidance lives in
+ * `get_started` (auto-derived from the live tool set, so it can't drift).
+ */
+const SERVER_INSTRUCTIONS = [
+  'AgentPlanner uses an intent-shaped, BDI-aligned tool vocabulary (renamed at v0.9 — there is no create_plan/quick_plan/create_node/quick_status).',
+  'New here or unsure which tool? Call `get_started` first — it returns the full tool map and recommended workflows.',
+  '',
+  'Common intents → tool:',
+  '- Create a goal → `create_goal` (a sub-goal → `derive_subgoal`)',
+  '- Create a plan with its task tree → `form_intention` (add tasks later → `extend_intention`; an R→P→I chain → `propose_research_chain`)',
+  '- Find and claim the next task → `claim_next_task`',
+  '- Update status / log progress / finish a task → `update_task` (folds the old quick_status + quick_log + add_log + release)',
+  '- Read a goal (details, progress, quality, bottlenecks) → `goal_state`; all goals’ health → `briefing` / `list_goals`',
+  '- Read a task in context → `task_context`; analyze a plan (critical path, bottlenecks, impact, coherence) → `plan_analysis`',
+  '- Record / recall knowledge → `add_learning` / `recall_knowledge`',
+  '- Queue a human decision → `queue_decision`; resolve one → `resolve_decision`',
+].join('\n');
+
+module.exports = { SERVER_INSTRUCTIONS };

package/src/tools/bdi/beliefs.js

@@ -617,7 +617,8 @@ const planAnalysisDefinition = {
   name: 'plan_analysis',
   description:
     "Advanced plan reads: impact analysis (delay/block/remove), critical path, " +
-    "bottleneck list, or coherence check.",
+    "bottleneck list, or coherence check. Replaces the legacy analyze_impact / " +
+    "get_critical_path / run_coherence_check / check_coherence_pending tools.",
   inputSchema: {
     type: 'object',
     properties: {

package/src/tools/bdi/intentions.js

@@ -791,14 +791,23 @@ const formIntentionDefinition = {
   name: 'form_intention',
   description:
     "Create a plan that achieves a goal, including an initial phase/task " +
-    "tree, in one call. Declare execution order inline: give nodes a `ref` and " +
+    "tree, in one call. This is the canonical way to CREATE A PLAN (replaces the " +
+    "legacy quick_plan / create_plan / import_plan_markdown; inline nodes replace " +
+    "create_node / quick_task; depends_on replaces create_dependency). " +
+    "Declare execution order inline: give nodes a `ref` and " +
     "list prerequisite refs/titles in `depends_on` to create 'blocks' edges in " +
     "the same call — don't ship a bare hierarchy. The response returns a " +
     "`structure` summary and warns (`created_without_dependencies`) when a " +
-    "multi-task plan has no edges. Defaults to status='active' for " +
-    "human-directed creation; pass status='draft' for autonomous loops so a " +
-    "human can review before promotion. Drafts surface in the dashboard " +
-    "pending queue and auto-promote to active when work begins on any node.",
+    "multi-task plan has no edges. Defaults to status='draft': a draft is a " +
+    "proposal — it surfaces in the human's pending queue, and task execution " +
+    "and claims are rejected (409) until the plan is activated. Pass " +
+    "status='active' when a human directed this plan in conversation and " +
+    "wants work to start immediately; you may also activate a draft later " +
+    "via update_plan(status='active') on the same basis. Acting " +
+    "autonomously with no human direction? Leave it draft and " +
+    "queue_decision to request activation. Plan completion is derived from " +
+    "task completion — plans read as 'completed' automatically at 100%; it " +
+    "cannot be set directly.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -809,7 +818,7 @@ const formIntentionDefinition = {
       status: {
         type: 'string',
         enum: ['draft', 'active'],
-        default: 'active',
+        default: 'draft',
       },
       visibility: {
         type: 'string',
@@ -885,7 +894,7 @@ async function createSubtree(apiClient, planId, parentId, children, results, ctx
 }
 
 async function formIntentionHandler(args, apiClient) {
-  const { goal_id, title, description, rationale, status = 'active', visibility = 'private', tree = [] } = args;
+  const { goal_id, title, description, rationale, status = 'draft', visibility = 'private', tree = [] } = args;
 
   if (apiClient.agentLoop?.createIntention) {
     const treeError = validateTreeShape(tree);
@@ -961,19 +970,22 @@ async function formIntentionHandler(args, apiClient) {
     }
   }
 
-  // 3. Link plan to goal (best-effort).
+  // 3. Create tree (top-level children parent to root via omitted parent_id).
+  const nodeResults = [];
+  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
+  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
+
+  // 4. Link plan to goal (best-effort) — AFTER the tree exists. The link
+  // endpoint cascades 'achieves' edges to all CURRENT task nodes, so linking
+  // before node creation wired zero achievers (goal_state then showed empty
+  // linked_tasks and fell back to coarse linked-plan stats). Order matters.
   try {
     await apiClient.goals.linkPlan(goal_id, plan.id);
   } catch (err) {
     // Non-fatal — plan exists, link can be retried by user.
   }
 
-  // 3. Create tree (top-level children parent to root via omitted parent_id).
-  const nodeResults = [];
-  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
-  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
-
-  // 4. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
+  // 5. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
   const resolveRef = (ref) => {
     if (ctx.refMap.has(ref)) return ctx.refMap.get(ref);
     const byTitle = ctx.titleMap.get(ref);
@@ -1049,7 +1061,7 @@ const extendIntentionDefinition = {
     "Add children under an existing phase or task. Use when an agent has " +
     "implicit authority to decompose work (e.g., a parent task they have " +
     "claimed). For high-stakes structural proposals, use queue_decision " +
-    "with proposed_subtasks instead. Defaults to status='active'.",
+    "with proposed_subtasks instead.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -1120,7 +1132,7 @@ const proposeResearchChainDefinition = {
     "Create a Research → Plan → Implement triple under an existing parent " +
     "task or phase. The Research task feeds Plan; Plan feeds Implement " +
     "(via 'blocks' dependency edges). Use when tackling work with " +
-    "significant unknowns. Defaults to status='active'.",
+    "significant unknowns.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -1363,7 +1375,11 @@ const updatePlanDefinition = {
       description: { type: 'string' },
       status: {
         type: 'string',
-        enum: ['draft', 'active', 'completed', 'archived'],
+        enum: ['draft', 'active', 'archived'],
+        description:
+          "Commitment lifecycle. 'completed' cannot be set — it is derived " +
+          "automatically when the plan's work reaches 100%. To close out a " +
+          "plan early, archive it.",
       },
       visibility: { type: 'string', enum: ['private', 'unlisted', 'public'] },
       metadata: { type: 'object', description: "Shallow-merged into existing metadata." },

package/src/tools/bdi/utility.js

@@ -8,9 +8,11 @@ const { version: MCP_VERSION } = require('../../../package.json');
 const getStartedDefinition = {
   name: 'get_started',
   description:
-    "Onboarding for new agents. Returns the BDI tool surface map and recommended " +
-    "workflows: mission control loop (Cowork), single-task session (Code/CLI), " +
-    "multi-agent claiming (OpenClaw).",
+    "Call this FIRST when you are new to AgentPlanner or unsure which tool to use " +
+    "(e.g. looking for create_plan / quick_plan — the answer is form_intention). " +
+    "Returns the live BDI tool-surface map and recommended workflows: mission " +
+    "control loop (Cowork), single-task session (Code/CLI), multi-agent claiming " +
+    "(OpenClaw). The map is derived from the actual tool set, so it can't drift.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -29,6 +31,17 @@ async function getStartedHandler(args, apiClient) {
     api = { version: 'unavailable' };
   }
 
+  // Derived from the actual module definitions so this map can't drift from the
+  // real tool set (it silently did — delete_blueprint and record_criterion_progress
+  // were both missing at points). Lazy require avoids any load-order cycle.
+  const namesOf = (mod) => (mod.definitions || []).map((d) => d.name);
+  const toolsByNamespace = {
+    beliefs: namesOf(require('./beliefs')),
+    desires: namesOf(require('./desires')),
+    intentions: namesOf(require('./intentions')),
+    workspaces: namesOf(require('./workspaces')),
+  };
+
   return formatResponse({
     as_of: asOf(),
     mcp_version: MCP_VERSION,
@@ -39,12 +52,7 @@ async function getStartedHandler(args, apiClient) {
       "AgentPlanner exposes a BDI-aligned MCP surface. Tools are grouped by " +
       "Beliefs (state queries), Desires (goals), and Intentions (committed actions). " +
       "Each tool answers one whole agentic question and returns an `as_of` timestamp.",
-    tools_by_namespace: {
-      beliefs: ['briefing', 'list_plans', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
-      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal', 'record_criterion_progress'],
-      intentions: ['form_intention', 'extend_intention', 'link_intentions', 'propose_research_chain', 'claim_next_task', 'update_task', 'update_node', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
-      workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint', 'delete_blueprint'],
-    },
+    tools_by_namespace: toolsByNamespace,
     recommended_workflows: [
       {
         name: 'Set up new work a human asked for',