@codemation/agent-skills 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @codemation/agent-skills
 
+## 0.1.9
+
+### Patch Changes
+
+- [#87](https://github.com/MadeRelevant/codemation/pull/87) [`4c50f29`](https://github.com/MadeRelevant/codemation/commit/4c50f29763ad7bc1e39723a6711ca3cf9add5014) Thanks [@cblokland90](https://github.com/cblokland90)! - Disable automatic packaged skill refreshes inside the Codemation framework monorepo so framework-author workflows stop dirtying the local worktree.
+  - keep `codemation skills sync` as the explicit refresh path after upgrading `@codemation/cli` or `@codemation/agent-skills`
+  - document the monorepo behavior in the packaged CLI skill and agent-skills README
+
+## 0.1.8
+
+### Patch Changes
+
+- [#78](https://github.com/MadeRelevant/codemation/pull/78) [`f451b1b`](https://github.com/MadeRelevant/codemation/commit/f451b1b4657b59406e15ce5f50b243e487ff99ed) Thanks [@cblokland90](https://github.com/cblokland90)! - Normalize fluent workflow DSL callback helpers around the runtime item contract.
+
+  `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` now receive `(item, ctx)` so workflow authors can use `item.json` consistently and read prior completed outputs through `ctx.data` without dropping down to direct node configs.
+
 ## 0.1.7
 
 ### Patch Changes
@@ -24,7 +40,7 @@
 
   `WorkflowAgentOptions` now takes `messages` (the same `AgentMessageConfig` as `AIAgent`) instead of
   `prompt`. The workflow helper passes `messages` through unchanged. Docs, workflow DSL skills, and the
-  test-dev sample use `itemValue(...)` for per-item prompts; execution docs note `itemValue` on agent
+  test-dev sample use `itemExpr(...)` for per-item prompts; execution docs note `itemExpr` on agent
   `messages`.
 
 ## Unreleased

package/README.md

@@ -19,7 +19,13 @@ The starter templates call the extractor automatically after `pnpm install`.
 
 ## Framework-managed copy
 
-The directory `.agents/skills/extracted` is **framework-managed**: Codemation overwrites packaged `codemation-*` skill folders there and removes stale packaged skill directories when you run `codemation dev`, `codemation build`, `codemation serve web`, or `codemation dev:plugin` (or `codemation skills sync`). Put project-local skills in sibling folders under `.agents/skills`, not inside `extracted`, unless you accept them being replaced.
+The directory `.agents/skills/extracted` is **framework-managed**:
+
+- In consumer projects, Codemation overwrites packaged `codemation-*` skill folders there and removes stale packaged skill directories when you run `codemation dev`, `codemation build`, `codemation serve web`, `codemation dev:plugin`, or `codemation skills sync`.
+- Inside the Codemation framework monorepo, the automatic refresh path is disabled to avoid polluting the local git worktree during framework development.
+- After upgrading `@codemation/cli` or `@codemation/agent-skills` while working in the monorepo, run `codemation skills sync` intentionally if you want the extracted copy refreshed.
+
+Put project-local skills in sibling folders under `.agents/skills`, not inside `extracted`, unless you accept them being replaced.
 
 ## Programmatic use
 

package/package.json

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

package/skills/codemation-cli/SKILL.md

@@ -36,6 +36,8 @@ Do not use this skill for workflow graph design, custom node implementation, or
 4. When Redis-backed execution is involved, mention the shared PostgreSQL requirement instead of assuming local SQLite still fits.
 5. In consumer mode, discovered plugins are loaded from the built JavaScript path declared in `package.json#codemation.plugin`, not from TypeScript source under `node_modules`.
 6. In plugin mode, the CLI TypeScript-loads only the current plugin repo through the generated `.codemation/plugin-dev/codemation.config.ts`.
+7. In the Codemation framework monorepo, automatic refresh of `.agents/skills/extracted` is intentionally disabled to keep the worktree clean.
+8. After `@codemation/cli` or `@codemation/agent-skills` package upgrades in monorepo work, remind the user to run `codemation skills sync` if they want the extracted packaged skills refreshed.
 
 ## Read next when needed
 

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

@@ -26,7 +26,7 @@ Do not use this skill for pure workflow chaining questions unless the node imple
 1. Prefer helper-based nodes first.
 2. Keep nodes deterministic and focused.
 3. Request credentials through named slots instead of hard-coded secrets.
-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).
+4. Put **static** options (credentials, retry policy, labels) on **config**; put **per-item** behavior in **inputs** / wire JSON and optional **`itemExpr`** 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

@@ -52,6 +52,6 @@ Reach for class-based node APIs when:
 
 ## Runtime reminder
 
-- **`defineNode`** runs **`execute` once per item** (with optional **`inputSchema`** and **`itemValue`** on config fields before **`execute`**)
+- **`defineNode`** runs **`execute` once per item** (with optional **`inputSchema`** and **`itemExpr`** 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-framework-concepts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codemation-framework-concepts
-description: Explains Codemation package boundaries, runtime concepts, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, or runtime modes.
+description: Explains Codemation package boundaries, runtime concepts, observability shape, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, telemetry, or runtime modes.
 compatibility: Designed for Codemation apps, plugins, and framework contributors.
 ---
 
@@ -8,7 +8,7 @@ compatibility: Designed for Codemation apps, plugins, and framework contributors
 
 ## Use this skill when
 
-Use this skill to explain package ownership, runtime shape, and the boundary between consumer code and framework code.
+Use this skill to explain package ownership, runtime shape, observability boundaries, and the boundary between consumer code and framework code.
 
 Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin implementation guidance when the user already knows the concept they need.
 
@@ -28,12 +28,15 @@ Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin
 - items carry workflow data
 - credentials provide typed runtime resources
 - activation is framework-managed and happens in the UI
+- telemetry is observability-first: traces, spans, artifacts, and metric points are framework-owned runtime data
+- run retention and telemetry retention can differ, so trend data can outlive raw run state
 
 ## Runtime rule of thumb
 
 1. Start with the minimum setup.
 2. Move to shared PostgreSQL and Redis when execution needs separate worker infrastructure.
 3. Keep workflow code stable while the runtime shape grows around it.
+4. Treat telemetry as part of the runtime contract, not as ad-hoc node-local logging.
 
 ## Read next when needed
 

package/skills/codemation-framework-concepts/references/architecture-map.md

@@ -40,6 +40,16 @@ That usually means:
 - Redis for queue-backed execution
 - BullMQ-backed scheduling
 
+## Observability data
+
+Codemation stores observability data in the host runtime alongside other application state:
+
+- traces and spans for execution correlation
+- artifacts for drill-down payloads such as AI messages or tool I/O
+- metric points for node-specific measurements without widening the span schema
+
+Run retention and telemetry retention are intentionally separate so operators can keep trend data longer than raw run state.
+
 ## Activation flow
 
 - deploy the workflow definition and any supporting plugin changes

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

@@ -23,7 +23,7 @@ That file is the plugin repository's source composition root. Consumers should d
 
 ## Node guidance
 
-- start with `defineNode(...)` and **`execute(...)`** for simple reusable nodes (per-item pipeline; optional **`inputSchema`** and **`itemValue`** on config fields)
+- start with `defineNode(...)` and **`execute(...)`** for simple reusable nodes (per-item pipeline; optional **`inputSchema`** and **`itemExpr`** 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,7 +17,8 @@ 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. 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.
+4. Activations are **batch-shaped** (`Items`); many steps use **per-item** execution (`execute`, including helper **`defineNode`**) with optional **`inputSchema`** and **`itemExpr`** on config fields. Batch reshape steps (split/filter/aggregate, **`defineBatchNode`**) work on the whole batch.
+5. Fluent callback helpers follow the runtime item contract: `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` receive `(item, ctx)`, so row fields live under `item.json` and earlier completed outputs are available through `ctx.data`.
 
 ## Authoring rules
 
@@ -44,7 +45,8 @@ Do not use this skill for CLI-only troubleshooting or deep host architecture que
 - Use `.agent(...)` for fluent workflow-defined agent steps.
 - Define agent messages with `messages`, not a workflow-specific prompt shortcut.
 - Use a static `messages` array for fixed prompts.
-- Use `itemValue(...)` when agent messages depend on the current item.
+- Use `itemExpr(...)` when agent messages depend on the current item.
+- Use fluent `.map((item, ctx) => ...)` when workflow data itself needs reshaping before the agent step.
 - `model` may be a provider string such as `"openai:gpt-4o-mini"` or a `ChatModelConfig`.
 
 ## Read next when needed

package/skills/codemation-workflow-dsl/references/builder-patterns.md

@@ -8,8 +8,8 @@ export default workflow("wf.example.id")
   .manualTrigger("Start", {
     step: "start",
   })
-  .map("Transform", (item) => ({
-    ...item,
+  .map("Transform", (item, _ctx) => ({
+    ...item.json,
     transformed: true,
   }))
   .build();
@@ -27,6 +27,8 @@ export default workflow("wf.example.id")
 - items usually carry `json` data and optional `binary` data
 - runtime nodes receive batches of items, not just one record
 - author workflow steps with batching in mind
+- fluent `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` callbacks receive `(item, ctx)`
+- read row fields from `item.json` and earlier completed outputs from `ctx.data`
 
 ## When to move beyond callbacks
 
@@ -53,5 +55,5 @@ Promote inline callbacks into custom nodes when:
 
 - use `.agent(...)` for agent steps in fluent workflow definitions
 - define agent prompts with `messages`
-- use `itemValue(...)` when message content depends on `item.json`
+- use `itemExpr(...)` when message content depends on `item.json`
 - use `outputSchema` when the workflow should expose typed structured agent output