@agentled/cli 0.1.6 → 0.5.0

package/patterns/v1/03-credit-efficiency.md

@@ -0,0 +1,130 @@
+# 03 — Credit efficiency: not burning money while building
+
+**Problem**: Developers restart full workflow executions to debug a single failed step, burning credits on work that was already done correctly.
+
+**Why it fails silently**: The restarted execution appears to succeed. The wasted spend accumulates in the background — 3–5× expected credit usage during development — until the invoice arrives.
+
+---
+
+## The core discipline: fix → retry → verify
+
+Every debugging cycle should follow exactly this sequence:
+
+1. **Identify** the failed step and its error
+2. **Fix** the configuration, prompt, or code
+3. **Retry from the failed step** — not from the beginning
+4. **Verify** the step output
+
+Starting a new full execution to debug a failed step is the most expensive habit in agentic development. It re-runs every step that already succeeded: the enrichment API call, the LLM prompt, the database read. All paid again. None of them changed.
+
+---
+
+## Anti-pattern
+
+```
+Execution fails at step 5 (AI scoring)
+→ Developer reads the error
+→ Fixes the prompt
+→ Starts a NEW execution from step 1
+→ Steps 1-4 run again: enrichment (5 credits), profile fetch (2 credits), web scrape (0 credits), data parse (0 credits)
+→ Step 5 runs with the fixed prompt
+→ Total wasted: 7 credits × every debug cycle
+```
+
+In a workflow with 3 debug cycles per feature: 21 wasted credits before it works.
+
+---
+
+## Correct pattern
+
+```
+Execution fails at step 5 (AI scoring)
+→ Developer reads the error
+→ Fixes the prompt in the workflow config
+→ Retries from step 5 — the platform reuses outputs from steps 1-4
+→ Step 5 runs with the fixed prompt
+→ Total wasted: 0 credits
+```
+
+Most workflow platforms expose a "retry from this step" action on failed executions. Use it every time.
+
+---
+
+## Test steps in isolation before wiring them
+
+Before adding a step to a live workflow, test it standalone with representative input data:
+
+```bash
+# Test an AI step with real input — no execution, no credits for upstream steps
+test_ai_action(
+  template: "Analyze this company: {{input.company}}. Score fit 0-100.",
+  responseStructure: { score: "number", reasoning: "string" },
+  input: { company: { name: "Stripe", industry: "fintech", employees: 4000 } }
+)
+
+# Test a code step in the same sandbox as production
+test_code_action(
+  code: "return input.items.filter(i => i.score > 70)",
+  input: { items: [{ name: "A", score: 85 }, { name: "B", score: 60 }] }
+)
+```
+
+This catches errors before they're in a running execution. Zero credits for upstream steps.
+
+---
+
+## Mock downstream steps with prior output
+
+When you need to test a downstream step (step 6) but don't want to re-run expensive upstream steps (steps 1-5):
+
+1. Find a prior execution where steps 1-5 succeeded
+2. Copy the output of step 5 from that execution
+3. Use it as mock input to `test_ai_action` or `test_code_action` for step 6
+
+```javascript
+// Prior execution step 5 output (saved from execution abc-123):
+const priorOutput = {
+  company: { name: "Stripe", score: 85, signals: ["YC", "series B"] }
+};
+
+// Test step 6 in isolation using that output
+test_ai_action(
+  template: "Based on this profile, draft a 3-sentence outreach: {{input.company}}",
+  input: priorOutput
+)
+```
+
+No re-enrichment. No re-fetching. No wasted credits.
+
+---
+
+## One execution at a time
+
+Don't start a new execution while one is in flight for the same workflow. Reasons:
+- Parallel executions on the same data produce duplicate writes
+- You can't read the output of execution A while debugging it if execution B is also running
+- If both fail, you now have two half-processed states to reconcile
+
+The discipline: start → observe → retry or fix → verify. Sequential, not parallel.
+
+---
+
+## Credit cost by step type (reference)
+
+| Step type | Typical cost | Notes |
+|---|---|---|
+| AI action (standard model) | 5–15 credits | Varies by model tier and output length |
+| Data enrichment (LinkedIn, Hunter) | 2–5 credits | Per-record cost |
+| Web scrape | 0 credits | Free |
+| HTTP request | 0 credits | Free |
+| Code step | 0 credits | Free |
+| Knowledge graph read/write | 1 credit | Flat |
+| Browser automation | 10–15 credits | Per task |
+
+Expensive steps are AI and enrichment. These are the ones you never want to re-run unnecessarily.
+
+---
+
+## One-line rule
+
+> When a step fails, fix it and retry from that step — never start a new execution; use isolated step testing to catch errors before they're in a running workflow.

package/patterns/v1/04-loop-patterns.md

@@ -0,0 +1,147 @@
+# 04 — Loop patterns: iterating without N+1 or data loss
+
+**Problem**: Loops in agentic workflows silently drop items, produce N+1 API calls, or pass incomplete results to downstream steps because the loop hasn't finished yet.
+
+**Why it fails silently**: A loop that processes 10 items looks the same in logs as one that processes 9 — the missing item has no error, just an absence. Downstream steps that read loop output before completion get partial data with no warning.
+
+---
+
+## The loop completion trap
+
+The most common loop mistake: a downstream step reads loop results before the loop has finished.
+
+```yaml
+# Wrong: downstream step starts before loop finishes
+steps:
+  - id: enrich-companies
+    type: loop
+    over: "{{input.companies}}"
+    step: enrich-each
+
+  - id: generate-report   # starts immediately, reads partial results
+    type: ai-action
+    input: "{{steps.enrich-companies.results}}"
+```
+
+In async execution, `generate-report` may start with 3 of 10 companies enriched. The report is incomplete. No error is raised.
+
+---
+
+## Anti-pattern
+
+```yaml
+# Wrong: no loop completion gate
+- id: process-items
+  type: loop
+  over: "{{steps.fetch.items}}"
+  step: process-each
+
+- id: summarize   # may run with 0 items if loop is still in flight
+  type: ai-action
+  prompt: "Summarize these results: {{steps.process-items.outputs}}"
+```
+
+---
+
+## Correct pattern
+
+Add a `loop_completion` entry condition on every step that consumes loop output:
+
+```yaml
+- id: process-items
+  type: loop
+  over: "{{steps.fetch.items}}"
+  step: process-each
+
+- id: summarize
+  type: ai-action
+  entryConditions:
+    onCriteriaFail: "wait"          # block until condition is met
+    conditionText: "Wait for all processing to complete"
+    criteria:
+      - type: loop_completion
+        stepId: process-items       # which loop to wait for
+        operator: "=="
+        value: true
+  prompt: "Summarize these results: {{steps.process-items.outputs}}"
+```
+
+`onCriteriaFail: "wait"` blocks this step until all loop iterations finish. The step then runs once with the complete output.
+
+---
+
+## Pairing loop results back to source records
+
+After a loop that calls an external API or runs an AI step per item, you often need to pair each result back to the original record for a KG or CRM write.
+
+The problem: loop outputs are indexed by iteration order, not by the original record's ID.
+
+```javascript
+// Code step: pair loop outputs with source records
+const sourceItems = input.sourceItems;        // original array
+const loopOutputs = input.loopOutputs;        // same-length array of results
+
+return sourceItems.map((item, index) => ({
+  ...item,                                     // original fields
+  ...loopOutputs[index],                       // enriched fields
+  sourceId: item.id,                           // explicit ID link
+}));
+```
+
+Place this code step after the loop completion gate, before the write step.
+
+---
+
+## N+1: when to loop vs when to batch
+
+A loop that calls an LLM or enrichment API once per item is an N+1 pattern. For 100 items: 100 API calls, 100 credit charges, 100× the latency.
+
+**Ask: does the API support batch input?**
+
+```yaml
+# Wrong (N+1): one LLM call per item
+- id: classify-each
+  type: loop
+  over: "{{input.emails}}"
+  step:
+    type: ai-action
+    prompt: "Classify this email: {{currentItem.body}}"
+
+# Correct (batch): one LLM call for all items
+- id: classify-all
+  type: ai-action
+  prompt: |
+    Classify each of these emails. Return a JSON array in the same order.
+    Emails: {{input.emails}}
+  responseStructure:
+    classifications: "array of { id: string, category: string, priority: string }"
+```
+
+Not every step supports batching — enrichment APIs often don't. But AI steps almost always do. Default to batch for AI classification, extraction, and scoring over lists.
+
+---
+
+## Fire-and-forget anti-pattern
+
+```yaml
+# Wrong: loop dispatches child workflows with no completion tracking
+- id: dispatch-scoring
+  type: loop
+  over: "{{input.candidates}}"
+  step:
+    type: call-workflow
+    workflowId: score-candidate
+    input: "{{currentItem}}"
+
+- id: aggregate-scores   # starts immediately — child workflows haven't finished
+  type: ai-action
+  prompt: "Aggregate these scores: {{steps.dispatch-scoring.outputs}}"
+```
+
+When the loop calls child workflows, completion tracking is especially important — child workflow execution time varies. Always add a `loop_completion` gate before aggregating.
+
+---
+
+## One-line rule
+
+> Always gate the step that consumes loop output on `loop_completion` with `onCriteriaFail: "wait"` — loops run asynchronously and downstream steps will read partial data without it.

package/patterns/v1/05-child-workflow-contracts.md

@@ -0,0 +1,151 @@
+# 05 — Child workflow contracts: composable workflows with typed returns
+
+**Problem**: Monolithic workflows become unmaintainable, and child workflows called from orchestrators fail silently because their return contracts aren't defined — the calling workflow gets `undefined` for every field it tries to read.
+
+**Why it fails silently**: A child workflow that ends with a `milestone` step instead of a `return` step completes successfully from the platform's perspective. The calling workflow receives no data and no error. Every field reference like `{{steps.call-child.score}}` resolves to empty string.
+
+---
+
+## The milestone vs return mistake
+
+```yaml
+# Wrong: child workflow ends with milestone
+- id: score-company
+  type: ai-action
+  prompt: "Score this company 0-100..."
+  responseStructure:
+    score: "number"
+    decision: "string"
+
+- id: done           # ← milestone = terminal, no data returned to caller
+  type: milestone
+  name: "Complete"
+```
+
+The calling orchestrator runs `call-workflow` and gets back nothing. `{{steps.call-child.score}}` is empty. No error is raised.
+
+---
+
+## Anti-pattern
+
+```yaml
+# Wrong: child workflow
+steps:
+  - id: enrich
+    ...
+  - id: score
+    ...
+  - id: done           # milestone doesn't return data
+    type: milestone
+
+# Calling orchestrator:
+- id: call-child
+  type: call-workflow
+  input: { companyUrl: "{{input.url}}" }
+
+- id: use-result
+  type: ai-action
+  prompt: "Based on score {{steps.call-child.score}}..."
+  # ^ always empty — milestone returned nothing
+```
+
+---
+
+## Correct pattern
+
+Child workflows must end with a `return` step that explicitly declares what they return:
+
+```yaml
+# Correct: child workflow
+steps:
+  - id: enrich
+    ...
+  - id: score
+    type: ai-action
+    responseStructure:
+      score: "number 0-100"
+      decision: "invest | pass | monitor"
+      summary: "string"
+
+  - id: return-results    # ← return step, not milestone
+    type: return
+    returnConfig:
+      fields:
+        - name: score          # the name the caller uses
+          stepId: score        # which step produced it
+          field: score         # which field from that step
+        - name: decision
+          stepId: score
+          field: decision
+        - name: summary
+          stepId: score
+          field: summary
+
+# Calling orchestrator:
+- id: call-child
+  type: call-workflow
+  input: { companyUrl: "{{input.url}}" }
+
+- id: use-result
+  type: ai-action
+  prompt: "Based on score {{steps.call-child.score}}, decision: {{steps.call-child.decision}}..."
+  # ^ now populated correctly
+```
+
+---
+
+## Designing a return contract
+
+A return contract is the interface between the child workflow and its callers. Treat it like a function signature:
+
+1. **Be explicit**: list every field the caller might need — don't assume they'll dig into nested objects
+2. **Use flat field names**: `score` not `scoringCard.total_score` — callers reference these as template variables
+3. **Match names to caller expectations**: if the orchestrator uses `{{steps.call-child.decision}}`, the return contract must export a field named `decision`
+4. **Version changes carefully**: adding fields is safe; renaming or removing fields breaks every orchestrator that calls this child
+
+```yaml
+# Comprehensive return contract
+returnConfig:
+  fields:
+    - { name: score,           stepId: score-step,   field: total_score }
+    - { name: decision,        stepId: score-step,   field: decision }
+    - { name: summary,         stepId: score-step,   field: executive_summary }
+    - { name: teamEvaluations, stepId: eval-team,    field: evaluations }
+    - { name: rawData,         stepId: enrich,       field: companyProfile }
+```
+
+---
+
+## The god-workflow anti-pattern
+
+A single workflow with 25+ steps that handles intake, enrichment, scoring, routing, outreach, and CRM sync:
+
+```
+trigger → fetch → enrich → score → route → draft-email → approve → send → 
+update-crm → update-kg → notify-slack → generate-report → archive → done
+```
+
+Problems:
+- A failure in step 12 requires re-running steps 1-11
+- You can't reuse the scoring logic in another context
+- Testing requires running the entire pipeline end-to-end
+- A single developer change can break the entire flow
+
+**Break it into composable child workflows:**
+
+```
+Orchestrator:
+  trigger → call: enrich-workflow → call: score-workflow → call: route-workflow → done
+
+enrich-workflow:    fetch → enrich → return { profile }
+score-workflow:     receive profile → score → return { score, decision }
+route-workflow:     receive decision → route → draft → approve → send → return { sent }
+```
+
+Each child workflow can be tested independently, retried independently, and reused by other orchestrators.
+
+---
+
+## One-line rule
+
+> Child workflows must end with a `return` step (not `milestone`) with an explicit `returnConfig.fields` list — milestone completes silently with no data returned to the caller.

package/patterns/v1/06-conditional-routing.md

@@ -0,0 +1,151 @@
+# 06 — Conditional routing: conditions that actually fire
+
+**Problem**: Entry conditions on workflow steps silently fail to apply — steps run unconditionally, or skip unconditionally — because the wrong field names are used to configure them.
+
+**Why it fails silently**: The wrong field names (`conditions` instead of `criteria`, `field` instead of `variable`) are not validation errors. The platform silently ignores unrecognized fields and applies no condition at all. The step runs every time, or skips every time, with no visible indication that the condition isn't being evaluated.
+
+---
+
+## The field name trap
+
+This is the most subtle silent failure in workflow configuration. Two pairs of field names look interchangeable but aren't:
+
+| Wrong | Correct |
+|---|---|
+| `conditions` | `criteria` |
+| `field` | `variable` |
+
+```yaml
+# Wrong: unrecognized field names — condition is silently ignored
+entryConditions:
+  onCriteriaFail: "skip"
+  conditions:                    # ← wrong: should be "criteria"
+    - field: "{{input.score}}"   # ← wrong: should be "variable"
+      operator: ">"
+      value: 70
+
+# Correct: recognized field names — condition is evaluated
+entryConditions:
+  onCriteriaFail: "skip"
+  criteria:                      # ← correct
+    - variable: "{{input.score}}"  # ← correct
+      operator: ">"
+      value: 70
+```
+
+The wrong version doesn't error. The step runs unconditionally, as if no condition existed.
+
+---
+
+## Anti-pattern
+
+```yaml
+# Wrong: routes HOT leads to Slack, but the condition is silently ignored
+- id: notify-hot-lead
+  type: app-action
+  app: slack
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditions:                         # ← wrong field name
+      - field: "{{steps.score.category}}"  # ← wrong field name
+        operator: "=="
+        value: "HOT"
+  # Result: every lead triggers a Slack notification, including COLD and WARM
+```
+
+---
+
+## Correct pattern
+
+```yaml
+# Correct: HOT leads only
+- id: notify-hot-lead
+  type: app-action
+  app: slack
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditionText: "Only notify for HOT leads"
+    criteria:                                    # ← correct
+      - variable: "{{steps.score.category}}"    # ← correct
+        operator: "=="
+        value: "HOT"
+```
+
+---
+
+## How to verify a condition is actually firing
+
+When a condition behaves unexpectedly (step always runs, or always skips), check:
+
+1. **Field names**: is it `criteria`/`variable`? Not `conditions`/`field`?
+2. **Variable path**: does `{{steps.score.category}}` actually resolve? Check the referenced step's output in execution logs.
+3. **Value type**: comparing a string `"70"` to a number `70` with `>` may not work as expected — check that types match.
+4. **Null safety**: `isNotNull` checks should come before value comparisons to avoid null reference issues.
+
+```yaml
+# Pattern: null-safe condition chain
+criteria:
+  - variable: "{{steps.enrich.company}}"
+    operator: "isNotNull"          # check existence first
+  - variable: "{{steps.score.total}}"
+    operator: ">"
+    value: 70                      # then compare value
+```
+
+---
+
+## The LLM-as-router anti-pattern
+
+Using an AI step to make a binary routing decision that a simple condition can handle:
+
+```yaml
+# Wrong: burning 10 credits to decide yes/no
+- id: decide-routing
+  type: ai-action
+  creditCost: 10
+  prompt: |
+    Given this lead's score of {{steps.score.value}}, should we send a Slack alert?
+    Score above 80 means yes. Below 80 means no.
+    Return: { shouldAlert: boolean }
+
+- id: send-alert
+  entryConditions:
+    criteria:
+      - variable: "{{steps.decide-routing.shouldAlert}}"
+        operator: "=="
+        value: true
+```
+
+```yaml
+# Correct: free condition, no LLM call needed
+- id: send-alert
+  entryConditions:
+    onCriteriaFail: "skip"
+    conditionText: "Only alert for high-score leads"
+    criteria:
+      - variable: "{{steps.score.value}}"
+        operator: ">"
+        value: 80
+```
+
+Use AI for decisions that require reasoning, judgment, or context. Use conditions for decisions that follow a deterministic rule.
+
+---
+
+## `onCriteriaFail` reference
+
+| Value | Behavior |
+|---|---|
+| `"skip"` | Skip this step, continue to the next |
+| `"stop"` | Stop the entire execution |
+| `"wait"` | Block this step until criteria are met (used for loop/group completion) |
+
+Common mistakes:
+- Using `"stop"` when you mean `"skip"` — stops the whole workflow instead of just bypassing one step
+- Using `"skip"` when you mean `"wait"` — the step runs immediately with incomplete data instead of waiting for a loop to finish
+
+---
+
+## One-line rule
+
+> Always use `criteria` (not `conditions`) and `variable` (not `field`) in entry conditions — wrong field names are silently ignored and the condition never evaluates.