@codemation/agent-skills 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @codemation/agent-skills
 
+## 0.1.5
+
+### Patch Changes
+
+- [#54](https://github.com/MadeRelevant/codemation/pull/54) [`35b78bb`](https://github.com/MadeRelevant/codemation/commit/35b78bb4d8c7ee2998a8b8e51e5ffc3fd901e4c7) Thanks [@cblokland90](https://github.com/cblokland90)! - **Breaking change:** `defineNode(...)` now follows the per-item pipeline: implement **`execute(args, context)`** (optional **`inputSchema`**, **`mapInput`**, and **`TWireJson`** on the generated runnable config). Add **`defineBatchNode(...)`** with **`run(items, context)`** for plugin nodes that still require batch **`run`** semantics.
+
+  Built-in nodes and workflow DSL (`split` / `filter` / `aggregate` on the fluent chain, Switch routing, execution normalization) align with the unified runnable model.
+
+  Align documentation (site guides, repo **`AGENTS.md`**, **`strict-oop-di`** skill, **`packages/core/docs/item-node-execution.md`**) and the **plugin** starter **`AGENTS.md`** with **config** for static wiring (credentials, retry, presentation) vs **inputs** / wire JSON for per-item behavior.
+
+## 0.1.4
+
+### Patch Changes
+
+- [#52](https://github.com/MadeRelevant/codemation/pull/52) [`bb2b3b8`](https://github.com/MadeRelevant/codemation/commit/bb2b3b89069697c6aa36aac1de7124c5eea65c3e) Thanks [@cblokland90](https://github.com/cblokland90)! - **Breaking change:** `defineNode(...)` now follows the per-item pipeline: implement **`executeOne(args, context)`** (optional **`inputSchema`**, **`mapInput`**, and **`TWireJson`** on the generated runnable config). Add **`defineBatchNode(...)`** with **`run(items, context)`** for plugin nodes that still require legacy batch **`Node.execute`** semantics.
+
+  Align documentation (site guides, repo **`AGENTS.md`**, **`strict-oop-di`** skill, **`packages/core/docs/item-node-execution.md`**) and the **plugin** starter **`AGENTS.md`** with **config** for static wiring (credentials, retry, presentation) vs **inputs** / wire JSON for per-item behavior.
+
 ## 0.1.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/agent-skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Reusable agent skills for Codemation projects and plugin development.",
   "publishConfig": {
     "access": "public"
@@ -37,6 +37,7 @@
     "skills"
   ],
   "scripts": {
+    "changeset:verify": "pnpm --workspace-root run changeset:verify",
     "test": "vitest run"
   }
 }

package/skills/codemation-custom-node-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codemation-custom-node-development
-description: Guides Codemation custom node development with `defineNode(...)`, reusable node modules, credential-aware nodes, and the class-based node fallback for advanced cases. Use when creating or updating custom nodes for apps or plugin packages.
+description: Guides Codemation custom node development with `defineNode(...)` (`execute` per item), `defineBatchNode(...)` (batch `run`), reusable node modules, credential-aware nodes, and the class-based node fallback for advanced cases. Use when creating or updating custom nodes for apps or plugin packages.
 compatibility: Designed for Codemation apps and plugin packages that define reusable nodes.
 ---
 
@@ -15,16 +15,18 @@ Do not use this skill for pure workflow chaining questions unless the node imple
 ## Default approach
 
 1. Start with `defineNode(...)`.
-2. Keep the runtime behavior in `run(...)`.
+2. Implement **`execute(args, context)`** — one mapped **input** in, one output payload per item (activations are still batch-shaped; the engine iterates items for you).
 3. Give the node a stable key and a clear title.
-4. Promote callback-heavy logic into a node when the graph or tests need a stronger boundary.
+4. Optionally set **`icon`** on the `defineNode` definition so the workflow canvas shows a proper glyph (same string contract as `NodeConfigBase.icon`).
+5. Use **`defineBatchNode(...)`** with **`run(items, context)`** only when the node must process the **entire batch** at once (legacy batch semantics).
+6. Promote callback-heavy logic into a node when the graph or tests need a stronger boundary.
 
 ## Node rules
 
 1. Prefer helper-based nodes first.
 2. Keep nodes deterministic and focused.
 3. Request credentials through named slots instead of hard-coded secrets.
-4. Remember that runtime execution receives batches of items.
+4. Put **static** options (credentials, retry policy, labels) on **config**; put **per-item** behavior in **inputs** / wire JSON and optional **`itemValue`** on config fields (consistent with built-in nodes).
 5. Drop to class-based node APIs only when you need constructor-injected collaborators, decorators, or deeper runtime metadata.
 
 ## Testing with `WorkflowTestKit`

package/skills/codemation-custom-node-development/references/node-patterns.md

@@ -8,24 +8,31 @@ Use `defineNode(...)` when:
 - the node belongs to one app or plugin package
 - helper-based credential slots are enough
 
-## Standard helper shape
+## Standard helper shape (`execute`)
 
 ```ts
 export const uppercaseNode = defineNode({
   key: "example.uppercase",
   title: "Uppercase field",
+  icon: "lucide:languages",
   input: {
     field: "string",
   },
-  run(items, { config }) {
-    return items.map((item) => ({
-      ...item,
-      [config.field]: String(item[config.field as keyof typeof item] ?? "").toUpperCase(),
-    }));
+  execute({ input }, { config }) {
+    return {
+      ...input,
+      [config.field]: String(input[config.field as keyof typeof input] ?? "").toUpperCase(),
+    };
   },
 });
 ```
 
+Optional **`icon`** is forwarded to the generated node config for the canvas (Lucide `lucide:…`, **`builtin:…`** / **`si:…`**, or image URLs). See `packages/core-nodes/src/canvasIconName.ts` and the Next host `WorkflowCanvasNodeIcon` resolver.
+
+## Batch helper shape (`defineBatchNode`)
+
+When the node must see **all items in one call**, use **`defineBatchNode`** and **`run(items, { config, credentials, execution })`** returning outputs for the batch (same contract as other batch-shaped nodes such as **Aggregate**).
+
 ## When a custom node pays off
 
 Move from an inline callback to a custom node when:
@@ -45,6 +52,6 @@ Reach for class-based node APIs when:
 
 ## Runtime reminder
 
-- nodes process batches of items
-- keep them deterministic and testable
-- prefer real code paths or in-memory collaborators over heavy mocking
+- **`defineNode`** runs **`execute` once per item** (with optional **`inputSchema`** and **`itemValue`** on config fields before **`execute`**)
+- **`defineBatchNode`** runs **`run`** once per activation batch
+- keep nodes deterministic and testable; prefer real code paths or in-memory collaborators over heavy mocking

package/skills/codemation-plugin-development/SKILL.md

@@ -29,7 +29,7 @@ Do not use this skill for ordinary consumer workflow-only changes unless the wor
 ## Common plugin pieces
 
 - `codemation.plugin.ts`: plugin registration and sandbox app
-- `src/nodes/*`: custom node definitions
+- `src/nodes/*`: custom node definitions (`defineNode` → **`execute`**; `defineBatchNode` → batch **`run`**)
 - `src/credentialTypes/*`: custom credential definitions
 - `src/index.ts`: package exports
 - `test/*.test.ts` (optional): Vitest + `WorkflowTestKit` from `@codemation/core/testing` for engine-backed unit tests without starting the full host (`pnpm test`)

package/skills/codemation-plugin-development/references/plugin-structure.md

@@ -21,7 +21,8 @@ Use `codemation.plugin.ts` as the single place that:
 
 ## Node guidance
 
-- start with `defineNode(...)` for simple reusable nodes
+- start with `defineNode(...)` and **`execute(...)`** for simple reusable nodes (per-item pipeline; optional **`inputSchema`** and **`itemValue`** on config fields)
+- use `defineBatchNode(...)` only when the node must process the **whole activation batch** in one **`run(items, ...)`**
 - keep runtime logic close to the node definition
 - move to class-based node APIs when you need constructor-injected collaborators or deeper runtime metadata
 

package/skills/codemation-workflow-dsl/SKILL.md

@@ -17,14 +17,14 @@ Do not use this skill for CLI-only troubleshooting or deep host architecture que
 1. A workflow definition describes how items move from a trigger through downstream steps.
 2. The fluent authoring chain is the normal starting point for Codemation apps.
 3. Finish fluent workflow definitions with `.build()`.
-4. Think in batches of items, not single-record callbacks.
+4. Activations are **batch-shaped** (`Items`); many steps use **per-item** execution (`execute`, including helper **`defineNode`**) with optional **`inputSchema`** and **`itemValue`** on config fields. Batch reshape steps (split/filter/aggregate, **`defineBatchNode`**) work on the whole batch.
 
 ## Authoring rules
 
 1. Prefer the fluent `workflow(...)` chain for app-local workflow files.
 2. Keep workflow files focused on orchestration and named steps.
 3. Use custom nodes when a callback grows into reusable product logic.
-4. Remember that node execution receives batches of items, even when examples look single-item.
+4. Distinguish **batch activations** from **per-item node bodies**: custom nodes from **`defineNode`** implement **`execute`** per item unless you chose **`defineBatchNode`** for batch **`run`**.
 
 ## Typical flow