docs(v1.6.1): playbook freshness pass — lead with af workforce init

seanphan · seanphan · commit c9fa5309be4d · 2026-04-13T21:01:33.000-07:00
The v1.6.0 release shipped `af workforce init` as the native deploy default but three onboarding playbooks still pointed users at the deprecated `af paperclip init` — a real UX regression caught by the blueprint + playbook verification pass. Updated: - `first-touch`: "Deploy a team to AgenticFlow (native, v1.6+)" section now leads; paperclip section demoted to "DEPRECATED — sunset 2026-10-14" - `amazon-seller`: full rewrite with OPTION A (native) → OPTION B (paperclip deprecated). Shows `--include-optional-slots` for the full 5-agent team, MCP-attach-per-agent recipe pointing at the mcp-client-quirks playbook - `company-from-scratch`: flow restructured so native workforce comes first; paperclip path retained as legacy with clear sunset - `deploy-to-paperclip`: prominent ⚠️ DEPRECATED header + pointers to migrate-from-paperclip and amazon-seller/company-from-scratch playbooks Verified live: - All 6 blueprints (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller) translate cleanly through --dry-run - Full e2e `content-studio` deploy: creates workforce + 3 agents (ceo + cmo + engineer), wired graph validates with 0 errors, graph shape confirmed trigger → ceo → {cmo, engineer, output} - Clean delete of all 4 resources (workforce + 3 agents) via the v1.5.2 envelope Tests: 392 pass, 14 skipped, 10 todo — unchanged (content-only patch).
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@pixelml/agenticflow-cli",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "AgenticFlow CLI for agent-native API operations.",
   "license": "Apache-2.0",
   "repository": {
diff --git a/packages/cli/src/cli/changelog.ts b/packages/cli/src/cli/changelog.ts
@@ -13,6 +13,21 @@ export interface ChangelogEntry {
 }
 
 export const CHANGELOG: ChangelogEntry[] = [
+  {
+    version: "1.6.1",
+    date: "2026-04-14",
+    highlights: [
+      "Playbook freshness pass — three onboarding playbooks (`first-touch`, `amazon-seller`, `company-from-scratch`) now lead with `af workforce init` (v1.6 native deploy) and show the deprecated `af paperclip init` path as a secondary option with a sunset date",
+      "`deploy-to-paperclip` playbook got a prominent `⚠️ DEPRECATED` header pointing at `af playbook migrate-from-paperclip` and the sunset 2026-10-14",
+      "`amazon-seller` playbook expanded: shows `--include-optional-slots` to create all 5 agents, attach-MCP-per-agent recipe pointing at `mcp-client-quirks`, and smoke-run/publish commands",
+      "Verified: all 6 blueprints translate cleanly through `--dry-run` (node/edge math correct). Full e2e `content-studio` deploy creates + wires + validates + tears down cleanly",
+    ],
+    for_ai: [
+      "When `af bootstrap --json` returns workforces=0 and the user wants a team, the FIRST thing to show them is `af workforce init --blueprint <id> --dry-run --json` — the playbooks now lead with this, no longer with paperclip",
+      "For Amazon Singapore sellers, run `af playbook amazon-seller` — it shows the one-command native deploy path first, with `--include-optional-slots` for the full 5-agent team",
+      "`af playbook deploy-to-paperclip` now explicitly flags itself deprecated and points at `migrate-from-paperclip` — follow that path unless the user has an existing Paperclip instance",
+    ],
+  },
   {
     version: "1.6.0",
     date: "2026-04-14",
diff --git a/packages/cli/src/cli/playbooks.ts b/packages/cli/src/cli/playbooks.ts
@@ -46,11 +46,22 @@ export const PLAYBOOKS: Record<string, Playbook> = {
       "af agent create --body <payload> --json       # Create",
       "```",
       "",
-      "**Deploy a team to Paperclip:**",
+      "**Deploy a team to AgenticFlow (native, v1.6+):**",
       "```bash",
-      "af paperclip blueprints --json              # See templates",
-      "af paperclip init --blueprint <id> --json   # Deploy entire company",
-      "af paperclip connect --json                 # Wire to gateway",
+      "af paperclip blueprints --json                                # See 6 blueprints",
+      "af workforce init --blueprint <id> --name \"My Team\" --dry-run --json  # Preview",
+      "af workforce init --blueprint <id> --name \"My Team\" --json             # Creates",
+      "                                                                       # workforce + N",
+      "                                                                       # agents + wired",
+      "                                                                       # graph, all in",
+      "                                                                       # one command.",
+      "af workforce publish --workforce-id <id> --json              # Mint public URL",
+      "```",
+      "",
+      "**Deploy to Paperclip (DEPRECATED — sunset 2026-10-14):**",
+      "See `af playbook migrate-from-paperclip` for the full migration map.",
+      "```bash",
+      "af paperclip init --blueprint <id> --json   # Still works but prints deprecation warning",
       "```",
       "",
       "**See what's new after an upgrade:**",
@@ -325,9 +336,26 @@ export const PLAYBOOKS: Record<string, Playbook> = {
   },
   "deploy-to-paperclip": {
     topic: "deploy-to-paperclip",
-    title: "Deploy Agents to Paperclip",
-    summary: "Publish AgenticFlow agents to a Paperclip company where they receive tasks, execute work, and report results — all from the CLI.",
+    title: "Deploy Agents to Paperclip (DEPRECATED)",
+    summary: "[DEPRECATED — sunset 2026-10-14] Publish AgenticFlow agents to a Paperclip company. Use `af playbook migrate-from-paperclip` for the AgenticFlow-native alternative.",
     content: [
+      "# ⚠️  DEPRECATED — Migrate to `af workforce` by 2026-10-14",
+      "",
+      "This playbook describes the legacy Paperclip-based deploy. As of CLI v1.5.0,",
+      "AgenticFlow ships a native multi-agent deploy surface (`af workforce *`) that",
+      "replaces most of this flow — no separate Paperclip instance, no gateway to run,",
+      "no connect step. See:",
+      "",
+      "- **`af playbook migrate-from-paperclip`** — command-by-command map",
+      "- **`af playbook amazon-seller`** or **`af playbook company-from-scratch`** — native examples",
+      "- **`af workforce init --blueprint <id> --json`** — one-command native deploy (v1.6+)",
+      "",
+      "The commands below still work — you'll see a one-time `[deprecated]` warning per session.",
+      "Silence with `AF_SILENCE_DEPRECATIONS=1`. After the 2026-10-14 sunset the `af paperclip *`",
+      "commands will be removed.",
+      "",
+      "---",
+      "",
       "Paperclip is an orchestration control plane for AI agent companies.",
       "AgenticFlow agents can be deployed to Paperclip as HTTP-adapter workers",
       "that receive tasks and execute them.",
@@ -513,20 +541,15 @@ export const PLAYBOOKS: Record<string, Playbook> = {
       "VERIFY: `health: true`. EXTRACT: `projectId`.",
       "",
       "```bash",
-      "curl -s http://PAPERCLIP_URL/api/health",
-      "```",
-      "VERIFY: `status: \"ok\"`. Replace PAPERCLIP_URL with the user's Paperclip URL (default: http://localhost:3100).",
-      "IF FAIL: Paperclip is not running. Ask the user to start it.",
-      "",
-      "```bash",
       "af agent list --fields id,name,model --json",
       "```",
-      "VERIFY: at least 1 agent exists. These are the agents that will work in the company.",
-      "IF EMPTY: the user needs to create agents first — run `af playbook quickstart`.",
+      "VERIFY: at least 1 agent exists in the workspace (not strictly required — `af workforce init` creates fresh ones). If you want to re-use existing agents, note their IDs.",
       "",
       "---",
       "",
-      "## OPTION A: Blueprint (one command, recommended)",
+      "## OPTION A: AgenticFlow-native workforce (RECOMMENDED, v1.6+)",
+      "",
+      "One command creates workforce + N agents + wired DAG. No Paperclip, no gateway, no webhooks.",
       "",
       "### A1. Choose a blueprint",
       "```bash",
@@ -538,8 +561,40 @@ export const PLAYBOOKS: Record<string, Playbook> = {
       "- `sales-team` — lead gen + outreach (director, researcher, SDR)",
       "- `content-studio` — content production (creative dir, social, writer, visual)",
       "- `support-center` — customer support (manager, agent, KB)",
+      "- `amazon-seller` — Amazon SG seller team (CEO, listing, PPC, research, support)",
+      "",
+      "### A2. Deploy the team",
+      "```bash",
+      "af workforce init --blueprint BLUEPRINT_ID --name \"My Team\" --dry-run --json     # preview",
+      "af workforce init --blueprint BLUEPRINT_ID --name \"My Team\" --json              # creates",
+      "```",
+      "VERIFY: response has `schema: \"agenticflow.workforce.init.v1\"`, `mode: \"full\"`, `skeleton: false`, non-empty `agents` array.",
+      "EXTRACT: `workforce_id`, each `agents[].agent_id`.",
+      "",
+      "### A3. Inspect the wired graph (optional)",
+      "```bash",
+      "af workforce schema --workforce-id <id> --json",
+      "af workforce validate --workforce-id <id> --json  # expects 0 errors",
+      "```",
+      "",
+      "### A4. Attach tools/MCPs per agent (recommended)",
+      "Each agent starts with `tools: []`. For real use, attach Composio MCP clients (see `af playbook mcp-client-quirks`):",
+      "```bash",
+      "af mcp-clients list --name-contains \"google\" --fields id,name --json",
+      "af mcp-clients inspect --id <mcp_id> --json",
+      "af agent update --agent-id <agent_id> --patch --body '{\"mcp_clients\":[{\"mcp_client_id\":\"<id>\",\"run_behavior\":\"auto_run\",\"tools\":{}}]}' --json",
+      "```",
+      "",
+      "### A5. Run it",
+      "```bash",
+      "af workforce run --workforce-id <id> --trigger-data '{\"message\":\"Kick off week 1 tasks\"}'",
+      "af workforce publish --workforce-id <id> --json  # public URL for teammates",
+      "```",
+      "",
+      "## OPTION A-LEGACY: Paperclip (DEPRECATED — sunset 2026-10-14)",
+      "",
+      "Still functional but emits a deprecation warning. See `af playbook migrate-from-paperclip`.",
       "",
-      "### A2. Bootstrap the company",
       "```bash",
       "af paperclip init --blueprint BLUEPRINT_ID --budget 50000 --json",
       "```",
@@ -632,7 +687,7 @@ export const PLAYBOOKS: Record<string, Playbook> = {
   "amazon-seller": {
     topic: "amazon-seller",
     title: "Amazon Seller AI Team",
-    summary: "Deploy a 5-agent AI team for Amazon Singapore sellers — listing optimization, PPC, competitor analysis, pricing, and customer support. One command setup.",
+    summary: "Deploy a 5-agent AI team for Amazon Singapore sellers — listing optimization, PPC, competitor analysis, pricing, and customer support. One command.",
     content: [
       "Deploy an AI team that runs your Amazon Singapore business 24/7.",
       "",
@@ -642,79 +697,79 @@ export const PLAYBOOKS: Record<string, Playbook> = {
       "```",
       "VERIFY: `health: true`. If not, run `af login`.",
       "",
-      "```bash",
-      "curl -s http://PAPERCLIP_URL/api/health",
-      "```",
-      "VERIFY: `status: \"ok\"`. Default: http://localhost:3100",
+      "## OPTION A: AgenticFlow-native (RECOMMENDED, v1.6+)",
+      "",
+      "One command creates workforce + 5 real agents + wired DAG graph (trigger → CEO coordinator → 4 workers → output).",
       "",
-      "## STEP 1: Bootstrap the Amazon Seller Team",
       "```bash",
-      "af paperclip init --blueprint amazon-seller --budget 100000 --json",
+      "af workforce init --blueprint amazon-seller --name \"My Amazon Team\" --include-optional-slots --dry-run --json",
+      "# ^ Preview: see agent specs + estimated node/edge count, no side effects",
+      "",
+      "af workforce init --blueprint amazon-seller --name \"My Amazon Team\" --include-optional-slots --json",
+      "# ^ Creates it for real. Response: { workforce_id, agents:[{slot_role, agent_id, title}],",
+      "#                                    node_count, edge_count, next_steps }",
       "```",
-      "VERIFY: response has `agents` array with 5 entries and `tasks` array with 5 entries.",
-      "EXTRACT: `company.id` as COMPANY_ID.",
       "",
-      "This creates:",
-      "- Amazon Business Manager (CEO) — strategy, P&L, coordination",
-      "- Listing & SEO Specialist (CMO) — product listing optimization",
-      "- PPC Campaign Manager (Engineer) — advertising campaigns",
-      "- Market & Competitor Analyst (Researcher) — competitive intelligence",
-      "- Customer Support Agent (General) — buyer communication",
+      "VERIFY: response has `mode: \"full\"`, `agents` array with 4-5 entries (each with `agent_id`), and `skeleton: false`.",
       "",
-      "## STEP 2: Start Gateway",
+      "### Confirm the graph is wired (optional)",
       "```bash",
-      "af gateway serve --channels paperclip &",
+      "af workforce schema --workforce-id <id> --json",
+      "af workforce validate --workforce-id <id> --json    # 0 errors expected",
       "```",
-      "VERIFY: `curl -s http://localhost:4100/health` returns `status: \"ok\"`.",
       "",
-      "## STEP 3: Connect Agents",
+      "### Attach tools/MCPs per agent (recommended for real use)",
+      "Each auto-created agent starts with `tools: []`. To give them capabilities:",
       "```bash",
-      "af paperclip connect --json",
+      "# Example — give the Listing & SEO Specialist (CMO role) Google Sheets for tracking",
+      "af mcp-clients list --name-contains \"google sheets\" --fields id,name --json",
+      "af mcp-clients inspect --id <sheets_mcp_id> --json   # classify Pipedream vs Composio",
+      "af agent update --agent-id <cmo_agent_id> --patch --body '{\"mcp_clients\":[{\"mcp_client_id\":\"<id>\",\"run_behavior\":\"auto_run\",\"tools\":{}}]}' --json",
       "```",
-      "VERIFY: all agents show `status: \"connected\"`.",
       "",
-      "## STEP 4: Trigger Work",
-      "The init command created 5 starter tasks already assigned. Trigger each agent:",
-      "```bash",
-      "af paperclip issue list --json",
-      "```",
-      "For each issue, trigger the assigned agent via gateway:",
+      "See `af playbook mcp-client-quirks` for the Pipedream vs Composio write-safety distinction.",
+      "",
+      "### Run it",
       "```bash",
-      "curl -s -X POST http://localhost:4100/webhook/paperclip \\",
-      "  -H \"Content-Type: application/json\" \\",
-      "  -d '{\"agentId\":\"PC_AGENT_ID\",\"runId\":\"RANDOM_UUID\",\"context\":{\"issueId\":\"ISSUE_ID\",\"taskKey\":\"IDENTIFIER\",\"wakeReason\":\"Execute task\",\"wakeSource\":\"on_demand\"}}'",
+      "af workforce run --workforce-id <id> --trigger-data '{\"message\":\"Optimize our top 3 ASINs for CNY 2026.\"}'",
+      "# Streams SSE events — each event prints one JSON line. Exits when stream closes.",
+      "",
+      "af workforce publish --workforce-id <id> --json  # Mint a public_key + public_url so teammates can hit it",
       "```",
       "",
-      "## STEP 5: Monitor Results",
+      "## OPTION B: Paperclip (DEPRECATED — sunset 2026-10-14)",
+      "",
+      "Still works but emits a deprecation warning per session. Silence with `AF_SILENCE_DEPRECATIONS=1`.",
+      "",
       "```bash",
-      "af paperclip dashboard --json",
-      "af paperclip issue comments --id ISSUE_ID --json",
+      "af paperclip init --blueprint amazon-seller --budget 100000 --json",
+      "af gateway serve --channels paperclip &",
+      "af paperclip connect --json",
+      "af paperclip issue list --json",
       "```",
       "",
-      "## STARTER TASKS (auto-created)",
+      "See `af playbook migrate-from-paperclip` for the full paperclip → workforce command map.",
+      "",
+      "## WHAT THE 5 AGENTS DO",
+      "- **Amazon Business Manager (CEO)** — strategy, P&L oversight, coordinates the team",
+      "- **Listing & SEO Specialist (CMO)** — product listings, keyword research, A+ content",
+      "- **PPC Campaign Manager (Engineer)** — Sponsored Products/Brands/Display, bid optimization",
+      "- **Market & Competitor Analyst (Researcher)** — pricing intel, trend analysis",
+      "- **Customer Support Agent (General, optional)** — buyer messages, review replies — only created if you pass `--include-optional-slots`",
+      "",
+      "## STARTER TASKS (embedded in trigger.meta.starter_tasks)",
       "1. **Optimize top 3 product listings** (CMO) — title, bullets, backend keywords for SG market",
       "2. **Set up PPC campaigns** (Engineer) — Sponsored Products, SGD 500/mo, 25% ACoS target",
       "3. **Competitive analysis report** (Researcher) — top 5 competitors, pricing, gaps",
-      "4. **Draft review responses** (Support) — handle recent 1-2 star reviews",
+      "4. **Draft review responses** (Support) — handle recent 1-2 star reviews (optional agent)",
       "5. **Q2 pricing strategy** (CEO) — 11.11, Great Singapore Sale, National Day promos",
       "",
-      "## SKILLS AVAILABLE",
-      "These agents use the amazon-seller-pack skills:",
-      "- `listing-optimizer` — A9/A10 optimized titles, bullets, descriptions",
-      "- `keyword-researcher` — multilingual keywords (EN, ZH, MS) for SG market",
-      "- `review-analyzer` — sentiment analysis, complaint extraction, actionable insights",
-      "- `ppc-campaign-planner` — SP/SB/SD campaign structure with bid strategy",
-      "- `competitor-monitor` — pricing, listing quality, review comparison",
-      "- `pricing-strategist` — FBA fee calculation, margin optimization, promo calendar",
-      "- `customer-response` — Amazon-compliant buyer message drafts",
-      "- `product-launcher` — full launch pipeline (composed: keywords → listing → pricing → PPC)",
-      "",
       "## FOR AI AGENTS",
-      "1. Run `af paperclip init --blueprint amazon-seller --json` to create the full team.",
-      "2. Start gateway + connect: `af gateway serve --channels paperclip & af paperclip connect`.",
-      "3. Trigger agents via `/webhook/paperclip` with issueId from task list.",
-      "4. Each agent responds with structured analysis posted as issue comments.",
-      "5. Use `af agent run --agent-id <AF_ID> --message <task> --json` for direct queries.",
+      "1. Default: `af workforce init --blueprint amazon-seller --name \"<name>\" --include-optional-slots --json` creates a runnable 5-agent team in one call.",
+      "2. Attach MCPs/tools to each agent via `af agent update --patch` (tools start empty on init).",
+      "3. Smoke test with `af workforce run --workforce-id <id> --trigger-data '{\"message\":\"...\"}'`.",
+      "4. Publish a public URL via `af workforce publish --workforce-id <id>` when ready to hand off.",
+      "5. Clean up test deploys with `af workforce delete --workforce-id <id>` + `af agent delete --agent-id <id>` for each created agent.",
     ].join("\n"),
   },
   "mcp-to-cli-map": {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@pixelml/agenticflow-cli",`
`3`		`- "version": "1.6.0",`
	`3`	`+ "version": "1.6.1",`
`4`	`4`	`"description": "AgenticFlow CLI for agent-native API operations.",`
`5`	`5`	`"license": "Apache-2.0",`
`6`	`6`	`"repository": {`