Rachel/voc onboarding package

[rachelgrant27]

Summary

New voc-onboarding package: the Voice of Customer half of meta-and-voc-onboarding, extracted as-is and fully isolated from the Meta onboarding work (Account Context Brain, Creative Attributes, Meta Validation, Knoweth organize). Meta ad comments come along — they're a VoC integration, not Meta work.

One structural difference from the parent: nothing runs at install time. Install stages files and announces a trigger phrase; a person saying "run voice of customer onboarding" fires everything.

What's in the package

• voc-onboarding-walkthrough (new skill) — the entry point. Setup phase: workspace resolution from the conversation's own Motion context, reachability probes (OAuth + stored keys + Meta connection), human-confirmed account pinning, one daily voc-sync-<workspace>-<platform> routine per reachable platform with the first run (the 12-month backfill) kicked immediately. Presentation phase: per-integration VoC summary ("Judge.me: 1,240 reviews across 6 products") and the explained audit offer — method preview, additions and reference docs invited. Re-invoking is always safe: existing routines are skipped, mid-backfill invocations report counts so far, an existing audit gets a rerun offer.
• voc-data-pull — copied byte-for-byte from the parent at bce9619, including the meta-ad-comments recipe and per-creative template. One substitution: the setup trigger names this package's walkthrough instead of the parent's install.
• voc-audit — copied byte-for-byte, zero substitutions. Includes the latest output structure (numbered standalone findings, verbatim attributed quotes inline, explicit no-signal lines) and reference-docs intake.
• post-install.md — thin by design: announce the install, state the trigger phrase, stop.
• package-index.json — adds the one voc-onboarding entry (the index on main was empty).

Deliberately absent

No guards, no onboarded-workspace roster, no /agent/user.md writes anywhere — because nothing self-fires, no activation gate is needed. Idempotency comes from routine existence and files on disk. Also excluded: ACB, Creative Attributes, Meta Validation, Knoweth docs, and the meta-ad-performance-analysis skill.

Provenance and divergence

Extracted from meta-and-voc-onboarding at commit bce9619 (Aug 2026). The complete substitutions list lives in the README's "Provenance and divergence" section. The two packages do not track each other: fixes to shared files (voc-data-pull, voc-audit) must be mirrored by hand. Coexistence/uninstall interactions with the parent package are intentionally out of scope here and will be handled in the onboarding package.

Test plan

• Install on a test VM: confirm only the announcement renders — no probes, routines, or writes
• Say "run voice of customer onboarding": confirm workspace readout, reachability, pinning (multi-workspace org), routines created and first runs kicked
• Confirm backfill files land under /agent/brain/<workspace>/data-sources/voc/<platform>/ (one file per item; per creative for meta-ad-comments)
• After backfill: confirm the one-time async audit offer, and the summary + offer on re-invocation
• Yes to the audit: confirm compiled page at data-sources/voc/voice-of-customer-audit.md with numbered findings and attributed quotes
• Confirm /agent/user.md is untouched throughout

[greptile-apps]

Confidence Score: 3/5

Two issues need fixing before install attempts: the stale install-trigger text in voc-data-pull/SKILL.md and the main-branch source ref in the index.

The walkthrough, audit, and templates are internally solid. The two problems are specific and fixable: voc-data-pull/SKILL.md's 'Set up the recurring sync' section header still says install fires setup, which an agent reading that section in isolation would act on — producing the exact behavior the package is designed to prevent. Separately, the index's ref: 'main' means installs will 404 until this code lands on main, breaking the test plan step the moment staging is exercised.

Files Needing Attention: voc-onboarding/voc-data-pull/SKILL.md (stale install trigger in 'Set up the recurring sync') and package-index.json (ref: 'main' before code is on main).

Sequence Diagram

sequenceDiagram
    participant H as Human
    participant PM as Package Manager
    participant PI as post-install.md
    participant WK as voc-onboarding-walkthrough
    participant DP as voc-data-pull
    participant RT as voc-sync Routine
    participant AU as voc-audit

    PM->>PI: Install package - stages files only
    PI-->>H: Announces install and trigger phrase

    H->>WK: run voice of customer onboarding
    WK->>WK: Step 0 - resolve workspace from Motion context
    WK->>WK: Phase 1 - probe OAuth and stored keys and Meta connection
    WK->>H: Account confirmation questions for multi-workspace orgs
    H-->>WK: Confirm account pins
    WK->>DP: Set up recurring sync per reachable platform
    DP->>RT: routine add and routine run for first backfill
    RT-->>H: Background backfill running silently

    RT->>RT: First fully covered backfill completes
    RT->>H: One async audit offer with plan preview
    RT->>RT: Append voc-audit-offer to workspace changelog

    H->>WK: Re-invoke to check on VoC onboarding
    WK->>WK: Phase 2 - read platform folders and count items
    WK-->>H: Per-integration summary and audit offer

    H->>AU: yes to audit offer
    AU->>AU: Steps 0-6 - locate data, count gate 200+, bucket, persona
    AU->>AU: Step 7 - write voice-of-customer-audit.md
    AU-->>H: Audit output and confirmed save path

Loading

Comments Outside Diff (3)

1. voc-onboarding/voc-data-pull/SKILL.md, line 950-955 (link)

   Stale install-time trigger language left in "Set up the recurring sync"

   The heading of this section still reads "Setup runs when this package finishes installing (the install is the ask) or when asked directly" — language copied verbatim from the meta-and-voc-onboarding parent, where install was the trigger. In voc-onboarding, install does nothing; the walkthrough skill is the sole trigger.

   The PR's stated substitution list updates only the "When to use" first bullet, but this section header was missed. An AI agent reading downward past the corrected "When to use" section and into "Set up the recurring sync" will find contradictory instructions: one place says "never at install," this place says "install is the ask." Because agents resolve ambiguity by proximity, this stale line is likely to win for any agent that jumps directly to the setup section.

2. package-index.json, line 15-28 (link)

   ref: "main" points to a branch that does not yet contain this code

   The source entry resolves the package from the main branch of this repo, but this PR targets staging. Until the staging → main promotion completes, any install attempt driven by this index entry will 404 — the voc-onboarding/ directory simply won't exist at main yet. The test plan step "Install on a test VM" would reproduce this immediately on a staging-only VM reading from this index.

3. voc-onboarding/README.md, line 158-162 (link)

   "Complete list" claim is inaccurate — "Set up the recurring sync" section not listed

   The README declares this as the complete substitutions list, but voc-data-pull/SKILL.md's "Set up the recurring sync" section header also retains install-time trigger language from the parent and was not updated. That section should appear here so the divergence is tracked and future mirrors don't re-introduce the same inconsistency.

_{Reviews (1): Last reviewed commit: "feat(voc-onboarding): VoC-only onboardin..." | Re-trigger Greptile}