dimagi-internal/ace / skills/coach-session-capture
coach-session-capture
VerifiedRecord a Coach chat, ACE as the worker. Use for demo footage.
Coach Session Capture
Records a conversation with an ACE Coach (skills/ocs-coach-setup) that starts
EXACTLY as a real one does, with ACE answering as the worker from a scripted persona.
Two modes, one start:
| Mode | Delivery | Use for |
|---|---|---|
mobile | Labs sends it — start_ocs_outreach with deliver_to = ACE's own Connect test user — and ACE answers in the CommCare app's Messaging screen on the AVD | demo footage (what a worker sees); the end-to-end Connect channel |
web | an OCS web chat for ACE's OCS login, with the same start written into its state | fast QA of the Coach's behaviour; no device |
The start is identical in both modes (lib/coach-session-capture.ts
coachStartFromPreview; enforced: test/lib/coach-session-capture.test.ts): the
Coach's first message is Labs' fixed opening verbatim, and the session state carries
coach_briefing = the briefing Labs composed for that worker. Both strings are taken
from Labs' own start_ocs_outreach PREVIEW (workers[0].opening, workers[0].prompt),
never re-derived — that is the production path in connect-labs tasks/ai_sessions.py.
The carve-out (owner decision, Jonathan 2026-10-07)
The coach design's rule is ACE never triggers outreach. The one exception: ACE may
send a coaching conversation to its own Connect test user to record itself
answering on mobile. Nothing wider — never a real worker, never a staff member's
ConnectID. Mobile mode commits ONLY through scripts/coach-capture-mobile-plan.ts,
which resolves the test user's ConnectID username from CommCare HQ by ACE_E2E_PHONE
(a +7426 demo number) and refuses (exit 2) any other deliver_to. Web mode sends
nothing through Connect, so it needs no carve-out. (A person sending from the Labs
panel is a different case: Labs' coaching card in canopy's chat sends on their click,
and ACE holds no token for it.)
Inputs
| Parameter | Used for | Resolver |
|---|---|---|
workflow_id, labs_run_id, scope | the programme or opportunity report the Coach is wired to | explicit arg; default: run_state phases.synthetic-data-and-workflows.products.ocs_coach.coaching_on[]; else the program context doc |
worker | one worker key with a red or yellow coachable indicator | explicit arg; default: first hit of workflow_run_indicators(band: "red") |
persona | agree (default), dispute, safety | explicit arg |
turns | turns.json: the worker's lines for each persona, authored for THIS opp (see below) | optional explicit arg; default: the programme-neutral script |
coach_experiment_id | the Coach (pk) + its PUBLISHED version number (ocs_get_chatbot) | explicit arg; default: run_state ocs_coach.experiment_id |
channel_bot_name (mobile) | the Coach's commcare_connect bot name (ocs-coach-build.ts --connect-bot-name) | explicit arg; default: run_state ocs_coach.connect_channel |
hq_domain (mobile) | where the test user's mobile worker lives | default: ACE_HQ_DOMAIN / run_workspace.hq_domain |
out_folder_id | where coach-capture/ is written | explicit arg; default: the run's or demo's Drive folder |
With explicit ids the skill runs on any live Coach and report, with no run. The carve-out above is unchanged in every mode: mobile delivery goes only to ACE's own test user.
Worker turns: the opp's own words, or neutral
The default script (PERSONA_TURNS in lib/coach-session-capture.ts) is
programme-neutral — no programme nouns, no place names — because it is played into
every opp's Coach (enforced: findProgrammeLiterals in
test/lib/coach-session-capture.test.ts). It used to say "waterpoint" and name a
village, so on a programme with neither the simulated worker invented that context and
the Coach coached on it (ace#2804, group-payment-test/20261007-1700).
For footage, or to test grounding properly, write turns.json for this opp:
{"agree": [...], "dispute": [...], "safety": [...]} (a persona you omit plays the
default). Derive every line from the opp's own PDD, app summary and the worker's red
topic in the preview's briefing — the activity the worker does, the form they file,
a reason the data could miss that fits this programme. Never copy another opp's
turns, and never invent a place, person or object the PDD does not name (CLAUDE.md
§ No inferred backstory). Keep each line short (≤ 25 words) and keep the persona's
arc: agree ends on a specific plan, dispute gives a credible reason the data would
miss, safety discloses a threat.
Products
Under the demo's or run's Drive folder, coach-capture/:
mobile-<persona>.mp4— the stitched device recording;mobile-<persona>_transcript.txt(OCS session read-back)web-<persona>.mp4+web-<persona>.json(transcript, final session state, participant data, overstatement hits)- the OCS
session_idof each conversation (in the transcripts), so Labs' task view links to it
Process
1. Preview (both modes)
workflow_action_preview_view(action: "initiate_ai_coach", run_id, program_id|opportunity_id, arguments: {workers: [{key}]}, deliver_to: <ACE test username>). This is Labs'
app-only preview (the MCP Apps coaching View's): since connect-labs#2348 the agent-facing
workflow_run_action preview of a coaching action carries no confirm (a send to a
worker is a person's click), and off canopy this tool previews a QA send only, so
deliver_to is required (connect-labs#2351). Pass it in web mode too: on a synthetic
opportunity Labs only resolves the REAL Coach when deliver_to is set (otherwise the
preview names the sample bot synthetic-muac-coaching, which coachStartFromPreview
refuses). A preview sends nothing. Save the response to preview.json; its workers
also carry the picture inline (image.data_uri), which nothing here needs.
2. Web mode
ACE_ROOT="${CLAUDE_PLUGIN_ROOT:-$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['ace@ace'][0]['installPath'])")}"
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/coach-capture-web.ts" \
--preview preview.json --experiment-pk <pk> --version <published> --persona agree \
[--turns turns.json] --out <dir>
transcript.json records turns_source: opp | default.
It starts an OCS web chat (start_authed_web_session), writes the start's
session_data into the session state before the first message, plays the persona,
and records video.webm. Run personas one at a time: OCS keeps participant data
per (participant, chatbot), so concurrent sessions for ACE's one OCS login overwrite
each other's coaching status. Pass = every persona ends chatbot_task_status: completed, overstatements: []; dispute records agreement: disputed with no plan
pushed; safety records chatbot_escalations: ["safety"].
The one difference from mobile, which OCS gives no way to remove: the fixed opening
is not in the web session's history. trigger_bot (the only verbatim-message path)
refuses web/api ("Create the channel first" — those channels are team-level) and
answers HTTP 500 on embedded_widget (OCS ApiChannel "requires either an existing
session or a user"). The transcript records opening_not_in_history: true; the
worker's first turn answers the opening as on the phone. OCS's chat page also shows its
own static greeting ("Hello, you can ask me anything…"), which is not the Coach's — do
not use web footage in a demo.
3. Mobile mode
-
Restore the device.
mobile_ensure_avd_running(cold boot + registration). The test user must have no stale thread state to depend on — every capture starts from the Channels list. -
Resolve and guard.
commcare_list_users(domain: ACE_HQ_DOMAIN)→users.json, thenACE_ROOT="${CLAUDE_PLUGIN_ROOT:-$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['ace@ace'][0]['installPath'])")}" node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/coach-capture-mobile-plan.ts" \ --preview preview.json --hq-users users.json --out plan.jsonExit 2 = refused: stop. Never hand-edit
plan.jsonor bypass it. -
Send.
workflow_run_actionagain withplan.argumentsandplan.confirm(Labs' token is bound to them), thenworkflow_action_status(execution_id)→ the OCSsession_id.ocs_get_sessionmust show the opening as the first assistant message andstate.coach_briefingset. Then check OCS actually delivered it, ~25 s after the send (OCS answers the send before it delivers to PersonalID, and records a failure only as a team notification; a cleansession_idis not delivery, ace#3362):node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/ocs-delivery-failures.ts" \ --participant <ace_test_username> --since-minutes 5Exit 2 = OCS failed to deliver: stop, report it against ace#3362, and do not spend a device run waiting for a message that was never sent. Exit 3 = the saved OCS login expired (
/ace:ocs-login). -
Open the thread.
mobile_run_recipe(connect-messaging-open.yaml, envVars: {CHANNEL_NAME, PIN: ACE_E2E_PIN}). The channel row exists only after step 3. -
Each persona turn (the same lines web mode plays —
turns.jsonif you wrote one, else the default;resolvePersonaTurns):mobile_run_recipe(connect-messaging-reply.yaml, {MESSAGE}); read the Coach's answer fromocs_get_session(newest assistant message); thenmobile_run_recipe(connect-messaging-await.yaml, {REPLY_START: replyStartPattern(answer)}). The answer appears on the phone without push notifications (GMS is off on the AVD) — verified 2026-10-07. -
Stitch the per-recipe mp4s in order (
ffmpeg -f concat -c copy) and upload with the OCS transcript. Same pass criteria as web, read from the session'sparticipant_data.
MCP Tools Used
connect-labs:workflow_run_action,workflow_action_status,workflow_run_indicatorsace-ocs:ocs_get_session,ocs_get_chatbotace-connect:commcare_list_usersace-mobile:mobile_ensure_avd_running,mobile_run_recipe,mobile_capture_ui_dumpace-gdrive:drive_create_folder,drive_upload_binary
Mode Behavior
Not part of /ace:run's phase loop; it is invoked for Phase 7 demo footage (the
coaching cut films the report's "Start coaching" flow, and this skill supplies what the
worker sees next) and ad hoc to QA a Coach. Every send needs no further approval inside
the carve-out because its only recipient is ACE's own test identity; anything else is
refused in code.
Terminology
Worker-facing text follows skills/_terminology.md — the platform is "Connect".
Change Log
- 2026-10-07 — Created. First live run: chlorine Coach (OCS 14002, v3), worker Ibrahim
Lawal (
10092::cr_g02), mobile sessiond492a571-34e4-4b6c-98e5-f0a6c9065870on CommCare 2.64.0, web sessions for all three personas. - 2026-10-07 — ace#2804: default worker turns made programme-neutral (they named a
waterpoint and a village on every opp); per-opp turns via
--turns. - 2026-10-18 — Inputs rewritten as parameters with resolvers (run_state is the default,
not the only source);
out_folder_idadded so a live Coach can be captured outside a run. ace#3148.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |