Sync Template

Synchronize a downstream project generated from blogic-template-ts with the latest upstream template state.

Use blogic-cz/blogic-template-ts as source of truth.

Prefer this local path when available:

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

Reference that path as $TPL in commands.

Prerequisites

Use gh CLI authenticated when available.
Load debugging-with-opensrc skill when available; otherwise run equivalent opensrc / git commands directly.
Use agent-tools (gh-tool release list/view) when available; otherwise use native gh release list/view.
Clone template with opensrc when available; otherwise clone https://github.com/blogic-cz/blogic-template-ts into a temporary local directory and use that path as $TPL.

Phase 0: Discovery — What Changed in the Template

Step 0: Materialize template source locally

Materialize the template repo before diffing:

bun run opensrc:use blogic-cz/blogic-template-ts
ls opensrc/repos/github.com/blogic-cz/blogic-template-ts/

If opensrc is unavailable, clone with git clone and set $TPL to that clone path.

Step 1: Detect current template version in project

Detect the current template version marker:

package.json (templateVersion, template-version, synced-from)
.template-version
Git history for sync commits
CHANGELOG.md sync entries

If no baseline exists, request the baseline version from the user before continuing.

Step 2: Enumerate upstream changes since baseline

Enumerate changes with releases, commits, and PR metadata:

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

When gh-tool is unavailable, replace gh-tool commands with gh release ... commands.

Step 3: Categorize changes for adoption strategy

Classify each change into one category:

| 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:

| # | Category | Change | Template Files | Effort | Priority |
|---|----------|--------|---------------|--------|----------|

Phase 1: Package Updates First (MANDATORY)

Align package versions before applying template file sync.

Step 1: Compare project and template package versions

Read package manifests in both trees and build a version-gap table.

Build a comparison table:

| Package | Project Version | Template Version | Gap |
|---------|----------------|-----------------|-----|

Step 2: Execute package updates

If packages are behind, prefer update-packages skill. If that skill is unavailable, run equivalent manual updates with the same constraints.

Apply this sequence:

Create branch: chore/sync-template-packages-$(date +%y%m%d-%H%M)
Update only already-used packages to template version or newer.
Commit package updates separately before template file sync commits.
Verify with project checks before continuing.

Apply these rules:

Package updates MUST be committed before any template changes
Preserve package-group coordination (tanstack, trpc, effect, drizzle)
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 infrastructure files to adopt

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

For each infrastructure file:

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"

git diff --no-index $TPL/<file> <file>

Step 2: Build the name substitution matrix

Build substitution matrix per references/substitution-rules.md.

Step 3: Identify project-specific divergences to preserve

Flag intentional business-logic divergences and preserve them:

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)

Apply these 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/.

Step 1: Create the plan file

mkdir -p .sisyphus/plans

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

Step 2: Apply canonical plan format

Load and apply references/plan-template.md.

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

Present summary and wait for explicit 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.

Prefer task delegation when subagents are available.

Fallback when subagents are unavailable: execute tasks sequentially in the main agent, keep the same acceptance criteria, and preserve planned commit grouping.

Per-task execution flow

For each task in the plan:

Mark TODO in_progress
Execute task (delegate when available; otherwise run directly)
Verify acceptance criteria
Run QA scenario
Mark TODO completed
Commit as specified in plan

Delegation prompt template

Use the delegation prompt from references/plan-template.md.

After each wave

bun run check
bun run test

Resolve failures before the next wave.

Phase 5: Verification & Stamp

Run verification recipes from references/verification-recipes.md.

Apply substitution policy from references/substitution-rules.md.

Guardrails

NEVER overwrite project-specific business logic (routes, services, schema beyond defaults)
NEVER leave @blogic-template/ or blogic-template-ts strings in synced project files, except approved exceptions in references/substitution-rules.md
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 synced project files, except approved exceptions in references/substitution-rules.md
.template-version file updated to new version
All plan tasks marked completed
Plan file exists in .sisyphus/plans/