菜单
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).