ethos-cli 0.7.1 → 0.7.3

package/skills/launch-gifting-campaign.md

@@ -0,0 +1,310 @@
+---
+name: launch-gifting-campaign
+description: Open Ethos in a browser for recipient CSV upload, collect gift preference, search stored gift catalog options, create a structured gifting agent column, and guide creation of a gifting campaign.
+---
+
+# launch-gifting-campaign
+
+Use this when the user wants to launch a gifting campaign from a CSV of target
+recipients or accounts. Keep CSV upload in the browser-based Ethos product
+flow; do not replace it with `ethos tables import-csv` unless the user
+explicitly asks for a CLI-only fallback.
+
+Never name the external catalog/source used for gift options. Say "gift
+catalog", "gift options", or "catalog item".
+
+Do not refresh or reload the table page after creating columns, running
+columns, or writing cells. The table updates live; refreshing creates
+unnecessary UX friction. Only reload if the user explicitly asks.
+
+Keep user-facing updates concise and status-oriented. Do not expose internal
+skill wording, step numbers, variable names, command names, config JSON, run
+ids, or column ids unless the user explicitly asks for debugging detail.
+
+## Required CLI
+
+The Ethos CLI (`ethos`) is required. If `ethos` is not installed or not on
+`PATH`, install the latest CLI and retry:
+
+```sh
+npm install -g ethos-cli@latest --prefer-online
+```
+
+If a command fails because the CLI is not authenticated, run:
+
+```sh
+ethos auth login --agent-client auto
+```
+
+then retry the failed command.
+
+## Core Architecture
+
+Create one structured agent column as the source of truth for gifting setup.
+Do not create separate imported columns for Gift, Price, Shipping Time,
+Reasoning, Shipping Address, or Personalized Note. Those values live as JSON
+fields in the agent column and can be expanded in the UI when the user wants to
+inspect them.
+
+The gifting agent column must have `config.kind = "gifting_campaign"` and
+these output fields:
+
+- `gift_catalog_item_id`
+- `gift_name`
+- `gift_price`
+- `gift_shipping_time`
+- `gift_reasoning`
+- `shipping_address`
+- `address_status`
+- `personalized_note`
+- `research_summary`
+- `gift_signal`
+- `fallback_search_query`
+- `evidence_url`
+- `confidence:integer`
+
+The campaign builder imports virtual variables from this structured column:
+`gift_catalog_item_id`, `gift_name`, `gift_price`, `gift_shipping_time`,
+`gift_reasoning`, `shipping_address`, and `personalized_note`. Expansion is
+optional and should not become the source of truth.
+
+## Flow
+
+1. Use the hook-created upload handoff first. If context contains an injected
+   handoff for this flow, reuse its `handoff_token` and `upload_url`; do not
+   run `ethos flows start` again. On Codex, open `upload_url` in the in-app
+   Browser. On shell clients, the hook or `--open` may already open the OS
+   browser.
+
+2. Only when no hook handoff was injected, run:
+
+   ```sh
+   ethos flows start launch-gifting-campaign --agent-client auto --json
+   ```
+
+   Add `--open` only on shell clients. On Codex, do not pass `--open`; open
+   `response.upload_url` in the in-app Browser. Save `response.agent_client`
+   as `AGENT_CLIENT`; if it is unavailable, use `codex` on Codex and
+   `claude-desktop` on Claude.
+
+3. Immediately ask the requirement question while the CSV uploads. If
+   `response.next_prompt` is available, ask that exact prompt. Otherwise ask:
+
+   ```text
+   Please answer these while the CSV uploads:
+   - What type of gift should I send?
+   - Should I pick the same gift for everyone, or should I research each recipient and pick individually?
+   - Do you want personalized notes included?
+
+   For example: "dessert, research each person, include notes" or "cupcakes, one gift for everyone, no notes."
+   ```
+
+   Save the gift category as `GIFT_BRIEF`, the selection mode as
+   `GIFTING_MODE` (`same_gift`, `personalized_research`, or a deterministic
+   user-specified split), and the note preference as `INCLUDE_NOTES`. If the
+   user only gives a gift category, ask the missing mode and note questions
+   before creating any agent column.
+
+4. Capture the uploaded table:
+
+   ```sh
+   ethos flows wait "$HANDOFF_TOKEN" --json
+   ```
+
+   Save `response.table_id` and `response.org_id`.
+
+5. Inspect the uploaded table:
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" tables get "$TABLE_ID" --json
+   ```
+
+   Identify a small, stable set of recipient inputs: full name, LinkedIn URL,
+   company name, job title, company domain/website, person location, and the
+   best available business/work address column. Prefer business/work address
+   columns when both work and home address columns exist. Avoid optional
+   descriptive fields like company keywords, long descriptions, social URLs, or
+   previous enrichment evidence unless the user specifically asks to use them.
+   If no address column exists, ask whether to leave addresses missing for now
+   or use any raw address field the user identifies. Do not create a separate
+   address column.
+
+6. Search the stored gift catalog. Use a small set for same-gift campaigns and
+   a broader set for personalized research:
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" gifting catalog search "$GIFT_BRIEF" --limit 5 --json
+   ethos --org-id "$TABLE_ORG_ID" gifting catalog search "$GIFT_BRIEF" --limit 25 --json
+   ```
+
+   Show concise options with name, price, and shipping time when available. Do
+   not mention the external supplier. For same-gift mode, ask the user to
+   confirm the selected gift. For personalized research mode, use the broader
+   candidate set in the agent instructions. If the user asks for a
+   deterministic split, encode the split rule and selected catalog candidates
+   in the agent instructions.
+
+7. Create the gifting setup agent.
+
+   For same-gift or deterministic split campaigns, create a `person_enrichment`
+   agent that uses row data and the confirmed catalog candidates to produce the
+   structured gifting output. It does not need web abilities unless the user
+   asked for research.
+
+   For same-gift or deterministic split campaigns:
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" agents create \
+     --name "Gifting setup - <brief name>" \
+     --workflow-type person_enrichment \
+     --instructions "$AGENT_INSTRUCTIONS" \
+     --json
+   ```
+
+   For personalized research campaigns, add `web-search`, `web-fetch`, and
+   `linkedin-profile-lookup`. Only add `browser-use` and `--tool-preset
+   browser` when the research genuinely needs interactive or gated browsing.
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" agents create \
+     --name "Gifting setup - <brief name>" \
+     --workflow-type person_enrichment \
+     --ability web-search \
+     --ability web-fetch \
+     --ability linkedin-profile-lookup \
+     --instructions "$AGENT_INSTRUCTIONS" \
+     --json
+   ```
+
+   The instructions must tell the agent to return strict JSON with the output
+   fields above. `gift_price` must be the formatted price per gift including
+   currency when available, and `gift_shipping_time` must be the shortest
+   accurate shipping or delivery estimate available for the selected gift. Use
+   an empty string when either value is not available; do not guess. For
+   personalized research, tell it to research public LinkedIn and web
+   information, identify a gift signal, choose the best matching catalog
+   candidate, and include concise reasoning with a public link when useful. If
+   there is no strong public signal, use the best general campaign gift and
+   explain that no specific public preference was found. Never mention the
+   external catalog/source in instructions, output, notes, or chat.
+
+8. Create the structured gifting agent column:
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" tables columns create-agent "$TABLE_ID" \
+     --name "Gifting Campaign" \
+     --agent-id "$GIFTING_AGENT_ID" \
+     --prompt "$GIFTING_COLUMN_PROMPT" \
+     --output-field "gift_catalog_item_id" \
+     --output-field "gift_name" \
+     --output-field "gift_price" \
+     --output-field "gift_shipping_time" \
+     --output-field "gift_reasoning" \
+     --output-field "shipping_address" \
+     --output-field "address_status" \
+     --output-field "personalized_note" \
+     --output-field "research_summary" \
+     --output-field "gift_signal" \
+     --output-field "fallback_search_query" \
+     --output-field "evidence_url" \
+     --output-field "confidence:integer" \
+     --input-column "$RECIPIENT_NAME_COLUMN_ID" \
+     --input-column "$RECIPIENT_COMPANY_COLUMN_ID" \
+     --agent-client "$AGENT_CLIENT" \
+     --config-json '{"kind":"gifting_campaign"}' \
+     --json
+   ```
+
+   Pass only the stable recipient inputs identified above with repeated
+   `--input-column`; omit any placeholder input ids that do not exist. If the
+   command rejects an input column, re-read the table metadata, remove the
+   invalid id, and retry with the minimal stable set rather than broadening the
+   selected inputs.
+
+9. Run the first 3 rows only:
+
+   ```sh
+   ethos --org-id "$TABLE_ORG_ID" tables runs start "$TABLE_ID" "$GIFTING_COLUMN_ID" \
+     --scope count \
+     --row-count 3 \
+     --json
+   ```
+
+   Tell the user: "The gifting setup is running on the first 3 rows. Review
+   those results; if they look right, say go and I’ll run the rest." This is
+   the clear next step after the first run finishes.
+
+10. If the user approves, run the same column for empty rows. Do not create a
+    new column:
+
+    ```sh
+    ethos --org-id "$TABLE_ORG_ID" tables runs start "$TABLE_ID" "$GIFTING_COLUMN_ID" \
+      --scope empty \
+      --json
+    ```
+
+    Tell the user the remaining rows are running and that the next step is
+    creating the campaign from the table. Do not refresh the browser.
+
+11. If the user asks to change a specific generated field, update the JSON
+    field in the source agent cell. Do not edit an expanded projection as the
+    source of truth. Examples:
+
+    ```sh
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field personalized_note \
+      --value "$UPDATED_NOTE" \
+      --json
+
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field gift_catalog_item_id \
+      --value "$UPDATED_GIFT_CATALOG_ITEM_ID" \
+      --json
+
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field gift_name \
+      --value "$UPDATED_GIFT_NAME" \
+      --json
+
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field gift_price \
+      --value "$UPDATED_GIFT_PRICE" \
+      --json
+
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field gift_shipping_time \
+      --value "$UPDATED_GIFT_SHIPPING_TIME" \
+      --json
+
+    ethos --org-id "$TABLE_ORG_ID" tables cells set "$TABLE_ID" "$ROW_ID" "$GIFTING_COLUMN_ID" \
+      --field gift_reasoning \
+      --value "$UPDATED_REASONING" \
+      --json
+    ```
+
+12. Tell the user to use the table page's `Create campaign` button. Ethos will
+    route gifting-ready tables to the gifting campaign builder. The builder
+    should use:
+
+    - `gift_catalog_item_id` as the per-recipient gift id variable when present.
+    - `gift_name` as the gift name variable.
+    - `gift_price` / `price_per_gift` as the per-recipient price display variable.
+    - `gift_shipping_time` / `shipping_time` as the per-recipient shipping-time variable.
+    - `shipping_address` as the address variable.
+    - `personalized_note` as the note variable only when notes were requested.
+
+13. The campaign detail page's launch action creates internal gifting orders
+    and sends one compact campaign-level ops notification with the campaign
+    link, source table link, and ready/missing-address counts.
+
+## Notes
+
+- If catalog search returns no options, ask the user for a broader gift type
+  and search again.
+- Do not launch the campaign if the address output is missing for most rows
+  unless the user explicitly wants to create the campaign with missing-address
+  orders.
+- Expanded columns are for inspection convenience. When Codex updates a gift,
+  reasoning, address, or note, patch the structured agent cell field.
+- Do not say the gift catalog source name in chat, notes, column prompts, or
+  user-facing instructions.