Engine-root file swap for PRs

Engine-root file swap for PRs

Date: 2026-03-22 Status: accepted

Problem

The scaffolder repo root has files that serve dual purposes: CLAUDE.md, STANDARDS.md, PROJECT-INSTRUCTIONS.md, RELEASE-CHECKLIST.md. The operator customizes these locally (personal AI names, operator notes, project-specific rules). But the repo on GitHub needs the generic/product versions — not the operator’s personal config.

Decision

templates/engine-root/ holds the generic product versions of these files. It is gitignored — it’s a local staging area, not part of the shipped product.

Before any PR, Harley runs a swap:

1. Back up operator’s custom root files to .engine-root-backup/
2. Copy templates/engine-root/* to repo root (overwrite)
3. Commit the generic versions
4. Push / create PR
5. Restore operator’s custom files from .engine-root-backup/
6. Delete .engine-root-backup/

The repo on GitHub always has clean generic files. The operator always has their custom versions locally. The swap is transparent and automatic.

What’s in templates/engine-root/

• CLAUDE.md — generic standing instructions (Claude Chat / Claude Code)
• STANDARDS.md — development standards with generic names
• PROJECT-INSTRUCTIONS.md — template for Claude.ai with example custom section
• RELEASE-CHECKLIST.md — release checklist with generic names

What’s gitignored

• templates/engine-root/ — the generic templates (local staging)
• .engine-root-backup/ — temporary backup during swap

What’s tracked in git

• Root-level CLAUDE.md, STANDARDS.md, PROJECT-INSTRUCTIONS.md, RELEASE-CHECKLIST.md (these are the generic versions after swap — the product files)

Custom instruction

The scaffolder project’s CLAUDE.md includes a permanent instruction for Harley: “Before any PR, run the engine-root swap.” This is project-specific — it only applies to the scaffolder development repo, not to projects created with sc create.