@baselane/packs 0.1.0

package/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 4: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 4 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Detached HEAD — present exactly these 3 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 5: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
+```
+
+Then: Cleanup worktree (Step 6), then delete branch:
+
+```bash
+git branch -d <feature-branch>
+```
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+```
+
+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then: Cleanup worktree (Step 6), then force-delete branch:
+```bash
+git branch -D <feature-branch>
+```
+
+### Step 6: Cleanup Workspace
+
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| 4. Discard | - | - | - | yes (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" is ambiguous
+- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+
+**Cleaning up worktree for Option 2**
+- **Problem:** Remove worktree user needs for PR iteration
+- **Fix:** Only cleanup for Options 1 and 4
+
+**Deleting branch before removing worktree**
+- **Problem:** `git branch -d` fails because worktree still references the branch
+- **Fix:** Merge first, remove worktree, then delete branch
+
+**Running git worktree remove from inside the worktree**
+- **Problem:** Command fails silently when CWD is inside the worktree being removed
+- **Fix:** Always `cd` to main repo root before `git worktree remove`
+
+**Cleaning up harness-owned worktrees**
+- **Problem:** Removing a worktree the harness created causes phantom state
+- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+- Remove a worktree before confirming merge success
+- Clean up worktrees you didn't create (provenance check)
+- Run `git worktree remove` from inside the worktree
+
+**Always:**
+- Verify tests before offering options
+- Detect environment before presenting menu
+- Present exactly 4 options (or 3 for detached HEAD)
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+- `cd` to main repo root before worktree removal
+- Run `git worktree prune` after removal

package/skills/first-party/README.md

@@ -0,0 +1,32 @@
+# First-party skills
+
+Baselane-authored skills, distributed alongside the imported third-party seed catalog.
+
+Unlike the rest of `skills/` — which `scripts/import-skills.ts` fetches from upstream repos and
+**wipes and rebuilds on every re-import** — everything under this `first-party/` directory is
+hand-authored and version-controlled here. `resetFetchedArea()` in the import script preserves this
+subtree, so re-running the fetch never clobbers it.
+
+## Layout
+
+```
+first-party/
+  manifest.json          # [{ name, category }] — the skills to load, in catalog order
+  <skill-name>/SKILL.md  # one dir per skill; standard agentskills.io SKILL.md (frontmatter + body)
+```
+
+## Conventions
+
+- **No `attribution`.** First-party skills are ours; they carry no third-party licence notice and no
+  `LICENSE` file. `loadSeedSkills` tags them `source: "baselane"` (`FIRST_PARTY_SOURCE`), which drives
+  the catalog's first-party/third-party filter.
+- **Must pass `validateSkill`** — slug name, single-line description (≤1024 chars), body ≤500 lines.
+- **`category`** is one of the phase slugs (`plan` / `write` / `debug` / `review` / `ship`) or any
+  custom org category; it is baselane-side taxonomy and is never written into SKILL.md frontmatter.
+
+## Adding a skill
+
+1. Create `first-party/<name>/SKILL.md`.
+2. Add `{ "name": "<name>", "category": "<phase>" }` to `manifest.json`.
+3. `loadSeedSkills()` picks it up automatically — it becomes catalog-visible, importable, and
+   overlap-detectable with no further wiring.

package/skills/first-party/append-only-jsonl-stores/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: append-only-jsonl-stores
+description: Use when building a simple durable store without a database — persist each change as a new JSON line appended to a .jsonl file, fold latest-record-per-id on read, and never rewrite a line in place.
+---
+
+# Append-only JSONL stores
+
+For modest persistence needs, a database is often overkill. An append-only JSON-Lines file — one
+JSON object per line — gives you durable, debuggable, dependency-free storage. **Updating a record
+means appending a new line with the changed fields; you never rewrite or delete an existing line.**
+
+## The pattern
+
+- **Write:** serialize the record to one line, `appendFile` it. Never open-truncate-rewrite.
+- **Read:** stream the file top to bottom, `JSON.parse` each line, and **fold latest-record-per-id
+  wins** — a later line for the same id supersedes the earlier one.
+- **Delete:** append a tombstone (e.g. `{ id, deleted: true }`); the fold treats it as "gone."
+- **Malformed line:** skip it and keep going. A half-written trailing line from a crash must not
+  break every future read.
+
+```ts
+// update = append a new line, not mutate the old one
+await appendFile(path, JSON.stringify({ id, ...changes }) + "\n");
+
+// read = fold latest-per-id
+const byId = new Map();
+for (const line of (await readFile(path, "utf8")).split("\n")) {
+  if (!line.trim()) continue;
+  try { const r = JSON.parse(line); byId.set(r.id, r); } catch { /* skip malformed */ }
+}
+```
+
+## Why append-only
+
+- **Crash-safe writes.** Appending never corrupts existing data; the worst case is one torn trailing
+  line, which the reader skips.
+- **Free audit history.** Every version of every record is still on disk, in order — invaluable for
+  debugging "how did this get into that state?".
+- **Immutability by construction.** Records are never mutated in place, so a reader mid-fold can
+  never observe a half-updated record.
+
+## Trade-offs and remedies
+
+- **File grows unbounded.** Periodically **compact**: read, fold to latest-per-id, and rewrite a
+  fresh file atomically (write to a temp path, then rename). Compaction is the *only* time you
+  rewrite — and it produces a new file rather than editing lines.
+- **Whole-file read on load.** Fine up to tens of thousands of records; past that, reach for a real
+  database. This pattern is for the small-to-medium tier, not for high write throughput.
+- **No cross-record transactions.** If you need multi-record atomicity or rich queries, this is the
+  wrong tool.

package/skills/first-party/golden-snapshot-discipline/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: golden-snapshot-discipline
+description: Use when a code path has committed golden/snapshot output — treat a snapshot diff as a signal, review it before regenerating, and update the golden only when the change in output is intentional.
+---
+
+# Golden snapshot discipline
+
+A golden snapshot is committed expected output — rendered files, serialized structures, generated
+text — that a test compares byte-for-byte against what the code produces now. Its whole value is
+that **an unintended change to output shows up as a failing diff.** Regenerating snapshots
+reflexively to make the test pass throws that value away.
+
+## The rule
+
+- **A snapshot diff is a question, not a chore.** When a golden test fails, read the diff first. Did
+  *this* change intend to alter that output?
+- **Intended change → update the golden in the same commit,** so the diff is reviewable alongside the
+  code that caused it. The reviewer sees both the cause and the effect.
+- **Unintended change → you found a bug.** Fix the code; do not update the golden. The snapshot just
+  did its job.
+- **Never regenerate blindly.** `--update`-ing every snapshot to get green is how a real regression
+  silently becomes the new "expected."
+
+## Workflow
+
+```
+1. Run the tests → a golden fails.
+2. Read the diff. Is every changed byte something this change was supposed to do?
+   - YES → regenerate the golden, commit code + golden together, call out the output change.
+   - NO  → stop. The code is wrong. Fix it; the golden stays.
+```
+
+## Why this matters
+
+- **Catches action-at-a-distance.** A refactor "far away" from the output path that nonetheless
+  shifts a byte is exactly what goldens exist to surface.
+- **Makes output changes explicit and reviewed.** A golden update in a diff is a visible,
+  human-approved statement: "yes, the output changed, on purpose, this way."
+
+## Authoring goldens that stay useful
+
+- Keep them **deterministic** — sort keys, pin timestamps/versions/random seeds, normalize line
+  endings — so a passing test means "output is correct," not "output happened to match today."
+- Keep them **readable** — a golden a human can eyeball makes review of its diffs meaningful.
+- Scope them tightly — one golden per unit of output, so a failure points at what changed.

package/skills/first-party/immutable-updates/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: immutable-updates
+description: Use when updating objects, arrays, or records in application code — return a new copy with the change applied instead of mutating the original in place, to prevent hidden side effects and aliasing bugs.
+---
+
+# Immutable updates
+
+When you change a value, **produce a new copy — never mutate the argument you were handed.** Shared
+references mean an in-place mutation is a spooky-action-at-a-distance bug: some other holder of the
+same object sees a change it never asked for.
+
+```ts
+// WRONG — mutates the caller's object
+function rename(user, name) {
+  user.name = name;
+  return user;
+}
+
+// CORRECT — returns a new object, original untouched
+function rename(user, name) {
+  return { ...user, name };
+}
+```
+
+## Patterns
+
+- **Object field:** `{ ...obj, field: value }`.
+- **Nested field:** spread each level you touch — `{ ...obj, addr: { ...obj.addr, city } }`.
+- **Array append/remove:** `[...list, item]`, `list.filter(x => x.id !== id)`,
+  `list.map(x => x.id === id ? { ...x, done: true } : x)` — not `push`/`splice`/index assignment.
+- **Record update:** `{ ...map, [key]: value }` and `const { [key]: _drop, ...rest } = map` to remove.
+
+## Why it pays off
+
+- **No hidden side effects.** A function that returns a new value can't corrupt state its caller
+  still depends on. Behavior is a function of inputs, not of call order.
+- **Debugging is local.** When a value is wrong, the mutation that produced it is the expression
+  that built it — not some distant `.sort()` or field write on a shared reference.
+- **Safe concurrency and change-detection.** Referential equality (`prev !== next`) becomes a
+  reliable "did this change?" signal for caches, memoization, and UI diffing.
+
+## When in-place is acceptable
+
+A locally-scoped object that never escapes the function — a builder/accumulator you allocated and
+return once — is fine to mutate. The rule protects values that are *shared*: arguments, fields on
+long-lived state, anything another holder still references.

package/skills/first-party/manifest.json

@@ -0,0 +1,10 @@
+{
+  "skills": [
+    { "name": "ts-extension-imports", "category": "write" },
+    { "name": "immutable-updates", "category": "write" },
+    { "name": "append-only-jsonl-stores", "category": "write" },
+    { "name": "zero-dependency-discipline", "category": "review" },
+    { "name": "golden-snapshot-discipline", "category": "review" },
+    { "name": "validate-at-boundaries", "category": "review" }
+  ]
+}

package/skills/first-party/ts-extension-imports/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ts-extension-imports
+description: Use when writing or editing TypeScript in a no-build ESM repo that runs .ts sources directly under Node — every relative import must carry an explicit .ts extension, or Node's resolver fails to find the file at runtime.
+---
+
+# TypeScript `.ts`-extension imports
+
+Some TypeScript projects have **no build step**: packages are consumed directly as `.ts` sources
+over ESM, run by Node (≥24) with `--experimental-transform-types` semantics. There is no transpile
+pass and no emitted `.js`. In that setup one rule is load-bearing:
+
+**Every relative import must carry its explicit `.ts` extension.**
+
+```ts
+// CORRECT — the path resolves to a file that exists on disk
+import { validatePack } from "./validate.ts";
+import type { WorkflowPack } from "../types.ts";
+
+// WRONG — extensionless: works with a bundler, but Node's ESM resolver won't guess ".ts"
+import { validatePack } from "./validate";
+
+// WRONG — ".js": there is no emitted .js in this tree, so this points at nothing
+import { validatePack } from "./validate.js";
+```
+
+## Why
+
+- Node's ESM loader resolves the specifier you write, **verbatim**. It does not try appending
+  extensions the way a bundler does. An extensionless or `.js` specifier names a file that isn't
+  on disk, and the import throws `ERR_MODULE_NOT_FOUND` at runtime — not at build time, because
+  there is no build.
+- The extension is part of the module's identity here, not decoration.
+
+## What this rule does **not** change
+
+- **Bare package specifiers stay bare.** `import { readFile } from "node:fs/promises"` and
+  `import { x } from "@scope/pkg"` have no extension — the rule is about *relative* paths (`./`,
+  `../`) only.
+- **Type-only imports still need it.** `import type { Foo } from "./foo.ts"`. The extension names
+  the file on disk; whether the import is erased at runtime is irrelevant to resolution.
+- **Directory index imports.** Prefer naming the file explicitly (`./index.ts`) rather than relying
+  on directory resolution, which ESM does not do without a package boundary.
+
+## Before you save
+
+- [ ] Every `from "./…"` / `from "../…"` ends in `.ts`.
+- [ ] No `.js` extension in any relative import (there is no `.js` in this source tree).
+- [ ] `node:*` and package specifiers left extensionless.
+- [ ] Dynamic `import("./x.ts")` and re-exports (`export { y } from "./y.ts"`) carry `.ts` too.

package/skills/first-party/validate-at-boundaries/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: validate-at-boundaries
+description: Use when code receives data from outside its own module — user input, API responses, file contents, env vars, message payloads — validate it against a schema at the boundary and fail fast, so untrusted shapes never propagate inward.
+---
+
+# Validate at boundaries
+
+Every place external data enters your system is a boundary: an HTTP handler, a file read, an API
+response, an environment variable, a queue message. **Validate at the boundary, before the data
+reaches any logic that assumes it is well-formed.** Inside the boundary, the value is trusted because
+you already checked it — not because you hope it is right.
+
+```ts
+// At the boundary: parse into a known shape, or reject.
+const parsed = OrderSchema.parse(await req.json()); // throws on bad shape
+createOrder(parsed);                                 // inner code trusts `parsed`
+```
+
+## Rules
+
+- **One validator is the authority for each shape.** Route every entry point for that shape through
+  it — built-in, user-supplied, or machine-generated. Never hand-construct or trust an unvalidated
+  object further in.
+- **Fail fast, name the field.** Reject the whole input on the first violation with a message that
+  says which field was wrong and why. A vague "invalid input" costs the caller a debugging session.
+- **Parse, don't just check.** Return a typed value from validation so downstream code carries the
+  guarantee in its types, not just in a comment.
+- **Never trust "internal" data blindly.** An API response or a sibling service's payload is external
+  to your module even if it's inside your company — validate it the same way.
+
+## Why
+
+Unvalidated data that flows inward turns a boundary problem into a deep-stack mystery: the crash
+happens three layers down, far from the malformed input that caused it. Validation at the edge keeps
+the failure where the bad data actually entered, where the error message can still be specific.
+
+## Boundaries to cover
+
+HTTP request bodies and query params · file and config contents · third-party API responses ·
+environment variables (validate presence and format at startup) · deserialized messages/events ·
+anything read from a store you did not just write in the same transaction.

package/skills/first-party/zero-dependency-discipline/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: zero-dependency-discipline
+description: Use when tempted to add a third-party package — first check for a zero-dependency way using the platform and existing code, because most "we need a library" moments are solvable with a few lines and no new supply-chain risk.
+---
+
+# Zero-dependency discipline
+
+Before adding any third-party dependency, **prove you need it.** A new package is permanent
+surface area: supply-chain risk, version churn, transitive bloat, and one more thing to audit. The
+default answer to "should we pull in a library for this?" is "probably not — check first."
+
+## The check, in order
+
+1. **Does the platform already do it?** Modern runtimes ship a lot: `fetch`, `crypto`,
+   `structuredClone`, `Intl`, `URL`, streams, `node:*` modules. Reach here first.
+2. **Do we already have it?** A helper, an existing dependency that covers the case, or a pattern
+   elsewhere in the codebase you can follow.
+3. **Is it a few lines to write ourselves?** A slug function, a debounce, a small parser, an
+   env-var reader — vendoring 20 lines you understand beats importing 2,000 you don't.
+4. **Only if all three fail:** consider a dependency — and then weigh maintenance, license, size,
+   and transitive count before committing.
+
+## Worked example
+
+An HTTP API integration does **not** require the vendor's SDK. Global `fetch` plus the documented
+REST endpoints is usually the whole job — no SDK, no auth-helper package, no version-pinning dance.
+The same holds for most "convenience" wrappers around things the platform already exposes.
+
+## Why the bar is high
+
+- **Supply chain.** Every dependency (and its transitive tree) is code you now run and must trust.
+- **Longevity.** Zero-dep code doesn't break when an upstream maintainer ships a breaking major or
+  abandons the package.
+- **Clarity.** Code you wrote is code you can read, debug, and change. A black-box import is not.
+
+## When a dependency IS the right call
+
+Genuinely hard, well-specified, security-sensitive problems — cryptography primitives, timezone
+databases, complex parsers/compilers — are where a mature, audited library beats rolling your own.
+The discipline is not "never add deps"; it's "don't add one until the platform, the codebase, and a
+few honest lines have each failed to cover it."