@codemation/agent-skills 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @codemation/agent-skills
 
+## 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
+
+- [#41](https://github.com/MadeRelevant/codemation/pull/41) [`a72444e`](https://github.com/MadeRelevant/codemation/commit/a72444e25c4e744a9a90e231a59c93f8d90346e5) Thanks [@cblokland90](https://github.com/cblokland90)! - Add `WorkflowTestKit` and related engine test harness exports on `@codemation/core/testing`, with create-codemation templates and agent skills updated to document plugin unit tests.
+
+## 0.1.2
+
+### Patch Changes
+
+- [#39](https://github.com/MadeRelevant/codemation/pull/39) [`cbfe843`](https://github.com/MadeRelevant/codemation/commit/cbfe843ef2363e400a219f4d0bcd05b091ab83b4) Thanks [@cblokland90](https://github.com/cblokland90)! - Add `WorkflowTestKit` and related engine test harness exports on `@codemation/core/testing`, with create-codemation templates and agent skills updated to document plugin unit tests.
+
 ## 0.1.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/agent-skills",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Reusable agent skills for Codemation projects and plugin development.",
   "publishConfig": {
     "access": "public"

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(...)` (`executeOne` 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,18 +15,24 @@ 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 **`executeOne(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 **`mapInput`** (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`
+
+For engine-backed tests without the host, use **`WorkflowTestKit`** from **`@codemation/core/testing`**: **`registerDefinedNodes([...])`**, then **`runNode`** or **`run`**. See the plugin development doc and `@codemation/core` tests for examples.
+
 ## Read next when needed
 
 - Read `references/node-patterns.md` for `defineNode(...)` patterns and packaging guidance.

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 (`executeOne`)
 
 ```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(),
-    }));
+  executeOne({ 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 **`Items`** per port (same as class-based **`Node.execute`**).
+
 ## 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 **`executeOne` once per item** (with optional **`mapInput`** / **`inputSchema`** before enqueue)
+- **`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,9 +29,14 @@ 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` → **`executeOne`**; `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`)
+
+## Unit tests (`WorkflowTestKit`)
+
+Import **`WorkflowTestKit`** from **`@codemation/core/testing`**. Use **`registerDefinedNodes([...])`** for `defineNode` packages, then **`runNode({ node: yourNode.create(...), items })`** or **`run({ workflow, items })`** for fuller graphs. Prefer this for fast node tests; use **`codemation dev:plugin`** when you need the UI and persistence.
 
 ## Read next when needed
 

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 **`executeOne(...)`** for simple reusable nodes (per-item pipeline; optional **`mapInput`** / **`inputSchema`**)
+- 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 (`executeOne`, including helper **`defineNode`**) with optional **`mapInput`** / **`inputSchema`**. 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 **`executeOne`** per item unless you chose **`defineBatchNode`** for batch **`run`**.
 
 ## Typical flow