Syncs Starbase-managed project files by adding the canonical/starbase remote and merging starbase/main into the current branch. Use when updating common.mk and related shared Starcraft build/CI conventions.
92%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Run the preparation script from the root of the child repository:
bash <path-to-skill>/scripts/prepare_merge.sh [BRANCH_SUFFIX]BRANCH_SUFFIX is optional; defaults to today's date
(work/update-starbase-YYYY-MM-DD).STATUS=... block (BRANCH, BASE, CHANGED_FILES,
and — when relevant — CONFLICTED_FILES and PLACEHOLDER_WARNINGS) for
one of four STATUS values, then continue with the matching step below:
STATUS=clean (exit 0): merge succeeded with no conflicts. Continue to
Phase 2.STATUS=conflicted (exit non-zero): merge stopped with conflicts.
Resolve each file in CONFLICTED_FILES per
references/file_ownership.md, then
git add the resolved files and git merge --continue before
continuing to Phase 2.STATUS=already-up-to-date (exit 0): starbase/main has no commits
that aren't already in the branch. No work branch was created — there
is nothing to sync or open a PR for. Stop here and report this to the
user.STATUS=failed (exit non-zero): git merge failed for a reason other
than an ordinary conflict (e.g. untracked files that would be
overwritten, a failing merge hook). The merge was aborted; fix the
underlying issue from the git output above the status block, then
re-run the script.If the script cannot be run, follow references/manual_merge_steps.md instead.
Report one of: merge-clean, merge-conflicted (with the conflicted file
list), already-up-to-date, or merge-failed.
When resolving merge conflicts, consult
references/file_ownership.md for the
complete ownership map and decision rules, including:
X | Y, tuple[X, Y], etc., and Python version caveats).If a reviewer's PR feedback asks for something that contradicts one of these
rules (or any other rule in this skill), see
references/reviewer_feedback_conflicts.md
for how to resolve it — don't silently follow one side without recording why.
When finalizing the Starbase merge commit, include the merge date as an
ISO 8601 date only (YYYY-MM-DD) in the commit message.
Do not include time or timezone.
Example:
chore(merge): update starbase (2026-06-18)The commit body must include a concise overview of the Starbase changes that were pulled in (for example: build-system updates, workflow changes, docs tooling changes, or dependency-management adjustments).
Use this template:
chore(merge): update starbase (<ISO-8601-DATE: YYYY-MM-DD>)
Merge `starbase/main` into this branch and sync Starbase-managed updates.
Overview of Starbase changes pulled in:
- <high-level change area 1>
- <high-level change area 2>
- <high-level change area 3>
- <high-level change area 4>
Conflict resolution applied:
- Kept child-repo version of `<child-owned-file-1>` (`--ours`).
- Kept child-repo version of `<child-owned-file-2>` (`--ours`).
- Took full `<source-of-truth-file-1>` from `starbase/main` (source-of-truth file).
- Took full `<source-of-truth-file-2>` from `starbase/main` (source-of-truth file).
- For this `<library|application>` repo:
- kept `<agents-template-file-to-delete-1>` deleted,
- kept `<agents-template-file-to-delete-2>` deleted,
- kept `AGENTS.md` authoritative and applied relevant updates from `<agents-template-reference-file>`.Run the deletion checklist (required, every merge):
Before validation, work through
references/file_ownership.md's
"Conflict rule 1b" — it doesn't show up as a conflict, so this is the
only point it gets caught.
Verify mixed-ownership files and clean up placeholders:
Structural diff: For any modified mixed-ownership file, diff against Starbase (git diff starbase/main -- <file>) and verify only child-owned values differ per references/file_ownership.md.
Placeholder grep: Scan for residual starcraft|starbase placeholder text:
git diff --name-only --diff-filter=d HEAD^1 HEAD | xargs -r grep -i -E "starcraft|starbase"Update any matches found (except external docs/style guide URLs) to use the child repository's name/purpose. Do not touch legitimate Starbase-ownership comments. Explicitly disposition every hit (fix or note as legitimate attribution in the merge commit message).
Run pre-PR validation (required):
Before creating a PR, ensure repository checks pass:
make format
make lint
make docs
make test-fastmake lint builds the docs as part of linting, but run make docs too so
docs-specific failures are caught and reported clearly on their own, not
just as a side effect of the lint target.
make format can rewrite doc-referenced code snippets (e.g. quote style)
pulled in via include/literalinclude (or equivalent) directives
without failing make docs. After formatting, verify each such directive
still resolves to the in-sync excerpt the docs page expects, adjusting
anchors/line numbers if formatting shifted them.
If Vale or make docs reports spelling failures:
Starbase or Starcraft: Indicates unmigrated template prose in docs/. Rewrite the prose for the child repository; never add these to .custom_wordlist.txt.vale-ignore) at the point of use instead of adding it to the global wordlist.docs/.custom_wordlist.txt to force a clean build. If in an interactive session, ask the operator how to disposition the flagged words (add to wordlist, inline ignore, or rewrite); only fall back to listing unresolved words in the PR description if in a non-interactive session.Do not create the PR until these commands complete successfully.
Check every file changed by the merge for preparation PR candidates (required):
Some fixes discovered while merging or validating are pre-existing or
unrelated issues (e.g. latent bugs, mechanical formatting diffs, new
default-enabled tooling, or large net-new template files). Bundling these
into the merge PR obscures the merge diff. This is a mandatory audit, not
a reactive check — do not wait for a reviewer to flag it. Lean toward
distilling changes that could reasonably land on main independently
(a new formatter's reformatting pass is the canonical example), without
over-splitting small incidental fixes.
When you find one, split it into a separate draft preparation PR against
origin/main before finalizing the merge — using its own git worktree,
and optionally delegated to a background subagent, so it doesn't block
the main merge work. Consult
references/preparation_prs.md for
trigger criteria, the worktree/subagent workflow, stacked PR workflows,
lifecycle requirements (draft-only, operator promotion), and provenance
link rules.
When opening the PR, apply the label:
PR: MergeDocument change provenance on each file:
For every file added, deleted, or modified by the merge, post GitHub PR
review comments explaining the provenance of the changes. Consult
references/pr_provenance.md for the
comment format, prefix template, provenance-description conventions, the
GitHub API details (rate limiting, subject_type: file), and the rules
for suggestion-only own-invention workarounds and precedent citations.
Open the PR as a draft, request a Copilot review while it is still draft
(gh pr create --draft --reviewer "copilot-pull-request-reviewer[bot]" ...,
or gh pr edit <PR_NUMBER> --add-reviewer "copilot-pull-request-reviewer[bot]" on an already-open PR), and keep
iterating until the review is clean enough for the operator to mark it
ready.
references/reviewer_feedback_conflicts.md
before acting on it.origin/main or starbase/main has gained new commits (including
"GitHub reports conflicts with main"), do not layer another merge commit
on top of the existing one. Follow
references/refresh_stale_pr.md to
rebuild the merge commit and preserve all existing follow-up commits.git rebase -i
can drop the merge commit's second parent or flatten the history, since
the branch's first commit is itself a merge commit):# Find the merge commit created by the sync (its only merge commit).
MERGE_HASH=$(git log --merges -n 1 --format=%H)
# Soft-reset to it: this keeps every follow-up-fix diff staged, without
# touching the merge commit's parents.
git reset --soft "$MERGE_HASH"
# Fold the staged diffs into the merge commit, keeping its message/parents.
git commit --amend --no-edit
# Push the rewritten branch.
git push --force-with-lease origin <branch>references/pr_provenance.md — they
apply for the entire life of the PR, not just the initial merge, and
every follow-up-fix review comment must be posted in the same turn you
push the corresponding fix.canonical/copilot-collections
b33daf8
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.