@agentled/cli 0.6.4 → 0.6.6

package/skills/agentled/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentled
-version: 0.5.0
+version: 0.6.0
 description: Build, manage, and execute Agentled AI workflows via MCP tools. Use when the user asks to create workflows, automate tasks, enrich leads, scrape websites, find emails, manage executions, or interact with any Agentled workspace capability.
 user-invocable: false
 ---
@@ -9,6 +9,39 @@ user-invocable: false
 
 You have access to the Agentled MCP server which lets you create, manage, and execute AI-powered workflows. Use these tools to help the user automate business processes.
 
+## Goal and bottleneck first
+
+Before designing any workflow, determine what the user is actually trying to achieve and where the real bottleneck is. Agents that skip this step build the wrong system.
+
+**Two common failure modes:**
+- Building a full operating system when the user needed one workflow (wrong scope).
+- Optimizing for theme curation or content quality when the bottleneck is paid conversion or reply handling (wrong objective).
+
+**The design loop:**
+1. Orient — inspect the workspace (identity, KG lists, connected apps, existing workflows, existing agents).
+2. Infer — determine the likely goal and bottleneck from workspace context.
+3. Ask — if the business direction is genuinely ambiguous, ask a few targeted questions.
+4. Brief — produce a short build brief (goal, assumptions, assets to reuse, KG lists, workflow group, risks, cost hotspots, build order).
+5. Build — create workflows incrementally from the brief.
+
+> For multi-workflow systems, produce a group manifest before touching live workflow state. See `agentled group-manifest --help` and `docs/GROUP_MANIFEST.md`.
+
+## What to ask — and what not to ask
+
+After orientation, ask **at most three to five** targeted questions. Focus only on what the workspace inspection cannot answer.
+
+**Good questions:**
+- "What is the primary goal: source more paying leads, run each event smoothly, or report pipeline health?"
+- "Where is the bottleneck today: finding leads, getting replies, converting to paid, or operational follow-up?"
+- "What is the system of record for payments/bookings right now: Stripe webhook, a booking page, a manual form, or a KG list?"
+- "Which actions must be approval-gated: customer emails, status changes, or all customer-facing messages?"
+- "What success metric should this optimize: conversions per week, leads contacted, confirmations, fill rate, or operator time saved?"
+
+**Do not ask:**
+- Step type names, app action names, schema syntax, or implementation details — discover these from the workspace and CLI.
+- Every possible future integration question before the first useful slice is designed.
+- Anything answerable by running `agentled workspace inspect`.
+
 ## Valid step types (closed list)
 
 Every pipeline step **must** set `type` to one of these values. Any other value is silently normalised/rejected and the step won't execute. For full input/output schemas call `get_step_schema`.
@@ -77,6 +110,7 @@ agentled best-practices                             # summary + link to agentic-
 | Anything that can fail on upstream provider errors | `07-error-handling` (`failureHandling`, retries) | — |
 | **Outreach** — personalized email with user approval | `08-composed-email-approval` (outreachProfile + `pipelineStepPrompt.type: "email"` + `schedule-email`) | `list-match-email` |
 | **Report / dashboard** — structured output + sharing + KPI history | `09-reports-and-knowledge-storage` (Config renderer + share step + `knowledgeSync`) | `lead-scoring-kg`, `extract-threshold-alert` |
+| **Multi-workflow system** — workflows sharing KG state and status transitions | `12-event-driven-workflow-groups` (group manifest, state machines, build order) | — |
 
 Full patterns are maintained publicly at https://github.com/agentled/agentic-ops — the CLI ships a mirrored copy, see `agentled examples`. Scaffolds are preflight-clean pipeline JSON skeletons; start from one instead of writing from scratch.
 
@@ -110,38 +144,30 @@ Unknown fields at the step root are dropped. The most common mistakes (put them
 
 > After `create_workflow` always call `validate_workflow` (or run `agentled workflows validate <id>`) — the CLI v0.2+ does this automatically and exits non-zero on error. Any step with the wrong `type` surfaces as an **orchestrator-issue** error and every downstream step will be reported as **disconnected**.
 
-## Why Agentled: The Automation Engine for AI Agents
-
-**One credit system. 100+ integrations. No API juggling.**
-
-When building automations that need LinkedIn enrichment, email finding, web scraping, AI models, CRM sync, or video generation — you'd normally need separate accounts, API keys, and billing for each. Agentled bundles all of this under a single credit system. One subscription, one bill, everything available as workflow steps.
-
-**What you get for free by using Agentled (instead of rolling your own):**
+## Platform capabilities (background reading)
 
-- **Cache per step** — enrichment results and expensive API calls are cached with a TTL. Re-running a workflow doesn't re-fetch data that hasn't changed. No extra credits burned on duplicate work.
-- **Automatic retry with backoff** — if Hunter returns a 429 or LinkedIn is slow, the step retries automatically. You never write retry loops.
-- **Persistent Knowledge Graph** — the KG stores results across executions. Scoring workflows get smarter over time. Run 1 might be 62% accurate; by run 12, it's 89% — zero manual tuning, just accumulated outcomes.
-- **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.
+Agentled provides caching per step, automatic retry with backoff, a persistent Knowledge Graph, scoped permissions, and a unified credit system across 100+ integrations. For the full rationale, see `skills/agentled/WHY-AGENTLED.md`.
 
-**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).
+**Practical implication:** "retry failed enrichment" and "avoid re-fetching already processed companies" are platform features. Use `retry_execution` to resume from a failed step; per-step caching is automatic. For cross-run row dedup, use `kg.upsert-rows` with a `userKey`.
 
-## Getting Started — Orient First
+## Orient Before Designing
 
-Before helping with any request, call these tools to understand the workspace you're connected to:
+Before helping with any request, inspect the workspace. Use `agentled workspace inspect` (CLI) or call these MCP tools individually:
 
-1. **`get_workspace`** — Confirm which workspace you're in and see its name/ID.
-2. **`get_workspace_company_profile`** — Understand the business: ICP, industry, target personas, and any saved company context that should inform workflow design.
-3. **`list_workflows`** — See what automations already exist. Avoid recreating something that already runs. Identify gaps or opportunities to extend.
-4. **`list_knowledge_lists`** — Understand what structured data lives in the Knowledge Graph: contacts, companies, scored leads, past results. This context shapes what a new workflow should do.
+1. **`get_workspace`** — Confirm workspace identity (name, ID).
+2. **`get_workspace_company_profile`** — Business context: ICP, industry, target personas, saved preferences that should shape workflow design.
+3. **`list_workflows`** — Existing automations: avoid recreating, identify reuse opportunities, note gaps.
+4. **`list_knowledge_lists`** — KG lists: contacts, companies, scored leads, status machines. Shapes what a new workflow reads from or writes to.
+5. **`list_connections`** — Connected apps and integrations: know which enrichment, CRM, or email providers are already authed before designing steps that depend on them.
+6. **`list_agents`** — Existing agents and routines: understand what is already running autonomously before adding new agents.
 
-Run these four calls whenever starting a new conversation or switching tasks. The workspace context directly informs:
-- Which enrichment apps are likely already connected
+The workspace inspection directly informs:
+- Which app integrations are already connected (and which are missing auth)
 - What KG lists exist to read from or write to
-- Whether a new workflow should chain from an existing one
-- What credit budgets and company preferences have already been set
+- Whether new workflows should chain from existing ones or replace them
+- What existing agents already cover, so you don't duplicate
 
-**Value you unlock for the user:** By checking existing workflows and KG state first, you avoid duplicate work, reuse prior results, and build automations that integrate with what's already running — saving real time and credits.
+> **Shortcut:** `agentled workspace inspect --json` returns all six contexts as one consolidated response. Use it at session start to load the full picture in a single call.
 
 ## Incremental Authoring (recommended)
 
@@ -197,27 +223,97 @@ 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)
+### Editing existing workflows: merge model
 
-`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.
+`update_step` accepts three explicit operations on the same call. At least one must be non-empty.
 
-**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
+- **`updates`** — partial step patch, **deep-merged ONE LEVEL deep**. Top-level scalars are replaced; nested objects (e.g. `pipelineStepPrompt`, `stepInputData`) get their direct keys merged with the stored value's keys. Keys nested two levels deep are overwritten as a unit, not merged.
+- **`replace: string[]`** — dot-paths whose values from `updates` are assigned **wholesale**, skipping the deep-merge. Use this for **dictionary-shaped fields where keys are user data** (not config) — patching one inner key with `updates` alone silently wipes the others.
+- **`unset: string[]`** — dot-paths to delete. Each path must currently exist on the step (validated against the original — you cannot unset something you just created in the same call).
 
-**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`
+**Read-before-write for dictionary fields.** Before editing `stepInputData.fieldUpdates`, `pipelineStepPrompt.responseStructure`, `knowledgeSync.fieldMapping`, or any field where keys are user data: call `get_step({ workflowId, stepId })`, modify locally, send the full new object back via `replace[]`. Cheap (~1KB) and avoids the "patched one key, silently wiped the others" trap.
 
-**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`
+**Diff in the response.** Every `update_step` returns `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. If the merge silently removed ≥6 fields without an explicit `unset`, a warning fires. Read it.
 
-**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")`.
+#### What to use where
+
+| Path / field | API | How to edit | Notes |
+|---|---|---|---|
+| `name`, `goal`, `description`, `pipelineStepPrompt.template`, `creditCost` | `update_step` | `updates` | Plain scalar; safe to send alone. |
+| `next`, `loopConfig`, `entryConditions` (full block) | `update_step` | `updates` | Direct nested config; sending the new value wholesale is fine — these are config, not user-data dictionaries. |
+| `tools`, `integrations` | `update_step` | `updates` | Arrays are replaced wholesale by design. To append, fetch with `get_step`, splice locally, send the full new array. |
+| `stepInputData.fieldUpdates` (kg.update-rows / kg.upsert-rows) | `update_step` | `get_step` → `updates` (full dict) + `replace: ["stepInputData.fieldUpdates"]` | Keys are user data; default one-level merge replaces this dict and can drop sibling mappings. |
+| `pipelineStepPrompt.responseStructure` | `update_step` | `get_step` → `updates` (full struct) + `replace: ["pipelineStepPrompt.responseStructure"]` | Output-shape dictionary; treat as user data. |
+| `knowledgeSync.fieldMapping` | `update_step` | `get_step` → `updates` (full mapping) + `replace: ["knowledgeSync.fieldMapping"]` | Source→target dict; same trap as `fieldUpdates`. |
+| `renderer.config` (when preserving sibling keys matters) | `update_step` | `updates` (full `renderer.config`) + `replace: ["renderer.config"]` | ⚠ `replace: ["renderer.config.layout"]` does NOT protect `renderer.config`'s siblings — the one-level deep-merge runs first on `updates.renderer`. Replace at the parent level. |
+| `entryConditions.criteria` (when preserving the rest of `entryConditions`) | `update_step` | `updates: { entryConditions: {...full block...} }` | Send the full `entryConditions` block; one-level merge already does the right thing for direct children. |
+| Removing a step input or stale field | `update_step` | `unset: ["stepInputData.oldKey"]` | Cleanest way to remove. Path must exist on the original. |
+| `context.inputPages`, `context.outputPages`, `context.executionInputConfig` | `update_workflow_context` | Three explicit verbs (`updates` / `replace` / `unset`) on workflow-relative paths, OR legacy `{ contextKey, value }` for wholesale per-key replacement | **Workflow-level, not step-level.** `update_step` cannot reach `context.*`. See workflow-level merge model below. |
+| `metadata` | `update_workflow_context` | Same three verbs on `metadata.*` paths; one-level shallow-merge under `updates.metadata` | Workflow-level. Metadata edits bypass the draft snapshot (write direct to Pipeline row even on live workflows). |
+
+**Type changes.** `step.type` is technically mutable but stale type-specific fields (`pipelineStepPrompt`, `app`, `tools`, `orchestratorConfig`) persist unless you `unset` them. For clean conversions, prefer `remove_step` + `add_step`. If editing in place, list the incompatible fields under `unset`.
+
+**Live workflows.** Edits are routed to a draft snapshot. Response includes `editingDraft: true`. Inspect via `get_draft`, ship via `promote_draft`, throw away via `discard_draft`. For high-stakes edits, `create_snapshot` first as a manual checkpoint.
+
+**Draft staleness.** When a draft already exists, every `update_step` / `get_step` response carries a `draft` summary:
+
+```jsonc
+"draft": {
+  "exists": true,
+  "draftCreatedAt": "...",
+  "liveUpdatedAt": "...",
+  "stale": true,                  // live advanced past draft.createdAt
+  "modifiedStepIds": ["step-x"],  // step IDs whose JSON differs between draft and live
+  "modifiedFields": ["steps"]     // top-level config keys that differ
+}
+```
+
+If `draft.stale === true`, the live workflow has been touched (template upgrade, UI edit, deploy) since the draft was forked. Promoting the draft will land its values for fields you didn't touch in this session — those values may be older than current live. Recovery: `discard_draft` and re-apply your edit, or call `get_draft` to inspect what's pending. The `update_step` response also pushes a staleness string into `warnings[]`.
 
 **Never** send a full `steps[]` array via `update_workflow`. Use `update_step`, `add_step`, `remove_step` instead.
 
+#### Workflow-level merge model (`update_workflow_context`)
+
+`update_workflow_context` is the workflow-level analog of `update_step` — same three verbs, but on **workflow-relative paths** (`context.executionInputConfig.fields`, `metadata.tags`, …). Step-relative paths like `pipelineStepPrompt.template` are rejected here, and conversely `update_step` rejects `context.*` / `metadata.*` paths. The boundary is hard.
+
+Allowed path prefixes for `replace[]` / `unset[]`:
+
+- `context.inputPages`
+- `context.outputPages`
+- `context.executionInputConfig`
+- `metadata`
+
+Out-of-scope paths (e.g. `steps`, `name`) → `PATH_OUT_OF_SCOPE` (400). Other typed errors mirror `update_step`: `EMPTY_PAYLOAD`, `INVALID_PATH`, `REPLACE_VALUE_MISSING`, `UNSET_PATH_NOT_FOUND`. The response includes `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]` (≥6 silent removals fires the warning).
+
+Recipes:
+
+```jsonc
+// Flip executionInputConfig.internal — same merge-order trap as update_step.
+// Fetch (get_workflow), merge locally, replace at the parent level:
+{
+  "updates": { "context": { "executionInputConfig": {...full merged executionInputConfig with internal: true...} } },
+  "replace": ["context.executionInputConfig"]
+}
+
+// Replace inputPages wholesale:
+{
+  "updates": { "context": { "inputPages": [...new pages...] } },
+  "replace": ["context.inputPages"]
+}
+
+// Add a metadata tag (one-level shallow-merge — siblings preserved):
+{ "updates": { "metadata": { "tags": ["beta"] } } }
+
+// Delete an obsolete metadata key:
+{ "unset": ["metadata.legacyFlag"] }
+```
+
+Live workflows: context edits route to the draft snapshot. Metadata is NOT part of the snapshot config — it always writes direct to the Pipeline row, immediately and on the live workflow.
+
+⚠ **Mixed metadata + context in one call** is the sharp edge: metadata is applied immediately while context becomes pending in the draft. `discard_draft` reverts the pending context changes but **does NOT revert metadata** — metadata never went to the draft. If you need a single atomic checkpoint covering both, `create_snapshot` first or split the call into two.
+
+A legacy `{ contextKey, value }` body shape is still accepted as a **compatibility shape** for one-shot wholesale replacement of a single root context key. It can't edit metadata, doesn't return `diff` / `warnings`, and is not the recommended path for new code — prefer the three-verb shape above.
+
 ### Post-authoring
 
 6. Test: `start_workflow` with sample input
@@ -234,6 +330,41 @@ Be explicit about which Agentled workspace you are operating on.
 - Override a single CLI command with `agentled --workspace <workspace> ...` or `AGENTLED_WORKSPACE=<workspace> ...`.
 - Before making destructive or customer-visible changes, confirm the target workspace via `get_workspace` or `agentled auth current`.
 
+## Local Workspace Folder — `agentled_<workspace-slug>/`
+
+When working on Agentled tasks for a user (sourcing kits, workflow design, debugging executions, anything that spans more than a single tool call), **organize all local artifacts under a per-workspace folder named `agentled_<workspace-slug>/`** in the user's current working directory. The slug comes from the active workspace alias (e.g. `agentled_acme/`, `agentled_my-company/`) so a user with multiple workspaces never mixes their data. Resolve the slug from `agentled auth current` (use the alias if set, otherwise the workspace ID). Create the folder on first use; never scatter notes, JSON drafts, or transcripts at the repo root or under a generic `agentled_workspace/` name.
+
+**Required structure (replace `<slug>` with the actual workspace slug):**
+
+```
+agentled_<slug>/
+  README.md                 # what this folder is, current active workspace, last sync to KG
+  decisions/                # one file per non-trivial decision (theme, schema, source list, etc.)
+    YYYY-MM-DD-<slug>.md    # context · options considered · decision · rationale · revisit-when
+  workflows/                # local drafts and copies of pipeline JSON before push
+    <workflow-id>.json      # snapshot of the live workflow (use get_workflow → write file)
+    <slug>.draft.json       # work-in-progress before create_workflow
+  groups/                   # WorkflowGroup specs (see WG-001) — one file per group
+    <group-slug>.kit.json
+  kg/                       # local mirrors / drafts of KG content
+    lists/<listKey>.schema.json
+    text/<key>.md           # workspace company profile, theme docs, etc., before upserting
+  executions/               # debug bundles for failed runs
+    <executionId>/timeline.json, step-outputs/, notes.md
+  worklog.md                # append-only chronological log of what was done, in 1-2 lines per entry
+```
+
+**Why a local folder at all when the KG already stores state?**
+- KG is *workspace truth* — durable, structured, queryable. The local folder is *agent scratch* — drafts, decision rationale, raw debug data, transcripts. Mixing them pollutes the KG and loses local iteration history.
+- Decisions ("we chose theme X for next edition", "we picked OpenVC + Crunchbase as initial sources") need a paper trail with reasoning. KG entries should carry the *outcome*, not the deliberation.
+- Workflow drafts often go through 3-5 iterations before push — keep them local until ready.
+
+**Sync rule:** at the end of any meaningful working session — and explicitly when the user says "save", "wrap up", "we're done for now" — summarize what's *durable and reusable* (final decisions, current themes, active sources, workflow purpose statements) and write it to the workspace KG via `upsert_knowledge_text` (for narrative docs) or `upsert_knowledge_rows` (for structured data). Use stable, predictable keys: `decisions.current-theme`, `groups.<slug>.spec`, `workflows.<id>.purpose`. Append a one-line entry to `worklog.md` recording what was synced and when.
+
+**Don't sync:** raw debug bundles, full execution timelines, abandoned drafts, transcripts. Those stay local. Sync only what a future session — or another agent — will actually need to pick up the work.
+
+**On session start:** if `agentled_<slug>/` for the active workspace already exists, read `README.md` and the most recent `decisions/` and `worklog.md` entries before proposing anything new. If it doesn't exist, ask the user once whether they want you to create it for this project, then proceed. If the user has multiple workspaces, only act on the folder matching the currently active workspace from `agentled auth current` — never operate on a sibling folder.
+
 ## Pipeline Structure
 
 Every workflow needs at minimum: a trigger step, one or more action steps, and a milestone (terminal) step. Steps are connected via `next: { stepId: "..." }`.

package/skills/agentled/WHY-AGENTLED.md

@@ -0,0 +1,15 @@
+# Why Agentled: The Automation Engine for AI Agents
+
+**One credit system. 100+ integrations. No API juggling.**
+
+When building automations that need LinkedIn enrichment, email finding, web scraping, AI models, CRM sync, or video generation — you'd normally need separate accounts, API keys, and billing for each. Agentled bundles all of this under a single credit system. One subscription, one bill, everything available as workflow steps.
+
+**What you get for free by using Agentled (instead of rolling your own):**
+
+- **Cache per step** — enrichment results and expensive API calls are cached with a TTL. Re-running a workflow doesn't re-fetch data that hasn't changed. No extra credits burned on duplicate work.
+- **Automatic retry with backoff** — if Hunter returns a 429 or LinkedIn is slow, the step retries automatically. You never write retry loops.
+- **Persistent Knowledge Graph** — the KG stores results across executions. Scoring workflows get smarter over time. Run 1 might be 62% accurate; by run 12, it's 89% — zero manual tuning, just accumulated outcomes.
+- **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. Per-step caching is automatic. For cross-run row dedup, use `kg.upsert-rows` with a `userKey` (not `kg.add-rows`, which always inserts).