@orderful/droid 0.50.0 → 0.52.0

package/src/tools/propose-plan/skills/propose-plan/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: propose-plan
+description: "Produce a structured plan with evidence and actions for human approval. Use when an agent must propose write operations, research current state before making changes, or produce actions that require human-in-the-loop review before execution."
+globs: []
+alwaysApply: false
+allowed-tools: []
+---
+
+# Propose Plan
+
+Structure your findings into a plan for human approval. Use this skill when you've researched the current state, understand what needs to happen, and are ready to propose the specific actions to take.
+
+This skill teaches you how to package what you've learned into structured evidence and discrete actions that a reviewer can approve, modify, or reject before anything is executed.
+
+Never call write tools directly. Each proposed write is described as an **action** in your plan output. Approved actions are executed separately after human review.
+
+## Plan Structure
+
+A plan has two parts:
+
+1. **Evidence** — your analysis of the gathered context: what it shows, why changes are needed, and what will happen if the plan is approved
+2. **Actions** — an ordered list of discrete operations to execute, each mapped to a specific tool call
+
+The human reviewer sees your evidence first (the reasoning and impact), then reviews each action. Clear evidence builds trust; vague evidence gets rejected.
+
+## Output Format
+
+Produce a single JSON object matching the schema in `references/output-schema.json`. The shape:
+
+```json
+{
+  "name": "string — short human-readable plan name (optional)",
+  "category": "string — grouping category, e.g. org-provisioning (optional)",
+  "evidence": {
+    "reasoning": "string — your analysis of what needs to happen and why",
+    "sourceSummary": "string — concise summary of what you found during research",
+    "sourceRaw": "object — raw source data from research (optional)",
+    "impactSummary": "string — what will change if this plan is approved",
+    "caveats": ["string — anything uncertain, auto-generated, or requiring follow-up"]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": {
+        "tool": "string — the tool name exactly as you see it in your available tools"
+      },
+      "description": "string — human-readable description of what this action does",
+      "payload": "object — arguments to pass to the tool"
+    }
+  ]
+}
+```
+
+### Evidence Fields
+
+| Field           | Purpose                                                                                                 | Reviewer Experience                                          |
+| --------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `reasoning`     | Your analysis — what needs to happen and why. Cite actual data from your research, not assumptions.     | First thing they read. Establishes trust.                    |
+| `sourceSummary` | Concise summary of what you found. Include entity names, IDs, and states.                               | Quick scan to verify you looked at the right things.         |
+| `sourceRaw`     | Optional. Raw API responses or data snapshots as a JSON object.                                         | Expandable detail for reviewers who want to verify.          |
+| `impactSummary` | What changes if the plan is approved. Be specific — "creates org X with ISA ID Y" not "creates an org". | The core decision point. Reviewer approves based on this.    |
+| `caveats`       | Optional. Flag anything uncertain, auto-generated, or needing manual follow-up.                         | Prevents surprises. Reviewers appreciate honesty about gaps. |
+
+### Action Fields
+
+| Field         | Purpose                                                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | Action category. Use `mcp_call` for MCP tool invocations.                                                                                   |
+| `config`      | Identifies which tool to call. For `mcp_call`: `{ "tool": "create_org" }`. Use the tool name exactly as it appears in your available tools. |
+| `description` | Human-readable summary. The reviewer sees this before expanding the payload. Write it for someone who won't read the raw payload.                |
+| `payload`     | Raw arguments passed directly to the tool. No wrapping or nesting — exactly what the tool expects.                                               |
+
+## Building Evidence From What You Know
+
+By the time you're writing a plan, you've already done the research — queried tools, read documents, collected the data you need. Your job now is to analyse what you found and structure it into a plan.
+
+If read tools are still available, use them to **verify and fill gaps** — check for conflicts, confirm preconditions, resolve ambiguities. But the research phase is behind you. Focus on structuring what you know into clear evidence and precise actions.
+
+When writing evidence:
+
+1. **Cite the gathered data** — reference specific entities, IDs, and values. A reviewer can't verify "the account exists" but they can verify "Salesforce account SF-001234 (Acme Corp) has no OrgID".
+2. **Flag conflicts** — if the gathered data reveals duplicates, collisions, or unexpected state, surface that prominently.
+3. **Note gaps** — if data is missing or ambiguous, say so in caveats rather than guessing. A plan with honest gaps is more useful than one with invented data.
+
+## Writing Actions
+
+Each action represents one tool call. `config.tool` identifies which tool to call, and `payload` carries the arguments — both must be precise.
+
+**Order matters.** List actions in dependency order — if action B depends on the result of action A, action A comes first. The execution step processes them sequentially.
+
+**One action per tool call.** Don't batch multiple operations into a single action. If provisioning requires creating an org, then creating a billing customer, those are two separate actions.
+
+**Only propose tools from your available list.** You've been given a set of write tools you can propose actions for. If a required operation isn't in that list, note it as a caveat — don't invent actions for tools that don't exist.
+
+**Payloads must be complete.** Include every required field the tool expects. Don't leave placeholders or TODOs in payloads. For values that don't exist yet because they come from a prior action, use a template reference (see below). If you can't determine a value at all, flag it in caveats and omit the action.
+
+### Action Dependencies (Template References)
+
+When an action needs a value produced by a prior action — like an org ID that doesn't exist until the org is created — use a Handlebars template reference in the payload value.
+
+**Syntax:** `{{ actions.N.result.path }}` where `N` is the zero-based action index and `path` navigates the result object.
+
+At execution time, the system resolves these references using the actual results from completed actions. The human reviewer sees the template expression and understands the data flow — they're approving the intent ("use the org ID from step 1"), not the literal runtime value.
+
+**Rules:**
+
+- Only reference actions that come _before_ the current action (lower index)
+- Use dot-path navigation to reach nested values: `{{ actions.0.result.org.id }}`
+- Static values and template references can coexist in the same payload
+- Every other payload field should still use concrete values you already know
+
+**Example:**
+
+```json
+{
+  "type": "mcp_call",
+  "config": { "tool": "create_billing_customer" },
+  "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+  "payload": {
+    "orgId": "{{ actions.0.result.id }}",
+    "orgName": "Acme Corp",
+    "contactEmail": "jane@acme.com"
+  }
+}
+```
+
+Here `orgId` will be resolved at runtime from the result of action 0 (e.g., `create_org`). The reviewer sees that billing depends on the org creation step.
+
+## Example
+
+Say you've been asked to provision an Orderful org for a new customer. You've queried Salesforce, searched for existing orgs, and gathered the relevant data. Your plan output might look like:
+
+```json
+{
+  "evidence": {
+    "reasoning": "Salesforce account Acme Corp (SF-001234) was signed on 2026-03-01 and has no Orderful OrgID. No existing Orderful org matches by name or ISA ID. The account's primary contact is jane@acme.com. ISA ID derived from Customer_ISA_ID__c field: ACME001.",
+    "sourceSummary": "Salesforce: Acme Corp (SF-001234), signed 2026-03-01, no OrgID. Orderful: no org named 'Acme Corp', no ISA ID 'ACME001' in use.",
+    "sourceRaw": {
+      "salesforce_account": { "Id": "SF-001234", "Name": "Acme Corp", "OrgID__c": null, "Customer_ISA_ID__c": "ACME001" },
+      "orderful_org_search": { "results": [] }
+    },
+    "impactSummary": "Creates Orderful org 'Acme Corp' with ISA ID 'ACME001', creates billing customer in ChargeBee, and sends welcome email to jane@acme.com.",
+    "caveats": ["ARR not found in Salesforce — billing customer will be created without revenue data. Manual update may be needed."]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_org" },
+      "description": "Create Orderful org 'Acme Corp' with ISA ID 'ACME001'",
+      "payload": {
+        "name": "Acme Corp",
+        "isaId": "ACME001",
+        "contactEmail": "jane@acme.com"
+      }
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_billing_customer" },
+      "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+      "payload": {
+        "orgId": "{{ actions.0.result.id }}",
+        "orgName": "Acme Corp",
+        "contactEmail": "jane@acme.com"
+      }
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "invite_user" },
+      "description": "Send welcome email to jane@acme.com for Acme Corp org",
+      "payload": {
+        "email": "jane@acme.com",
+        "orgId": "{{ actions.0.result.id }}"
+      }
+    }
+  ]
+}
+```
+
+## What Not To Do
+
+These are hard rules. Violating any of them will cause the plan to be rejected or produce incorrect results.
+
+- **Don't call write tools directly.** Your job is to propose, not execute. Every write operation must be described as an action in your plan output. If you call a write tool yourself, the approval flow is bypassed and there is no audit trail.
+- **Don't include read operations as actions.** Actions are for writes only — things that change state and need human approval. Reading data is research, not an action. If you need to look something up, use read tools directly during your research phase.
+- **Don't fabricate data.** If a value wasn't in your research and you can't verify it with read tools, say so in caveats. Never guess IDs, names, emails, or configuration values. A plan with honest gaps gets sent back for more research. A plan with invented data gets approved and breaks things.
+- **Don't produce actions for tools outside your available list.** You can only propose actions for tools you've been given. If an operation requires a tool you don't have, note it as a caveat — don't invent an action for it. The execution step will reject unknown tools.
+- **Don't skip evidence.** A plan without evidence will be rejected. The reviewer needs to see what you found, what it means, and what will change. Evidence is not optional filler — it is how the reviewer decides whether to approve.
+- **Don't combine multiple operations into one action.** Each action is one tool call. "Create org and set up billing" is two actions, not one. The execution step calls each action individually — a combined action will fail.
+- **Don't hardcode values from actions that haven't run yet.** If action 2 needs the org ID from action 1, don't guess or invent a value — use a template reference: `"orgId": "{{ actions.0.result.id }}"`. The execution step resolves these at runtime. Never put a placeholder like `"TBD"` or `"<org-id>"` in a payload.
+- **Don't use vague descriptions.** "Create org" tells the reviewer nothing. "Create Orderful org 'Acme Corp' with ISA ID 'ACME001'" tells them exactly what will happen. The description is what the reviewer reads before deciding whether to expand the payload.

package/src/tools/propose-plan/skills/propose-plan/references/output-schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PlanOutput",
+  "description": "Structured plan output produced by an LLM agent for human review and approval",
+  "type": "object",
+  "required": ["evidence", "actions"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Short human-readable name for the plan"
+    },
+    "category": {
+      "type": "string",
+      "description": "Grouping category for the plan (e.g. org-provisioning)"
+    },
+    "evidence": {
+      "type": "object",
+      "description": "Research findings and rationale supporting the plan",
+      "required": ["reasoning", "sourceSummary", "impactSummary"],
+      "properties": {
+        "reasoning": {
+          "type": "string",
+          "description": "Analysis of what needs to happen and why"
+        },
+        "sourceSummary": {
+          "type": "string",
+          "description": "Concise summary of research findings with entity names and IDs"
+        },
+        "sourceRaw": {
+          "type": "object",
+          "description": "Raw source data from research",
+          "additionalProperties": true
+        },
+        "impactSummary": {
+          "type": "string",
+          "description": "What changes if the plan is approved"
+        },
+        "caveats": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Risks or caveats to flag for review"
+        }
+      },
+      "additionalProperties": false
+    },
+    "actions": {
+      "type": "array",
+      "description": "Ordered list of MCP tool calls to execute",
+      "items": {
+        "type": "object",
+        "required": ["type", "config", "description", "payload"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "mcp_call",
+            "description": "Action category — v0 only supports mcp_call"
+          },
+          "config": {
+            "type": "object",
+            "description": "Configuration specifying which MCP tool to invoke",
+            "required": ["tool"],
+            "properties": {
+              "tool": {
+                "type": "string",
+                "description": "Tool name as it appears in the available tools"
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of what this action does"
+          },
+          "payload": {
+            "type": "object",
+            "description": "Arguments to pass to the MCP tool",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}