Skip to content

Engagement layout template

This is the layout each engagement repository fills. It is a template only: no engagement is ever added to this repository, real or fictional (C-5).

Where an engagement lives

Every engagement, real or fictional, lives in its own repository, cut from a tagged release of rosetta-deploy, with this repository as its upstream remote (DT-RX-038 Q-C-bis-3):

  • Real customers: a private repository on GitSoma, inside the Salesforce boundary. Never in the vernonkeenan GitHub org.
  • Simulations and fictional customers: a private repository in the vernonkeenan org, set up the same way.

To start one:

  1. Create an empty private repository. Clone this repository at a release tag, rename its remote to upstream, add the new repository as origin, and push.
  2. Copy customer/_template/ to customer/<customer>/ in the new repository and fill it there. A simulation says in customer/<customer>/README.md that it is fictional.
  3. Change nothing outside customer/<customer>/. Then merging the next tag from upstream conflicts with nothing, and the library's generated folders stay as Rosetta wrote them (C-1).

CI in an engagement repository

The repository inherits the library's CI (.github/workflows/ci.yml). Where its host runs GitHub Actions, set two things before the first pull request, under Settings > Secrets and variables > Actions:

  • The repository variable CUSTOMER_SCAN_ENGAGEMENT: the folder name, such as northwind-traders for customer/northwind-traders/. Without it, the customer-scan job takes the repository for the library and refuses the folder.
  • The repository secret CUSTOMER_DENYLIST: the customer's own names and its people's names, one per line. They may appear inside customer/<customer>/ and nowhere else, contributions/ included. Without the secret, customer-scan fails. A simulation that the library itself names, such as Northwind Traders, leaves that name off, or merging the next tag from upstream fails.

Email addresses, phone numbers and other personal data still fail inside the folder. Use example.com addresses and 555 numbers, or leave them out.

The layout

Folder Holds, in the engagement repository
project-docs/ The engagement's working documents: dossier, notes, requirements
archaeology/ The engagement twin (twin.json) and the archaeology run's notes, written by the archaeology deploy edition; the CP/ and ADR/ drafts are generated from the twin
deliverables/ What is delivered to <customer>: the Solution Thesis, and any SOW or Spec Manifest Rosetta compiles for it
ADR/ The engagement's own ADRs, as drafts that cite library ids
CP/ The engagement's own context patterns, as drafts that cite library ids
background/ What the team knows about <customer>: business, goals, landscape, constraints
terminology/ <customer>'s own terms and acronyms, mapped to the library's

Each folder holds a README.md placeholder that says what goes in it. Engagement files cite the library by id and release, such as cp-g-014 at v0.1.0, and never copy library files.

In this repository

Only customer/_template/ lives under customer/. A pull request that adds any other folder under customer/, or any customer name or data anywhere, is refused (C-5).

This page as Markdown — for pasting into Claude or another assistant · llms.txt