Skip to content

dimagi-internal/ace / skills/connect-program-setup

connect-program-setup

Unverified

Create 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

ParameterUsed forResolver
organization_slugthe 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)
archetypearchetype-aware program naming + archetype-matched reuseexplicit arg; default: the PDD's archetype: frontmatter
domain, descriptionthe domain match in the reuse scan, and the program descriptionexplicit arg; default: the PDD
connect_delivery_type, country, currency, budget, datesthe create-time-only program fields Step 4 gatesexplicit arg; default: the PDD's program_parameters
pddthe resolver for every field above that the caller does not passexplicit arg (a Drive file id); default: 1-design/idea-to-pdd.md
existing programsthe reuse-vs-create decisionread 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 with parentFolderId = phaseFolderId) — program-id, decision rationale (reuse / create), admin program URL
  • opp.yaml.connect.program.{id, url, connect_int_id} — written on first create (and refreshed on reuse with verified live values). connect_int_id is ConnectProd's integer program id, resolved through labs_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

  1. 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 the archetype: 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 ## Archetypes below.

  2. Check for existing programs that match this opportunity's domain/scope. Call connect_list_programs({organization_slug}) with NO name filter 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: a name: 'Bednet' query returned 12 programs and could never return Malaria 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 null for delivery_type/budget/currency/ country/dates — hydrate the shortlisted candidates via connect_get_program before 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-space 2026-09-01, 42 rows serialize to 57,425 chars of which 43,239 (75.3%) are description, and the call returned no usable data at all. A capped row is flagged description_truncated: true and a description_projection block reports the count. The domain signal you shortlist on is in the opening sentences; when you need the whole thing, read it from connect_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. (The name filter 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.

  3. 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:

  1. connect_get_program({ organization_slug, program_id }) → live refreshable fields.

  2. 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 durable bednet-check-2-visit program, 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 via npx tsx -e, having the snippet readFileSync that 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, so start_date diverges only when the live start is later than the PDD start and end_date only 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 live name and the PDD's archetype — they cost nothing and they are what powers step 3 below.

  3. Emit every line in warnings[] verbatim into the program notes and the run summary — UNCONDITIONALLY, before branching on anything (ace#1966). inSync is about the four REFRESHABLE fields only, so a program whose content this run has just brought fully up to date reports inSync: true and can still carry a warnings[] entry: nameArchetype fires when the durable NAME asserts an archetype the PDD does not declare. Gating the emit on inSync (or on the "unsafe to update" branch) drops exactly that case, which is how Bednet Check Multi-Stage Study — 2026 kept advertising multi-stage on 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 puts name in updateArgs, and it is right not to: connect_update_program accepts name, 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.

  4. If inSync: note "program content verified against this run's PDD" in the program notes and continue (having already done 3).

  5. If diverging AND updating is safe (the normal case at Phase 4 — this run has not published a solicitation yet): apply the helper's updateArgs via connect_update_program({ organization_slug, program_id, ...updateArgs }) — but send the description as description_path, pointing at the file from sub-step 2, never as inline description (grep docs/atom-schemas.md for 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, and updateArgs never contains name. Log each refreshed field (old → new) in the program notes.

  6. 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_amount are 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.

  1. Create the program via connect_create_program:

    • organization_slug: the configured PM org (connect_orgs.pm_org from 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: read connect_delivery_type from the PDD's § Program Parameters — do NOT choose one here. Resolve it against connect_list_delivery_types({organization_slug}) and pass the matching row's int id. 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 no slug: 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's connect_delivery_type text 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 string delivery_type is 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: read opportunity_currency and opportunity_country from the PDD, then gate them through checkProgramLocale (lib/program-locale.ts) before calling create. HALT on ok: false and surface the verdict's detail verbatim. 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 SEND country: connectCountryName(verdict.country), never the alpha-3. Connect's create serializer matches country on Country.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 as MWI (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 if connectCountryName returns null; never type a spelling by hand. Send currency as 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, currency and country are create-time-only — step 3's update path is explicit that connect_update_program must 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 on ai-demo-space 2026-09-16, with nothing binding these to the PDD: seven of eleven live turmeric programs run under delivery type Interview for a market survey, and the current one pairs country: IND with currency: 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:

  1. connect_get_program({ organization_slug, program_id }) → program.budget.

  2. Compute Σ(total_budget) over this program's opps — obtainable again as of ace#1550, having been unobtainable on every prior run. Call

    connect_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 whose program_name could 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 one EXPECTED_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 on poverty-graduation/20260905-1345: a 40-second-old program with matched_rows: 0 and 11 org-wide setup_incomplete rows 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_budget and dashboard_read_counts. Read summary.sigma_known and branch; the four UNKNOWN conditions documented below are evaluated for you, and sigma_unknown_reasons names 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-space 2026-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_opportunity reads 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, pass write_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")) in program/api/serializers.py, the check that raises "Budget exceeds the program budget" — so an exact Σ predicts the create-time rejection exactly.

    Never pass program_id to 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 on program_name instead — 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 × 10 on 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_budget and program_name are read off the opportunity DASHBOARD, and each degrades to undefined when 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. On bednet-check-2-visit/20260825-1310, 16 of 81 hydrated ai-demo-space rows came back with the list-page key set only (no program_name, no total_budget, no start_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 missing program_name on such a row is a FACT: the opp is in no program, so exclude it from Σ and do not let it make Σ unknown. A missing total_budget on 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, so OpportunityDashboard.get 302s to the payment-unit wizard instead (is_setup_complete = payment units

      • total_budget + start_date + end_date, each payment unit with max_total/max_daily). This is the ace#1637 cohort, root-caused 2026-09-06: 11 of 11 such rows on ai-demo-space returned 302 → …/payment_units/create while 6 of 6 ok rows 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_complete is false when ANY of the four is missing, and connect_create_opportunity sets 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 as unreadable_rows and 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 returns setup_incomplete_rows next to unreadable_rows in the summarize_by_program summary, so this is a read, not a re-derivation.

    The residual this leaves is a COST, not a mystery: each setup_incomplete row adds EXPECTED_OPP_BUDGET to 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 the delete_stale_opportunities task scheduled weekly by migration 0105 (opportunity/tasks.py), which removes opportunities created more than 6 months ago with no visits — so a setup_incomplete row ages out on its own after six months (ace#2083). (active being 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 listing block alongside opportunities, and listing.complete !== true means 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. Report listing.truncated_reason verbatim. (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_read other than 'ok' — its program_name and total_budget were not read, so it can be neither assigned to nor excluded from this program. A row with dashboard_read: 'ok' and no program_name does NOT make Σ unknown — it is definitively outside this program and is simply excluded (ace#1637). A setup_incomplete row 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 2 connect_list_programs result) — the scoping is by NAME, so a duplicate name makes it ambiguous.
  3. Raise the ceiling.

    • Σ known: raise only when program.budget − Σ < EXPECTED_OPP_BUDGET × 3 (keep room for at least a few more runs), via connect_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 on bednet-check-2-visit/20260825-1310, which lifted Bednet Check Multi-Stage Study — 2026 from 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 keeps
      

      Raise only when program.budget < target, and then to target exactly. 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. If listing.complete !== true — the one case where you do not know how many rows exist at all — fall back to program.budget + EXPECTED_OPP_BUDGET × 10 and 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> opps or Σ 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_BUDGET must itself be at least min_budget_for_one_user × FUND_USERS (= Σ(max_total × (amount + org_amount)) over the planned payment units × ~3, the same floor connect-opp-setup Step 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.

  1. Write program details via drive_create_file with parentFolderId = phaseFolderId (the 4-connect folder; surfaced at ACE/<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)
  2. Persist program reference to opp.yaml via mcp__plugin_ace_ace-gdrive__update_yaml_file with the default shallow merge — 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_id only once Step 6a has resolved it. On the reuse path, leave any existing connect_int_id in opp.yaml as-is (don't clear it). An int_id on a connect_create_program / connect_get_program result 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, whose fields are program_id, name, slug, description, organization, delivery_type, budget, currency, country, start_date, end_date — no id (dimagi/commcare-connect commcare_connect/program/api/serializers.py). The int-delivery_type path 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/, ProgramDataExportSerializer fields = ["id", "name", ...] — and no UUID), behind TokenHasScope export: an OAuth token, so ACE's session cookie gets 403. Labs holds that token, which is why labs_context is 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).

  1. 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, every supply_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. Without connect_int_id (Step 6a still unresolved) there is nothing to register yet: say so in the step's summary with the 6a residual — solicitation-create Step 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 with parentFolderId = phaseFolderId — the 4-connect folder ID, never a path string), update_yaml_file (write opp.yaml.connect.program block, merge: 'shallow')
  • Connect (ace-connect MCP, 0.10.47+):
    • connect_list_programs — discovery (name = case-insensitive substring; filtered rows hydrated with FULL descriptions). Unfiltered rows carry capped descriptions flagged description_truncated (ace#1799); full_descriptions: true or write_to_path opt out
    • connect_list_delivery_types — resolve the PDD's connect_delivery_type against the live {id, name} rows; pass the int id to create. Returns no slug on purpose (ace#2865)
    • connect_create_program — create (int delivery_type → the HTML form; a slug → REST POST /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) and budget for the headroom check (Step 4a)
    • connect_list_opportunities — prefer summarize_by_program, which implies hydrate and returns the Σ classification instead of the rows (ace#1799); write_to_path writes the rows to disk. With hydrate: 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 a listing completeness block; listing.complete !== true makes Σ 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 as description_path (an absolute local path the server reads off disk), never inline (ace#2291)
  • Connect Labs (connect-labs MCP): 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-stage stages 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-visits stages the ENTITY (each case runs its own clock independently, and the programme wants exactly one of each).
  • 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:

  1. Prefer an archetype-NEUTRAL name when the archetype is at all contested in the PDD (a ## Archetype section that argues against a sibling archetype is the tell). "<Domain> Follow-Up Study" survives a later reclassification; "<Domain> Multi-Stage Study" does not.
  2. 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 name and the PDD archetype to reconcileProgramWithPdd and it returns the [WARN] line in warnings[] (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 (no name filter; 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

DateChangeAuthor
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-16Step 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-15Step 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-17The 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-06The 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-26Step 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-28Replace HITL workaround with connect_*_program atoms (ace-connect 0.8.1)ACE team
2026-04-30Switch 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-30Step 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-21Step 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-23Step 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-21Step 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-01Steps 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-06Stop 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-06Root-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-16delivery_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-26Step 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
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall