@skarmy/growth-agent

Skarmy's Growth Lead — finds the fastest path to attention, customers, and feedback, and does the work: web research + trends data, a prioritized growth plan, a real venture CRM (with reply/do-not-contact logging), outbound email drafts with redraft hygiene, Meta ad campaign drafts + insights windows, X campaign specs, launch collateral, and organic social calendars. Joins the team when the team-selection judge matches its inclusion criterion: "Reaching and winning customers is central to whether this works."

A prompt-runtime agent on the Skarmy hub: onTurn runs a bounded JSON-action loop (≤12 actions/turn) — each step is one metered ctx.callModel that returns one action (search, trends, crm_upsert, crm_log, draft_emails, withdraw_batch, draft_campaign, write_file, …) executed against the hub-provided capability handles.

The approval gate (why this agent can't send anything)

The agent drafts; the founder pulls the trigger. There is structurally no send/approve/push method on the agent's context — outbound email batches and Meta campaign pushes only leave the platform through founder-authenticated hub UI actions (outbox panel / Campaigns panel / the approve composer mode, which the hub intercepts server-side). The agent observes real statuses on later turns via email_status / ads_status. The one write it has over its own drafts is send-reducing: withdraw_batch cancels its OWN still-DRAFT batch (DRAFT→CANCELED) when it redrafts, so exactly one pending draft sits in the outbox.

What this package owns

• growthManifest — identity: key growth, version 0.3.0, model (GROWTH_MODEL ?? OPENROUTER_MODEL ?? openai/gpt-4.1-mini), stage ["document","files"], tools ["web_search","files","extract","trends","crm","email_outreach","ads"], per-turn limits, defaultInputs (/brief.md, /specs/spec.md, /BUILD.md), composer modes (approve, discuss).
• growthDefinition — persona system prompt + the action loop (src/turn-loop.ts). Degrades gracefully: absent/unconfigured capabilities become explained no-ops; no model key yields a deterministic offline reply (spec §11), so keyless CI stays green.
• src/capabilities.ts — the agent's proposed SDK 0.3 context APIs (PromptCrmApi, PromptEmailApi, PromptAdsApi, FounderProfileView) plus mirrors of the 0.3 draft (files/search/extract/trends/emitStage/emitEvents). Local until @skarmy/agent-sdk 0.3 publishes, then this file collapses to re-exports.

Notable v0.3.0 loop features: crm_log records founder-reported replies, meetings, and do-not-contact requests (REPLIED/DO_NOT_CONTACT contacts are excluded from future batches); email_status with a batchId returns a batch's full drafts including bodies (the revision flow reads its own copy back); get_insights takes a window (today/7d/lifetime) for weekly reports; trends gives interest-over-time for channel/topic bets; fetched external content is sentinel-wrapped as data-not-instructions; schedule_follow_up drafts a future-dated follow-up batch (dueAt required — the hub surfaces it for approval when due); a per-turn duplicate-draft guard refuses re-drafting the same recipients after a saved draft (withdraw first to redraft).

Artifacts it maintains in the venture file store: /growth/plan.md (staged as the document pane), /growth/icp.md, /growth/outreach/*, /growth/campaigns/* (X specs as x-*.md), /growth/social/calendar.md, /growth/launch/* (Engineering Lead handoff), /growth/reports/*.

Founder-adaptive behavior

The context may carry ctx.founderProfile (a mirror of the hub's DiscoveryOnboardingProfile — free-text fields like technicalLevel, commitment, resources). When present, the persona prompt renders it; when absent, the agent infers the founder's technicality and capacity from the brief and how they talk. Either way it fits itself to a tier:

| | non-technical | semi-technical (default) | technical | |---|---|---|---| | Vocabulary | plain words; growth terms defined in-line first use ("ICP (who exactly you're selling to)") | practical, brief explanations where they help | terse, metrics-forward | | Numbers | never raw ids/cents — "$5/day" | dollars | channel economics: reply/CTR ranges, CAC ceiling, numeric kill criteria | | /growth/plan.md | one-page checklist, "this week" first | standard plan | includes economics + multi-adset test structures | | Outreach | first batches ≤10 recipients | standard | standard | | Ads mode | recommend REVIEW, never AUTO | REVIEW default | may explain AUTO with its server-side caps | | Reassurance | every outreach/ads reply restates nothing sends/spends until approval | on request | on request |

The tier changes how the agent presents and what it recommends — never which rules apply: approval gates, provenance, and compliance are identical for everyone. This is deliberately prompt-level only — the action surface is never tiered (misclassifying a founder must never remove a capability).

Non-goals

• No list-buying or data-enrichment services — contacts come only from verifiable research with recorded provenance.
• No auto-posting — organic social ships as draft calendars; there are no posting APIs on the context.
• No domain checks — near-zero growth value; the domain_check tool grant was considered and rejected.
• No inbound reply parsing (v1) — replies go to the founder's real inbox by design; "replied" is founder-reported and recorded via crm_log.
• No per-user manifest variants — one manifest, one action surface; founder adaptation is prompt-level.

Develop

Prereqs: Node 22+ (@skarmy/agent-sdk resolves from npm).

npm install
npm run typecheck
npm test           # action-parser + turn-loop unit tests, SDK contract test
npm run eval:growth -- --fixtures 2   # real-model quality gate (needs OPENROUTER_API_KEY; keyless → SKIP)

The contract test currently validates a projection onto SDK 0.2.1 (which predates the 0.3 tool keys) plus explicit assertions pinning the 0.3 surface — see src/contract.test.ts. TODO(sdk-0.3): pin ^0.3.0 and drop the projection.

Publish & pin

1. Drop "private": true.
2. Publish via a GitHub release (CI uses pnpm publish so the publishConfig src→dist rewrite applies — npm publish shipped a broken agent-sdk 0.2.0 once).
3. The hub adds @skarmy/growth-agent, registers growthManifest/growthDefinition (replacing the growth placeholder in src/lib/agents/definitions/leads.ts), and wires the growth capability handles (ctx.crm/ctx.email/ctx.ads) in its prompt-capabilities builder.

License

MIT