Repository navigation
feat(design): add the micro-branch skill for non-linear design iteration - #47
Conversation
Adds a Stack-owned `micro-branch` skill. Each design attempt ("take") gets
its own git branch and worktree, so iterations never overwrite each other.
Takes are laid out side by side on a local canvas, and the person can jump
back to any take, build a new round on one, or pick one into trunk.
- scripts/mb.py (stdlib Python, JSON output): init, round new/next/close,
take new, publish, open, pick, canvas, feedback, status. State lives in
<git-common-dir>/micro-branch/, shared by worktrees and never pushed.
- Pick squash-merges into trunk with traceable trailers, then tags every
take as mb-archive/<round>/<take> before removing branches or worktrees.
- Canvas adapters: Twombly pinned at 0.4.10 (fixed port 4848; usage pings,
update checks and remote interface updates off; share/login/join refused;
republish uses `update` so comments stay), and a zero-dependency local
board that mirrors every take.
- Failed builds publish nothing; frames that Twombly's gates reject are
recorded with their problems and stay visible on the board.
- Change.org-agnostic by design; a test fails if the skill names an employer
or private system.
- Registers the capability (classifier, layout migration, reconciliation,
catalog digest, counts) and adds tests/test_micro_branch.py (12 tests on
throwaway repos, Twombly faked).
Verified end to end on a sample repo against the real twombly@0.4.10:
add, update, gate rejection, feedback, pick, archive and restore.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b23eb5834c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| git("worktree", "remove", "--force", str(worktree), cwd=repo.cwd) | ||
| git("branch", "-D", take["branch"], cwd=repo.cwd) | ||
| take.update(archive_tag=tag, status="picked" if take["id"] == picked else "archived") |
There was a problem hiding this comment.
If archiving a later take fails, for example because its work-in-progress commit fails a pre-commit hook, earlier takes have already had their worktrees and branches deleted, but locked_state discards all state updates on the exception. Those takes retain archive_tag: null, so open refuses to restore them despite their tags existing. Retrying round close does not repair this: the missing-branch check skips those takes without recording their archive tags. This is reproducible with two dirty takes and a hook rejecting the second. Persist completed archive operations durably or recover and verify existing archive tags before skipping missing branches.
Useful? React with 👍 / 👎.
| if args.no_squash: | ||
| proc = run(["git", "merge", "--no-ff", "-m", subject + body, take["branch"]], cwd=trunk_tree, check=False) | ||
| else: | ||
| proc = run(["git", "merge", "--squash", take["branch"]], cwd=trunk_tree, check=False) |
There was a problem hiding this comment.
When a take begins tracking a path that is ignored and locally present on trunk, the cleanliness check passes and this merge silently overwrites the trunk file. In the inspected cmd_pick flow, both merge variants omit --no-overwrite-ignore; git merge -h describes --[no-]overwrite-ignore as “update ignored files (default)”. I reproduced a successful pick replacing an ignored trunk file's local contents with the take's version, without preserving the original in Git. Pass --no-overwrite-ignore to both merge variants so a collision fails rather than destroying local data.
Useful? React with 👍 / 👎.
| if not path.exists(): | ||
| path.parent.mkdir(parents=True, exist_ok=True) | ||
| git("worktree", "prune", cwd=repo.cwd) | ||
| git("worktree", "add", str(path), take["branch"], cwd=repo.cwd) | ||
| restored = True |
There was a problem hiding this comment.
For projects using the documented dependency setup recipes, archiving removes the ignored node_modules directory or symlink, and restoring the worktree here does not recreate it. Consequently, open reports success but the documented next step of running the project's dev server, or republishing the restored take, fails because dependencies are missing. New takes already call run_setup with take_env; apply the same initialization when open recreates a worktree, and report setup failures consistently.
Useful? React with 👍 / 👎.
What
A Stack-owned
micro-branchskill (stack:micro-branch). Each design attempt ("take") lives on its own git branch and worktree, takes are laid out side by side on a local canvas, and the person can jump back to any take, start a new round from one, or pick one into trunk.How
skills/design/micro-branch/scripts/mb.py: stdlib Python, JSON output. Commands:init,round new|next|close,take new,publish,open,pick,canvas,feedback,status.<git-common-dir>/micro-branch/. Every worktree shares it, and nothing is pushed.picksquash-merges into trunk with trailers, then tags each take asmb-archive/<round>/<take>. It removes branches and worktrees only after checking the tag.share,loginandjoinare refused. Republishing usesupdate, so comments stay on the frame.rejectedwith the problems, and the board still shows it.Checks
tests/test_micro_branch.py: 12 tests on throwaway repos, with Twombly faked.twombly@0.4.10on a sample repo: add, update in place, Google Fonts gate rejection, feedback mapping, pick, archive, restore, and the board render.Plan:
docs/plans/2026-11-06-micro-branch-skill-plan.md.🤖 Generated with Claude Code