diff --git a/.claude/skills/branching-strategy/SKILL.md b/.claude/skills/branching-strategy/SKILL.md new file mode 100644 index 00000000..d4434b9a --- /dev/null +++ b/.claude/skills/branching-strategy/SKILL.md @@ -0,0 +1,53 @@ +--- +name: branching-strategy +description: Use when creating a new branch or git worktree for a feature, bugfix, or experiment — before choosing a base branch or running `git checkout -b`, `git switch -c`, or `git worktree add`. +--- + +# Branching Strategy + +## Overview + +New work branches start from an `upstream/XX-dev` integration branch (e.g. `upstream/0.6-dev`) — never silently from `main` or from whatever happens to be checked out. **The user chooses the base; you never pick it yourself.** + +`main` is the release line. `upstream/XX-dev` branches are the versioned dev/integration lines where feature and bugfix work lands. + +## Workflow + +1. **Refresh and discover bases.** Remote-tracking refs go stale here; fetch first: + ```bash + git fetch origin --prune + git branch -a --list '*upstream/*' # upstream/XX-dev lines + git branch -a --list '*feat/*' --list '*fix/*' # active working branches + ``` + If remote state is in doubt, cross-check with `gh api repos///branches --jq '.[].name'`. + +2. **Ask the user which base to start from** (AskUserQuestion). Always ask, even when only one `upstream/XX-dev` exists. Offer as choices: + - Each `upstream/XX-dev` branch — recommend the newest version. + - "An existing working branch" — for work that depends on another in-flight branch. + +3. **Create the branch** (name it `feat/` or `fix/`, matching existing repo conventions): + ```bash + git checkout -b fix/ + # or isolated: + git worktree add ../- -b feat/ + ``` + +4. **Dependent base? Flag the merge-back immediately.** If the base is a working branch rather than `upstream/XX-dev`, tell the user in your response, and repeat it when the work is ready to merge: + > ⚠️ This branch is based on ``, not `upstream/XX-dev`. It must merge back only after (or together with) its parent, and merging into `upstream/XX-dev` may conflict with the parent's changes. Rebase onto the parent if it moves. + +5. Don't push or set an upstream tracking branch until the user asks. + +## Quick Reference + +| Situation | Base | Extra step | +|---|---|---| +| Feature / bugfix | `upstream/XX-dev` chosen by user | — | +| Work depending on an in-flight branch | that working branch, if user confirms | Merge-back conflict warning (step 4) | +| Base unclear / user unavailable | stop and ask | Never guess | + +## Common Mistakes + +- **Branching from current HEAD or `main` without asking** — the checked-out branch is not evidence of the right base. List the `upstream/*-dev` lines and ask. +- **"Only one dev branch exists, so no need to ask"** — still ask; the user may want a dependent working branch as base, or a new dev line may be pending. +- **Silent dependent branch** — creating a branch off another feature branch without stating the merge-back risk leaves the user to discover conflicts at PR time. +- **Trusting stale remote refs** — always `git fetch origin --prune` before listing candidate bases. diff --git a/.cursor/rules/branching-strategy.mdc b/.cursor/rules/branching-strategy.mdc new file mode 100644 index 00000000..75ab59a0 --- /dev/null +++ b/.cursor/rules/branching-strategy.mdc @@ -0,0 +1,17 @@ +--- +description: Branching strategy — apply when creating a new branch or git worktree for a feature, bugfix, or experiment, before choosing a base branch or running git checkout -b, git switch -c, or git worktree add +globs: +alwaysApply: false +--- + +# Branching Strategy + +New work branches start from an `upstream/XX-dev` integration branch (e.g. `upstream/0.6-dev`) — never silently from `main` or from whatever branch is checked out. The user chooses the base; never pick it yourself. + +1. `git fetch origin --prune`, then list `upstream/*-dev` lines and active `feat/*`/`fix/*` branches. +2. Ask the user which base to start from, offering each `upstream/XX-dev` (newest recommended) plus "an existing working branch" for work that depends on another in-flight branch. Ask even when only one dev line exists. +3. Create the branch as `feat/` or `fix/` from the chosen base. +4. If the base is a working branch rather than `upstream/XX-dev`, warn immediately: it must merge back only after (or together with) its parent, merging into `upstream/XX-dev` may conflict with the parent's changes, and it needs a rebase if the parent moves. Repeat the warning at merge time. +5. Do not push or set upstream tracking until asked. + +Canonical workflow: @.claude/skills/branching-strategy/SKILL.md diff --git a/.gitignore b/.gitignore index cf665c6f..6c79bae2 100644 --- a/.gitignore +++ b/.gitignore @@ -53,8 +53,9 @@ credentials.json # Cache .elastos/ -# Claude Code (user-specific settings) -.claude/ +# Claude Code (user-specific settings; shared skills are tracked) +.claude/* +!.claude/skills/ # External dependencies puter-upstream/ diff --git a/AGENTS.md b/AGENTS.md index 3957cd91..2576642d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,27 @@ lives in [state.md](state.md), and open work lives in [TASKS.md](TASKS.md). - Always report remote divergence. A local branch being green is not the same as `elacity/` being up to date. +## Creating Work Branches + +New feature or bugfix branches start from an `upstream/XX-dev` integration +branch (e.g. `upstream/0.6-dev`) — never silently from `main` or from whatever +branch happens to be checked out. The user chooses the base; do not pick it +yourself: + +- Run `git fetch origin --prune`, then list `upstream/*-dev` lines and active + `feat/*`/`fix/*` branches before proposing bases. +- Ask the user which base to start from, offering each `upstream/XX-dev` + (newest recommended) plus "an existing working branch" for work that depends + on another in-flight branch. Ask even when only one dev line exists. +- If the chosen base is a working branch rather than `upstream/XX-dev`, warn + immediately: the new branch must merge back only after (or together with) + its parent, merging it into `upstream/XX-dev` may conflict with the parent's + changes, and it needs a rebase if the parent moves. +- Name branches `feat/` or `fix/`; do not push or set upstream + tracking until asked. + +Canonical workflow: [.claude/skills/branching-strategy/SKILL.md](.claude/skills/branching-strategy/SKILL.md). + ## Branch Lifecycle Before creating, deleting, merging, or publishing branches, produce a short