Add CS skill overlay (keeps upstream SKILL.md pristine)

skills/fizzy/SKILL.md stays byte-identical to upstream so it never conflicts on
merge. CS-specific Fizzy guidance (board structure, archiving, restricted-board
access, tag IDs) lives in skills/fizzy/OVERLAY.md and is appended onto the
installed skill by scripts/install-skill.sh — so agents get it in every project
without diverging the upstream file. Additive files only; no merge conflicts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: waynemsmith

scripts/install-skill.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Install the Fizzy skill, then append the CS fork overlay.
+#
+# Why: we keep skills/fizzy/SKILL.md byte-identical to upstream so it never
+# conflicts on merge. Our CS-specific guidance lives in skills/fizzy/OVERLAY.md
+# and is appended onto the *installed* skill here, so agents get it in every
+# project without diverging the upstream file.
+#
+# Run after building/installing the binary:
+#   make build && cp bin/fizzy ~/.local/bin/fizzy && scripts/install-skill.sh
+#
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OVERLAY="$HERE/skills/fizzy/OVERLAY.md"
+MARKER="<!-- CS-FIZZY-OVERLAY -->"
+
+[ -f "$OVERLAY" ] || { echo "overlay not found: $OVERLAY" >&2; exit 1; }
+
+# Write the upstream skill (overwrites the installed copy with pristine content).
+fizzy skill install >/dev/null
+
+# Resolve the installed skill file (Claude loads it via a symlink).
+SKILL_LINK="$HOME/.claude/skills/fizzy/SKILL.md"
+SKILL_FILE="$(readlink -f "$SKILL_LINK" 2>/dev/null || echo "$SKILL_LINK")"
+[ -f "$SKILL_FILE" ] || { echo "installed skill not found: $SKILL_FILE" >&2; exit 1; }
+
+# fizzy skill install just overwrote it, so the marker is gone — append once.
+if grep -qF "$MARKER" "$SKILL_FILE"; then
+  echo "overlay already present in $SKILL_FILE"
+else
+  printf '\n' >> "$SKILL_FILE"
+  cat "$OVERLAY" >> "$SKILL_FILE"
+  echo "overlay appended to $SKILL_FILE"
+fi

skills/fizzy/OVERLAY.md

@@ -0,0 +1,55 @@
+<!-- CS-FIZZY-OVERLAY -->
+
+---
+
+# Concurrent-Systems — Fizzy conventions (fork overlay)
+
+> Appended to the upstream skill by `scripts/install-skill.sh`. Upstream
+> `SKILL.md` stays byte-identical so it never conflicts on merge; iterate CS
+> guidance here.
+
+## Board structure — where work lives
+
+- **Team boards = execution.** Work chunks live on the team board that has the
+  capacity to finish them (Ops, Dev, Finance, LT). One owner per card. This is
+  where WIP is real — don't spread executable work onto other boards or it gets
+  lost.
+- **`🎯 Projects` = initiatives.** One card per multi-week initiative (outcome +
+  one accountable owner), columns `Maybe? → On Deck → Active → Done`. The
+  initiative card is the **hub**; its chunks live on team boards and mention the
+  project by name + link in their description. Keep the Active set small.
+- **Pipeline boards only for standing flows** a dedicated crew owns end-to-end
+  (Incidents, Leads). They *track* the flow and hand execution cards to team
+  boards; they don't hold the work. Don't model low-volume things (a one-off
+  incident) as pipelines — that's ceremony; just make the work chunks.
+
+## Archiving done cards
+
+- `fizzy card move <n> --to <board>` **preserves closed/Done state** (the GUI
+  can't — it forces a reopen). So the CLI is the bulk-archive tool.
+- CS keeps a `🗄️ Archive-<Board>` board per board. Sweep done cards with a loop:
+  `for n in $(fizzy card list --board <SRC> --indexed-by closed --all --jq '.data[].number'); do fizzy card move "$n" --to <ARCHIVE>; done`
+- **Restricted boards:** `fizzy board create` is ALWAYS all-access (the
+  `--all_access false` flag is ignored) and the CLI has **no grant/revoke** for
+  per-user access. So for a sensitive board (e.g. LT), a human must lock access
+  in the **GUI** first; verify with `fizzy board accesses --board <id>` that the
+  archive's access matches the source **before** moving cards in, or restricted
+  cards leak.
+
+## Tags
+
+- Get a tag's **ID** (needed for `--tag`) from `fizzy tag list --all` — it
+  paginates, so `--all` is required; each tag object also has a `url` that is the
+  GUI cross-board rollup link.
+- `fizzy card list --tag <ID>` is **cross-board by default** (no `board_ids`
+  injection); pass `--board` only to scope to one board. (Upstream fix in
+  basecamp/fizzy-cli#181; carried locally until merged.)
+- Don't mint a tag per initiative unless you'll retire it — there's no
+  `tag delete`; a tag disappears only when removed from every card.
+
+## This fork
+
+`~/g/fizzy-cli-fork` tracks `upstream/master` (basecamp/fizzy-cli) and builds the
+latest v4 (not on Homebrew yet). Carries only: the #181 cross-board fix (pending
+upstream) and this skill overlay. Update: `git pull && make build && cp bin/fizzy
+~/.local/bin/fizzy && scripts/install-skill.sh`.