Skip to main content

Adoption guide

Adoption should reduce context, not add another layer of duplicate rules.

The intended entrypoint

The user-facing entrypoint is deliberately version-independent:
The agent first identifies the exact target repository, obtains the Engineering System from the supplied URL, pins the baseline SHA, and follows standards/ADOPTION.md to inspect the repository before changing files. The target repository does not need to contain tools/adopt.py beforehand. The agent can use an authenticated GitHub integration or a temporary checkout of datarelay-labs/engineering-system, then run the helper against the target root. The Engineering System itself is not copied wholesale into the product repository.

Deterministic bootstrap

Read-only audit:
Apply after rule/CI review:
The bootstrap installs only missing common surfaces and does not overwrite existing project files.

Fail-closed boundaries

Adoption stops instead of guessing when:
  • the worktree is dirty
  • existing AI/engineering rules have not been reviewed
  • more than one plausible test command exists
  • existing CI is present but shared/native ownership has not been decided
  • an existing adoption would need destructive overwrite
  • the immutable canonical baseline cannot be resolved

Managed adoption identity

Managed repositories record enough information to show which Engineering System baseline and which project-native checks are in use:
ci_mode can be shared or native.
  • shared uses the Engineering System reusable affected-test workflow.
  • native preserves existing project CI, maps the concrete workflow files that own the affected-test invariant, and keeps the generated Engineering System workflow compliance-only.
  • merge_gate_status is verified, advisory, or unknown; never infer branch protection merely because workflows exist.
  • Production-oriented repositories explicitly record runbook and incident-response posture.
Current managed adoption also routes material design-bearing changes through the lightweight standards/DESIGN.md gate and production-impacting failures through standards/OPERATIONS.md. For production-oriented projects it records project-native runbook/health/recovery contracts, reconciles observable GitHub merge enforcement, and uses an executable release contract when real project-native commands exist. This does not require a new design document or incident document for every task; the smallest durable artifact that fits the decision remains preferred.

New or empty repository

A brand-new project still needs an explicit Git repository boundary because branch, HEAD, history, and reviewable change are part of the safety model. Establish or initialize the intended repository first, then use the same link-only adoption flow. If there is genuinely no executable product code yet, --allow-no-tests may be used as a temporary bootstrap state. It is not a permanent testing exemption: once executable implementation begins, establish real project-native tests and update the affected-test contract before normal development/release qualification is considered complete. Do not invent a framework, product architecture, release command, or operations contract merely to make adoption look complete. Start with the canonical templates from: github.com/datarelay-labs/engineering-system Base adoption requires:
Pin the Engineering System version used by the repository. If you explicitly enable optional Cursor compatibility, add the Cursor adapter files separately:
These are related but separate concerns: the base engineering rules can be used without AI session continuity.

Existing repository with many AI rules

Do not blindly add another always-on rule. First classify the existing rules:
Keep product-specific invariants and stricter valid rules. Remove duplicated generic engineering guidance from product repositories and reference the Engineering System instead, so any implementation agent reads less repeated context.

Adoption-pending repositories

A valid Work Packet may exist before the repository has completed Engineering System adoption. When AGENTS.md or .engineering/* are missing during resume:
  • record ENGINEERING_SYSTEM_ADOPTION=ABSENT_OR_PENDING
  • continue under the canonical Engineering System default when the Work Packet is otherwise valid
  • do not silently create, merge, or modify adoption files unless the active workstream explicitly authorizes adoption work
This lets release or feature work continue without accidentally mixing governance adoption into the product change.

Install the Cursor resume command

On the machine running Cursor:
This installs the optional Cursor compatibility command. It is disabled by default. ChatGPT may invoke /work-resume only after explicit owner reactivation for the current packet and IMPLEMENTER=CURSOR.

Add ChatGPT routing, not the whole standard

ChatGPT Custom Instructions should stay short. They only need to say:
  • use the canonical Engineering System
  • resolve the repository first
  • use Work Packets for implementation authority and chat continuity
  • read only minimal relevant context
  • never claim unexecuted or different-HEAD evidence as PASS
Do not copy every Engineering System standard into Custom Instructions.

Optional: connect Desktop Commander

For direct development-host audit, connect Desktop Commander Remote MCP and restrict it to the intended development paths. This is optional. GitHub remains the durable baseline even when remote audit is available.

Adoption qualification

File presence alone is not PASS. Managed adoption validates required surfaces, version/baseline identity, session-continuity files, baseline-pinned caller workflows, test metadata, CI ownership, and release wiring when configured. Then run the repository’s cheapest real project-native smoke/affected test. Report the adoption as complete only after the required validation and smoke checks succeed:

Session continuity smoke test

A simple default continuity smoke test is:
If the same workstream resumes without copying a large prompt, the continuity path is working.
Last modified on September 29, 2026