Tier 5: Reference (compare and report, selective apply)
File Pattern
Notes
release-please-config.json
Varies by project type
.release-please-manifest.json
Version tracking
skaffold.yaml
Dev environment config
Execution
Extract Mode
Goal: Scan a repo and identify improvements that could benefit other repos.
Step 1: Identify the source repo
If repo name provided, use /Users/lgates/repos/ForumViriumHelsinki/<repo-name>.
Otherwise use the current working directory (must be inside an FVH repo).
Step 2: Scan tooling files
Scan for all tracked config categories:
fd -t f -d 3 '(claude|renovate|auto-merge|release-please|container-build|Dockerfile|justfile|skaffold)' <repo-path>
Also check:
.github/workflows/*.yml
justfile
Dockerfile*
renovate.json
release-please-config.json
.release-please-manifest.json
skaffold.yaml
Step 3: Compare against workspace patterns
For each file found:
Wholesale tier: Hash the file content and compare against the most common version across all repos. Report if this repo has a newer/different version.
Parameterized tier: Extract the shared core (strip known variation points) and compare structure.
Structural tier (justfile): Check for standard recipes (default, help, dev, build, clean, lint, format, format-check, test, pre-commit, ci). Report missing standard recipes and non-standard names (e.g., check instead of lint).
Pattern-based tier: Detect tech stack, then check for best practices:
Pinned base images (not latest)
.dockerignore present
Multi-stage builds
Non-root user
SHA-pinned GitHub Actions
SBOM/provenance attestation
Reference tier: Note divergences from the most common configuration.
Step 4: Generate extract report
Config Extract Report: <repo-name>
====================================
Wholesale Configs:
claude.yml ✅ Matches canonical (sha: abc123)
renovate.json ⚠️ Differs from canonical — newer features detected
Parameterized Configs:
auto-merge-image-updater.yml ✅ Core matches, variation: branch-prefix=argocd
release-please.yml ⚠️ Has publish job (novel improvement)
Structural (Justfile):
Standard recipes: 8/11 present
Missing: format-check, pre-commit, ci
Non-standard names: none
Pattern-based (Dockerfile):
Stack: Python
✅ Pinned base image (python:3.12-slim)
✅ Multi-stage build
⚠️ Missing .dockerignore
✅ Non-root user
Potential Improvements to Propagate:
1. renovate.json — has newer schedule config
2. release-please.yml — publish job pattern
Diff Mode
Goal: Compare a specific file across all FVH repos.
Step 1: Resolve file pattern
Interpret the file pattern argument:
Full path: .github/workflows/claude.yml
Short name: claude.yml → search in .github/workflows/
Glob: *.yml → match all workflows
Step 2: Find the file across repos
fd -t f '<pattern>' /Users/lgates/repos/ForumViriumHelsinki --max-depth 4
Step 3: Group by content hash
For each found file, compute a content hash:
shasum -a 256 <file>
Group files by identical hash. Sort groups by size (largest first = most common version).
Step 4: Identify the "best" version
Heuristics for selecting the canonical version:
Most common hash (majority rules)
If tie: most recently modified
If tie: from infrastructure repo (reference repo)
Step 5: Generate diff report
Config Diff: .github/workflows/claude.yml
==========================================
Group 1 (canonical) — 18 repos [sha: abc123]:
citylogger, CycleRoutePlanner, FVHIoT-python, ...
Group 2 — 2 repos [sha: def456]:
theme-management, OLMap
Differences from canonical:
- Line 12: uses different action version
- Line 25: extra step for Node setup
Not present in (5 repos):
infrastructure, helm-webapp, terraform-modules, ...
Recommendation: Update Group 2 repos to match canonical.
For small files (< 100 lines), show an inline unified diff between the canonical and each outlier group.
Apply Mode
Goal: Propagate a config file from source to target repos.
Step 1: Determine source
If --from specified, use that repo's version
Otherwise, run diff mode internally to find the canonical version
Step 2: Determine targets
If --to specified, use those repos
If --all, use all repos that currently have the file (excluding source)
Otherwise, ask the user which repos to target
Step 3: Determine sync strategy by tier
Wholesale: Copy file verbatim to targets.
Parameterized: Copy file but preserve known variation points:
auto-merge-image-updater.yml: preserve BRANCH_PREFIX value
release-please.yml: preserve extra publish/deploy jobs
Structural (justfile): Do NOT overwrite. Instead:
Add missing standard recipe stubs (commented templates)
Suggest renaming non-conforming recipes
Preserve all project-specific recipes and recipe bodies
Pattern-based: Only apply general improvements matching the target's stack:
Pin unpinned base images
Add missing .dockerignore
Update SHA-pinned actions
Do NOT change build args, multi-arch config, or app-specific steps
Reference: Show diff and ask user to confirm each change.
Step 4: Preview changes (default / --dry-run)
For each target repo, show the unified diff of what would change.
Dry Run: Apply .github/workflows/claude.yml
============================================
repo: OLMap
Status: Will update (sha def456 → abc123)
Diff:
@@ -12,1 +12,1 @@
- uses: actions/checkout@v3
+ uses: actions/checkout@v4
repo: theme-management
Status: Will update (sha def456 → abc123)
Diff: (same as above)
Total: 2 repos would be updated
Step 5: Execute changes (--confirm or user approval)
For each target repo:
Create a branch: config-sync/<filename-slug>
Copy/update the file
Commit with conventional message: chore: sync <filename> from <source-repo>
Push and create PR via gh pr create
cd /Users/lgates/repos/ForumViriumHelsinki/<target-repo>
git checkout -b config-sync/claude-yml
# ... apply changes ...
git add <file>
git commit -m "chore: sync claude.yml from canonical
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin config-sync/claude-yml
gh pr create --title "chore: sync claude.yml" --body "$(cat <<'EOF'
## Summary
- Synced `.github/workflows/claude.yml` to match canonical version
- Source: most common version across 18 repos
## Changes
<inline diff>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
Inside a quoted heredoc (<<'EOF'), backticks, $, and \ are already literal — never backslash-escape them. A stray \`` lands in the rendered PR body and needs a follow-up gh pr editto fix. To skip the$(cat ...)subshell entirely, feed the body straight togh` over stdin:
gh pr create --title "chore: sync claude.yml" --body-file - <<'EOF'## Summary
- Synced `.github/workflows/claude.yml` to match canonical version
EOF
Report results:
Apply Results:
OLMap: PR #42 created — https://github.com/ForumViriumHelsinki/OLMap/pull/42
theme-management: PR #15 created — https://github.com/ForumViriumHelsinki/theme-management/pull/15
