agents: Split repo guidance into skills

.agents/skills/browser-automation/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: browser-automation
+description:
+  Use when opening, inspecting, clicking, filling, snapshotting, or otherwise
+  automating web pages for this repo, including local dev servers and
+  browser-based verification.
+---
+
+# Browser Automation
+
+Use `agent-browser` for web automation in this repo. Run:
+
+```bash
+agent-browser --help
+```
+
+Core workflow:
+
+```bash
+agent-browser open <url>
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser fill @e2 "text"
+```
+
+Re-run `agent-browser snapshot -i` after page changes so element refs stay
+current.
+
+Use browser automation for behavior that needs a rendered page, real DOM state,
+or interactive verification. Prefer focused Bun tests for pure logic and
+non-browser integration behavior.

.agents/skills/git-commits/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: git-commits
+description:
+  Use when preparing, splitting, reviewing, or creating git commits in this
+  repo, especially after larger implementations that should be broken into
+  independently verified commits.
+---
+
+# Git Commits
+
+## Message Style
+
+Use the following commit message template:
+
+```
+<type>(<scope>): <subject>
+
+<description>
+```
+
+- The <type> can be: agents, chore, ci, docs, feat, fix, perf, refactor, test,
+  tool.
+- The <scope> can be a project, package, or app name; omit the scope and its
+  wrapped parens if none is clear.
+- The <subject> and <description> should explain the motivations and changes.
+- All line lengths must be 72 characters or fewer; hard-wrap to 72 columns
+- Use imperative mood; be concise
+- Include user-provided context when it improves the message
+- Do not include AI attribution in or after the description
+
+## Commit Boundaries
+
+Each commit should be independently understandable and shippable.
+
+- Split unrelated behavior, package areas, generated artifacts, and dependency
+  bumps into separate commits.
+- For larger implementations, commit in vertical slices: tests or fixtures,
+  implementation, docs/examples, and follow-up polish can be separate only when
+  each commit still makes sense on its own.
+- Do not mix mechanical formatting with behavioral changes unless the formatter
+  only touched the files required for that change.
+- Do not include local artifacts from `.agents/ignore/`, `.context/`, logs,
+  build outputs, or editor files.
+- Before committing, inspect staged changes with `git diff --cached` and make
+  sure every staged file belongs to the commit's stated purpose.
+
+If two changes would need different test commands or different reviewers, they
+usually deserve different commits.
+
+## Verification Before Each Commit
+
+Every commit should be verified before it is created.
+
+If the full baseline fails for unrelated pre-existing issues, say that in the
+commit handoff and include the first relevant failure. Do not describe the
+commit as fully verified unless the required commands actually passed.
+
+## Creating Commits
+
+Use non-interactive commands where possible:
+
+```bash
+git status --short
+git diff -- <paths>
+git add <paths>
+git diff --cached
+git commit -m "<message>"
+```
+
+Use a commit body for non-obvious changes:
+
+```bash
+git commit -m "fix(diffs): Fix virtualized scroll focus" -m "Keep focus anchored when rows are recycled during scroll so keyboard navigation does not lose the active item."
+```

.agents/skills/performance/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: performance
+description:
+  Use when changing loops, collection processing, invalidation logic, tree/diff
+  traversal, path scanning, virtualized rendering calculations, or any code
+  where repeated scans or boolean control flow affect performance or
+  correctness.
+---
+
+# Performance
+
+Avoid nested loops and O(n^2) operations unless there is a clear reason.
+
+- Calculate expensive values once before a loop, not inside it.
+- Prefer precomputed maps, sets, indexes, or a single backward scan over nested
+  repeated scans.
+- If you need to know whether meaningful elements remain, compute that boundary
+  once before the main loop.
+
+Example of the preferred pattern:
+
+```typescript
+let lastMeaningfulIndex = items.length - 1;
+for (let i = items.length - 1; i >= 0; i--) {
+  if (items[i].someCondition) {
+    lastMeaningfulIndex = i;
+    break;
+  }
+}
+
+for (let i = 0; i <= lastMeaningfulIndex; i++) {
+  const isLast = i === lastMeaningfulIndex;
+  // ...
+}
+```
+
+After changing boolean logic or invalidation paths, simplify the final control
+flow before calling the work done. If code is already inside `if (foo)`, do not
+keep `|| foo` in assignments inside that block.

.agents/skills/testing-and-verification/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: testing-and-verification
+description:
+  Use when adding or running tests, checking snapshots, choosing between Bun
+  tests and Playwright, running lint/format/typecheck, or deciding the
+  verification scope for a change.
+---
+
+# Testing and Verification
+
+## Baseline Commands
+
+After code changes, run the required baseline from the monorepo root:
+
+```bash
+bun run format
+bun run lint
+```
+
+Useful check/fix pairs also run from the monorepo root:
+
+```bash
+bun run format:check
+bun run format
+bun run lint
+bun run lint:fix
+bun run lint:css
+bun run lint:css:fix
+```
+
+For code changes, also run the relevant package-level typecheck:
+
+```bash
+cd <package-or-app>
+bun run tsc
+```
+
+## Unit and Integration Tests
+
+Use Bun's built-in test runner. Tests usually live in a `test/` folder inside
+each package and use `describe`, `test`, and `expect` from `bun:test`.
+
+Prefer unit or integration tests by default:
+
+```bash
+cd packages/diffs && bun test
+cd packages/trees && bun test
+cd packages/truncate && bun test
+```
+
+Other packages and apps also expose local test scripts when relevant, for
+example `packages/path-store`, `packages/tree-test-data`, and `apps/docs`.
+
+## Snapshots
+
+Bun supports `toMatchSnapshot()`. Avoid new snapshot coverage unless it is
+shallow and narrowly scoped to the exact behavior under test.
+
+Update snapshots from the package directory:
+
+```bash
+bun test -u
+```
+
+## Browser and E2E Tests
+
+Add Playwright/browser E2E tests only when behavior cannot be validated without
+a real browser engine. Good candidates include computed style checks, shadow DOM
+boundaries, and browser-only rendering behavior.
+
+Keep E2E coverage small and high-value:
+
+```bash
+cd packages/trees && bun run coverage
+cd packages/trees && bun run test:e2e
+cd packages/path-store && bun run test:demo
+cd apps/docs && bun run test:e2e
+```
+
+If E2E fixtures or dev servers are started in a worktree, follow the cleanup
+contract from the `worktrees-and-dev-servers` skill.

.agents/skills/tooling-and-dependencies/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: tooling-and-dependencies
+description:
+  Use when running repo scripts, adding or changing dependencies, editing
+  package.json files, installing packages, or deciding how Bun workspace
+  commands should be invoked in this monorepo.
+---
+
+# Tooling and Dependencies
+
+## Bun
+
+- Use `bun` exclusively for commands and package operations.
+- Do not use `npm`, `pnpm`, `npx`, or other package runners unless there is a
+  specific reason and you explain it.
+- Bun can run TypeScript directly, so local scripts may be `.ts` files without a
+  separate compile step.
+
+## Dependency Catalog
+
+This monorepo uses Bun's `workspaces.catalog` in the root `package.json`.
+
+- Never add a version directly to an individual package's `package.json` by
+  default.
+- To add a dependency:
+  1. Add the exact version to the root `package.json` under
+     `workspaces.catalog`, for example `"new-package": "1.2.3"`.
+  2. Reference it from the package with `"new-package": "catalog:"`.
+- Do not run `bun add <package>` inside a package directory; it writes direct
+  versions and breaks the catalog pattern.
+- Published packages may intentionally use ranges for end-user compatibility.
+  `apps/docs` should use catalog versions; published packages such as
+  `packages/diffs` may use ranges only when that is intentional.
+
+## Scripts
+
+- Package scripts should work from the package directory.
+- Common scripts may be mirrored at the root as shortcuts. A root mirror should
+  not behave differently from the package script it wraps.
+- Use the workspace runner when convenient:
+
+```bash
+bun ws <project> <task>
+bun ws <project> <task> --some --flag
+```
+
+`bun ws` forwards arguments to the target script and does not require a
+standalone `--` separator. The only special handling is that `-v` and
+`--verbose` are consumed by `scripts/ws.ts`.

.agents/skills/typescript-monorepo/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: typescript-monorepo
+description:
+  Use when adding or changing packages/apps, TypeScript configs, workspace
+  dependencies, package references, exports, or monorepo project-reference
+  relationships.
+---
+
+# TypeScript Monorepo
+
+## TypeScript
+
+Use TypeScript everywhere practical. Compiler settings are intentionally fairly
+strict.
+
+- Shared compiler options live in `tsconfig.options.json`.
+- Root `tsconfig.json` manages project references across the monorepo.
+- Most package `tsc` scripts use `tsgo`, but agents should run them through the
+  package script: `bun run tsc`.
+
+## Project References
+
+When adding a new package or app:
+
+- Add it to the root `tsconfig.json` references.
+- Ensure its local `tsconfig.json` follows existing package/app patterns.
+
+When one workspace package depends on another:
+
+- Add the dependency as `workspace:*` in the consuming package.
+- Add the dependency to the consuming package's TypeScript `references` block
+  when needed for accurate and fast typechecking.
+
+## Workspace Dependencies
+
+Use the dependency catalog rules from `tooling-and-dependencies` for external
+packages. Use `workspace:*` for internal package dependencies.
+
+If a package is published, review its `exports`, `typesVersions`, `files`, peer
+dependencies, and publish scripts before changing public entrypoints or
+dependency ranges.

.agents/skills/worktrees-and-dev-servers/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: worktrees-and-dev-servers
+description:
+  Use when working with the repo's bun run wt helper, Pierre-managed worktrees,
+  dev-server port offsets, stale server cleanup, Playwright fixtures, or Chrome
+  debug instances. Do not use this as a substitute for host-provided workspace
+  isolation.
+---
+
+# Worktrees and Dev Servers
+
+Pierre includes a repo-specific `git worktree` helper for local/manual
+parallelization outside host-managed agent workspaces. Managed Pierre worktrees
+live at:
+
+```text
+~/pierre/pierre-worktrees/<slug>/
+```
+
+Each managed Pierre worktree owns a port offset so dev servers, E2E fixtures,
+and the Chrome remote-debug instance do not collide. The main clone keeps
+historical default ports; linked Pierre worktrees shift ports.
+
+If you are already inside a Conductor, Codex, Claude, or other host-provided
+workspace, do not create another worktree unless the user explicitly asks for a
+Pierre-managed worktree. Still use this skill when you start repo dev servers or
+E2E fixtures, because the cleanup and port-offset rules apply to those scripts.
+
+## Worktree Commands
+
+The `bun run wt` suite is defined in `scripts/wt.ts` and manages only
+Pierre-managed worktrees:
+
+```bash
+bun run wt new <slug>    # create a worktree, allocate offset, bun install
+bun run wt rm <slug>     # kill its processes, remove the worktree
+bun run wt clean         # kill zombie servers on all managed worktree ports
+bun run wt clean <slug>  # clean one managed worktree
+bun run wt ps            # show per-worktree port status (LISTEN / -)
+bun run wt list          # summary of managed + external worktrees
+```
+
+Dev scripts pick up the offset through `scripts/ws.ts`, which reads
+`<worktree>/.env.worktree`. Before starting, they run `scripts/run-dev.sh` to
+kill any stale process bound to the target port.
+
+## Cleanup Contract
+
+If you start dev servers, Playwright fixtures, or Chrome debug instances inside
+a worktree, run cleanup before completing your turn:
+
+```bash
+bun run wt clean <slug>
+```
+
+Use `bun run wt clean` when you do not know the slug or need to clean every
+managed worktree. Use `bun run wt rm <slug>` only when intentionally tearing
+down the worktree itself.

.gitignore

@@ -30,6 +30,7 @@ tsconfig.tsbuildinfo
 .claude/*
 .codemogger/*
 .omx/
+.agents/ignore/
 .env.worktree
 
 #tmp