@agentled/cli 0.7.6 → 0.7.8

package/skills/agentled/references/step-schemas.md

@@ -0,0 +1,148 @@
+# Step Schemas & Template Variables
+
+> Loaded on demand from the Agentled skill. `get_step_schema` (MCP) and
+> `agentled schema --step-type <type>` (CLI) are the **authoritative** sources —
+> this file is a fast reference for the common shapes.
+
+## 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: "..." }`.
+
+```json
+{
+  "name": "My Workflow",
+  "goal": "What this workflow achieves",
+  "steps": [
+    { "id": "trigger", "type": "trigger", "name": "Start", "pipelineStepStartConditions": { "trigger": { "type": "manual" } }, "next": { "stepId": "action" } },
+    { "id": "action", "type": "aiAction", "name": "Analyze", "pipelineStepPrompt": { "template": "...", "responseStructure": {} }, "creditCost": 10, "next": { "stepId": "done" } },
+    { "id": "done", "type": "milestone", "name": "Complete" }
+  ],
+  "context": {
+    "executionInputConfig": {
+      "title": "Run Workflow",
+      "fields": [{ "name": "input_field", "label": "Input", "type": "text", "required": true }]
+    }
+  }
+}
+```
+
+## Step Types
+
+### Trigger
+```json
+{ "id": "trigger", "type": "trigger", "name": "Start", "pipelineStepStartConditions": { "trigger": { "type": "manual" } }, "next": { "stepId": "next-step" } }
+```
+
+`pipelineStepStartConditions.trigger.type` is one of: `manual`, `schedule`, `webhook`, `event`, `delay`, `app_event`. For `schedule` add `config: { frequency: "daily", time: "07:00" }` (or a cron expression). For `app_event` add `config: { appId, triggerSlug, connectionSource }`. **Do not put `triggerType` at the step root** — it is not in the step schema and is silently dropped on save.
+
+### App Action
+```json
+{
+  "id": "enrich",
+  "type": "appAction",
+  "name": "Enrich Company",
+  "app": { "id": "agentled", "actionId": "agentled.get-linkedin-company-from-url", "source": "native" },
+  "stepInputData": { "profileUrls": "{{input.company_url}}" },
+  "next": { "stepId": "next-step" }
+}
+```
+
+### AI Action
+```json
+{
+  "id": "analyze",
+  "type": "aiAction",
+  "name": "Analyze",
+  "pipelineStepPrompt": {
+    "template": "Analyze this company: {{steps.enrich.company}}",
+    "responseStructure": { "score": "number 0-100", "summary": "string" }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "next-step" }
+}
+```
+
+### AI Step Model & Provider Configuration
+
+AI steps can optionally specify a model and provider via the `agent` field:
+
+```json
+{
+  "id": "analyze",
+  "type": "aiAction",
+  "agent": { "model": "claude-4-6-sonnet", "provider": "anthropic" },
+  "pipelineStepPrompt": { "template": "...", "responseStructure": {} },
+  "creditCost": 10,
+  "next": { "stepId": "next-step" }
+}
+```
+
+**Supported Providers:** `openai`, `anthropic`, `google`, `mistral`, `deepseek`, `kimi`, `minimax`, `bytedance`, `perplexity`, `xai`
+
+**Supported Models by Provider:**
+
+| Provider | Models |
+|----------|--------|
+| `openai` | `gpt-5-nano`, `gpt-5-mini`, `gpt-5.4`, `o4-mini`, `o3`, `o3-pro`, `o3-deep-research` |
+| `anthropic` | `claude-4-6-sonnet`, `claude-4-5-haiku`, `claude-4-6-opus` |
+| `google` | `gemini-3-pro`, `gemini-3-flash`, `gemini-2.5-pro`, `gemini-2.5-flash` |
+| `mistral` | `mistral-large-latest`, `mistral-small-latest`, `codestral-latest` |
+| `deepseek` | `deepseek-chat`, `deepseek-reasoner` |
+| `kimi` | `kimi-k2.5` |
+| `minimax` | `minimax-m2.5` |
+| `bytedance` | `doubao-seed-1.6-flash`, `seed-2.0-mini`, `doubao-seed-1.8-beta` |
+| `perplexity` | `sonar-pro`, `sonar`, `sonar-reasoning-pro`, `sonar-reasoning` |
+| `xai` | `grok-4.3`, `grok-3-mini` |
+
+> **Tip:** Use `list_models` to get the full up-to-date list of supported model IDs. Use the internal model IDs (e.g., `claude-4-6-sonnet`), NOT the raw API model IDs (e.g., `claude-sonnet-4-6`). Using unsupported model IDs will result in a validation error.
+
+### Code Step
+```json
+{
+  "id": "transform",
+  "type": "code",
+  "name": "Transform Data",
+  "codeConfig": { "language": "javascript", "code": "const data = {{steps.prev.output}};\nreturn data.map(x => x.name);" },
+  "next": { "stepId": "next-step" }
+}
+```
+
+### Milestone (terminal)
+```json
+{ "id": "done", "type": "milestone", "name": "Complete" }
+```
+
+## Template Variables
+
+| Pattern | Description |
+|---------|-------------|
+| `{{input.fieldName}}` | Input page field value |
+| `{{steps.stepId.field}}` | Previous step output |
+| `{{currentItem}}` | Current item in a loop |
+| `{{currentItem.field}}` | Nested field in loop item |
+
+## Loop Configuration
+
+To iterate over a list from a previous step:
+```json
+{
+  "loopConfig": { "enabled": true, "field": "{{steps.prev.items}}", "ItemAlias": "currentItem" }
+}
+```
+
+## Entry Conditions
+
+Skip or stop a step based on prior output:
+```json
+{
+  "entryConditions": {
+    "onCriteriaFail": "skip",
+    "conditionText": "Skip if no URL",
+    "criteria": [{ "variable": "{{input.url}}", "operator": "isNotNull" }]
+  }
+}
+```
+
+Operators: `==`, `!=`, `>`, `<`, `isNull`, `isNotNull`, `contains`.
+
+**Important**: Use `criteria` (not `conditions`) and `variable` (not `field`).

package/skills/agentled/references/workspace-folder.md

@@ -0,0 +1,74 @@
+# Local Workspace Folder & Workspace Surfaces
+
+> Loaded on demand from the Agentled skill. Read this when a task spans more
+> than a single tool call and produces local artifacts (drafts, decisions,
+> debug bundles), or when seeding a templated workspace's sidebar/home.
+
+## 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`. For any group of workflows that forms a client-facing workspace pipeline, also create or update a client-readable KG text guide such as `<workspace-or-pipeline>.design`, `groups.<slug>.guide`, or `pipelines.<slug>.design`. Put the client explanation first (what it does, how it works, where data comes from, how approvals/sync/reporting work), then put workflow IDs, caveats, and debug details under "Operator Notes." Append a one-line entry to `worklog.md` recording what was synced and when.
+
+**Worksession feedback:** in the final user-facing wrap-up for each meaningful working session, include a concise retrospective: what worked, what did not work or blocked progress, concrete improvements for the next session, and any follow-up risks. If the feedback is about Agentled itself — CLI behavior, MCP tools, workflow validation, app integrations, docs, missing capabilities, confusing errors, or platform behavior — send it to the Agentled team with the `submit_feedback_to_agentled` MCP tool when available. From the CLI, use `agentled feedback submit --type <bug|feature_request|escalation|ask> --title "<title>" --description "<details>"`.
+
+**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.
+
+## Workspace Surfaces
+
+The workspace home and sidebar carry workspace-level UI state on `Workspace.metadata`. These surfaces are read-only via the MCP today (most tooling does not need to write them), but agents authoring templated workspaces should know they exist:
+
+### Pinned outputs (sidebar shortcuts)
+
+`Workspace.metadata.pinnedOutputs[]` lists output pages that appear in the sidebar **after Knowledge & Data**, always visible regardless of which workflow is currently open. Operators set these manually from each output page's configuration sheet (toggle: *"Pin to workspace home"*). Pin sparingly: only pin output pages that are useful as direct workspace-level destinations, such as a recurring report, scoring dashboard, or canonical results list. Do not pin every output page, implementation detail, approval surface, or one-off execution artifact; normal workflow output pages remain accessible from the workflow itself. Each entry:
+
+```json
+{
+  "pipelineId": "wfl_abc123",
+  "pipelinePathname": "deal-flow",
+  "outputPagePathname": "weekly-report",
+  "label": "Weekly Investor Report",
+  "iconName": "FileText",
+  "pipelineName": "Deal Sourcing",
+  "colorTextClass": "text-emerald-700 dark:text-emerald-400",
+  "pinnedAt": "2026-05-09T10:00:00Z"
+}
+```
+
+All snapshot fields capture the source values at pin time and do not auto-update if the workflow or page is later renamed or restyled. To refresh, the operator unpins and re-pins.
+
+Sidebar rendering uses each field directly:
+- `label` is the primary line.
+- `pipelineName` renders in small muted text below the label, so two pins with the same `label` from different workflows are distinguishable.
+- `iconName` resolves to a lucide icon (defaults to `Pin` if missing or unknown).
+- `colorTextClass` is applied as a Tailwind class on the icon, mirroring the source workflow's accent. Use the same shape produced by the workflow style picker (e.g. `text-emerald-700 dark:text-emerald-400`).
+- The pin row renders as **active** when the operator's current URL matches the pin's target.
+
+When seeding a workspace via templates, pre-populate `pinnedOutputs[]` only for the curated artifacts the operator should access directly from the workspace sidebar on day one. Supply `pipelineName` and `colorTextClass` for the proper rendering (otherwise they fall back to the muted default, which still works but loses the visual cue). Pin entries reference output pages that exist on workflows in the same workspace; entries pointing at deleted or renamed pipelines still render — the URL just resolves to a 404 page until the pin is removed.