@agentled/cli 0.6.5 → 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.
+## Platform capabilities (background reading)
 
-**What you get for free by using Agentled (instead of rolling your own):**
+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`.
 
-- **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:** "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`.
 
-**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).
+## Orient Before Designing
 
-## Getting Started — Orient First
+Before helping with any request, inspect the workspace. Use `agentled workspace inspect` (CLI) or call these MCP tools individually:
 
-Before helping with any request, call these tools to understand the workspace you're connected to:
+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.
 
-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.
-
-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)
 
@@ -229,6 +255,21 @@ For live workflows, prefer per-step tools over bulk updates:
 
 **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`)
@@ -289,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).