القائمة
Upgrade an existing L2/L3 project to the current template version. Use when: upgrading a variant-based project, syncing template improvements, refreshing scripts/agents/skills/docs/commands.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Runs the full project sync pipeline — lifecycle update, audit, L0→L1 publish, commit, push, and PR creation.
Runs the full project sync pipeline — lifecycle update, audit, L0→L1 publish, commit, push, and PR creation.
Turn a topic or your own materials into a single self-contained, interactive HTML report — top tabs, clickable reference drawers, dense tables, comparison heatmaps, inline SVG, in-page search, a light/dark theme toggle, and multilingual support. Use when: user says "/explain-me", "/reportme", "make a report", "create report", "explain this topic". Inspired by beret21/reportme.
Document Production Workflow for co-deck — generates searchable, themed handbooks as static sites (GitHub Pages). Three modes: standalone handbook, lecture companion (reads co-deck slide_deck.md), full course site. Responds to "make handbook", "create handbook", "build course site", "companion handbook" (triggered by Korean phrases too). H-Stage pipeline (H-0 through H-7). Independent from the 11-Stage slide pipeline.
Turn a topic or your own materials into a single self-contained, interactive HTML report — top tabs, clickable reference drawers, dense tables, comparison heatmaps, inline SVG, in-page search, a light/dark theme toggle, and multilingual support. Use when: user says "/explain-me", "/reportme", "make a report", "create report", "explain this topic". Inspired by beret21/reportme.
Pre-edit fact-forcing quality gate. Ensures agents investigate a file's importers, schemas, and scope constraints before making changes. Part of the 3-layer enforcement model (Hook → Prompt → Skill).
| name | upgrade-project |
| description | Upgrade an existing L2/L3 project to the current template version. Use when: upgrading a variant-based project, syncing template improvements, refreshing scripts/agents/skills/docs/commands. |
| version | 1.1.0 |
| status | active |
| scope | workspace |
| owner | pm |
| last_reviewed | "2026-07-31T00:00:00.000Z" |
| metadata | {"type":"scaffolding","triggers":["upgrade project","upgrade template","sync project with template","refresh project","update project infrastructure"]} |
Upgrades an existing project created from a variant template to match the current template version.
co-* variant templatebun must be installedScript: scripts/upgrade-project.ts
Usage: bun scripts/upgrade-project.ts <project-path> [--variant <name>] [--platform claude|antigravity|both] [--dry-run] [--prune-removed] [--rollback]
| Argument | Required | Description |
|---|---|---|
<project-path> | Yes | Path to the target project |
--variant <name> | No | Auto-detected from .claude/template-version.txt |
--platform <val> | No | claude, antigravity, or both (default: both) |
--dry-run | No | Analyze without making changes |
--prune-removed | No | Remove files present in project but absent from template |
--rollback | No | Restore pre-upgrade git stash snapshot |
The upgrade tool classifies files into categories:
| Category | Behavior | Examples |
|---|---|---|
| LOCKED | Unconditional overwrite | Git hooks, .gitleaks.toml, .gitattributes |
| MERGE | Section-based merge via markers | CLAUDE.md, GEMINI.md, .gitignore, agents/pm.md |
| DOCS_MERGE | Section-based merge (managed blocks) | AGENTS.md, docs/<variant>.context.md |
| DOCS_OVERWRITE | Plain overwrite (no blocks) | docs/phase-definitions.md |
| VARIANT_DOCS_SYNC | Version/hash-based sync | docs/engagement-orchestration.md, docs/team-configuration-guide.md |
| COMMANDS_SYNC | Hash-based sync | .claude/commands/*.md, .gemini/commands/*.md |
| SYNC_IF_NEWER | Version-based update | Scripts (.ts), agents (.md), skills (SKILL.md) |
| PRESERVE | Never touched | README.md, src/ |
| OVERWRITE | Governance files | docs/_common/security.md |
The merge engine recognizes these marker patterns for section-based merge:
| Marker | Open | Close | Use Case |
|---|---|---|---|
| WORKSPACE-MANAGED | <!-- WORKSPACE-MANAGED[:desc] --> | <!-- /WORKSPACE-MANAGED --> | Generic managed sections |
| COMMON-CLAUDE | <!-- COMMON-CLAUDE:START --> | <!-- COMMON-CLAUDE:END --> | CLAUDE.md shared sections |
| COMMON-GEMINI | <!-- COMMON-GEMINI:START --> | <!-- COMMON-GEMINI:END --> | GEMINI.md shared sections |
| VARIANT-INJECT | <!-- VARIANT-INJECT:label --> | <!-- END VARIANT-INJECT --> | Variant template injection points |
| COMMON-AGENTS | <!-- COMMON-AGENTS:START --> | <!-- COMMON-AGENTS:END --> | AGENTS.md shared sections |
| DYNAMIC_SKILLS | <!-- DYNAMIC_SKILLS_START --> | <!-- DYNAMIC_SKILLS_END --> | Skill registry tables |
pre-upgrade-snapshot-YYYYMMDD for rollback--dry-run mode: Full analysis with zero writescat <project>/.claude/template-version.txtbun scripts/upgrade-project.ts <project> --dry-runcd <project> && git add -A && git commit -m "chore: pre-upgrade"bun scripts/upgrade-project.ts <project>cd <project> && git status && git diff --cachedgit commit -m "chore: upgrade template to vX.Y.Z"git stash list
git stash pop stash@{0}
After upgrading, run the following to confirm script registry consistency:
cd <project-directory>
bun scripts/verify-scripts.ts --verify
Must exit 0 with 0 errors. If ghost entries appear, the project's scripts/SCRIPTS.md may need manual cleanup (see Constitution §6.5 Tier 3 SCRIPTS.md Filtering).