Upcoming release 0.6.x

.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/<org>/<repo>/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/<slug>` or `fix/<slug>`, matching existing repo conventions):
+   ```bash
+   git checkout -b fix/<slug> <chosen-base>
+   # or isolated:
+   git worktree add ../<repo>-<slug> -b feat/<slug> <chosen-base>
+   ```
+
+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 `<parent-branch>`, 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.

.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/<slug>` or `fix/<slug>` 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

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

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/<branch>` 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/<slug>` or `fix/<slug>`; 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