dimagi-internal/ace / skills/connect-program-setup
connect-program-setup
UnverifiedCreate or reuse a Connect program matched to a PDD's delivery archetype and record its id. Needs an approved PDD.
Connect Program Setup
Create or select a Connect program for this opportunity.
Inputs
| Parameter | Used for | Resolver |
|---|---|---|
organization_slug | the org for every call in this skill (see Which org below) | explicit arg; default: connect_orgs.pm_org (from /ace:doctor --preflight, passed in by the connect-setup dispatch) |
archetype | archetype-aware program naming + archetype-matched reuse | explicit arg; default: the PDD's archetype: frontmatter |
domain, description | the domain match in the reuse scan, and the program description | explicit arg; default: the PDD |
connect_delivery_type, country, currency, budget, dates | the create-time-only program fields Step 4 gates | explicit arg; default: the PDD's program_parameters |
pdd | the resolver for every field above that the caller does not pass | explicit arg (a Drive file id); default: 1-design/idea-to-pdd.md |
| existing programs | the reuse-vs-create decision | read live: connect_list_programs({organization_slug}) |
Outside a run (a program project that needs a program, with no PDD), pass
the fields explicitly. Step 4's gates (connect_delivery_type resolved
against the live list, checkProgramLocale on country and currency) apply
the same way to explicit values: they are checks on the value, not on
where it came from. Step 6's opp.yaml write applies only when an opp
folder exists; otherwise record the program id in the program context doc.
Which org. organization_slug throughout this skill is the configured PM
org — connect_orgs.pm_org from preflight (lib/connect-orgs.ts; see
playbook/integrations/connect-api.md § Which Connect orgs ACE acts in). Never
type a slug here. One exception, and it wins: on the reuse path, the org is
the one recorded in opp.yaml.connect.program.url (/a/<org>/program/<id>/) —
an existing program's own org stays authoritative even if the instance's PM org
has since changed. The program always lives in the PM org; when
connect_orgs.nm_org is configured, connect-opp-setup Step 3 invites that NM
org to this program and creates the run's opportunity HELD by it (the PM→NM
flow, operator decision 2026-09-26). This skill does not invite anyone — it
only creates or reuses the program.
Phase folder anchor
The connect-setup agent passes a phaseFolderId (the 4-connect folder ID,
anchored to the run folder per agents/orchestrator-reference.md § Per-Phase Folder Lifecycle). Every drive_create_file write in this skill MUST set
parentFolderId = phaseFolderId — drive_create_file's parentFolderId is
required and must be a folder ID, never a path string. Writing by path-string
alone makes the artifact land outside 4-connect and fail
verify_phase_artifacts(phase='connect') (jjackson/ace#635).
Products
4-connect/connect-program-setup.md(written withparentFolderId = phaseFolderId) — program-id, decision rationale (reuse / create), admin program URLopp.yaml.connect.program.{id, url, connect_int_id}— written on first create (and refreshed on reuse with verified live values).connect_int_idis ConnectProd's integer program id, resolved throughlabs_context(Step 6a; no Connect create or read surface returns it, ace#3213), used by Step 7's tenancy registration and the Phase 8 solicitation surfaces. This is the single durable cross-run reference for the Connect program; every subsequent run of this opp reads it to skip program-create.
Terminology
Every string this skill puts in front of a reader follows
skills/_terminology.md: Connect, never CommCare Connect, and
US spelling, always — program, enrollment, enroll, organization, behavior, center; never
programme, enrolment, organisation (owner, 2026-10-20: "everything should be US spelling",
ace#3232). Identifiers (case properties, slugs, ids, config keys) keep their spelling.
Process
-
Resolve the inputs. Use each explicit parameter the caller passed; read the rest from the PDD (default
ACE/<opp-name>/runs/<run-id>/1-design/idea-to-pdd.md), including thearchetype:field. Program shape is mostly archetype-agnostic, but program NAME and DESCRIPTION should signal archetype so future opps under the same program can be grouped coherently. See## Archetypesbelow. -
Check for existing programs that match this opportunity's domain/scope. Call
connect_list_programs({organization_slug})with NOnamefilter and consider the full org list (dimagi-internal/ace#1252). A name-substring scan is structurally blind to a same-domain, same-archetype program under different words — live case: aname: 'Bednet'query returned 12 programs and could never returnMalaria ITN Exploration Multi-Stage Study, the one same-domain multi-stage candidate in the org. Program names are generated per-archetype by this very skill, so two runs of the same real intervention that describe their domain differently will never find each other by name, by construction — and the silent miss creates exactly the duplicate program the reuse rule exists to prevent.Match candidates on delivery type + archetype (both structured, both known at this point); use the name only for ranking/display. Unfiltered rows carry
nullfor delivery_type/budget/currency/ country/dates — hydrate the shortlisted candidates viaconnect_get_programbefore judging fit on those.Descriptions on unfiltered rows are CAPPED (ace#1799). In a mature org the full prose is most of the payload and overflows the tool-result cap outright — measured on
ai-demo-space2026-09-01, 42 rows serialize to 57,425 chars of which 43,239 (75.3%) aredescription, and the call returned no usable data at all. A capped row is flaggeddescription_truncated: trueand adescription_projectionblock reports the count. The domain signal you shortlist on is in the opening sentences; when you need the whole thing, read it fromconnect_get_program(which Step 3a does anyway).write_to_path: "/abs/path.json"writes every full row to disk and returns a handle instead — use it if you want to grep the whole org. (Thenamefilter remains available as a case-insensitive substring match whose rows come back fully hydrated, jjackson/ace#1089 — fine for a targeted lookup, never for the reuse scan.) Prefer archetype-matched programs when reusing — running an FGD opp under a program whose other opps are all atomic-visit creates a mixed-method reporting headache downstream.Record the candidate set in the artifact:
connect-program-setup.md§ Reuse-vs-create decision must state how many programs were considered (the full org count) and on what axis they were matched, so "no reusable program existed" is falsifiable by a reader. A count that silently reflects a name-filtered subset is the #1252 defect. -
Decide: reuse or create
- If an existing program fits AND shares the archetype, note the program ID; run step 3a, then skip step 4.
- If an existing program matches the domain but not the archetype,
flag the mismatch in
auto_surfaced/ program notes; default to creating a new one unless the admin explicitly opts in. - If no match: proceed to step 4.
3a. Reconcile reused program content against THIS run's PDD
(jjackson/ace#1078). Only the program's identity is durable
(UUID, org, delivery type, currency, country, name — see
agents/orchestrator-reference.md § Fork Points). Its content
(description, budget, dates) was authored from the PDD of whichever
run created it, and a later run's PDD can contradict it — the live,
LLO-facing program once advertised an enforced 500m GPS payment gate
the current PDD deliberately made non-enforcing. On every reuse:
-
connect_get_program({ organization_slug, program_id })→ live refreshable fields. -
Author this run's PDD-derived description to a local file first (an absolute path, e.g.
<scratch>/program-description.md) and never hold it only in the conversation. A program description is the whole programme design in prose — measured live 2026-09-17 on the durablebednet-check-2-visitprogram, 21,012 chars — it is re-derived on EVERY reuse, and it has two consumers from here: the reconciler just below and the update in sub-step 5. One file read twice costs nothing and makes those two copies identical by construction; two emissions of the same prose are two generations, which is the ace#1737 class (ace#2291).Then compare against this run's PDD-derived values with
reconcileProgramWithPdd(lib/program-reconcile.ts— pure helper; run it vianpx tsx -e, having the snippetreadFileSyncthat description file rather than pasting the prose into it — or replicate its semantics exactly: description compares whitespace-normalized; budget diverges only when the live ceiling is below the PDD budget, since Step 4a deliberately raises it above for headroom; dates use the same CONTAINMENT rule — the program window holds every opportunity on the durable program, sostart_datediverges only when the live start is later than the PDD start andend_dateonly when the live end is earlier than the PDD end (trimmed YYYY-MM-DD, compared lexicographically; an empty live date diverges). A live window wider than the PDD's is healthy and never narrowed (ace#2985)). Pass the livenameand the PDD'sarchetype— they cost nothing and they are what powers step 3 below. -
Emit every line in
warnings[]verbatim into the program notes and the run summary — UNCONDITIONALLY, before branching on anything (ace#1966).inSyncis about the four REFRESHABLE fields only, so a program whose content this run has just brought fully up to date reportsinSync: trueand can still carry awarnings[]entry:nameArchetypefires when the durable NAME asserts an archetype the PDD does not declare. Gating the emit oninSync(or on the "unsafe to update" branch) drops exactly that case, which is howBednet Check Multi-Stage Study — 2026kept advertisingmulti-stageon an LLO-facing surface while its own refreshed description said "deliberately NOT multi-stage". Do not rename the program to resolve it. The reconciler never putsnameinupdateArgs, and it is right not to:connect_update_programacceptsname, so ACE can rename, but a live LLO-facing program name is an operator's call. Surface it and move on — nothing downstream reads an archetype off a name (Step 2 matches on delivery type + archetype, never the name), so a stale token is a stale label, not a wrong input. -
If
inSync: note "program content verified against this run's PDD" in the program notes and continue (having already done 3). -
If diverging AND updating is safe (the normal case at Phase 4 — this run has not published a solicitation yet): apply the helper's
updateArgsviaconnect_update_program({ organization_slug, program_id, ...updateArgs })— but send the description asdescription_path, pointing at the file from sub-step 2, never as inlinedescription(grepdocs/atom-schemas.mdfor the current signature; do not restate it here). The server reads the bytes off disk, so the prose does not pass through the model a second time, and the bytes sent are the bytes the reconciler judged. An unreadable or empty file is a typed refusal naming the path and nothing is sent — a blanked description on a live LLO-facing program is the failure this guards (ace#2291). Never send delivery_type/currency/country — durable, andupdateArgsnever containsname. Log each refreshed field (old → new) in the program notes. -
If updating is unsafe (a live solicitation or external artifact already references the current text, or review mode withheld approval): the
[WARN]lines from step 3 are the record — one per diverging field, plus the name check — so the divergence lands somewhere visible instead of nowhere.
3b. On the REUSE path, check the candidate's locale and delivery type
against the PDD — and report, do not "fix". Hydrate the chosen
program via connect_get_program and compare its live
delivery_type / currency / country against the PDD's
connect_delivery_type / opportunity_currency / opportunity_country
(use checkProgramLocale for the latter pair). None of the three is
updatable, so a divergence has exactly two honest outcomes — inventing
a third is the failure mode:
- Emit a
[WARN]line per diverging field into the program notes and the phase summary, naming live-vs-PDD. This is the default. - Escalate to the operator when the CURRENCY diverges, because
that one silently misprices every payment unit built on the
program:
amount/org_amountare whole-currency-unit integers, so rates authored in INR against a USD program are out by ~83x, not merely mislabelled. State the only real remedy (a replacement program) and let the operator decide — do not create one unprompted.
Never send these fields to connect_update_program to close the gap —
it does not accept them, and a create-time-only field cannot be
reconciled after the fact.
-
Create the program via
connect_create_program:-
organization_slug: the configured PM org (connect_orgs.pm_orgfrom preflight; must be a program-manager org) -
name: archetype-signaling name (e.g."Vaccine Hesitancy Pilot (FGD) — Q2 2026") -
description: PDD's intervention summary -
delivery_type: readconnect_delivery_typefrom the PDD's § Program Parameters — do NOT choose one here. Resolve it againstconnect_list_delivery_types({organization_slug})and pass the matching row's intid. HALT if the PDD declares none, or if nothing in the live list matches — list the{id, name}rows that exist and ask. Never fall back to a nearest-looking label.Pass the
id, never a slug you derived from the name (dimagi-internal/ace#2865). The list atom deliberately returns noslug: the only page ACE can read renders<option value>+ label, so a slug is unreadable from here, and the derived one this atom used to return was right for 18 of 19 live delivery types and wrong for the 19th — on which Connect's REST create answered "delivery_type: Object with slug=19 does not exist." and Phase 4 had no working value at all. Matching the PDD'sconnect_delivery_typetext against the live LABELS is the right move; sending your normalisation of that text to Connect as if it were Connect's own slug is not. A stringdelivery_typeis still accepted and goes to the REST API — use it only for a slug you have from Connect itself. -
budget: total program budget from the PDD -
currency/country: readopportunity_currencyandopportunity_countryfrom the PDD, then gate them throughcheckProgramLocale(lib/program-locale.ts) before calling create. HALT onok: falseand surface the verdict'sdetailverbatim. The GATE works in ISO 3166-1 alpha-3 (the helper normalizes alpha-2 and plain names, so pass through whatever the PDD wrote), but SENDcountry: connectCountryName(verdict.country), never the alpha-3. Connect's create serializer matchescountryonCountry.name, so alpha-3 is rejected — live 2026-09-26, spark-facilitator/20260925-1536 Phase 4:country: 'MWI'→ "country: Object with name=MWI does not exist.";country: 'Malawi'→ created, and reads back asMWI(ace#2486). The write takes the name and the read returns alpha-3, so do not "fix" the send value to match the read-back. HALT ifconnectCountryNamereturnsnull; never type a spelling by hand. Sendcurrencyas the ISO 4217 code (verdict.expected). -
start_date/end_date: PDD timeline (YYYY-MM-DD)
Why these three are gated rather than defaulted.
delivery_type,currencyandcountryare create-time-only — step 3's update path is explicit thatconnect_update_programmust never be sent them. So a wrong value is not a bug you fix next run; it is baked into the program every future run of this opp reuses. Measured onai-demo-space2026-09-16, with nothing binding these to the PDD: seven of eleven live turmeric programs run under delivery typeInterviewfor a market survey, and the current one pairscountry: INDwithcurrency: USD— so every payment unit on it is denominated in the wrong money. Operator rule, 2026-09-16: an opportunity's amounts are always in the local currency of its country. Per the same decision these existing programs are left uncorrected (fix-forward only); the gate protects new ones. -
4a. Ensure program budget headroom (runs on both the reuse and create
paths; the raise is monotonic — it never shrinks a ceiling)
(jjackson/ace#588). Connect's program-budget validation on
connect_create_opportunity ("Budget exceeds the program budget") sums
the total_budget of all managed opps on the program — including
the inactive opps left by every prior /ace:run — against the fixed
program ceiling. There is no budget reclamation when a per-run opp goes
inactive, and per-run opp accumulation is expected by design (see
CLAUDE.md). So the ceiling monotonically fills until Phase 4 can no
longer create any opp (observed on malaria-rdt 20260531-0739: even a
2000 opp rejected against a 25000 ceiling with ~14 prior opps).
Because this is the durable, reused program (the reuse path skips create, so its budget never grows on its own), size the headroom here:
-
connect_get_program({ organization_slug, program_id })→program.budget. -
Compute Σ(
total_budget) over this program's opps — obtainable again as of ace#1550, having been unobtainable on every prior run. Callconnect_list_opportunities({ organization_slug, summarize_by_program: program.name, duplicate_program_name: <true iff the Step 2 program list shows two or more programs by this name>, program_created_this_invocation: <true iff Step 4 created the program in THIS invocation — never on the reuse path>, })On the create path, pass
program_created_this_invocation: true(ace#2083). A program Step 4 minted moments ago, before any opportunity was created against it, is newer than every row in the org — so a row whoseprogram_namecould not be read cannot be in it. The atom then rules the unreadable rows out (unreadable_rows_ruled_out: true,sigma_known: true, Σ = 0) instead of charging each oneEXPECTED_OPP_BUDGET, but only while the listing agrees (matched_rows == 0); a readable row already naming the program contradicts the claim and Σ stays unknown with a reason. Measured onpoverty-graduation/20260905-1345: a 40-second-old program withmatched_rows: 0and 11 org-widesetup_incompleterows was raised 126,000 → 176,400 for a consumption that was provably 0. On the reuse path the tax is genuinely warranted — those rows may be prior runs of this very program — so never pass it there.which implies
hydrate, does the whole classification server-side, and returns{listing, summary}with no rows —sigma_total_budget,sigma_known,sigma_unknown_reasons[],matched_rows,matched_opportunity_ids,excluded_outside_program,unreadable_rows,rows_missing_total_budgetanddashboard_read_counts. Readsummary.sigma_knownand branch; the four UNKNOWN conditions documented below are evaluated for you, andsigma_unknown_reasonsnames the ones that fired, verbatim, for the program notes.Do NOT ask for the rows and sum them yourself (ace#1799). The hydrated org-wide array measured 81,175 chars on
ai-demo-space2026-09-01 — over the tool-result cap, so it returns nothing usable and the step degrades to the conservative Σ-unknown branch or to an improvised out-of-band parse of the overflow file. Both fields exist on the HYDRATED row only:connect_get_opportunityreads them off the opportunity dashboard (the edit form carries neither, and the unhydrated list page carries nothing but id/name/short_description). If you genuinely need to inspect rows, passwrite_to_path: "/abs/path.json"and grep the file — never pull them into context.This Σ is the same set Connect itself sums —
Opportunity.objects.filter(program=program).aggregate(Sum( "total_budget"))inprogram/api/serializers.py, the check that raises "Budget exceeds the program budget" — so an exact Σ predicts the create-time rejection exactly.Never pass
program_idto the atom. The list page has no program column, so the atom used to silently ignore the filter and return the whole org; it is now refused loudly rather than dropped (ace#1022). Match onprogram_nameinstead — no opportunity read surface carries the program UUID.Cost, stated plainly: hydration fetches two pages per row across the whole org (concurrently, not serially) — the most expensive read in Phase 4. It buys the difference between a check and a guess: with Σ the raise is idempotent, without it the program ceiling inflates by
EXPECTED_OPP_BUDGET × 10on every run of every opp, forever, on the live LLO-facing program Step 3a reconciles against the PDD.First, split the rows on
dashboard_read(ace#1637). Every hydrated row carries it.total_budgetandprogram_nameare read off the opportunity DASHBOARD, and each degrades toundefinedwhen its card is absent — so until this marker existed, "in no program / states no budget" and "we could not read the page" were the same bytes. Onbednet-check-2-visit/20260825-1310, 16 of 81 hydratedai-demo-spacerows came back with the list-page key set only (noprogram_name, nototal_budget, nostart_date, no app ids), two of them prior runs of the very program being sized.-
dashboard_read: 'ok'— the page rendered and its infocards parsed. A missingprogram_nameon such a row is a FACT: the opp is in no program, so exclude it from Σ and do not let it make Σ unknown. A missingtotal_budgeton such a row is likewise a stated zero-or-absent budget, not a read failure. -
dashboard_read: 'setup_incomplete'— Connect refuses to render a dashboard for this opportunity at all (ace#1637; observed live 2026-09-06, 11 of 11 rows, repro below). Its setup was never finished, soOpportunityDashboard.get302s to the payment-unit wizard instead (is_setup_complete= payment unitstotal_budget+start_date+end_date, each payment unit withmax_total/max_daily). This is the ace#1637 cohort, root-caused 2026-09-06: 11 of 11 such rows onai-demo-spacereturned302 → …/payment_units/createwhile 6 of 6okrows returned 200. Still counts as unreadable for Σ — see the next bullet — but say so by name, because it is the one unreadable class that will never resolve by retrying, and because these are almost entirely ACE's own abandoned half-built opportunities from failed Phase 4 runs.
Do NOT read it as budget 0.
is_setup_completeis false when ANY of the four is missing, andconnect_create_opportunitysets a budget through the automation API without going near the form that requires payment units — so the redirect does not prove the budget is null. No Connect read surface states it either: the edit form has no budget field and/finalize/redirects to the same wizard (both verified live). -
anything else (
no_cards,not_a_dashboard,not_fetched) — the dashboard-sourced fields are UNREAD. Such a row can be neither assigned to nor excluded from the program. Count them asunreadable_rowsand carry that count into the branch below; never treat an unread field as an absent one.
Report the split verbatim in the program notes —
Σ over <k> rows; <n> excluded (no program, dashboard_read ok); <u> unreadable (<s> setup_incomplete). The atom returnssetup_incomplete_rowsnext tounreadable_rowsin thesummarize_by_programsummary, so this is a read, not a re-derivation.The residual this leaves is a COST, not a mystery: each
setup_incompleterow addsEXPECTED_OPP_BUDGETto the target below on every REUSED program sized against that org (the create path rules them out, above), and finishing or deleting the opportunity is the only thing that removes it. ACE cannot delete one: Connect exposes no opportunity-delete route (commcare_connect/opportunity/urls.py), and its only deletion path is thedelete_stale_opportunitiestask scheduled weekly by migration 0105 (opportunity/tasks.py), which removes opportunities created more than 6 months ago with no visits — so asetup_incompleterow ages out on its own after six months (ace#2083). (activebeing correlated-but-not-causal — 5 inactive rows DO carry the fields — is explained by the same finding: an opportunity can be deactivated after a complete setup.)Σ is UNKNOWN — not partial — in four cases. Check each before trusting it:
- the listing itself was incomplete: the atom returns a
listingblock alongsideopportunities, andlisting.complete !== truemeans rows exist that you did not see — Σ over the rows you got is not a smaller-but-valid total, it is a number about a different set. Reportlisting.truncated_reasonverbatim. (Connect paginates this view at 20 rows and said nothing about it until dimagi-internal/ace#1590; the walk is exhaustive now, so this should only fire above 5,000 opportunities in one org.); - a kept row carries no
total_budget(the dashboard's "Max Budget" card did not parse — this is how the field silently disappears if Connect restyles the page); - a row with
dashboard_readother than'ok'— itsprogram_nameandtotal_budgetwere not read, so it can be neither assigned to nor excluded from this program. A row withdashboard_read: 'ok'and noprogram_namedoes NOT make Σ unknown — it is definitively outside this program and is simply excluded (ace#1637). Asetup_incompleterow DOES make Σ unknown, and permanently: nothing in Connect will ever state its budget; - more than one program in the org shares
program.name(check the Step 2connect_list_programsresult) — the scoping is by NAME, so a duplicate name makes it ambiguous.
-
-
Raise the ceiling.
-
Σ known: raise only when
program.budget − Σ < EXPECTED_OPP_BUDGET × 3(keep room for at least a few more runs), viaconnect_update_program({ organization_slug, program_id, budget: Σ + EXPECTED_OPP_BUDGET × 10 })— a generous buffer so this step rarely re-fires, and a no-op when headroom is already ample.EXPECTED_OPP_BUDGET= the PDD's per-opp budget (default the program's own per-opp figure). -
Σ unknown: raise to a computed TARGET, and only if the ceiling is actually below it. Never
program.budget + …(ace#1637): a raise expressed relative to the current ceiling is not idempotent, so it compounds on every run of every opp on the shared program, forever, purely because a read failed. That is exactly what happened onbednet-check-2-visit/20260825-1310, which liftedBednet Check Multi-Stage Study — 2026from 19,400 to 64,400 against a KNOWN consumption of 4,062.Compute the worst case from what you actually know:
target = knownΣ # rows summed with dashboard_read: 'ok' + unreadable_rows × EXPECTED_OPP_BUDGET # assume each unread row consumes a full opp + EXPECTED_OPP_BUDGET × 3 # the same headroom the Σ-known branch keepsRaise only when
program.budget < target, and then totargetexactly. This is monotonic (it never shrinks a ceiling), it is idempotent (a second run with the same rows computes the same target and no-ops), and it bounds the ceiling by the number of opps that could plausibly exist rather than by how many times this step has run. Iflisting.complete !== true— the one case where you do not know how many rows exist at all — fall back toprogram.budget + EXPECTED_OPP_BUDGET × 10and say so, because there is genuinely no bound to compute.
Log the before/after budget in the program notes (Step 5) and which branch fired —
Σ = <n> over <k> oppsorΣ unknown (<reason>). Never write a computed Σ you did not actually compute: an unreported fallback is indistinguishable from a working check, which is precisely why ace#1550 went unnoticed for as long as it did.Single-opp floor:
EXPECTED_OPP_BUDGETmust itself be at leastmin_budget_for_one_user × FUND_USERS(=Σ(max_total × (amount + org_amount))over the planned payment units × ~3, the same floorconnect-opp-setupStep 4 enforces). If the PDD's per-opp budget is below that floor, use the floor — the program ceiling must be able to fund at least one opp that funds ≥1 FLW at its payment-unit max, or Phase 4 will halt on the budget-funds-≥1-FLW guard. -
This makes the by-design per-run accumulation safe without a reclamation mechanism (none exists yet — a payment-unit-delete / opp-budget-zeroing capability is tracked upstream, see jjackson/ace#573). When Connect's budget check is changed to count only active managed opps (the real fix, jjackson/ace#588), this headroom step can be relaxed.
-
Write program details via
drive_create_filewithparentFolderId = phaseFolderId(the4-connectfolder; surfaced atACE/<opp-name>/runs/<run-id>/4-connect/connect-program-setup.md):- Program ID (UUID)
- Program name
- Archetype declared at program creation (if new)
- Whether reused or newly created; note any archetype mismatch if reused
- Configuration details (delivery_type name + id, budget, currency, country, dates)
-
Persist program reference to
opp.yamlviamcp__plugin_ace_ace-gdrive__update_yaml_filewith the defaultshallowmerge —connect:is a top-level scalar key:connect: program: id: <UUID from step 3 reuse or step 4 create> url: <CONNECT_BASE_URL>/a/<org>/program/<uuid>/ connect_int_id: <integer | omit> # ConnectProd integer program id, resolved in Step 6a. NOT a labs-minted id. Lets solicitation-create skip a Labs round-trip. Omit while Step 6a has not resolved it — solicitation-create Step 5 resolves it as a fallback.Write
connect_int_idonly once Step 6a has resolved it. On the reuse path, leave any existingconnect_int_idinopp.yamlas-is (don't clear it). Anint_idon aconnect_create_program/connect_get_programresult is used if present, but expect none (6a).
6a. Resolve connect_int_id through labs — Connect will not hand it to
ACE (ace#3213). No Connect surface ACE can reach returns the program's
integer id, so do not wait for one on the create response:
- The REST create answers with
ProgramResponseSerializer, whosefieldsareprogram_id, name, slug, description, organization, delivery_type, budget, currency, country, start_date, end_date— noid(dimagi/commcare-connectcommcare_connect/program/api/serializers.py). The int-delivery_typepath goes to the HTML form, whose response is a re-rendered fragment. - Every web program route (
init/,<pk>/edit,<pk>/view,<pk>/invite,<pk>/opportunity-init) is keyed and rendered by the UUID (program/urls.py,templates/program/pm_home.html). - The only surface that emits the integer is the data export
(
/export/opp_org_program_list/,ProgramDataExportSerializerfields = ["id", "name", ...]— and no UUID), behindTokenHasScopeexport: an OAuth token, so ACE's session cookie gets 403. Labs holds that token, which is whylabs_contextis the path.
Call mcp__connect-labs__labs_context({search: <exact program name>}),
take the organization whose slug is this program's org, and within it
the program whose name equals the Connect program name exactly. One
match → that id is connect_int_id: write it to
opp.yaml.connect.program.connect_int_id with update_yaml_file
merge: 'deep' (a partial patch of connect.program), then run Step 7.
Zero or several → unresolved; never pick by "newest id" or a partial
name.
A fresh program is invisible to labs for up to an hour. Labs caches
the whole org tree per user for _ORG_DATA_CACHE_TTL = 3600 seconds
and the labs_context tool has no refresh argument
(dimagi-internal/connect-labs
connect_labs/labs/integrations/connect/oauth.py,
connect_labs/mcp/tools/labs_context.py). Observed on
connect-fi/20261018-1440: four lookups over the 20 minutes after the
create returned organizations: []. So a miss right after create is
expected, not a sign the program is missing. Re-run the lookup at the
END of Phase 4 (after connect-opp-setup), and once more ~60 minutes
after the create if the phase is still going. Still unresolved: leave
connect_int_id unset, and record a residual naming the program name,
the UUID, and the two commands that finish the job —
the labs_context lookup and
bin/ace-bind --add-program <connect_int_id> <workspace>/<opp>.
solicitation-create Step 5 retries the lookup and runs the bind
(Phase 8 starts well past the cache window).
opp.yaml is the only cross-run identity surface for the
Connect program — every subsequent run of this opp reads this
block to skip program-create (Step 3 reuse path). The Connect
opportunity, OCS chatbot, solicitation, etc. are per-run and
live in the producing run's run_state.yaml.phases.*.products.*;
only program is durable here.
Skip this write on the reuse path only if the existing
opp.yaml.connect.program.id value already matches what we just
verified live — no-op writes are fine but unnecessary. On any
value mismatch, overwrite (the live value wins; opp.yaml gets
corrected).
-
Register the program in the opp's tenancy (create AND reuse paths), so ACE's tenancy guard checks every later program-scoped labs write —
create_solicitation,create_response, everysupply_chain_*write, most of which labs cannot delete — against it (ace-web#914):"$CLAUDE_PLUGIN_ROOT/bin/ace-bind" --add-program <connect_int_id> [<workspace>/<opp>]It adds the id to ace-web's
connect_program_ids(an audited owner PATCH; a no-op when already there) and refreshes this session's binding, keeping its warn/enforce mode. The target defaults to the bound opp; pass<workspace>/<opp>when the session is unbound. It is safe because the program was just created in — or verified against — the opp's own PM org, which the guard checked. Withoutconnect_int_id(Step 6a still unresolved) there is nothing to register yet: say so in the step's summary with the 6a residual —solicitation-createStep 5 registers it once it resolves the id. A failure (not an owner, ace-web not yet carrying the field) does not fail this step — record it as a residual naming the command to re-run; until then program-scoped labs writes are refused as not set up (warn mode only logs them).
MCP Tools Used
- Google Drive:
drive_read_file,drive_create_file(always withparentFolderId = phaseFolderId— the4-connectfolder ID, never a path string),update_yaml_file(writeopp.yaml.connect.programblock,merge: 'shallow') - Connect (
ace-connectMCP, 0.10.47+):connect_list_programs— discovery (name= case-insensitive substring; filtered rows hydrated with FULL descriptions). Unfiltered rows carry capped descriptions flaggeddescription_truncated(ace#1799);full_descriptions: trueorwrite_to_pathopt outconnect_list_delivery_types— resolve the PDD'sconnect_delivery_typeagainst the live{id, name}rows; pass the intidto create. Returns noslugon purpose (ace#2865)connect_create_program— create (intdelivery_type→ the HTML form; a slug → RESTPOST /api/programs/). Returns the UUID only — no integer id on either path (Step 6a)connect_get_program— verify after create; read live fields for reconcile (Step 3a) andbudgetfor the headroom check (Step 4a)connect_list_opportunities— prefersummarize_by_program, which implies hydrate and returns the Σ classification instead of the rows (ace#1799);write_to_pathwrites the rows to disk. Withhydrate: true, the ONLY source of the headroom Σ's two inputs (total_budget,program_name— both dashboard-read per row, ace#1550); the unhydrated list page carries neither (Step 4a). Returns alistingcompleteness block;listing.complete !== truemakes Σ UNKNOWN (ace#1590)connect_update_program— refresh stale description/dates on reuse (Step 3a); raise the program budget ceiling, idempotently when Σ is known and on the conservative assumption when it is not (Step 4a). Send the refreshed description asdescription_path(an absolute local path the server reads off disk), never inline (ace#2291)
- Connect Labs (
connect-labsMCP):labs_context— the only reachable source of the program's integer id (connect_int_id, Step 6a; cached up to an hour after create, ace#3213)
Mode Behavior
- Auto: Create program (or reuse), proceed
- Review: Present program choice for approval before calling
connect_create_program
Dry-Run Behavior
When --dry-run is active:
- Write the program configuration (name, description, settings) to
comms-log/dry-run-connect-program-setup.md - Do not call
connect_create_program - State tracks as
dry-run-success
Archetypes
Program-level naming + description should hint the archetype for downstream coherence:
atomic-visit: prefer names like"<Domain> Survey — <Year>"or"<Domain> Field Deployment". Description leads with FLW deployment.focus-group: prefer names like"<Domain> FGD Pilot"or"<Domain> Qualitative Research". Description leads with discussion- group method.longitudinal-visits: prefer names like"<Domain> Follow-Up Study"or"<Domain> Two-Visit Study"— a name that signals a tracked entity revisited on its own clock. Description leads with the entity and its states (what is registered, what is revisited, what closes it). Do NOT name one"<Domain> Multi-Stage Study". The two archetypes are routinely confused and the distinction is exactly what the name should carry:multi-stagestages the PROGRAMME (one clock, a cohort advancing together through a go/no-go gate, a Learn app + Deliver app- payment unit per stage), while
longitudinal-visitsstages the ENTITY (each case runs its own clock independently, and the programme wants exactly one of each).
- payment unit per stage), while
multi-stage: prefer names like"<Domain> Multi-Stage Study". Description names each stage's protocol.
A name outlives the run that chose it. name is a DURABLE field
(lib/program-reconcile.ts § DURABLE_PROGRAM_FIELDS) — not because it is a
lookup key (Step 2 explicitly is not one), but because renaming a live,
LLO-facing program is an operator's call. So Step 3a refreshes description /
budget / dates against a later run's PDD but never the name. An archetype token
baked into a name is therefore permanent: when a later run's PDD declares a
different archetype, the description gets corrected and the name does not.
Live case — program efb8af66-… reads Bednet Check Multi-Stage Study — 2026 while its own refreshed description says "deliberately NOT
multi-stage" (ace#1966). Two consequences to work with, not around:
- Prefer an archetype-NEUTRAL name when the archetype is at all
contested in the PDD (a
## Archetypesection that argues against a sibling archetype is the tell)."<Domain> Follow-Up Study"survives a later reclassification;"<Domain> Multi-Stage Study"does not. - On reuse, if the live name's archetype token contradicts this run's
PDD archetype, say so. This is no longer yours to remember: pass the
live
nameand the PDDarchetypetoreconcileProgramWithPddand it returns the[WARN]line inwarnings[](nameArchetype), which Step 3a.3 emits unconditionally. Do not rename the program to fix it — surface it and let an operator decide. And note the reason is NOT "the name is the reuse-lookup key", which this file itself refutes at Step 2 (nonamefilter; match on delivery type + archetype; ace#1252). A rename would break no lookup. It is withheld because a live LLO-facing program name is an operator's decision, and because nothing needs it to be correct: the name is not authoritative for the archetype, the PDD is.
Decisions Log
Rows this skill writes use phase: "4-connect" and skill: "connect-program-setup", appended via decisions_append_rows.
Review fields (schema v6 — REQUIRED). The decisions log is the run's review artifact (the build memo is retired). Every row this skill appends carries plain — one plain-language line for a programme partner who has never seen ACE — and, where the choice is visible somewhere a reviewer can open, check_at + correct_looks_like. The atom rejects a partner-facing row without plain, or with jargon in it. Rules, a worked row and the review_ask semantics: skills/_decisions-review-fields.md; field contract: docs/decisions-contract.md.
Change Log
| Date | Change | Author |
|---|---|---|
| 2026-10-18 | ## Inputs are parameters with resolvers (org, archetype, domain, the create-time fields; the PDD is one resolver). Step 1 resolves explicit values first; Step 4's gates apply to explicit values the same way. | ACE (#3148 batch 3) |
| 2026-10-16 | Step 4a: the create path rules org-wide unreadable rows OUT of a program it just minted (ace#2083). A setup_incomplete opportunity is permanently unreadable, so each one forced Σ unknown and added EXPECTED_OPP_BUDGET to the target of every program sized against the org — including a brand-new one that provably contained nothing (poverty-graduation/20260905-1345: 0 matched rows, 11 unreadable, raised 126,000 → 176,400). connect_list_opportunities gains program_created_this_invocation; with it, and with matched_rows == 0, summarizeOpportunitiesByProgram reports sigma_known: true and unreadable_rows_ruled_out: true. The reuse path is unchanged. The sweep half stays upstream-bound: Connect has no opportunity-delete route; its own weekly delete_stale_opportunities removes no-visit opportunities older than 6 months. Enforced: test/lib/connect-list-projection.test.ts § create-path narrowing. | ACE team |
| 2026-10-15 | Step 3a no longer proposes NARROWING a reused program's window below opportunities already on it (ace#2985). reconcileProgramWithPdd compared start_date/end_date by string equality and put any difference in updateArgs, so on smallholder-seasonal/20261015-1402 (program 09b74c39-…) it proposed end_date: 2030-01-31 while both existing opportunities end 2030-02-28. Dates now have containment semantics like budget: start_date diverges only when live starts later than the PDD, end_date only when live ends earlier; a wider live window is no diff, no updateArgs, no [WARN]. Enforced: test/lib/program-reconcile.test.ts § date containment, incl. the live repro. | ACE team |
| 2026-09-17 | The reuse-path description refresh no longer round-trips ~21 KB of prose through the model (ace#2291). connect_update_program gained description_path, the same <param>_path handle this server already offers on new_xform_xml_path / file_bytes_path / ccz_path: the server reads the bytes off disk verbatim. Step 3a refreshes description on EVERY reuse and reuse is the normal path after an opp's first run, so the inline-only shape cost ~5.8k output tokens per run forever (measured live 2026-09-17 on program efb8af66, ai-demo-space: 21,012 chars). It also removes a correctness gap — the description the reconciler judged and the description sent were two separate generations, with nothing making them match (the ace#1737 class). Step 3a now authors the description to a file first and points BOTH consumers at it. A relative, unreadable or empty file is a typed refusal naming the path with nothing sent, never a silently blanked LLO-facing description. Enforced: test/mcp/connect/unit/update-program-description-path.test.ts. | ACE team |
| 2026-09-06 | The name is made NON-AUTHORITATIVE in code, not in prose (ace#1966, cause #2). reconcileProgramWithPdd now takes the live name and the PDD archetype and returns nameArchetype, a CheckOutcome (lib/check-outcome.ts): a name whose archetype token contradicts this run's PDD produces a [WARN] in warnings[], and a caller that passes neither gets a loud UNABLE TO CHECK rather than silence. Step 3a now emits warnings[] unconditionally, before branching — inSync covers only the four refreshable fields, so the live case (Bednet Check Multi-Stage Study — 2026, content fully refreshed, inSync: true) was dropped by every branch that existed. name still never enters updateArgs: the reconciler reports, it does not rename. Also corrects the module's own false rationale — name was documented as durable "because it is the cross-run reuse-lookup key", which Step 2 has contradicted since ace#1252 (no name filter; match on delivery type + archetype). | ACE team |
| 2026-09-05 | § Archetypes: add the missing longitudinal-visits row, and state that a name outlives the run that chose it (ace#1966). The section covered atomic-visit / focus-group / multi-stage only — grep -n "longitudinal" on this file returned zero hits — even though connect-opp-setup § Archetypes has covered longitudinal-visits for some time, so an archetype ACE fully supports at the opportunity layer was named by improvisation at the program layer. Compounding it, name is in DURABLE_PROGRAM_FIELDS, so Step 3a can refresh a program's description against a later PDD but never its name: bednet-check-2-visit reuses a program called Bednet Check Multi-Stage Study — 2026 whose own ACE-refreshed description now says "deliberately NOT multi-stage", and the mislabel undermines Step 2's archetype-matched reuse scan. Guidance is to prefer archetype-neutral names when the archetype is contested and to [WARN] on a contradiction rather than autonomously rename a durable reuse key. The lib/program-reconcile.ts half stays open on ace#1966. | ACE team |
| 2026-08-26 | Step 4a can tell an ABSENT field from an UNREAD one, and the Σ-unknown raise is idempotent (ace#1637 — same class as #1550/#1590, third mechanism). connect_get_opportunity now returns dashboard_read (ok / no_cards / not_a_dashboard / not_fetched, from classifyDashboardRead in mcp/connect/backends/html-scrape.ts). total_budget / program_name / start_date come only off the opportunity dashboard and each degrades to undefined when its card is absent, so "in no program" and "could not read the page" were the same bytes; 16 of 81 hydrated ai-demo-space rows on bednet-check-2-visit/20260825-1310 were the second kind, two of them prior runs of the program being sized. A row with dashboard_read: 'ok' and no program_name is now EXCLUDED rather than making Σ unknown; only a genuinely unread row does. And the Σ-unknown branch no longer raises relative to the current ceiling — program.budget + EXPECTED_OPP_BUDGET × 10 is not idempotent, so it compounded every run and took that program from 19,400 to 64,400 against a known consumption of 4,062. It now computes knownΣ + unreadable_rows × EXPECTED_OPP_BUDGET + EXPECTED_OPP_BUDGET × 3 and raises only if the ceiling is below it. The relative raise survives only where no bound is computable (listing.complete !== true). Upstream residual left open and stated: why those 16 rows render no cards is still unknown — active is correlated but not causal. Enforced: test/mcp/connect/unit/dashboard-read-honesty.test.ts. | ACE team |
| 2026-04-28 | Replace HITL workaround with connect_*_program atoms (ace-connect 0.8.1) | ACE team |
| 2026-04-30 | Switch connect_create_program to POST /api/programs/ (commcare-connect PR #1135). delivery_type now accepts the slug; country is the human country name. (0.10.47) | ACE team |
| 2026-07-30 | Step 3a: reconcile reused program content (description/budget/dates) against the current run's PDD via lib/program-reconcile.ts — update or [WARN] per diverging field (jjackson/ace#1078). Note substring-match + hydration semantics of connect_list_programs (jjackson/ace#1089). | ACE team |
| 2026-08-21 | Step 4a: invert the branches — Σ(total_budget) is unobtainable on every Connect read surface, so the conservative raise is now the documented PRIMARY path and the connect_list_opportunities({hydrate: true}) call is dropped (20 sequential edit-page fetches for zero fields). Computed-Σ kept as the restore-if path (dimagi-internal/ace#1550). | ACE team |
| 2026-08-23 | Step 4a: a fourth UNKNOWN condition — connect_list_opportunities walked only Connect's first page (20 rows) with no signal more existed, so Σ could be computed over a fifth of the program and read as complete. The atom now paginates to exhaustion and returns a listing completeness block; Σ is UNKNOWN when listing.complete !== true (dimagi-internal/ace#1590). | ACE team |
| 2026-08-21 | Step 4a: Σ is executable again — connect_get_opportunity now reads total_budget + program_name off the opportunity dashboard, so a hydrated list can be scoped to this program and summed (supersedes the row above, same day). Names the three UNKNOWN cases and requires the branch taken to be reported in the program notes (dimagi-internal/ace#1550). | ACE team |
| 2026-09-01 | Steps 2 + 4a: both MANDATED org-wide list calls overflowed the tool-result cap in ai-demo-space and returned no usable data (measured 2026-09-01: programs 42 rows/57,425 chars, 75.3% description prose; opportunities hydrated 71 rows/81,175 chars). Step 4a now calls connect_list_opportunities({summarize_by_program}), which does the whole Σ classification server-side and returns a few hundred characters instead of the rows; Step 2's unfiltered rows come back with capped descriptions. write_to_path on both atoms is the escape hatch (dimagi-internal/ace#1799). | ACE team |
| 2026-09-06 | Stop routing concerns to a gate brief that does not exist (dimagi-internal/ace#1884). 0.13.116 removed the per-skill gate-brief file class and the ace#1880 sweep removed the remaining *.md PATHS, but prose directives naming the gate brief as a DESTINATION survived in 15 files — a concern "surfaced in the gate brief" is surfaced nowhere. Repointed at the verdict YAML's auto_surfaced block, which is what the orchestrator actually renders the pause summary from. Gated by the new destination check in test/skills/gate-brief-removal-complete.test.ts. | ACE team |
| 2026-09-06 | Root-caused ace#1637: the unreadable rows are opportunities Connect REFUSES to render a dashboard for, and they now say so (dashboard_read: 'setup_incomplete'). OpportunityDashboard.get 302s any opportunity whose is_setup_complete is false (payment units + total_budget + start_date + end_date, each unit with max_total/max_daily) to the payment-unit wizard — and ace-connect FOLLOWED that redirect, so parseOpportunityDashboard was handed the wizard and classifyDashboardRead correctly reported no_cards about the wrong page. Measured live 2026-09-06 on ai-demo-space: 11 of 11 previously-no_cards rows returned 302 → …/payment_units/create and 6 of 6 ok rows returned 200; 10 of the 11 have zero payment units. The detail fetch now uses maxRedirects: 0 and the status + Location reach the classifier. Step 4a still counts these as unreadable and the arithmetic is unchanged — is_setup_complete is false when ANY of the four is missing and connect_create_opportunity sets a budget through the automation API without payment units, so inferring 0 would be a guess about a value Connect owns — but the count is reported separately as setup_incomplete_rows, because it is the one unreadable class retrying can never fix. active being correlated-but-not-causal is explained by the same finding. Enforced: test/mcp/connect/unit/dashboard-read-honesty.test.ts (incl. a pin on maxRedirects: 0) + test/lib/connect-list-projection.test.ts. | ACE team |
| 2026-09-16 | delivery_type, currency and country are now READ from the PDD and gated, not chosen here (operator decision 2026-09-16). All three are create-time-only — step 3.5 already forbids sending them to connect_update_program — so a wrong value is baked into a program every future run of the opp reuses, and nothing bound them to the design. Measured on ai-demo-space 2026-09-16: seven of eleven live turmeric programs run under delivery type Interview for a market survey, and the current one (b2ca75f6) pairs country: IND with currency: USD, mispricing every payment unit built on it (amount/org_amount are whole-currency-unit integers, so an INR rate against a USD program is out by ~83x, not mislabelled). Step 4 now resolves connect_delivery_type against the live connect_list_delivery_types and HALTS on an absent or unmatched slug, and gates {country, currency} through checkProgramLocale (lib/program-locale.ts), which never defaults to USD and halts on an unrecognised country. New step 3b applies the same comparison on the REUSE path, where the fields cannot be repaired at all — [WARN] per divergence, operator escalation when the CURRENCY diverges. Upstream, idea-to-pdd-qa § launch_parameters_present now requires and coherence-checks the trio, so an incoherent pair fails at Phase 1 rather than Phase 4. Existing programs are deliberately left uncorrected (fix-forward only, same decision). Enforced: test/lib/program-locale.test.ts + test/skills/idea-to-pdd-qa/launch-parameters.test.ts. | ACE team |
| 2026-09-26 | Step 4 SENDS the country NAME, not the alpha-3 (ace#2486). The 2026-09-16 row told Step 4 to send the normalized verdict.country (alpha-3), regressing the correct 2026-04-30 contract: Connect's create serializer is SlugRelatedField(slug_field="name") on Country, so country: 'MWI' failed live with "country: Object with name=MWI does not exist." (spark-facilitator/20260925-1536 Phase 4, 2026-09-26) while 'Malawi' succeeded and read back as MWI. The gate still works in alpha-3; the send value is now derived via connectCountryName (lib/program-locale.ts), whose CONNECT_COUNTRY_NAME is copied from Connect's own COUNTRIES seed (migration 0092), not a generic ISO list. Enforced: test/lib/program-locale.test.ts (coverage of every COUNTRY_CURRENCY key, MWI → Malawi, unknown → null, name round-trips through normalizeCountry). | ACE team |
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 |