@codemation/agent-skills 0.3.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,187 @@
 # @codemation/agent-skills
 
+## 0.5.1
+
+### Patch Changes
+
+- [#241](https://github.com/MadeRelevant/codemation/pull/241) [`0dc4aa5`](https://github.com/MadeRelevant/codemation/commit/0dc4aa5fae5e76735d063102a8e6fc761c1774dc) Thanks [@cblokland90](https://github.com/cblokland90)! - ai-agent skill: make the binary→agent passdown prescriptive. The builder was hand-rolling a "base64 encode" node (which fails at runtime: "No binary attachment found on item") instead of relying on the native `item.binary` passdown. The skill now spells out DON'T (no encode/base64 node, no stringifying bytes into a prompt) vs DO (feed `item.binary` straight in; for an HTTP download set `responseFormat: "binary"`; for a non-adjacent source forward with the agent's `binaries` option).
+
+## 0.5.0
+
+### Minor Changes
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(agent-skills): add the intake-automation-playbook concierge planning skill
+
+  Adds `codemation-intake-automation-playbook`, a plain-language planning playbook for the
+  Concierge to load when a user wants to automate handling of incoming things (emails,
+  messages, orders, leads, form submissions, documents). It teaches the Concierge to
+  recognise the abstract intake pattern and proactively surface the nine dimensions a
+  non-technical owner forgets to ask for — especially traceability, duplicate-handling,
+  human-review, match→link→report, and testing on real data.
+
+  Tagged `audience:concierge` (a reserved-tag convention) so it loads only in the Concierge's
+  `find_skills` and is excluded from the builder/coder skill index — node/DSL skills and this
+  planning skill never cross audiences.
+
+- [#227](https://github.com/MadeRelevant/codemation/pull/227) [`2130eab`](https://github.com/MadeRelevant/codemation/commit/2130eab49bcba708eca898f45fc400913470b11f) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(core-nodes): replace managed model-id with complexity token
+
+  `CodemationChatModelConfig` now takes a `complexity: ManagedComplexity` token
+  (`"low" | "medium" | "high" | "xhigh"`) instead of a free model-id string.
+  The managed LLM broker maps the token to a concrete provider model and thinking
+  effort server-side — the framework never references concrete model ids.
+
+  Breaking changes:
+  - `CodemationChatModelConfig(name, model)` → `CodemationChatModelConfig(name, complexity)`
+    where `complexity` is one of `"low" | "medium" | "high" | "xhigh"`.
+  - `temperature` option removed from `CodemationChatModelConfig` — Anthropic rejects
+    temperature when thinking is engaged; the broker injects thinking for medium/high.
+  - `ManagedModelDto`, `CodemationManagedModel` types removed.
+  - `ManagedModelFetcher` class removed — the `/api/llm/managed-models` discovery
+    endpoint is no longer part of the complexity-token contract.
+
+  Factory change: `CodemationChatModelFactory` now uses `@ai-sdk/anthropic` +
+  `createAnthropic` (Anthropic-native route) instead of `@ai-sdk/openai` +
+  `createOpenAI` (OpenAI-compat route). This is required so the broker's injected
+  `thinking` / `output_config.effort` fields survive the round-trip — they are
+  stripped by the OpenAI-compat route.
+
+  Examples and agent-skills updated to use complexity tokens throughout.
+
+- [#234](https://github.com/MadeRelevant/codemation/pull/234) [`13f9f11`](https://github.com/MadeRelevant/codemation/commit/13f9f11454855f44cd0849ea7e8f0c60f4a28964) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(core): make `description` a first-class config option every authorable node accepts directly
+
+  A node's plain-language `description` (the non-technical "what does this step do" line rendered in
+  the node properties sidebar) is now a normal option passed inline alongside `id`, exactly like any
+  other config field — no wrapper or clone helper:
+
+  ```ts
+  new Callback("Tag order as received", markReceived, { id: "mark", description: "Tags the order." });
+  new If("High value?", (i) => i.json.total > 1000, { id: "gate", description: "Routes big orders." });
+  new CronTrigger("Nightly", { schedule: "0 2 * * *" }, { id: "nightly", description: "Runs nightly." });
+  ```
+
+  - `NodeConfigBase` gains `readonly description?: string` (mirrors `icon`), and the
+    `WorkflowSnapshotCodec` carries it into the persisted snapshot config the host / canvas mappers
+    read — so the sidebar renders it. (`description` was added to the codec's non-serializable
+    fallback whitelist for parity with `icon`.)
+  - Every authorable built-in node threads `description` into its config: options-object nodes
+    (`Callback`, `MapData`, `Assertion`, `HttpRequest`, `AIAgent`, `TestTrigger`) accept it in their
+    options; bare-id nodes (`If`, `Split`, `Filter`, `Aggregate`, `Wait`, `Switch`, `SubWorkflow`,
+    `Merge`, `NoOp`, `IsTestRun`, `CronTrigger`, `WebhookTrigger`, `ManualTrigger`) now take a final
+    `string | { id?: string; description?: string }` argument — a bare `"id"` string still works
+    (back-compat).
+  - The `define*` factory helpers carry it too: `defineNode`, `defineBatchNode`,
+    `definePollingTrigger` (and everything layered on `defineNode` — `defineRestNode`,
+    `defineHumanApprovalNode`/`inboxApproval`, and the collection CRUD nodes) now accept
+    `{ id?, description? }` in the trailing `create(config, name, idOrOptions)` slot, so a per-instance
+    `description` survives into the persisted snapshot. A bare string id still works (back-compat).
+  - The `workflow-dsl` skill teaches business-action node titles and a one-line `description` set
+    directly in each node's options.
+
+  This supersedes the rejected `present(node, { description })` clone-helper approach (PR [#232](https://github.com/MadeRelevant/codemation/issues/232)/[#233](https://github.com/MadeRelevant/codemation/issues/233)):
+  `description` is a normal inline option, not a prototype clone.
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(agent-skills): reorganise skills into builder/ + concierge/ audience sub-trees, add drift-gate
+
+  All 22 legacy `codemation-*` flat skills are replaced by two audience-scoped sub-trees:
+  - `skills/builder/*` — 18 skills covering workflow DSL, nodes, credentials, custom-node development,
+    execution-context (`getOutputItem` cross-step access pattern), document AI, Gmail, HITL, MCP
+    capabilities, REST, testing, workspace files, Odoo, MS Graph, CLI, framework concepts,
+    plugin development, and connect-external-systems.
+  - `skills/concierge/*` — 4 skills: credentials binding, intake-automation-playbook, and the two
+    vertical guidance scenarios (procurement-intake, invoice-to-accounting).
+
+  A **skill drift-gate** (`scripts/verify-skill-code.mjs`, wired as the package `typecheck` / `verify-skills`
+  target, and enforced in CI) extracts every checked ` ```typescript ` block from every skill and
+  typechecks it against the live `@codemation/*` framework source. Blocks that are genuinely illustrative
+  pseudo-code use ` ```ts no-check ` or ` ```text ` so the gate skips them.
+
+  The `PackageMetadataExtractor` skill-discovery walk is updated to recurse through audience-grouping
+  directories so the nested layout is transparent to the catalog. `AGENTS.md` now documents the
+  drift-gate as a hard requirement alongside node-surface changes.
+
+  Example workflows previously served as standalone catalog entries are now embedded inside skill
+  ` ```typescript ` blocks, making the skill itself the canonical reference. The `packages/examples`
+  barrel no longer re-exports builder examples (`export {}` only); goldens in `src/goldens/` remain
+  for the builder eval.
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - Wire the unified-artifacts L2 layer (Phase 2): tag the 5 topic skills that become a parent's L2
+  overview (`parent` + `overview: true` on ai-agent-node, document-scanner, credential-development,
+  workspace-files, custom-node-development), mark plugin-development a child of `extending`, and add 7
+  short authored topic overviews (flow-control, triggers, http-and-apis, human-in-the-loop, testing,
+  data-shaping, gmail). Every topic parent now resolves to an L2 overview + its example children.
+
+### Patch Changes
+
+- [#230](https://github.com/MadeRelevant/codemation/pull/230) [`67b11fe`](https://github.com/MadeRelevant/codemation/commit/67b11fef992bbb91ce772bee7a602e0e3b4ac966) Thanks [@cblokland90](https://github.com/cblokland90)! - docs(workflow-dsl): add a "Filter vs If — choose up front" decision rule
+
+  The builder would draft "keep only real orders" as an `If` + `.when` (the skill's leading branching
+  example), then realise a `Filter` is the right shape and **rewrite the whole workflow** — the single
+  biggest source of slow procurement builds (a full rewrite is minutes of regeneration). The
+  `workflow-dsl` skill now states the rule before the `If` example: to KEEP ONLY items matching a
+  condition and drop the rest, use a `Filter` (one node, single trunk); reach for `If` + `.when` ONLY
+  when the two branches do DIFFERENT downstream work. The first draft now uses `Filter` and is the one
+  the model keeps.
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - docs(agent-skills): make the six framework-extending skills honest and concise
+
+  Tightens the rarely-read "extending the framework" skills — `codemation-custom-node-development`,
+  `codemation-credential-development`, `codemation-plugin-development`, `codemation-framework-concepts`,
+  `codemation-cli`, and `codemation-mcp-capabilities` — so every checked `typescript` block compiles
+  against the live framework and the prose matches the gold skill style.
+
+  Each drifted example was either fixed to compile against the real API (`defineNode` per-item
+  `execute(args, ctx)` shape; `credentials.<slot>()` accessors; `args.ctx.binary` for attachments;
+  `defineBatchNode` without `inputSchema`; `McpServerDeclaration` from `@codemation/core` with
+  `transport: "http"`) or converted to a `text` fence when it was a genuinely illustrative
+  fragment. Frontmatter was trimmed to a third-person what+when description with the
+  parent/overview menu framing removed. The skill drift-gate now passes for all six.
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(core-nodes-odoo): inline the Odoo plugin into the framework monorepo so the skills drift-gate resolves it
+
+  Moves `@codemation/core-nodes-odoo` from the parent monorepo (`plugins/codemation-nodes-odoo`)
+  into `packages/core-nodes-odoo` as a first-class framework package. The drift-gate
+  (`tsconfig.skillcheck.json`) path mappings are updated to point to the inlined source,
+  resolving the CI failure where the builder/odoo and builder/execution-context skill blocks
+  could not resolve `@codemation/core-nodes-odoo` outside the parent monorepo context.
+
+- [#226](https://github.com/MadeRelevant/codemation/pull/226) [`6720268`](https://github.com/MadeRelevant/codemation/commit/672026861d15bfd8f64ea3e405e506a7184a2e77) Thanks [@cblokland90](https://github.com/cblokland90)! - test(core-nodes): regression tests for explicit id acceptance on Assertion and TestTrigger
+
+  Adds three regression tests that prove `Assertion` and `TestTrigger` accept an explicit `id`
+  in their options object and that the id survives into `WorkflowDefinition.nodes[].id` through
+  `WorkflowBuilder.add()`. A build-eval run had tripped on inconsistent id acceptance; this
+  establishes a permanent guard.
+
+  Also updates the `testing` skill's full example to set explicit ids on the `Assertion` and
+  `IsTestRun` nodes, consistent with the `workflow-dsl` gotcha ("Set an explicit `id` on every
+  node"). The `TestTrigger` in that example already carried an id.
+
+- [#235](https://github.com/MadeRelevant/codemation/pull/235) [`666ff05`](https://github.com/MadeRelevant/codemation/commit/666ff05121f19413d7b6c97161f01028920889e9) Thanks [@cblokland90](https://github.com/cblokland90)! - Strengthen the builder skills to set a plain-language `description` on **every** node. The
+  `workflow-dsl` skill now makes "every node, no exceptions" a hard rule — naming the easily-forgotten
+  node types (trigger / test-trigger, OCR / PDF-scan, AI-agent, notify / test-notification) and adding a
+  pre-finish self-check ("re-read the whole workflow, confirm every node has a title AND a description").
+  The `document-ai` skill's scan example now authors the scanner with `{ id, description }` (and gives
+  its webhook trigger one too) so the OCR step is never left bare.
+
+  Measured on the builder `non_tech_friendly` eval (BUILD1-procurement): descriptions 0.73 → 0.92 and
+  titles 0.82 → 1.00 (overall 0.77 → 0.96) from the skill changes alone.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#185](https://github.com/MadeRelevant/codemation/pull/185) [`be520d2`](https://github.com/MadeRelevant/codemation/commit/be520d2755144a3709ecc109019b84e2c502337e) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(workspace-files): examples + skill (story 04)
+
+  Two CI-verified examples for workspace file nodes:
+  - node-workspace-files-read.example.ts — read a workspace CSV by filename (latest-wins) + parse
+  - concierge-digest-to-workflow.example.ts — concierge digests PDF → workflow reads derived JSON
+
+  New codemation-workspace-files skill documenting: read-by-filename vs pinned fileId, binary slot
+  handoff, read-only boundary, and the raw-upload → concierge-digests → workflow-reads pattern.
+
+### Patch Changes
+
+- [#184](https://github.com/MadeRelevant/codemation/pull/184) [`8c5b213`](https://github.com/MadeRelevant/codemation/commit/8c5b213092501bb48aa0c575b0489bbd36b46c79) Thanks [@cblokland90](https://github.com/cblokland90)! - Add `codemation-document-scanner` skill entry covering analyzerType routing table, confidence opt-in (LD6), output shape, and when to choose the managed node vs standalone OCR nodes.
+
 ## 0.3.0
 
 ### Minor Changes