Sync Template

Synchronize a downstream project (generated from blogic-template-ts ) with the latest template version.

Source of truth: blogic-cz/blogic-template-ts cloned via opensrc into opensrc/repos/github.com/blogic-cz/blogic-template-ts/ .

Prerequisites

• gh CLI authenticated

• agent-tools installed (for gh-tool release list/view )

• debugging-with-opensrc skill loaded (for opensrc commands)

Phase 0: Discovery — What Changed in the Template

Step 0: Clone the template repo via opensrc

The template repo MUST be available locally for diffing. Use opensrc to clone it:

Clone blogic-template-ts into opensrc/repos/

bun run opensrc:use blogic-cz/blogic-template-ts

Verify it's there

ls opensrc/repos/github.com/blogic-cz/blogic-template-ts/

All subsequent references use the path: opensrc/repos/github.com/blogic-cz/blogic-template-ts/

Abbreviated as $TPL in this document for readability. The actual commands MUST use the full relative path.

Step 1: Find the project's current template version

Look for a template version marker in the project:

Check package.json for templateVersion field

grep -i 'templateVersion|template-version|synced-from' package.json

Check for a .template-version file

cat .template-version 2>/dev/null

Check git log for last sync commit

git log --oneline --grep='sync-template|template sync|update from template' -5

Check CHANGELOG.md for template sync entries

grep -i 'template|sync' CHANGELOG.md | head -10

If no marker found, ask the user: "What template version was this project generated from? (e.g., v0.3.0)"

Step 2: Enumerate template changes since last sync

Use the opensrc clone and GitHub API to find everything that changed:

List all template releases after the project's version

agent-tools-gh release list --repo blogic-cz/blogic-template-ts

View specific release notes for each version

agent-tools-gh release view <tag> --repo blogic-cz/blogic-template-ts

Get commit log between versions (using the opensrc clone)

git -C opensrc/repos/github.com/blogic-cz/blogic-template-ts log --oneline <old-tag>..<new-tag>

Get full diff between versions

git -C opensrc/repos/github.com/blogic-cz/blogic-template-ts diff <old-tag>..<new-tag> --stat

List PRs merged between versions

gh pr list --repo blogic-cz/blogic-template-ts --state merged --search "merged:>YYYY-MM-DD" --limit 50

Step 3: Categorize changes

Classify each change into one of:

Category Description Action

Infrastructure CI/CD, Docker, Helm, configs, tooling Adopt directly (with name substitution)

Dependencies Package version bumps, new deps Delegate to update-packages skill

Patterns Code patterns, conventions, lint rules Adopt with adaptation

Features New app features, routes, services Evaluate — may not apply

Fixes Bug fixes in shared code Adopt if the bug exists in project

Output a summary table:

Phase 1: Package Updates First (MANDATORY)

Before applying any template changes, bring packages up to date. Outdated packages cause merge conflicts and false failures.

Step 1: Compare package versions

Compare the project's dependencies against the template's current versions:

Read template's package.json(s) from opensrc clone

cat opensrc/repos/github.com/blogic-cz/blogic-template-ts/package.json cat opensrc/repos/github.com/blogic-cz/blogic-template-ts/apps/web-app/package.json cat opensrc/repos/github.com/blogic-cz/blogic-template-ts/packages/*/package.json

Read project's package.json(s)

cat package.json cat apps/web-app/package.json cat packages/*/package.json

Build a comparison table:

Step 2: Delegate to update-packages skill

If packages are behind:

• Load the update-packages skill

• Create a branch: chore/sync-template-packages-$(date +%y%m%d-%H%M)

• Follow the update-packages workflow to bring ALL packages to template version or newer

• Commit package updates separately BEFORE template sync changes

• Verify: bun run check && bun run test

Rules:

• Package updates MUST be committed before any template changes

• Use the update-packages skill's group coordination (tanstack, trpc, effect, drizzle groups)

• DO NOT add packages the project doesn't use — only update existing ones

Phase 2: Deep Scan & Diff

Compare the project against the template file by file to find all divergences.

Step 1: Identify template infrastructure files

Load references/template-files.md for the categorized file list.

For each infrastructure file in the template:

• Check if the file exists in the project

• If it exists, diff it against the template version

• If it doesn't exist, flag it as "missing from project"

Diff a specific file between template (opensrc) and project

diff opensrc/repos/github.com/blogic-cz/blogic-template-ts/<file> <file>

Or use git diff for better output

git diff --no-index opensrc/repos/github.com/blogic-cz/blogic-template-ts/<file> <file>

Step 2: Build the name substitution matrix

Every file copied from the template MUST apply name substitution. Build the matrix from the project:

Detect project name from package.json

grep '"name"' package.json | head -1

Detect org scope

grep '"@' package.json | head -5

Build substitution table:

Template Value Project Value

@blogic-template/

@<project-scope>/

blogic-template-ts

<project-name>

blogic-template

<project-short-name>

Step 3: Identify project-specific divergences to preserve

Some files WILL differ intentionally — the project has its own business logic. Flag these:

• apps/web-app/src/routes/ — project-specific routes

• packages/services/src/ — project-specific services

• packages/db/src/schema/ — project-specific schema (beyond template defaults)

• Environment-specific configs (Helm values, CI secrets)

Rules:

• NEVER overwrite project-specific business logic with template defaults

• Template infrastructure files (lint, tooling, CI) should be adopted fully

• When a file has BOTH infrastructure changes AND project-specific content, merge selectively

Phase 3: Triage & Plan

Generate a phased implementation plan in .sisyphus/plans/ format.

Step 1: Create the plan file

mkdir -p .sisyphus/plans

Name: .sisyphus/plans/YYMMDDHHMM-sync-template-vX.Y.Z.md

Step 2: Plan structure

Follow the andocs-backport plan format. Include:

• TL;DR — Quick summary, deliverables, effort estimate, parallel execution note

• Context — Template version gap (from → to), number of changes, categories

• Name Substitution Matrix — All template→project name mappings

• Work Objectives — Core objective, concrete deliverables, definition of done, must have, must NOT have

• Execution Strategy — Parallel waves with dependency matrix

• TODOs — Each task with:

• What to do (detailed steps)

• Must NOT do (guardrails)

• Recommended agent profile (category + skills)

• Parallelization (can run in parallel, blocks, blocked by)

• References (template files from opensrc clone, project files to update)

• Acceptance criteria (verifiable conditions)

• QA scenarios (bash commands with assertions)

• Commit grouping

Step 3: Wave organization

Standard wave pattern for template sync:

Wave 0 (Sequential — foundation): └── Package updates (if not done in Phase 1)

Wave 1 (Parallel — infrastructure): ├── Skills & tooling updates ├── Lint & formatter config ├── CI/CD pipeline updates ├── Docker & Helm updates └── Config file updates (tsconfig, vitest, etc.)

Wave 2 (After Wave 1 — code changes): ├── Fix lint violations from new rules ├── Apply code pattern updates └── Update docs (AGENTS.md, README)

Wave 3 (After Wave 2 — cleanup): └── Final cleanup + verification

Wave FINAL (After ALL — verification): ├── Plan compliance audit ├── Code quality review └── Scope fidelity check

Step 4: Present plan to user

Output the plan summary and ask for approval before execution:

Sync Template v<old> → v<new>

Changes: N commits, M PRs, K releases Waves: 4 (+ verification) Tasks: N total Estimated effort: [Small/Medium/Large]

Approve to start execution?

Phase 4: Execution

Execute the plan wave by wave, using task delegation.

Per-task execution flow

For each task in the plan:

• Mark TODO in_progress

• Delegate to appropriate agent with category + skills from the plan

• Verify acceptance criteria

• Run QA scenario

• Mark TODO completed

• Commit as specified in plan

Delegation prompt template

TASK: [from plan] EXPECTED OUTCOME: [from acceptance criteria] REQUIRED TOOLS: [from plan] MUST DO:

• Apply name substitution matrix: [matrix from plan]
• Reference template files from: opensrc/repos/github.com/blogic-cz/blogic-template-ts/
• [task-specific requirements] MUST NOT DO:
• Overwrite project-specific business logic
• Leave template names (blogic-template) in project files
• [task-specific guardrails] CONTEXT:
• Template source: opensrc/repos/github.com/blogic-cz/blogic-template-ts/<file>
• Project target: <file>
• [additional context]

After each wave

bun run check bun run test

Fix any failures before proceeding to the next wave.

Phase 5: Verification & Stamp

Step 1: Run final checks

bun run check && bun run test

Step 2: Verify no template names leaked

Search for template-specific strings that should have been substituted

grep -r '@blogic-template/' . --include='.ts' --include='.json' --include='.yml' --include='.yaml' | grep -v node_modules | grep -v .git | grep -v .sisyphus | grep -v opensrc grep -r 'blogic-template-ts' . --include='.ts' --include='.json' --include='.yml' --include='.yaml' | grep -v node_modules | grep -v .git | grep -v .sisyphus | grep -v CHANGELOG | grep -v skills-lock | grep -v opensrc

Step 3: Update the template version marker

Update .template-version (create if missing)

echo "<new-template-version>" > .template-version

Or update package.json templateVersion field

Step 4: Final commit

git add .template-version git commit -m "chore: sync with blogic-template-ts <new-version>"

Guardrails

• NEVER overwrite project-specific business logic (routes, services, schema beyond defaults)

• NEVER leave @blogic-template/ or blogic-template-ts strings in project files (except opensrc clone)

• ALWAYS clone the template via bun run opensrc:use blogic-cz/blogic-template-ts first

• ALWAYS apply the name substitution matrix to every file copied from the template

• ALWAYS update packages FIRST before applying infrastructure changes

• ALWAYS run bun run check && bun run test after each wave

• ALWAYS preserve project-specific configurations (Sentry project, Helm namespaces, CI secrets)

• DO NOT add template-only dependencies the project doesn't need

• DO NOT apply template features the project hasn't opted into

• DO NOT use hardcoded absolute paths — always use relative opensrc/repos/github.com/blogic-cz/blogic-template-ts/

Definition of Done

• bun run check passes (0 errors)

• bun run test passes

• No @blogic-template/ or blogic-template-ts strings in project files (except .template-version, CHANGELOG, opensrc/)

• .template-version file updated to new version

• All plan tasks marked completed

• Plan file exists in .sisyphus/plans/