agent-planner-mcp 1.5.19 → 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.5.19",
+  "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/tools/bdi/intentions.js

@@ -798,10 +798,16 @@ const formIntentionDefinition = {
     "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: {
@@ -812,7 +818,7 @@ const formIntentionDefinition = {
       status: {
         type: 'string',
         enum: ['draft', 'active'],
-        default: 'active',
+        default: 'draft',
       },
       visibility: {
         type: 'string',
@@ -888,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);
@@ -1055,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: {
@@ -1126,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: {
@@ -1369,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." },