@n8n/instance-ai 1.10.1 → 1.11.0

package/skills/planned-task-runtime/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: planned-task-runtime
+description: >-
+  Handles system follow-up turns: planned-task-follow-up (synthesize, replan,
+  build-workflow, checkpoint), background-task-completed, running-tasks context,
+  create-tasks silence rules, and detached delegate completion. Load whenever
+  any of these tags appear or after spawning   create-tasks or delegate.
+recommended_tools:
+  - create-tasks
+  - complete-checkpoint
+  - build-workflow
+  - delegate
+  - task-control
+  - workflows
+  - verify-built-workflow
+  - executions
+---
+
+# Planned Task Runtime
+
+Load this skill when the current message contains `<planned-task-follow-up>`,
+`<background-task-completed>`, `<running-tasks>`, or immediately after calling
+`create-tasks` or `delegate`.
+
+## Silence after spawning tasks
+
+**After calling detached or scheduled task tools** (`delegate` or
+`create-tasks`): do not write any text. The task card or approval card shows the
+user what's being built or done; restating it is redundant. Do NOT summarize the
+plan, list credentials, describe what the agent will do, or add status details.
+Progress is already visible to the user in real time.
+
+When `create-tasks` returns after approval, tasks are already running. Do not
+summarize or add status text — the user already approved the plan and the
+checklist shows progress. Wait for `<planned-task-follow-up>` to arrive; do not
+invent synthetic follow-up turns.
+
+## Never poll
+
+**Never poll and never sleep.** Background tasks (`delegate`) settle via
+`<planned-task-follow-up>` turns that arrive automatically when work finishes.
+After you spawn or acknowledge one, end your turn. Do not call
+`workflows(action="list")`, `executions(action="list")`, or any shell command
+to check progress — you will receive a follow-up turn the moment the task settles.
+If a task appears stuck, tell the user and stop; do not try to detect completion
+yourself. Do not re-dispatch a build whose task ID is already visible in
+`<running-tasks>`.
+
+When `<running-tasks>` context is present, use it only to reference active task
+IDs for cancellation or corrections.
+
+Always pass `conversationContext` when spawning background agents (`delegate`) —
+summarize what was discussed, decisions made, and information gathered.
+
+If the user sends a correction while a build is running, call
+`task-control(action="correct-task")` with the task ID and correction.
+
+## Synthesize follow-up
+
+When `<planned-task-follow-up type="synthesize">` is present, all planned tasks
+completed successfully and any unsettled runtime verification obligations have
+already been handled. Before the final message, inspect workflow task outcomes:
+if a workflow still has `verificationReadiness.status === "needs_setup"`, call
+`workflows(action="setup")` for that workflowId; if it has
+`verificationReadiness.status === "not_verifiable"`, include the readiness
+guidance as a clear warning/manual-test note and do not call it verified. Treat
+verified workflow drafts as finished deliverables — they are ready to use. If the
+original user request explicitly asked to run or execute the workflow after
+building it, call `executions(action="run")` once for the built workflow;
+checkpoint verification does not satisfy a user-requested run. Otherwise write a
+concise completion message that names each delivered artifact (data tables,
+workflows) and summarizes what it does, using the user's time zone for any
+scheduled timings. Do not hedge with phrases like "ready to go live" or "let me
+know when you're ready" — the work is done. If any workflow is unpublished,
+state that plainly as a one-line next-step note ("Publish when you want it live —
+you can do that from the workflow editor."), not as a gating condition. Do not
+create another plan.
+
+## Replan follow-up
+
+When `<planned-task-follow-up type="replan">` is present, a planned task failed
+and the graph is in `awaiting_replan`. You MUST take action in this same turn —
+handle a single simple task directly (matching tool: `build-workflow`,
+`data-tables`, `delegate`, etc.), call `create-tasks` with
+`planningContext.source: "replan"` for multiple dependent tasks, or explain the
+blocker to the user if nothing sensible remains. Do NOT reply with an
+acknowledgement or status update alone — the scheduler will not fire another
+follow-up until you act, and the thread will silently stall.
+
+Replan routing (do not re-plan from scratch):
+
+- One simple task remains (single data-table op, credential setup, single-workflow
+  patch) → handle directly with the matching tool.
+- Multiple dependent tasks still need scheduling → `create-tasks` with
+  `planningContext.source: "replan"`.
+- Nothing sensible remains → explain the blocker to the user.
+
+## Build-workflow follow-up
+
+When `<planned-task-follow-up type="build-workflow">` is present, load the
+`workflow-builder` skill and build exactly the `buildTask` in the payload. If
+`buildTask.workflowId` is present, update that workflow; otherwise create a new
+one. If `buildTask.isSupportingWorkflow === true`, pass `isSupportingWorkflow:
+true` to `build-workflow`; that saved supporting workflow is the task's final
+deliverable. Save with `build-workflow` and stop after a successful save — do not
+verify, set up credentials, publish, call `complete-checkpoint`, create a new
+plan, or write a user-facing message. If `build-workflow` returns fixable
+validation errors, patch in the same turn and save again. If the build is
+blocked, explain the blocker briefly; the planned task finalizer will mark the
+task failed.
+
+## Checkpoint follow-up
+
+When `<planned-task-follow-up type="checkpoint">` is present, the block contains
+exactly one checkpoint task (`checkpoint.id`, `checkpoint.title`,
+`checkpoint.instructions`, and `checkpoint.dependsOn` — the outcomes of prior
+tasks, including workflow build outcomes with their `outcome.workItemId` /
+`outcome.workflowId`). **Always require structured verification evidence —
+never trust builder prose.** Before completing the checkpoint, inspect each
+dependent persisted workflow with `workflows(action="get-json", workflowId)` and
+compare the actual graph to the build task and checkpoint goal. Build/save
+success is not proof of workflow quality. If the saved workflow is only a draft,
+lacks the requested outcome, or verification evidence is weak, patch the same
+workflow in this checkpoint turn and re-read/re-verify it. If a dependency outcome
+contains successful `outcome.verification` tool evidence (`attempted: true`,
+`success: true`, an `executionId`, and executed-node evidence) and your
+persisted-workflow inspection agrees the requested outcome is present, use that
+evidence without re-running verification. Otherwise execute
+`checkpoint.instructions` using your tools — typically `verify-built-workflow`
+with the work item ID from the build outcome, or `executions(action="run")` for a
+built workflow with real credentials and a testable trigger. If verification
+succeeds and any verified workflow dependency outcome has
+`outcome.setupRequirement.status === "required"`, call
+`workflows(action="setup")` with that workflowId before `complete-checkpoint`;
+the inline setup card appears automatically in the AI Assistant panel, so do not
+tell the user to open the editor, use the canvas, or click a Setup button. If
+setup returns `deferred: true`, respect it and still complete the checkpoint
+with a result that says setup was deferred. Do not call
+`credentials(action="setup")` or `apply-workflow-credentials` for workflow
+setup. Then call `complete-checkpoint(taskId, status, result)` **exactly once**
+to report the outcome (`status: "succeeded"` on pass, `"failed"` on a verification
+failure). Do not create a new plan, do not write a user-facing message — the
+checkpoint card in the plan checklist is the user-visible surface. End your turn
+as soon as `complete-checkpoint` returns.
+
+**If your verification surfaced a bug you can patch in place** (e.g., a Code-node
+shape issue), load the `workflow-builder` skill and call `build-workflow`
+directly during this checkpoint turn, passing the existing `workflowId` and the
+dependency `workItemId`. Then re-verify in the same checkpoint turn. Keep the
+patch count small: if the issue cannot be narrowed within two rounds, call
+`complete-checkpoint(status="failed", error=...)` with a summary of what remains
+and let replan take over.
+
+## Background task completed
+
+When `<background-task-completed>` is present, a detached background task
+finished. The `result` field holds the sub-agent's authoritative summary of what
+was actually done. **When you write the user-facing recap, take factual details —
+model IDs, node names, resource IDs, parameter values — directly from this
+`result` text.** Do not substitute values from conversation history or training
+priors: if the `result` says `gpt-5.4-mini`, write `gpt-5.4-mini`, not "GPT-4o
+mini" or any other name you associate with the provider. The task spec describes
+intent; the `result` describes what actually happened.

package/skills/planning/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: planning
+description: >-
+  ONLY for coordinated multi-artifact work: multiple workflows with dependencies,
+  shared data-table schema/migration across tasks, or the user explicitly asked
+  to review a plan first. Do NOT use for new one-off workflows, single-workflow
+  edits, verification-only requests, or standalone data-table ops — use
+  workflow-builder or data-table-manager instead.
+recommended_tools:
+  - create-tasks
+  - workflows
+  - nodes
+  - credentials
+  - data-tables
+  - parse-file
+  - research
+  - ask-user
+---
+
+# Planning
+
+Use this skill to design a dependency-aware task graph in the orchestrator and
+submit it with `create-tasks`. Do not spawn another agent, do not delegate the
+planning step, and do not use incremental plan item tools.
+
+## When NOT to use this skill
+
+Stop and use `workflow-builder` + `build-workflow` instead when the request is:
+
+- A new or one-off single workflow, even if it sounds large or unfamiliar
+- An edit to one existing workflow (nodes, expressions, credentials, schedule, Code)
+- Verification, setup, or credential collection for a workflow you just built
+- A workflow-local data table whose schema ships with that same workflow
+- Standalone data-table list/schema/query/create/mutation work
+
+Do not call `create-tasks` just to get approval, verification, or a checklist for
+a single workflow. Workflow verification is automatic from structured build
+outcomes after `build-workflow`.
+
+## When to use this skill
+
+Planning is only for work that needs coordination: multiple workflows,
+dependencies between workflows, shared data-table schema or migration work across
+tasks, multiple durable artifacts, broad best-practice research across many
+sources, genuinely ambiguous business-process architecture that cannot be
+resolved with one `build-workflow` call, or an explicit user request to review a
+plan first.
+
+If shared data tables are involved, load `data-table-manager` before this skill
+and carry the relevant table guidance into workflow task specs. Clear
+single-workflow builds and existing-workflow edits use `workflow-builder` with
+`build-workflow` directly. Standalone data-table work uses `data-table-manager`
+with direct `data-tables` and `parse-file` calls.
+
+## Method
+
+1. Decide whether the request is plan-worthy by coordination need, not by
+   whether a workflow is new.
+2. Discover what materially affects the plan with normal tools:
+   `nodes(action="suggested")`, `credentials(action="list")`,
+   `data-tables(action="list")`, `parse-file`, `workflows`, and `research`
+   when relevant.
+3. Prefer reasonable assumptions over questions. Ask the user only when the
+   answer would materially change the plan and cannot be discovered.
+4. Build a dependency-aware graph. Producers must come before consumers.
+   Independent tasks should not depend on each other.
+5. Put single workflow-local table requirements inside that workflow task spec.
+   Do not create separate data-table tasks unless the table work is a durable
+   artifact shared across tasks.
+6. Add checkpoint tasks only for exceptional semantic checks that normal
+   workflow verification cannot cover.
+7. Call `create-tasks` with `planningContext.source: "planning-skill"`,
+   a concise `summary`, optional `assumptions`, `postBuildRunRequested: true`
+   only when the user explicitly asked to run, execute, or test a workflow
+   after building it, and the final task graph.
+8. After calling `create-tasks`, do not write visible text. The approval card is
+   the user-visible surface.
+
+## Task Graph Rules
+
+- Use task kinds exactly as supported: `build-workflow`, `delegate`, and
+  `checkpoint`.
+- Each task `id` must be stable and referenced by dependency edges.
+- Each `title` should be short and user-facing.
+- Each `spec` must be the complete executor briefing for that task. The task
+  executor may not see your broader planning notes.
+- For `build-workflow` tasks, describe outcomes, key behaviours, integrations,
+  data-table requirements, schedules in the user's timezone, setup expectations,
+  credential assumptions, and verification-relevant trigger/input details. Do
+  not write node-by-node wiring or fake user data.
+- If a `build-workflow` task's final deliverable is a supporting sub-workflow,
+  set `isSupportingWorkflow: true` on that task. Do not set it for helper
+  sub-workflows that are only intermediate artifacts inside a larger main
+  workflow task.
+- For `delegate` tasks, include all context the background task needs and list
+  only the tools it should use.
+- For `checkpoint` tasks, write the semantic validation goal, the exact
+  evidence to inspect, and a plain pass/fail condition.
+
+## Assumptions And Questions
+
+- Never ask about things tools can discover, such as available credentials,
+  existing data tables, workflow names, node availability, or attached-file
+  structure.
+- Never ask for implementation details such as node choices, column names, or
+  trigger mechanics when a sensible default exists.
+- Never default resource identifiers the user did not mention, such as Slack
+  channels, calendars, spreadsheets, folders, databases, or recipient lists.
+  Leave them for the builder to resolve or collect through setup.
+- If exactly one matching credential exists, assume it and mention the
+  credential name in `planningContext.assumptions`.
+- If no matching credential exists, plan normally. The builder will mock or
+  leave it unresolved and route setup after verification.
+- If multiple matching credentials exist and the user did not name one, ask once
+  with `ask-user` because the choice cannot be discovered.
+
+## Checkpoints
+
+Workflow verification is automatic from structured build outcomes. Do not add
+routine "verify this workflow" checkpoint tasks for every workflow.
+
+Checkpoint tasks are exceptional semantic checks. Use them for cross-workflow
+contracts, confirming a report combines upstream data correctly, validating a
+business invariant across deliverables, or checking a condition that cannot be
+covered by normal runtime verification.
+
+Do not add checkpoints for delegate tasks, and do not list `tools` on checkpoint
+tasks.
+
+## Revisions
+
+If the user rejects the plan with requested changes, revise surgically and call
+`create-tasks` again in the same orchestrator run with
+`planningContext.source: "planning-skill"`.
+
+If the user denies the plan outright, stop. Do not call `create-tasks` again in
+the same message group.

package/skills/post-build-flow/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: post-build-flow
+description: >-
+  Handles workflow verification and setup after build-workflow succeeds, or when
+  the message contains workflow-verification-follow-up or workflow-setup-required.
+  Load after direct builds, when verificationReadiness requires action, or on
+  orchestrator verify/setup follow-up turns.
+recommended_tools:
+  - verify-built-workflow
+  - workflows
+  - build-workflow
+  - executions
+---
+
+# Post-Build Flow
+
+Use this skill after `build-workflow` succeeds on a direct orchestrator build, or
+when the current message contains `<workflow-verification-follow-up>` or
+`<workflow-setup-required>`.
+
+For trigger `inputData` shapes, read
+`knowledge-base/reference/trigger-input-data-shapes.md` in the sandbox workspace
+when available, or load this skill's `references/trigger-input-data-shapes.md`
+linked file.
+
+## Verification follow-up
+
+When the current message contains `<workflow-verification-follow-up>`, verify
+immediately from the payload's `obligation` — do not acknowledge first. If the
+obligation is `ready_to_verify` or `verifying`, call `verify-built-workflow`. Do
+**not** call `workflows(action="setup")` in this turn and do **not** declare the
+workflow finished if `outcome.setupRequirement.status === "required"` — setup is
+routed automatically as a separate `<workflow-setup-required>` step after
+verification.
+
+## Setup follow-up
+
+When the current message contains `<workflow-setup-required>`, your only action is
+to call `workflows(action="setup")` with the `workflowId` from the payload. Do
+not verify, do not ask, do not write a message first — the inline setup card in
+the AI Assistant panel is the user-visible surface. If it returns `deferred:
+true`, respect the user's choice and do not retry with any other setup tool.
+
+## Publishing and testing
+
+**Publishing is never required for testing.** Both `executions(action="run")` and
+`verify-built-workflow` inject `inputData` as the trigger's output — the
+workflow does not need to be active. Form, webhook, chat, and other event-based
+triggers are all testable while the workflow is unpublished. Never publish a
+workflow as a precondition for running it.
+
+## After build-workflow succeeds
+
+1. Read `workflowId`, `workItemId`, `triggerNodes`, `verificationReadiness`, and
+   `setupRequirement` from the tool output. If the output is missing a
+   `workflowId`, explain that the build did not submit.
+   - Before treating a saved workflow as done, inspect the persisted workflow
+     with `workflows(action="get-json", workflowId)` and compare the actual
+     graph to the user's requested outcome. Build/save success only means a
+     workflow was saved; it does not prove the saved workflow is good.
+   - If the persisted workflow is missing the requested outcome, has an obvious
+     dead-end draft shape, or the verification evidence is weak, load the
+     `workflow-builder` skill and patch the same workflow with `build-workflow`
+     using the existing `workflowId` and `workItemId`; then inspect and verify
+     again.
+   - If `verificationReadiness.status === "already_verified"`, treat the
+     workflow as verified and do **not** call `verify-built-workflow` again.
+   - If `verificationReadiness.status === "ready"`, call
+     `verify-built-workflow` with the `workItemId` / `workflowId` and the
+     trigger-appropriate `inputData` shape.
+   - If `verificationReadiness.status === "needs_setup"`, call
+     `workflows(action="setup")` with the workflowId so the user can configure it
+     through the inline setup card in the AI Assistant panel.
+   - If `verificationReadiness.status === "not_verifiable"`, do not infer
+     lower-level verification conditions; use the readiness guidance to give a
+     clear warning or manual-test note. This is a warning completion state, not
+     a verified state and not an infinite blocker.
+2. After verification handling, if `setupRequirement.status === "required"` and
+   setup has not already run for this build, call `workflows(action="setup")`
+   with the workflowId.
+3. When `workflows(action="setup")` opens the inline setup card, the card is the
+   user-visible surface. Do not tell the user to open the editor, use the canvas,
+   or click a Setup button; the user does not need to navigate anywhere.
+4. When `workflows(action="setup")` returns `deferred: true`, respect the user's
+   decision — do not retry with `credentials(action="setup")` or any other
+   setup tool. The user chose to set things up later.
+5. Ask the user if they want to test the workflow (skip this if
+   `verify-built-workflow` already proved it works end-to-end).
+6. Only call `workflows(action="publish")` when the user explicitly asks to
+   publish. Never publish automatically.
+
+## Credentials before build
+
+Call `credentials(action="list")` first to know what's available. Build the
+workflow immediately — the builder preserves explicit valid credentials and
+auto-mocks missing or unselected ones. Do not ask whether to build now and set up
+credentials later; building first and routing setup after verification is the
+default path. Workflow verification is automatic from the build outcome; the
+orchestrator handles workflow setup after verification when the saved workflow
+still has mocked credentials or placeholders.
+
+**Ask once when a service has multiple credentials of the same type.** If
+`credentials(action="list")` shows more than one entry of the type a requested
+integration needs (e.g. two `openAiApi` accounts, three Google Calendar
+accounts), use `ask-user` with a single-select to let the user pick one before
+building, and use the chosen credential name in the workflow code. Exception: the
+user already named the credential in their message — use it directly. With a
+single candidate, auto-apply and do not ask.
+
+**Ask which auth type to use when a service supports more than one.**
+`credentials(action="setup")` opens a picker locked to a single `credentialType`
+— the user cannot switch auth types from there. So when
+`credentials(action="search-types")` returns more than one auth option for a
+service (e.g. `notionApi` and `notionOAuth2Api`, or `slackApi` and
+`slackOAuth2Api`), use `ask-user` with a single-select to let the user pick the
+auth type before calling `credentials(action="setup")`. List OAuth2 first and
+present it as the recommended option. Exception: the user has clearly indicated
+an auth type (e.g. "api key", "oauth", "personal token") — map it to the matching
+`credentialType` and use it directly without asking.

package/skills/post-build-flow/references/trigger-input-data-shapes.md

@@ -0,0 +1,38 @@
+# Per-trigger `inputData` shape
+
+Used by `verify-built-workflow`, `executions(action="run")`, and checkpoint
+verification. The pin-data adapter spreads or wraps based on trigger type —
+passing the wrong shape gives null downstream values that look like an
+expression bug.
+
+## Form Trigger (`n8n-nodes-base.formTrigger`)
+
+Flat field map, e.g. `{name: "Alice", email: "a@b.c"}`. The production Form
+Trigger emits each field directly on `$json`, so the builder's `$json.<field>`
+expressions are correct. **Do NOT wrap in `formFields`** — the adapter will
+reject the call.
+
+## Webhook (`n8n-nodes-base.webhook`)
+
+The body payload, e.g. `{event: "signup", userId: "..."}`. The adapter wraps it
+under `body`, so downstream nodes reference `$json.body.<field>`.
+
+## Chat Trigger (`@n8n/n8n-nodes-langchain.chatTrigger`)
+
+`{chatInput: "user message"}`.
+
+## Schedule Trigger (`n8n-nodes-base.scheduleTrigger`)
+
+Omit `inputData`; the adapter emits synthetic timestamp fields.
+
+## Other event triggers
+
+Linear, GitHub, Slack, MCP, and similar triggers: pass `inputData` matching the
+trigger's expected payload shape from the node type definition.
+
+## Debugging wrong null values
+
+**Do not patch a workflow first when verify returns null downstream values.**
+Re-run verify with the corrected `inputData` shape. Only patch the workflow if
+the expression is wrong against the *production* trigger output shape (consult
+node descriptions), not the `instanceAi` pin data path.