@agentled/cli/scaffolds/README.md

CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.

# CLI scaffolds

Each `*.json` file in this directory is a **preflight-clean pipeline skeleton**
keyed to one of the patterns in `agentic-ops/patterns/v1/` (canonical) or
`packages/cli/patterns/v1/` (byte-identical mirror).

Scaffolds are **pattern shapes, not domain templates.** The goal is to give
an agent (or human) a known-good starting point for a structural shape —
loop over a KG list, composed email with approval, conditional alert on
threshold, etc. — not to ship templates for every possible business use case.

## Contract

Every bundled scaffold:

1. Passes `agentled workflows validate --file <scaffold>` with zero errors
   and zero warnings.
2. Has a clear `name` and `goal` field that describes the pattern shape.
3. References the matching agentic-ops pattern number(s) in its `description`.
4. Uses domain-agnostic placeholder names (`candidate`, `metric_a`,
   `entity_id`) — not specific verticals.

> **Read [`patterns/v1/00-design-principles.md`](../patterns/v1/00-design-principles.md) first.** It defines the four pillars (idempotency, small scope, KG-list-as-connector, design-as-data) and the decision tree that tells you which scaffold to pick.

## Catalog

| Slug | Pattern(s) | Shape |
|------|-----------|-------|
| `minimal` | — | trigger → milestone (smallest valid pipeline) |
| `ai-with-tools` | — | trigger → `aiActionWithTools` (web_search + workspace_memory) → milestone |
| `email-polling-dedup` | 02 + 13 | schedule → fetch emails (label dedup) → loop process → add label |
| `lead-scoring-kg` | 04 + 09 | trigger → kg.read-list → AI scoring loop → knowledgeSync → report |
| `list-match-email` | 08 | trigger → kg.read-list → AI match top candidates → composed email (approval gate) → knowledgeSync |
| `extract-threshold-alert` | 06 + 09 | trigger → AI extract → threshold check (code) → external update → conditional Slack alert → knowledgeSync |
| `source-to-kg` | 12 + 15a | schedule → generate queries → search → extract → kg.upsert-rows(`userKey`, status:`new`) — idempotent sourcing half of a two-workflow group |
| `kg-process-update` | 12 + 15b | schedule → kg.read-list(status:`new`) → loop process → kg.update-rows(status:`processed`) — processing half of a two-workflow group |
| `child-with-return` | 05 + 12 | manual → enrich → score → `return` (internal:true, called via call-workflow) |
| `orchestrator-kg-loop` | 11 | manual → kg.read-list → loop call-workflow per row → wait loop_completion → kg.update-rows → summarize |

## Bring your own scaffolds

The bundled set is deliberately small. Workspaces, teams, or customers who
have recurring workflow shapes should maintain their own scaffold library
outside this CLI release cycle:

1. Drop JSON files in `~/.agentled/scaffolds/` or set
   `AGENTLED_SCAFFOLDS_DIR=/path/to/your/scaffolds`.
2. Run `agentled workflows scaffold --list` — local scaffolds appear with
   a `[local]` tag next to their name.
3. Local slugs **shadow bundled ones** with the same name, so a team can
   override `list-match-email.json` with a locally-tuned version without
   forking the CLI.

Any JSON in those directories must also pass `workflows validate --file`.
The CLI doesn't gate this at load time — but a scaffold that fails preflight
will waste an operator's time, which is exactly what the scaffold set is
meant to prevent.

## Editing the bundled set

The bundled scaffolds are meant to stay small and pattern-focused. If you
want to propose a new one:

- It must map to an existing agentic-ops pattern (or come with a new pattern).
- It must be domain-agnostic — name fields `candidate` / `metric_a` /
  `entity_id`, not `mentor` / `mrr` / `companyId`.
- The `description` must state the pattern number it demonstrates.
- Commit both the scaffold and a preflight test verifying it passes.