@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/synth-creator/rules/done-means-fresh-evidence.md

@@ -0,0 +1,18 @@
+---
+# concepts: tests, build
+paths:
+  - "placeholder"
+---
+
+# "Done" means evidence from this turn
+
+<constraints>
+Always do:
+- Before saying done, fixed, passing, faster or "sounds the same", run the command that proves it in this turn and quote its verdict: test-verdict JSON, null-test result in dBFS, benchmark p99, golden-image score.
+- Say exactly what was not verified, and why ("not run on Windows", "listened only, not measured").
+- Treat a subagent's report as a claim. Check its diff and re-run its verdict before passing it on.
+
+Never do:
+- Report success from memory of an earlier run, from a build that only compiled, or from "should work".
+- Report a partial pass as a pass.
+</constraints>

package/packs/synth-creator/rules/hooks-and-gates.md

@@ -0,0 +1,21 @@
+---
+# concepts: tooling
+paths:
+  - "placeholder"
+---
+
+# Hooks, gates and tools: each seen red, each fault logged
+
+<constraints>
+Always do:
+- Give every hook and gate a `--selftest` that plants its fault, and run it from the project's plants script (the `plants` command in `.claude/layout.json`). A new gate goes in there in the same commit. A gate that has never been seen red proves nothing.
+- Log a workflow fault (a hook, a tool, the build queue, a test run) in `workflow-bugs.md` before fixing it (the `workflow-bugs` skill), and close it with cause, fix and what now catches it.
+- Run Python on files that come from outside with `-I`. Measure files with Python, not with BSD or GNU tool flags.
+- Keep a planted fault in the test build only: one macro or `constexpr` flag that is false in the shipped binary, and a release gate that searches the binary for it (`cpp-faults-only-in-the-test-build`).
+- Treat a hook that blocks correct work as a red check: stop, report its exact message, and log it. The hook is fixed first, with a selftest that plants the right case and the wrong one; the work resumes after.
+- Make a fix to a hook, rule, check or skill that every synth uses in claude-packs, with its test, then take it in with `npx --no-install @thedecipherist/claude-packs update`. Only a law that is about this project alone stays in this project's `.claude/`.
+
+Never do:
+- Route around a block: no code put into an unrelated existing file, no file pushed past the line limit, no write through the shell after a refusal, no override variable.
+- Change a hook so that its own selftest passes while the fault it exists for gets through.
+</constraints>

package/packs/synth-creator/rules/long-work-in-the-background.md

@@ -0,0 +1,16 @@
+---
+# hook: time-guard.mjs
+---
+# Long work runs in the background, and a warning about time is acted on
+
+<constraints>
+Always do:
+- Start anything over about two minutes as a background job with its output in a file; you are told when it ends. Do other work meanwhile.
+- When `time-guard` says something is slow, look at it now: find what is running, say so, and stop it if it is not needed.
+- Commit an agent's work when `time-guard` says it has gone unsaved.
+
+Never do:
+- Wait in a `sleep`, `until` or `pgrep` loop, or poll a job's output file.
+- Start a second copy of a job that is still running, or start it again without reading why the first one ended.
+- Treat a slow job as normal because the last one was slow too.
+</constraints>

package/packs/synth-creator/rules/timing-from-synthcore.md

@@ -0,0 +1,16 @@
+---
+# concepts: cpp
+---
+
+# Time and keys come from synthcore: one clock, written once
+
+<constraints>
+Always do:
+- Link `synthcore` for tempo, MIDI clock, transport, sync modes, QWERTY and the focus rule. Subclass `core::CoreHost`, and make `host.readTransport (getPlayHead(), midi, n);` the second line of `processBlock`, after `ScopedNoDenormals`.
+- Have every tempo-synced thing read the one master clock. Tap tempo sets the same `bpm` parameter the clock reads.
+- Fix a fault in the clock in `synthcore`, once, with its test, and take it in everywhere.
+
+Never do:
+- Read the play head, count MIDI clock bytes or work out a tempo in a unit. `timing-from-synthcore` refuses it.
+- Copy `synthcore`'s code into a unit, or write a second clock because one thing needs it.
+</constraints>

package/packs/synth-creator/skills/build-step/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: build-step
+description: Use when work begins on a step of a synth's build.md, when a step's "done when" may be met, when a session starts or ends in a repo with a build.md, or when someone asks where the build is. Also /build-step.
+---
+
+# One build step: its own branch, from start to merge
+
+The canonical text is the repo's own `build.md` ("Rules for this file") and its `CLAUDE.md`. This file is the operating
+summary. Where they disagree, the repo wins. The step tool is the project's (the `step` command in `.claude/layout.json`,
+usually `python3 tools/step.py`); if the repo has none, copy `tools/step.py` and `tools/hooks/` from a sibling synth that
+has them before doing any of this by hand.
+
+The house rule: **every build task is built in a new branch. Once completed it is merged into the
+trunk. We must not be able to lose any work.** MegaSynth lost two days of panel work to one checkout, more to work nobody
+had written down as started, and more to steps called done because the code compiled. A step is a promise with a
+measurement on the end, and a pushed branch is what a dead session leaves behind.
+
+## 0. Before acting on a paste from the user
+
+- If the project's spec carries an edition line ("Spec edition: ..." at the top of `docs/*-spec.md`) and the paste names an
+  edition, check the file shows it. Older, or no line: **stop and say so**, naming both editions.
+- Every file a paste names must be there. One missing or older: **stop and tell the user**, naming the file and what was found;
+  do not carry on with the parts that do not depend on it.
+
+## 1. At the start of a session
+
+```
+python3 tools/step.py status
+```
+
+It prints the count, the current step, the branch you are on, uncommitted changes and every branch not yet merged, with
+its last commit. An unmerged branch is unfinished work: read its last commit message and its In-progress row before
+starting anything else. Read `bugs.md`'s Open table too.
+
+**If the work in front of you is not a step in build.md, stop and ask the user whether the plan has changed.** A bug fix or a
+change of plan the user has agreed goes on `start --work <name> "task"` and is merged with `land`.
+
+## 2. Start: the branch comes first
+
+```
+python3 tools/step.py start <STEP> "<the task, smaller than the step>"
+```
+
+This makes the step's branch from the trunk, writes the task under "In progress" with its start time (date, time, zone),
+commits and pushes the branch. Nothing is committed straight onto the trunk; `git-guard` refuses it.
+
+Read the step's "done when" now and decide how it will be measured. If it cannot be measured or seen in the opened app,
+say so before building.
+
+### The shape comes first (KWB-1)
+
+Before any code, name every concept the step touches and find its row in `design/shape.json` (ONE with its frozen id, or
+MANY with its count, generator, selectors and declared constants).
+
+- **A concept the step introduces gets its row first, as the step's first commit** (`step.py save "shape: <concept> row"`
+  with only `design/shape.json` in it), before any code that uses it. `shape-law` refuses an instance type with no row.
+- Build for the shape: one loop over every instance, or the generator. Test the behaviour once, on the template (`test-the-template-once`). An instance a bug was seen in goes on a `seen in:`
+  line; a rule that picks one is a selector listed in the row; a fixed one is a named constant there. Anything else is
+  refused with "example, rule, or constant?".
+- **Every subagent brief quotes the manifest row of every concept it touches, word for word**, and names the shape and
+  the generator, never an instance (`brief-guard` refuses "drive slot 2"; "seen in: slot 2, build for all slots" passes).
+- `npx --no-install @thedecipherist/claude-packs shape scan` lists what the repo already names by instance; a step that touches such a file fixes its
+  lines or leaves them as they were, never adds to them.
+
+## 3. While working: save often
+
+```
+python3 tools/step.py save "<what state it is in>" [--paths <new files>]
+```
+
+Commits everything changed and pushes the branch. Run it after every unit of work, before any risky command, and
+**always before a session ends**, saying if the work was interrupted and what is half done. It lists new files it was not
+told about; name them or ignore them, never leave them floating.
+
+- A bug goes into `bugs.md` the moment it is found, before it is fixed.
+- A red tripwire gate stops all other work.
+- Steps that run side by side each have their own branch. Switch with `start`; it refuses to switch over uncommitted work.
+
+## 4. Is it done?
+
+```
+python3 tools/step.py check
+```
+
+It runs the mechanical checks and prints the repo's "Runs through every step" list to walk by eye. Run the project's
+plants script (the `plants` command) before ticking: every planted fault red. Then the step's own "done when":
+
+- **Measured or seen in the opened app.** Rebuilt, opened, pressed. Not "wired", not "compiles", not "the test I just
+  wrote passes".
+- A gate that passed first time is suspect. Plant the fault it exists to catch and watch it fail.
+- Say which artefact was checked: the standalone, a probe, a picture the app rendered itself.
+
+If any part is not met, the step is not done. Say which part, `save`, and keep working or ask. The branch stays open;
+that is what it is for.
+
+## 5. Finish: merge into the trunk
+
+```
+python3 tools/step.py finish <STEP> --proof "<what was measured, with numbers>" [--paths <new files>]
+```
+
+On the step's branch. It brings the trunk into the branch first, ticks and dates the step, moves its In-progress row to
+the log with the finish time and what the step took, updates "Where we are" and the count, commits, merges into the trunk
+with a merge commit, writes that commit's short hash into the log line in a second commit, and pushes the trunk and the
+branch.
+
+It refuses an empty proof, a step that is not the current one (side-by-side steps take `--out-of-order`), and unnamed new
+files. If a merge conflicts it stops with both sides intact: resolve by hand, never by throwing a side away, and ask the user
+if it is not obvious which line is right. If it prints NOT PUSHED, push with the command it shows. A step is not finished
+until the trunk is pushed.
+
+## 6. Tell the user
+
+Conclusion first, in plain language: the step, what proved it, the new count, the next step. Show the changed `build.md`.
+Never claim a step works that has not been built, opened and measured.
+
+## Never
+
+- Delete a branch, here or on GitHub. Rebase, amend, squash or force-push. `git add -A`.
+- `checkout`, `restore`, `stash` or `reset --hard` over uncommitted work. `save` first.
+- Commit straight onto the trunk. Pass `--no-verify`.
+- Delete a step from build.md: strike it through with the reason and the date. A reopened step keeps its line, marked
+  REOPENED.
+- Tick from memory of an earlier session. Measure again.
+- Soften a red test in a commit message.

package/packs/synth-creator/skills/build-through-the-queue/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: build-through-the-queue
+description: Use when about to compile, run ctest, or run a program from a build folder, or when build-guard refused a command.
+---
+
+# Build through the queue (one job: no build takes the whole machine)
+
+<constraints>
+Always do:
+1. Use the project's wrapper first: the `build` and `test` commands in `.claude/layout.json`. Otherwise run `node .claude/tools/buildq.mjs <command>`.
+2. The queue runs two at a time and waits for a slot by itself; `--status` shows the slots. Run it in the foreground, or as a background job.
+3. As an agent, build only the targets the change needs (`--target X --target Y`) and run only its tests (`-R 'pattern'`, at most 30).
+4. An agent started as `KIND: light` does not build or run tests: do the light part, and say in the report what needs building.
+
+5. End a build's command with the build's own status. A background job reports its last command's status: a build followed by `echo` or `tail` reports theirs, and a stale binary reads as a pass. Keep the output in a file and read the build's exit.
+
+Never do:
+- Run `cmake --build`, `ctest`, `make`, `ninja`, `xcodebuild`, or a program from a build folder straight from the shell.
+- Wrap a build in a wait loop.
+- Build every target from an agent: the whole build runs once, before landing.
+</constraints>

package/packs/synth-creator/tools/buildq.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// buildq: the machine-wide build queue that build-guard sends every heavy job to (KF-1: the hook named a tool no pack shipped). Two jobs at a time, across every
+// project on the machine; a job waits for a slot by itself. A slot is a folder made atomically, holding its owner's pid; a dead owner's slot is taken back.
+// The exit status is the command's own, so `node .claude/tools/buildq.mjs ninja && next` means what it says. A status read after a pipe or an echo is theirs, not the build's (KF-37).
+//   node .claude/tools/buildq.mjs <command> [args...]    run it in the next free slot
+//   node .claude/tools/buildq.mjs --status               how many slots are taken
+// BUILDQ_DIR: where the slots live (default: the machine's temp folder). BUILDQ_SLOTS: how many (default 2).
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const DIR = process.env.BUILDQ_DIR ?? join(tmpdir(), 'claude-packs-buildq');
+const SLOTS = Number(process.env.BUILDQ_SLOTS ?? 2);
+const WAIT_MS = 500;
+const slotAt = (n) => join(DIR, `slot-${n}`);
+const nap = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function ownerOf(slot) {
+  try { return Number(readFileSync(join(slot, 'pid'), 'utf8')); } catch { return null; }
+}
+
+function isLive(slot) {
+  const pid = ownerOf(slot);
+  if (pid === null) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM'; // another user's job holds it
+  }
+}
+
+function claim() {
+  mkdirSync(DIR, { recursive: true });
+  for (let n = 0; n < SLOTS; n += 1) {
+    const slot = slotAt(n);
+    try {
+      mkdirSync(slot);
+      writeFileSync(join(slot, 'pid'), `${process.pid}\n`);
+      return slot;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (ownerOf(slot) !== null && !isLive(slot)) rmSync(slot, { recursive: true, force: true });
+    }
+  }
+  return null;
+}
+
+function status() {
+  const taken = Array.from({ length: SLOTS }, (_, n) => slotAt(n)).filter(isLive).length;
+  console.log(`${taken} of ${SLOTS} slots taken`);
+  return 0;
+}
+
+function run(command) {
+  let slot = claim();
+  for (; slot === null; slot = claim()) nap(WAIT_MS);
+  try {
+    const r = spawnSync(command[0], command.slice(1), { stdio: 'inherit' });
+    if (r.error) console.error(`buildq: ${command[0]}: ${r.error.message}`);
+    return r.status ?? 1;
+  } finally {
+    rmSync(slot, { recursive: true, force: true });
+  }
+}
+
+const args = process.argv.slice(2);
+if (args[0] === '--status') process.exit(status());
+if (!args.length) {
+  console.error('usage: node .claude/tools/buildq.mjs <command> [args...] | --status');
+  process.exit(2);
+}
+process.exit(run(args));

package/packs/synth-creator/tools/freeze.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Freeze the files that define "fixed" before changing the code that must satisfy them.
+//   node .claude/tools/freeze.mjs on "<reason>" <file-or-glob>...
+//   node .claude/tools/freeze.mjs off
+//   node .claude/tools/freeze.mjs status
+// The frozen-files hook refuses edits to anything on the list until it is turned off.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const STATE = join(ROOT, '.claude', 'state', 'frozen.json');
+const [cmd, reason, ...files] = process.argv.slice(2);
+
+const USAGE = 'usage: freeze.mjs on "<reason>" <files...> | off | status';
+
+function on() {
+  if (!reason || files.length === 0) {
+    console.error('usage: freeze.mjs on "<reason>" <file-or-glob>...');
+    return 2;
+  }
+  mkdirSync(join(ROOT, '.claude', 'state'), { recursive: true });
+  const prev = existsSync(STATE) ? JSON.parse(readFileSync(STATE, 'utf8')).files ?? [] : [];
+  const all = [...new Set([...prev, ...files])];
+  writeFileSync(STATE, `${JSON.stringify({ reason, files: all, since: new Date().toISOString() }, null, 2)}\n`);
+  console.log(`frozen (${reason}):\n${all.map((f) => `  ${f}`).join('\n')}`);
+  return 0;
+}
+
+const COMMANDS = {
+  on,
+  off: () => (rmSync(STATE, { force: true }), console.log('nothing frozen'), 0),
+  status: () => (console.log(existsSync(STATE) ? readFileSync(STATE, 'utf8') : 'nothing frozen'), 0),
+};
+
+const run = Object.hasOwn(COMMANDS, cmd) ? COMMANDS[cmd] : () => (console.error(USAGE), 2);
+process.exit(run());

package/packs/tui/checks/tui-entry-restores-terminal.json

@@ -0,0 +1,27 @@
+{
+  "id": "tui-entry-restores-terminal",
+  "why": "Entering the alternate screen or raw mode without an exit handler that restores them strands the user in a broken terminal after a crash. process.once('exit', restore), registered before the first render.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "concepts": [
+    "tui",
+    "tui-entry"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "\\?1049h|setRawMode\\s*\\(\\s*true\\s*\\)",
+  "needs": [
+    "\\?1049l|setRawMode\\s*\\(\\s*(?:false|wasRaw|prev\\w*|was\\w*)\\s*\\)",
+    "process\\.(?:once|on)\\s*\\(\\s*['\\\"](?:exit|SIGINT)['\\\"]"
+  ],
+  "bad": "process.stdout.write('\\x1B[?1049h\\x1B[?25l');\nconst { waitUntilExit } = render(<App />);",
+  "good": "process.stdout.write('\\x1B[?1049h\\x1B[?25l');\nconst restore = () => process.stdout.write('\\x1B[?25h\\x1B[?1049l');\nprocess.once('exit', restore);\nconst { waitUntilExit } = render(<App />);"
+}

package/packs/tui/checks/tui-gates-on-tty.json

@@ -0,0 +1,25 @@
+{
+  "id": "tui-gates-on-tty",
+  "why": "A TUI started on a non-TTY stdout (CI, a pipe, a log) writes escape codes into the log and reads stdin that never answers. Gate on isTTY and a minimum size, fall back to plain output.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "concepts": [
+    "tui-entry"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "\\?1049h|setRawMode\\s*\\(\\s*true\\s*\\)|\\brender\\s*\\(\\s*<",
+  "needs": [
+    "\\bisTTY\\b"
+  ],
+  "bad": "process.stdout.write('\\x1B[?1049h');\nrender(<App />);",
+  "good": "if (!process.stdin.isTTY || !process.stdout.isTTY) return printPlain(report);\nprocess.stdout.write('\\x1B[?1049h');\nrender(<App />);"
+}

package/packs/tui/checks/tui-no-ris-reset.json

@@ -0,0 +1,22 @@
+{
+  "id": "tui-no-ris-reset",
+  "why": "\\x1Bc (RIS) resets the whole terminal: colours, font, cursor settings, and behaves differently per emulator. Clear with \\x1B[2J\\x1B[H.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "concepts": [
+    "tui",
+    "tui-entry"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "pattern": "\\\\x1[bB]c(?![0-9A-Za-z])|\\\\u001[bB]c(?![0-9A-Za-z])|\\\\033c(?![0-9A-Za-z])",
+  "bad": "process.stdout.write('\\x1Bc');",
+  "good": "process.stdout.write('\\x1B[2J\\x1B[H');"
+}

package/packs/tui/checks/tui-resize-listener-removed.json

@@ -0,0 +1,26 @@
+{
+  "id": "tui-resize-listener-removed",
+  "why": "A resize listener that is never removed keeps rendering into a terminal the TUI has left, over the shell prompt. Every process.stdout.on('resize') has its off() on exit.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "concepts": [
+    "tui",
+    "tui-entry"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "process\\.stdout\\.on\\s*\\(\\s*['\\\"]resize['\\\"]",
+  "needs": [
+    "process\\.stdout\\.(?:off|removeListener)\\s*\\(\\s*['\\\"]resize['\\\"]"
+  ],
+  "bad": "process.stdout.on('resize', onResize);",
+  "good": "process.stdout.on('resize', onResize);\nconst exit = () => { process.stdout.off('resize', onResize); };"
+}

package/packs/tui/checks/tui-width-is-state.json

@@ -0,0 +1,33 @@
+{
+  "id": "tui-width-is-state",
+  "why": "A value computed from process.stdout.columns at render time keeps its old width after a resize until the next keypress. In a React/Ink component the width is state updated by the resize handler.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "globs": [
+    "**/*.tsx"
+  ],
+  "concepts": [
+    "tui"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**",
+    "**/bin/**",
+    "**/cli.tsx",
+    "**/index.tsx",
+    "**/main.tsx"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "process\\.stdout\\.columns",
+  "needs": [
+    "\\buseState\\s*\\(",
+    "['\\\"]resize['\\\"]"
+  ],
+  "bad": "const divider = '\\u2500'.repeat(process.stdout.columns ?? 80);",
+  "good": "const [termWidth, setTermWidth] = useState(process.stdout.columns ?? 80);\nuseEffect(() => { const on = () => setTermWidth(process.stdout.columns ?? 80); process.stdout.on('resize', on); return () => { process.stdout.off('resize', on); }; }, []);"
+}

package/packs/tui/pack.json

@@ -0,0 +1,44 @@
+{
+  "name": "tui",
+  "version": "1.0.0",
+  "description": "Terminal UIs (Ink + React or raw-mode Node): alternate screen, resize ordering, width as state, raw mode restored on every exit.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/tui"
+  },
+  "keywords": [
+    "terminal",
+    "tui"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "tui": [
+      "**/tui/**",
+      "**/*tui*",
+      "**/*.tui.*",
+      "**/ui/**/*.tsx",
+      "**/cli/**/*.tsx",
+      "**/ui/browse*",
+      "**/ui/screen*",
+      "**/screens/**"
+    ],
+    "tui-entry": [
+      "**/bin/**",
+      "**/cli.ts",
+      "**/cli.tsx",
+      "**/index.tsx",
+      "**/main.tsx",
+      "**/tui/index.*"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/tui/rules/tui-resize-and-screen.md

@@ -0,0 +1,25 @@
+---
+# concepts: tui, tui-entry
+paths:
+  - "placeholder"
+---
+
+# A TUI owns the alternate screen, clears before the framework draws, and treats size as state
+
+Every resize bug is one root cause: the renderer diffs its previous output and repositions the cursor, it does not clear and redraw. On resize, content it no longer owns stays visible, the cursor lands somewhere unknown, and a taller terminal re-reveals old scrollback lines.
+
+<constraints>
+Always do:
+- **Alternate screen from the entry point**: `process.stdout.write('\x1B[?1049h\x1B[?25l')` before the first render; restore with `'\x1B[?25h\x1B[?1049l'` in a `process.once('exit', …)` handler registered **before** rendering, so the terminal comes back even on a crash (`tui-entry-restores-terminal`).
+- **Clear handler registered in the entry point before `render()`**: `process.stdout.on('resize', () => process.stdout.write('\x1B[2J\x1B[H'))`. Node fires resize listeners in registration order; Ink registers its own inside `render()`, so a clear registered in a `useEffect` runs after Ink has drawn and blanks the screen until the next keypress.
+- **Width is state**: `const [cols, setCols] = useState(process.stdout.columns ?? 80)` in the root component, updated by a resize handler that does nothing else. A divider computed once from `process.stdout.columns` keeps its old width until the next keypress (`tui-width-is-state`).
+- Correct resize order, one job each: 1 entry-point clear, 2 the framework's layout, 3 the state update that re-renders width-dependent lines.
+- Raw-mode TUIs (no framework): gate on `process.stdin.isTTY && process.stdout.isTTY` and a minimum size, fall back to plain output otherwise; `setRawMode(true)` is paired with a restore of the previous raw state; one idempotent `exit()` (an `exited` flag) that removes the resize and data listeners, restores raw mode, shows the cursor and leaves the alternate screen; SIGINT routes through the same `exit()`.
+- Remove every `resize`/`data` listener on exit (`process.stdout.off`, `process.stdin.off`).
+
+Never do:
+- `\x1Bc` (RIS, reset to initial state): it resets colours, font and cursor settings and differs per emulator (`tui-no-ris-reset`). `\x1B[2J\x1B[H` only.
+- Escape codes written from a component's render path; they fight the framework's output buffer. Effects and the entry point only.
+- Resize logic split across several handlers that each clear, draw or set state.
+- A TUI on a non-TTY stdout (CI, a pipe): the escape codes become garbage in the log.
+</constraints>

package/packs/tui/skills/build-tui/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: build-tui
+description: Use when building or changing an interactive terminal UI (Ink + React, or raw-mode Node with @clack/prompts), or when a TUI shows ghost or repeated content, a blank screen after resize, a divider stuck at the old width, or a terminal left in a broken state after exit.
+---
+
+# build-tui
+
+One thing: scaffold or repair a TUI's entry point and root so the `tui-resize-and-screen` rule holds, then prove it with a resize.
+
+<constraints>
+Always do:
+1. Entry point, in this order: TTY and size gate (fallback to plain output when `!isTTY` or under 60×12) → enter alternate screen and hide the cursor → `process.once('exit', restore)` → `process.stdout.on('resize', clear)` → `render()` (Ink) or the raw-mode loop → on exit: `off` every listener, restore raw mode, show cursor, leave the alternate screen. One idempotent `exit()` used by the normal path and SIGINT.
+2. Root component (Ink): `termWidth` as state from `process.stdout.columns`, updated by a resize handler that only sets state; every width-dependent string derives from it.
+3. Raw mode (no framework): `setRawMode(true)` after saving `stdin.isRaw`; a single `data` handler mapping keys through a lookup table (`{ q: quit, j: down, k: up, … }`), never an if-chain; `render(state)` is the only function that writes to stdout.
+4. Prove it: run the TUI in a pty (`node-pty` or `script -q`), send a resize (`SIGWINCH` after changing `columns`/`rows`), and assert the frame has no repeated banner, no stale divider width, and that after quit the terminal is out of the alternate screen (`\x1B[?1049l` was written).
+5. Check versions with `latest-versions` (`ink`, `react`, `@clack/prompts`) before adding them.
+
+Never do:
+- Fix a resize bug by adding another clear somewhere; find which of the three handlers is out of order.
+- Ship without the `process.once('exit', …)` restore.
+</constraints>

package/packs/ui-craft/checks/ui-input-needs-autocomplete.json

@@ -0,0 +1,23 @@
+{
+  "id": "ui-input-needs-autocomplete",
+  "why": "An email, password or phone field with no autocomplete makes everyone type it by hand.",
+  "rule": ".claude/rules/forms-never-fight.md",
+  "concepts": [
+    "ui-markup"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
+  "pattern": "<input\\b(?![^>]*\\bautocomplete)[^>]*\\btype=[\"'{]*(?:email|password|tel)\\b",
+  "bad": "<input type=\"email\" name=\"email\" />\n",
+  "good": "<input type=\"email\" name=\"email\" autoComplete=\"email\" />\n",
+  "flags": "i",
+  "kind": "quality"
+}

package/packs/ui-craft/checks/ui-intl-for-dates.json

@@ -0,0 +1,21 @@
+{
+  "id": "ui-intl-for-dates",
+  "why": "A date built from its parts is wrong for most of the world. Use Intl.DateTimeFormat.",
+  "rule": ".claude/rules/dates-and-numbers.md",
+  "concepts": [
+    "ui-markup"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
+  "pattern": "\\.getMonth\\(\\)\\s*\\+\\s*1\\b",
+  "bad": "const d = `${t.getMonth() + 1}/${t.getDate()}`;\n",
+  "good": "const d = new Intl.DateTimeFormat(locale).format(t);\n"
+}

package/packs/ui-craft/checks/ui-no-ai-palette.json

@@ -0,0 +1,22 @@
+{
+  "id": "ui-no-ai-palette",
+  "why": "Purple and violet gradients are the most recognizable tell of generated UI. Use the project's palette.",
+  "rule": ".claude/rules/no-generated-look.md",
+  "concepts": [
+    "ui-markup",
+    "ui-styles"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
+  "pattern": "\\bfrom-(?:purple|violet|indigo|fuchsia)-\\d+\\b|linear-gradient\\([^)\\n]*\\b(?:purple|violet|indigo)\\b",
+  "bad": "<div className=\"bg-gradient-to-r from-purple-500 to-pink-500\" />\n",
+  "good": "<div className=\"bg-surface text-ink\" />\n"
+}