Skip to content

feat(blocks): shared prompt and config blocks, with a sync command - #111

Open
devin-ai-integration[bot] wants to merge 10 commits into
dr/credential-pin-checkfrom
dr/blocks
Open

devin-ai-integration[bot] wants to merge 10 commits into
dr/credential-pin-checkfrom
dr/blocks

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #94 (same commits, rebased onto main), opened as the Devin bot so it can be approved.

Value

V.A.L.U.E. tier: small. One new engine feature with its guard rails, tests, an example and a guide.

  • Problem: teams repeat the same prompt paragraphs (safety wording, tone) and the same settings (voice, transcriber, squad overrides) across assistants, squads and orgs, and the copies drift. Nothing in the engine could hold one copy. YAML anchors only reach inside one file and pull expands them, merge keys (<<) aren't processed at all and get sent to the API as a field, and Liquid {% include %} renders as nothing on a call.
  • Who it affects: anyone running more than one assistant or more than one org from this repo, most of all a group of sites that share one set of prompts.

How it works

  1. Prompt blocks. A line that says only @include <name> in a system prompt is replaced by templates/blocks/<name>.md. It works in an assistant's Markdown body, a system message in a .yml assistant, and system messages in squad overrides. Nothing inside a block is interpreted, so {{variables}} and other Liquid reach Vapi as written.
  2. Config blocks. A $include: <name> key in any mapping pulls in templates/config/<name>.yml. The file's own keys win: mappings merge key by key, and anything else the file sets, lists included, replaces the block's value whole. Two blocks in one list that set the same field differently are refused, as is $include beside a merge key.
  3. An org's own blocks win. A name is looked up in resources/<org>/templates/ first, then templates/. An org block that includes its own name gets the shared one, so it can add to it instead of copying it. A missing block or a loop is an error, never empty text.
  4. Expanded in the loader. validate, push, PR checks, drift hashes and the audit all load through the same parser, so they all see the finished resource.
  5. Pull never writes a file that uses blocks. Pull rewrites a file when the dashboard matches it, when only the dashboard changed, under --force and under --resolve=theirs. Each of those would replace a marker with a copy of the block. It now leaves such a file as written and saves the dashboard version beside it as a .bkp. copy when the two differ, without moving the drift baseline, so the edit is still flagged at the next pull and push.
  6. npm run sync-blocks. A block edit changes many resources and none of their files. Push now records the block content each resource went up with in state/<org>/blocks.json (committed, like the state file). While an org's state is in the older layout the record is resources/<org>/.vapi-blocks.json, which the commit step such a repository already has stages, and npm run migrate moves it with the rest. The command lists, across every org, the resources whose blocks changed since their last push. --apply runs apply per org for those files, so a resource edited in the dashboard is still refused by the drift check, and the command exits 1 naming what was left behind.
  7. Promotion and PR checks see a block edit. The promotion plan lists destination resources that need a push as sync, the promotion workflow runs on templates/**, and a shared block edit selects every PR check.
  8. validate warns about merge keys and Liquid include / render / layout tags, since both are dropped silently.

Guide: docs/guides/blocks.md. Example: examples/blocks/.

Verification

Nothing here was run against a live org. Every behaviour is covered by tests against fixtures or a local stub API.

Rule Test
Org block wins, then shared; an org block can extend the shared one tests/blocks.test.ts
The blocks record is written where the org's state is committed, in both layouts, and migrate moves it tests/blocks.test.ts
In a fresh clone on the older layout, pull keeps a merged change while a blocks record a push rewrote is still uncommitted tests/state-records-third-round.test.ts
Nesting, the loop error, the unknown-block error tests/blocks.test.ts
Liquid inside a block is untouched tests/blocks.test.ts
Config merge rule, and the refused cases tests/blocks.test.ts
Pull keeps the marker: in sync, dashboard ahead, --force, --resolve=theirs tests/blocks-pull.test.ts (all five fail with the guard removed)
Dry run lists affected resources across orgs; an org with its own block is not listed for a shared edit tests/blocks-sync.test.ts
--apply goes through apply → pull → push: the untouched resource is PATCHed, the dashboard-edited one is refused and stays listed tests/blocks-sync.test.ts
Promotion plans a block-only change as sync and deploys it tests/blocks-promotion.test.ts
A block-only change selects PR checks tests/blocks-promotion.test.ts
The example passes validate and the guide's snippets match its files tests/examples.test.ts
sync-blocks takes the repository's directory from the one module every command uses tests/base-dir.test.ts

Leaving blocks off the list of records migrate moves fails the record test. Making sync-blocks work out its own directory again fails tests/base-dir.test.ts.

npm run build passes and npm test passes 714/714 in CI (676 on the branch below), and npm run test:repository passes 9/9.

Things to know

  • A repository that stays on the older layout gets the record under resources/<org>/, so a commit step written before state/ existed commits it. Run end to end on a pipeline whose commit step stages the old state file through a helper script, with one assistant using a block: a promotion run with nothing to promote plans "no changes" and sends 12 requests and 0 writes, the same as a control whose step also stages state/. A block edit still reaches every org, and npm run sync-blocks in a clean clone lists nothing afterwards.
  • A resource that uses no blocks is loaded exactly as before: the expander returns the same object when it finds no marker.
  • The drift check only refuses when the checkout has a baseline for the resource. A fresh clone has none, with or without blocks.
  • While testing the sync path I found that an org with no credentials is re-bootstrapped on every push, which resets its baselines and so disables the drift check there. That predates this change. It's logged as entry 42 in improvements.md and not fixed here.
  • Promotion pushes with --resolve=ours, as it does for every file it promotes, so a sync entry overwrites a dashboard edit in the destination.
  • The test that runs sync-blocks --apply gives that one call 240 s where other tests give a command 60: it starts four commands in a row, and on a slow machine running the rest of the suite beside it the call took 72 s.

Stack

Third of three. Sits on #96, which sits on #97 (state/<org>/, moved into only by npm run migrate). The blocks record follows whichever layout the org is in.

Rebase fixes (last commit)

After rebasing onto #104, #106 and #107:

  • adopt-alias-files.ts hashes alias files with blocks expanded (parseResourceDataFromFile(path, RESOURCES_DIR)), so adoption cleanup works for files that use blocks.
  • blocksFilePull passes resourceType to canonicalizeForHash, so an assistant's metadata.gitops.folderPath doesn't show up as dashboard drift on every pull.
  • hashLocalResource expands blocks and strips assistant folderPath.
  • pushBlockingFindings keeps --strict blocking variable-undefined in the push preflight.
  • Leftover recanonicalize references removed.

Tests are in tests/blocks-integration.test.ts and tests/push-preflight.test.ts.

dhruva-vapi and others added 10 commits November 21, 2026 03:45
A system prompt can include a Markdown block with a line that says only
"@include <name>", and any mapping can include a YAML block with a
"$include" key, where the file's own keys win. Blocks are looked up in
resources/<org>/templates/ first, then in templates/ at the repository
root, so an org can replace or extend a shared block. The loader expands
them, so validate, push, PR checks and drift hashes all see the finished
resource. Liquid inside a block is passed through untouched.

Pull never writes a file that uses blocks. It used to rewrite a file
whenever the dashboard matched it, was ahead of it, or under --force and
--resolve=theirs, and each of those would replace a marker with a copy of
the block. It now leaves the file as written and saves the dashboard
version beside it when the two differ.

validate warns about YAML merge keys and Liquid include/render/layout tags,
which the engine and Vapi drop silently.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
A block edit changes what many resources send to Vapi without changing
their files, so nothing in git said which resources still ran old text.

Push now records the block content each resource went up with in
resources/<org>/.vapi-blocks.json. "npm run sync-blocks" lists, across
every org, the resources whose blocks changed since they were last pushed,
and with --apply deploys them through apply, so the drift check still
refuses a resource that was edited in the dashboard.

Promotion plans those resources as "sync" entries for the destination org,
the promotion workflow runs on templates/**, and a shared block edit
selects every PR check.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Adds docs/guides/blocks.md and examples/blocks/, two clinics that share a
red-flags prompt block and a voice config block, one with its own version
of the block. The examples test now copies an example's templates/ folder,
so the example is validated and the guide's snippets are checked against
its files.

Also corrects two statements the feature depends on: YAML merge keys are
not processed by the engine, and an undefined Liquid variable is left in
the prompt as written, not replaced with an empty string.

Logs the pull behaviour this replaces as improvements entry 39, and a
drift-check gap found while testing, in orgs with no credentials, as
entry 40.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Push writes the record, so it belongs with the rest of the engine's files.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…s it

An org whose state is still in the layout from before state/ gets its
record at resources/<org>/.vapi-blocks.json. A commit step written for that
layout stages resources/, so the record is committed, and a promotion run
with nothing to promote no longer plans a sync for every resource that uses
a block. An org whose state is in state/<org>/ keeps state/<org>/blocks.json.
npm run migrate moves the record with the state file and the pin.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
In the older layout a push that uses blocks rewrites
resources/<org>/.vapi-blocks.json, and until that is committed git shows it
as modified. The record is on the list migrate moves, so pull leaves it out
of what it counts as a person's edits. This pins it with a pull in a fresh
clone.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
sync-blocks worked out the repository's directory for itself, the one
module that still did. It would have worked in the repository while every
other module worked in a test's temporary directory.
tests/base-dir.test.ts names the line.

The blocks tests import the engine sandbox first, as every engine test
file does.

The test that runs sync-blocks --apply gives that one call 240 seconds.
It starts four commands in a row and took 72 seconds on a slow machine
beside the rest of the suite. cliRun takes the limit as a parameter and
keeps 60 seconds for every other call.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…umbers (#99)

* feat(validate): warn on undefined squad variables

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(validate): reject Liquid transfer destination numbers

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: explain squad variable and transfer number validation

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: link NHS example across stacked PR branches

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
* feat(validate): warn on undefined squad variables

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs(examples): add shared NHS practice squads

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(examples): inline practice-specific transfer destinations

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(validate): reject Liquid transfer destination numbers

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: explain squad variable and transfer number validation

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: add shared practice quick reference

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: link NHS example across stacked PR branches

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

I'll fix CI failures and address comments from users with write access that start with 'Devin'.

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

Devin Review

🟢 Devin Review found nothing to fix · View findings

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant