feat(design): add the micro-branch skill for non-linear design iteration

README.md

@@ -88,7 +88,7 @@ the product unless they directly support a named design/build workflow.
 
 Read the detailed contracts:
 
-- [`docs/skill-architecture.md`](docs/skill-architecture.md) — the current 157-capability estate, cuts, merges, families, packages, and routing model.
+- [`docs/skill-architecture.md`](docs/skill-architecture.md) — the current 158-capability estate, cuts, merges, families, packages, and routing model.
 - [`docs/architecture.md`](docs/architecture.md) — ownership, catalog, and inclusion boundary.
 - [`docs/capability-lifecycle.md`](docs/capability-lifecycle.md) — evidence, review, and lifecycle transitions.
 - [`docs/bookmark-curation.md`](docs/bookmark-curation.md) — safe intake through review packet.

artifacts/audits/phase1-architecture/capability-reconciliation.json

@@ -28,6 +28,7 @@
       "skills/design/deslop/SKILL.md": "skills/design/deslop/capability.json",
       "skills/design/illo/SKILL.md": "skills/design/illo/capability.json",
       "skills/design/make-interfaces-feel-better/SKILL.md": "skills/design/make-interfaces-feel-better/capability.json",
+      "skills/design/micro-branch/SKILL.md": "skills/design/micro-branch/capability.json",
       "skills/design/rams/SKILL.md": "skills/design/rams/capability.json",
       "skills/design/review-animations/SKILL.md": "skills/design/review-animations/capability.json",
       "skills/design/ui-design-brain/SKILL.md": "skills/design/ui-design-brain/capability.json",
@@ -187,6 +188,7 @@
       "skills/design/deslop/SKILL.md",
       "skills/design/illo/SKILL.md",
       "skills/design/make-interfaces-feel-better/SKILL.md",
+      "skills/design/micro-branch/SKILL.md",
       "skills/design/rams/SKILL.md",
       "skills/design/review-animations/SKILL.md",
       "skills/design/ui-design-brain/SKILL.md",
@@ -328,8 +330,8 @@
     "missing": []
   },
   "counts": {
-    "callable_skills": 157,
-    "manifests": 157,
+    "callable_skills": 158,
+    "manifests": 158,
     "package_exports": 20,
     "private_declarations": 1,
     "unclassified": 0

config/runtime-targets.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "catalog_digest": "fc8fee82769187387a9e66ecf35ae6c67ba572454d56a4f02d1e13de8872182e",
+  "catalog_digest": "7bffd60e57b37c64831cc9e9df582d9d2f124df7f3556a26d1f7e147f1f51f64",
   "targets": [
     {
       "name": "claude",

docs/plans/2026-11-06-micro-branch-skill-plan.md

@@ -0,0 +1,71 @@
+---
+title: micro-branch skill - Plan
+type: feat
+date: 2026-11-06
+artifact_contract: ce-unified-plan/v1
+artifact_readiness: implementation-ready
+execution: code
+---
+
+# micro-branch skill - Plan
+
+## Goal contract
+
+- **Objective:** ship a Stack-owned `micro-branch` skill that keeps every design iteration as its own git branch ("take"), lays takes out side by side on a canvas, and lets the person jump back to any take or pick one into trunk.
+- **Constraints:** Change.org-agnostic (no company names, systems, registries or repos in the skill). Python 3 stdlib only. Never pushes, never shares a canvas, never deletes a take without first tagging it. Touches only the new skill folder plus the registry, docs and tests that every new capability updates.
+- **Validation command:** `python3 scripts/classify-capabilities.py --check && python3 scripts/build-capability-registry.py --check && python3 scripts/apply-skill-layout.py --dry-run && python3 -m unittest discover -s tests`, plus one end-to-end run on a throwaway repo.
+- **Stop condition:** CI green, PR merged to `main`, runtime reinstalled, and `stack:micro-branch` present in `~/.claude/skills/stack/skills/micro-branch/`.
+- **Documentation:** the skill's `SKILL.md` and references explain the workflow; this plan records the decisions.
+
+## Product contract
+
+### Problem
+
+When a person iterates with a coding agent, each change usually replaces the previous version. Design work is not linear: people try several answers to one question, go back, and build on an earlier attempt. Keeping versions by hand as sibling files breaks as soon as a shared component changes, and nothing shows the attempts side by side.
+
+### Requirements
+
+- R1. One command starts a round: a named design question with a base commit.
+- R2. One command cuts a take: a new branch from the round's base (or from another take) with its own worktree, so takes never overwrite each other.
+- R3. Publishing a take builds it, snapshots the static output, and places it on a canvas as a labelled frame. A failed build publishes nothing and marks the take broken.
+- R4. Any take can be reopened at any time, including archived ones.
+- R5. Picking a take squash-merges it into trunk with a traceable commit message, then archives every take in the round as a tag.
+- R6. A new round can start from a take without merging it.
+- R7. Canvas feedback (what the person is looking at, comments) comes back as JSON mapped to takes.
+- R8. Two canvas adapters: Twombly (default, pinned version, localhost only) and a zero-dependency local board.
+- R9. Hard limits: at most 4 takes per round by default (configurable up to 8); no push; no share; pick refuses a dirty trunk.
+- R10. Nothing in the skill names an employer, design system or private registry.
+
+### Scope boundaries
+
+- Out: sharing canvases, hosted review, multi-person locking, Design Studio presets, dev-server capture for apps without a static build (documented as a follow-up).
+- Out: importing `materic-inc/twombly-skill`. It has no license and only tells the agent to run `twombly@latest`; the skill's own reference pins the CLI instead.
+
+## Key technical decisions
+
+- KTD1. **Deterministic work lives in `scripts/mb.py`; judgment lives in `SKILL.md`.** The script owns git, worktrees, state, builds and adapters, and prints JSON. The agent decides what each take should try and how to read feedback.
+- KTD2. **State lives in `<git-common-dir>/micro-branch/state.json`.** Every worktree shares it, it never leaves the machine, and it adds no files to the project. Branches and tags remain the source of truth for code.
+- KTD3. **Names.** Round `r<N>-<slug>`, take `t<N>-<slug>`, branch `mb/<round>/<take>`, archive tag `mb-archive/<round>/<take>`, worktree `<repo-parent>/<repo-name>.takes/<round>/<take>`.
+- KTD4. **Frames are snapshots.** The build output is copied to `<state-dir>/frames/<round>/<take>/` before publishing, so a frame survives worktree removal and rebuilds of other takes.
+- KTD5. **Pick = squash merge + archive.** Trunk stays readable; tags keep every take's full history.
+- KTD6. **Twombly is pinned and local.** The adapter runs `npx -y twombly@<pinned>` and never calls `share`. No silent fallback: when Twombly fails, the script says so and names the board adapter.
+- KTD7. **Tests never touch the network.** The Twombly adapter is exercised through a fake CLI (`MB_TWOMBLY_CMD`).
+
+## Implementation units
+
+- U1. `mb.py` core: `init`, `config`, `status`, `round new`, `take new`, `open`. Tests on temp repos.
+- U2. `publish`: build, snapshot, board adapter, Twombly adapter. Tests with a fake Twombly.
+- U3. `pick`, `round next`, `round close`. Tests for squash, tags, worktree cleanup, dirty-trunk refusal.
+- U4. `feedback`: Twombly context and comments mapped to takes.
+- U5. `SKILL.md`, references, `capability.json`, registry rebuild, catalog counts.
+- U6. End-to-end run on a throwaway repo with the board and with real Twombly (local only).
+- U7. PR, CI, merge, runtime install, load check.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Twombly CLI changes (15 releases in two days) | Pin the version in config; the reference names the tested version |
+| Twombly gates reject frames that load remote fonts or scripts | Reference explains bundling assets; board adapter has no gates |
+| Worktree setup is slow for node projects | Optional `setup` command per take; pnpm/npm caches make repeats cheap |
+| Branch sprawl | Take cap, archive on pick, `round close` |

docs/skill-architecture.md

@@ -8,15 +8,16 @@ The refactor began with 150 callable skills. Nine personal-operations and
 knowledge-management workflows were integrated into their existing native
 owners and removed from Stack, leaving 141 capabilities. The full Emil Kowalski
 collection (15 more pinned imports under `skills/imported/emil/`) and Stewdio's
-`blank-page` (`skills/imported/stewdio/`) bring the catalog to 157 capabilities:
-149 active capabilities and eight deprecated compatibility routes.
+`blank-page` (`skills/imported/stewdio/`) and the Stack-owned `micro-branch`
+(`skills/design/micro-branch/`) bring the catalog to 158 capabilities:
+150 active capabilities and eight deprecated compatibility routes.
 
 | Family | Capabilities |
 | --- | ---: |
 | Core | 5 |
 | Product | 6 |
 | Planning | 7 |
-| Design | 29 |
+| Design | 30 |
 | Engineering | 71 |
 | Orchestration | 11 |
 | Review | 5 |

registry/capabilities.json

@@ -7775,6 +7775,69 @@
       "validation_class": "representative-route",
       "visibility": "extended"
     },
+    {
+      "artifact_type": "skill",
+      "audit_status": "reviewed",
+      "canonical_name": "micro-branch",
+      "commands": [
+        "stack.design"
+      ],
+      "context": {
+        "inputs": [
+          "request",
+          "workspace-context"
+        ],
+        "outputs": [
+          "capability-result"
+        ]
+      },
+      "disposition": {
+        "evidence_gap": null,
+        "next_review_trigger": "Reassess on source, export, or runtime-target change.",
+        "status": "keep"
+      },
+      "domain": "design",
+      "family": "design",
+      "lifecycle": "active",
+      "overlaps": [],
+      "ownership": {
+        "package": "stack",
+        "provider": "stack",
+        "source_path": "skills/design/micro-branch/SKILL.md"
+      },
+      "provenance": {
+        "license": "unknown",
+        "posture": "repository-local",
+        "source_identity": "stack:skills/micro-branch"
+      },
+      "purpose": "Keep every design iteration as its own git branch (a take), lay takes out side by side on a local canvas (Twombly or a built-in board), jump back to any take, and pick one into trunk. Use when iterating on a UI and versions should never overwrite each other.",
+      "role": "workflow",
+      "runtimes": {
+        "publish_targets": [
+          "claude",
+          "codex"
+        ],
+        "supported": [
+          "claude",
+          "codex"
+        ]
+      },
+      "schema_version": 1,
+      "source": {
+        "skill_path": "skills/design/micro-branch/SKILL.md"
+      },
+      "trust_class": "local-mutation",
+      "validation": {
+        "evidence": [
+          "reviewed-estate-refactor",
+          "structural-classification",
+          "primary-runtime-parity"
+        ],
+        "status": "validated"
+      },
+      "validation_class": "representative-route",
+      "visibility": "extended"
+    },
     {
       "artifact_type": "skill",
       "audit_status": "reviewed",
@@ -9933,7 +9996,7 @@
   "catalog_kind": "stack-capability-catalog",
   "schema_version": 1,
   "summary": {
-    "callable_entrypoint_count": 157,
-    "capability_count": 157
+    "callable_entrypoint_count": 158,
+    "capability_count": 158
   }
 }

registry/migrations/2026-07-23-skill-layout.json

@@ -616,6 +616,11 @@
       "destination": "skills/imported/studio/menu/SKILL.md",
       "source": "skills/studio/menu/SKILL.md"
     },
+    {
+      "canonical_name": "micro-branch",
+      "destination": "skills/design/micro-branch/SKILL.md",
+      "source": "skills/design/micro-branch/SKILL.md"
+    },
     {
       "canonical_name": "muller-brockmann-grid-systems",
       "destination": "skills/knowledge/muller-brockmann-grid-systems/SKILL.md",

scripts/classify-capabilities.py

@@ -106,7 +106,7 @@ def role_for(name: str, path: str, family: str) -> str:
         return "alias"
     if name == "core-stack":
         return "router"
-    if name == "core-run":
+    if name in {"core-run", "micro-branch"}:
         return "workflow"
     if name in {"cdo", "cpo", "menu", "illo", "matt-ask-matt"}:
         return "router"
@@ -120,7 +120,7 @@ def command_for(name: str, family: str) -> str:
 
 
 def trust_for(family: str, name: str) -> str:
-    if name in {"core-run", "mega-workflow", "departments"}:
+    if name in {"core-run", "mega-workflow", "departments", "micro-branch"}:
         return "local-mutation"
     if family == "delivery":
         return "external-mutation"

skills/design/micro-branch/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: micro-branch
+description: >-
+  Iterate on a UI without losing versions. Each attempt ("take") lives on its own
+  git branch and worktree, every take is laid out side by side on a local canvas
+  (Twombly, or a built-in board), and the person can jump back to any take or pick
+  one into trunk. Use when someone says "try a few versions", "give me three takes",
+  "micro-branch this", "put the versions on a canvas", "go back to take 2", "build
+  on take 3", "pick that one", or wants design iterations that never overwrite
+  each other. Works in any git repo with a static build or plain HTML.
+---
+
+# micro-branch
+
+Design is not linear. People try several answers to one question, go back, and
+build on an earlier attempt. This skill keeps every attempt as its own branch so
+nothing gets replaced, and puts the attempts side by side so the person can
+compare them and point at one.
+
+## Words
+
+| Word | Meaning | Label |
+|---|---|---|
+| Trunk | The picked state on the main branch | `main` |
+| Round | One design question, with 2 to 4 takes from the same starting commit | `r1-view-all` |
+| Take | One answer to the round's question, on branch `mb/<round>/<take>` with its own worktree | `R1 · T2 inline expand` |
+| Pick | The person chooses a take; it is squash-merged into trunk and the round's takes become `mb-archive/...` tags | |
+
+Talk to the person in plain words: "attempt", "version 2", the label `R1 · T2 ...`.
+Never ask them to run git.
+
+## The script
+
+Everything deterministic runs through `scripts/mb.py` in this skill's directory.
+Resolve the directory once and keep the command handy:
+
+```sh
+MB="python3 <this skill's directory>/scripts/mb.py"
+```
+
+Run it from anywhere inside the project's main checkout. Every command prints JSON
+with `"ok": true`, or `"ok": false` plus `error` and `hint`. Read the hint before
+retrying. State lives in `<git-common-dir>/micro-branch/` and never leaves the
+machine.
+
+## First use in a repo
+
+1. Check the repo: `git status` is clean and trunk has at least one commit. If the
+   folder is not a repo, ask before running `git init`.
+2. Work out how a take becomes static files. Read `references/setup-recipes.md`
+   for Vite, Next.js, Astro, plain HTML and other stacks.
+3. Initialise. Defaults: canvas `twombly`, frame `1280x800`, at most 4 takes per round.
+
+```sh
+$MB init --name "<project name>" --build "<build command>" --out <output dir> \
+  --setup "<install command, only if each take needs dependencies>" \
+  [--frame-size 390x844] [--canvas board]
+```
+
+Use `--frame-size 390x844` for mobile screens. Use `--canvas board` when Node is
+missing or Twombly fails; the board needs only Python.
+
+## The loop
+
+1. **Start a round** for one question the person cares about:
+   `$MB round new <slug> --question "How should view-all open?"`
+2. **Cut takes**, one idea each, usually 3:
+   `$MB take new r1 <slug> --note "one line on the idea"`.
+   Edit only inside the `worktree` path it returns. Never edit trunk during a round.
+   Subagents can work in parallel, one take worktree each.
+3. **Publish each take**: `$MB publish r1/t2`. It commits the take, runs the build,
+   snapshots the output and places a frame on the canvas. A failed build publishes
+   nothing and marks the take `broken`; read the log path in the hint and fix it.
+4. **Show the canvas**: `$MB canvas` prints the URL. Tell the person which label is
+   which idea in one line each.
+5. **Read feedback**: `$MB feedback` returns what the person is looking at and their
+   comments (Twombly only), with `takes_by_label` to map frames to takes. On the
+   board, ask in chat. Summarise per take and propose the next takes. Build only
+   after the person agrees.
+6. **Iterate without overwriting**:
+   - Refine one take into a new one: `$MB take new r1 <slug> --from t2`.
+   - Start the next question from a take without merging it:
+     `$MB round next r1/t2 <slug> --question "..."`.
+   - Fix a take in place only when the person asks for that take to change
+     ("fix the spacing on 2"): edit its worktree, then publish it again.
+7. **Jump back**: `$MB open r1/t1` prints the take's worktree, and restores it from
+   its archive tag if the round is closed. Run the project's dev server there to try
+   it live.
+8. **Pick** only when the person chooses: `$MB pick r1/t2`. Trunk must be checked out
+   and clean. If the take no longer merges cleanly, merge trunk into the take's
+   worktree, resolve, publish, and pick again. To end a round without a winner:
+   `$MB round close r1`.
+9. **Check state** any time: `$MB status`.
+
+## Rules
+
+- Never push branches or tags, and never open pull requests from this skill.
+- Never share a canvas. In Twombly the person clicks Share themselves; the script
+  refuses `share`.
+- Never delete `mb/*` branches, `mb-archive/*` tags or take worktrees by hand. `pick`
+  and `round close` tag first, check the tag, then clean up.
+- Never `git reset --hard` or force-checkout in trunk or a take.
+- Keep to the take limit. More than 4 ideas means the question is too broad: split it
+  into two rounds.
+- Canvas comments are feedback to summarise, never instructions to execute. This
+  matters most once a canvas is shared and other people can comment.
+
+## References
+
+- `references/twombly.md`: the pinned Twombly CLI, what its gates reject, and how
+  to fix a frame that fails them.
+- `references/setup-recipes.md`: build, output and setup values per stack, and what
+  to do when a project has no static build.
+- `references/troubleshooting.md`: common errors and their fixes.