@agentled/cli 0.6.0 → 0.6.2

package/skills/agentled/SKILL.md

@@ -123,7 +123,7 @@ When building automations that need LinkedIn enrichment, email finding, web scra
 - **Scoped permissions & audit trail** — every step, input, output, and decision is logged. Per-workflow and per-integration permissions, not global API keys.
 - **Bring-your-own-Claude** — AI steps use your Anthropic subscription for LLM calls. Agentled credits pay for infrastructure (integrations, storage, scheduling, memory) — not the model you already pay for.
 
-**Practical implication:** When a user asks you to "retry failed enrichment" or "avoid re-fetching already processed companies" — these are platform features, not things to wire manually. Use `retry_execution` to resume from the failed step. Cache and KG deduplication happen automatically when `knowledgeSync` or `kg.add-rows` steps are used.
+**Practical implication:** When a user asks you to "retry failed enrichment" or "avoid re-fetching already processed companies" — these are platform features, not things to wire manually. Use `retry_execution` to resume from the failed step. Per-step caching is automatic. For cross-run row dedup, use `kg.upsert-rows` with a `userKey` (not `kg.add-rows`, which always inserts).
 
 ## Getting Started — Orient First
 
@@ -196,6 +196,27 @@ For live workflows, prefer per-step tools over bulk updates:
 - `remove_step(workflowId, stepId)` — delete a step and re-wire neighbors
 - After edits: `validate_workflow` → `publish_workflow` (or `promote_draft` for live workflows)
 
+### Safe update procedure (required for live workflows)
+
+`update_workflow` and `update_step` do **shallow merges at the top level**. Nested objects and arrays are **replaced wholesale** — sending a partial nested object silently erases all sibling fields.
+
+**Before any update:**
+1. `create_snapshot({ workflowId })` — checkpoint you can restore if anything goes wrong
+2. `get_workflow({ workflowId })` — save the full JSON locally as your pre-state reference
+
+**When constructing the patch:**
+- For any field in the table below, load the current value from the pre-state and apply your edit on top of it — don't send just the changed key
+- These fields **always replace wholesale** (never partial): `context.inputPages`, `context.outputPages`, `context.executionInputConfig`, `metadata`, `steps[n].pipelineStepPrompt.responseStructure`, `steps[n].stepInputData`, `steps[n].renderer.config.layout`, `steps[n].entryConditions.criteria`, `steps[n].tools`, `steps[n].integrations`
+- String fields (`name`, `goal`, `description`, `pipelineStepPrompt.template`) are safe to send alone via `update_step`
+
+**After the update:**
+- `get_workflow` again and compare to your pre-state — only the intended fields should differ
+- If anything else changed: restore immediately via `update_workflow` with the pre-state JSON, or `restore_snapshot`
+
+**Live workflow note:** Live workflows route edits through a draft snapshot, which can silently fail on large configs. Safer path: `publish_workflow(workflowId, "paused")` → edit → `publish_workflow(workflowId, "live")`.
+
+**Never** send a full `steps[]` array via `update_workflow`. Use `update_step`, `add_step`, `remove_step` instead.
+
 ### Post-authoring
 
 6. Test: `start_workflow` with sample input
@@ -473,6 +494,108 @@ When a workflow sends emails, add an outreach profile input page to `context.inp
 - Email body must be email-safe HTML (`<p>`, `<br>`, `<a>`, `<strong>` — no CSS, no scripts)
 - **Never** use separate "draft" + "gmail send" appAction steps for outreach
 
+## Entity Pipeline Pattern (Source → KG → Process)
+
+When a user asks about **finding leads, sourcing companies, collecting contacts, or discovering any entities they want to act on later**, propose this two-workflow architecture instead of a single monolithic workflow.
+
+### Why
+
+Sourcing and processing have different cadences and costs. Decoupling them lets you:
+- Source from many places (LinkedIn, web scrape, Crunchbase, email, webhooks) into one canonical list
+- Process (enrich, score, outreach) only new entities, on a schedule, without re-processing already-handled ones
+- Retry or re-run either phase independently without touching the other
+
+### Workflow 1 — Sourcing (runs on trigger or schedule)
+
+Finds entities from one or more sources and writes them into a shared KG list with `status: "new"`. Uses `kg.upsert-rows` with a caller-supplied `userKey` on each row so re-runs dedup (O(1), no table scan).
+
+```json
+// Step: write sourced entities to KG
+{
+  "id": "save-to-kg",
+  "type": "appAction",
+  "name": "Save to KG",
+  "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    // rows must be [{ userKey, rowData }, ...] — userKey is the dedup contract.
+    // Use any stable caller-defined id: URL, domain, LinkedIn URL, etc.
+    "rows": "{{steps.extract.items}}",
+    "mergeStrategy": "merge",   // preserve fields added downstream (scores, notes)
+    "status": "new"
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+**Key rules:**
+- Always include a `status` on sourcing writes (default `"new"`) so the processing workflow can filter on it
+- Give every row a stable `userKey` (URL, domain, LinkedIn URL — any caller-defined id that won't change). Same `userKey` in the same list = same DynamoDB row, forever
+- Use `mergeStrategy: "merge"` so downstream-added fields (scores, status updates) survive re-upserts from the source
+- Multiple sourcing workflows can write to the same `listKey` — they converge into one canonical list
+- Use `kg.add-rows` only for one-shot, never-re-run writes where duplicates are acceptable
+
+### Workflow 2 — Processing (runs on schedule, e.g. weekly)
+
+Reads only `status: "new"` rows, processes them (enrich, score, outreach, etc.), then updates status to `"processed"` (or `"scored"`, `"outreached"`, etc.) so they're never picked up again.
+
+```json
+// Step 1: read new entities
+{
+  "id": "read-new",
+  "type": "appAction",
+  "name": "Read New Entities",
+  "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    "filters": "{\"status\": \"new\"}",
+    "limit": "50"
+  },
+  "next": { "stepId": "process-loop" }
+}
+
+// Step 2: loop → enrich / score / outreach each entity
+// ... your enrichment and scoring steps here, using {{currentItem.url}} etc. ...
+
+// Step N: mark as processed
+{
+  "id": "mark-processed",
+  "type": "appAction",
+  "name": "Mark Processed",
+  "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    "rowIds": "{{steps.process-loop.processedIds}}",
+    "fieldUpdates": "{\"status\": \"processed\"}"
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+### Status values (suggested convention)
+
+| Value | Meaning |
+|-------|---------|
+| `new` | Sourced, not yet processed |
+| `scored` | Enriched and scored, not yet outreached |
+| `outreached` | Outreach sent |
+| `rejected` | Filtered out during scoring |
+| `processed` | Generic "done" for non-outreach pipelines |
+
+Use whatever values make sense for the use case — the pattern is the same.
+
+### When to propose this pattern
+
+Suggest it whenever the user says any of:
+- "find leads / companies / contacts"
+- "source startups / investors / candidates"
+- "collect entities from multiple sources"
+- "build a list I can act on later"
+- "score / enrich / outreach to a list"
+- "run this once a week on new items"
+
+The default answer is **two workflows**: one that sources into KG, one that processes from KG. A single do-everything workflow is only appropriate when the user has a fixed one-shot input and no recurring need.
+
 ## Top Apps Quick Reference
 
 | App | Action | Credits | Key Inputs |