Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,12 @@ references/ deep docs, loaded on demand by the workflow
maps.md map component policy
terminal-data.md search/JSON/pipeline discipline
agent-ops.md parallel dispatch, worktrees, remote machines
t3code.md T3 Code orchestration surface and usage guide
ship-verify.md deploy-and-verify discipline
go-dbtest.md DB-backed Go test recipe
release-train.md release mechanics conventions
upstream-port-sweep.md fork sync loop
handoff.md session-close handoff convention
setup.sh personalization generator
SETUP.md agent playbook (the recommended flow)
customize.example.yml answer-file template
Expand Down
14 changes: 9 additions & 5 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,13 @@ Persistent memory lives in a dedicated git repo following the [Agent Memory Repo
3. Read `references/toolchain.md` before adding, changing, or configuring lint/format/test/CI tooling.
4. Read `references/maps.md` for any map/location/geospatial UI.
5. Read `references/terminal-data.md` for search, JSON, pipelines.
6. Read `references/agent-ops.md` before dispatching parallel agents, worktree lanes, or remote-machine work.
7. Invoke `ponytail` (default `full`) on every response — shortest working diff, stdlib first, no speculative abstractions. Mark shortcuts `// ponytail: <ceiling>, <upgrade path>`.
8. Ship production-grade output: small modules, typed APIs, a11y, responsive, Docker-runnable.
9. After meaningful changes: add concise inline comments (what/why/dependencies) and commit on a feature branch with a structured message. Open a PR - never push to `main` directly (see Pull Request Workflow).
6. Read `references/agent-ops.md` before dispatching parallel agents, worktree lanes, or remote-machine work. Read `references/t3code.md` for the full T3 Code surface (CLI, MCP tools, providers, scheduling, PR watch, limits).
7. Read `references/ship-verify.md` before deploying, verifying a release, or claiming something is live — clean-worktree deploys, verify the artifact not the stamp, process-leak sweep.
8. Read `references/go-dbtest.md` before writing or running DB-backed Go tests (build-tag gating, isolated per-lane DBs, driver gotchas).
9. Read `references/release-train.md` before tagging or releasing; `references/upstream-port-sweep.md` before syncing a fork with upstream; `references/handoff.md` before reporting done on multi-session work.
10. Invoke `ponytail` (default `full`) on every response — shortest working diff, stdlib first, no speculative abstractions. Mark shortcuts `// ponytail: <ceiling>, <upgrade path>`.
11. Ship production-grade output: small modules, typed APIs, a11y, responsive, Docker-runnable.
12. After meaningful changes: add concise inline comments (what/why/dependencies) and commit on a feature branch with a structured message. Open a PR - never push to `main` directly (see Pull Request Workflow).

## Stack (locked — do not change without user approval)

Expand All @@ -53,8 +56,9 @@ Persistent memory lives in a dedicated git repo following the [Agent Memory Repo
| Browser (live session) | **browser-harness** — CDP control of the real logged-in Chrome; reaches auth-walled flows Playwright's clean profile can't | — |
| Task runner | **just** — `justfile` at repo root | `cli-developer` |
| Worktrees | **worktrunk (`wt`)** — git worktree lifecycle for parallel agent work: `wt switch -c <branch>` create+enter, `wt merge`, `wt remove`, `wt list` (status/CI), `wt switch pr:<n>`; project hooks automate `npm install`/env copy on create. Installed via linuxbrew; shell integration via `wt config shell install` | — |
| Agent orchestration | **t3code (`t3`)** — dispatch parallel agent threads in isolated worktrees: `t3 thread start <project> --worktree <ref> --branch <n> --wait --json`; remote machines via `t3 environment link`. Routing table: `references/agent-ops.md` | — |
| Agent orchestration | **t3code (`t3`)** — dispatch parallel agent threads in isolated worktrees: `t3 thread start <project> --worktree <ref> --branch <n> --wait --json`; remote machines via `t3 environment link`. Routing table: `references/agent-ops.md`; full surface + guide: `references/t3code.md` | — |
| CI (local) | **act** — run GitHub Actions locally pre-push (`act -j <job>`); **actionlint** — workflow YAML lint; `shellcheck` — shell script lint. `ciwatch` covers the remote side | — |
| CI (self-hosted) | **KERN** (https://github.com/Dvorinka/kern) — GH Actions-compatible runner fleet; workflows run unmodified, `kern` CLI + MCP endpoint for agents; see `references/toolchain.md` | — |
| HTTP debugging | **mitmproxy** (`mitmdump` headless) — capture/replay API traffic when the bug is on the wire | — |
| Agent telemetry | **agenttrace** — session cost/token/duration reports, `--baseline` delta gating | — |
| MCP servers | Whatever your harness wires — git, github, plus service MCPs (DB, files, deploys). Always `mcp_list_tools` before calling | — |
Expand Down
47 changes: 47 additions & 0 deletions references/go-dbtest.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Go DB tests

The DB-backed test pattern for Go projects. Read before writing or running
tests that need a real database.

## Recipe

- Run a throwaway Postgres in docker on a non-default port; credentials in
the compose file, never production.
- Gate tests behind a build tag (e.g. `-tags=dbtest`) and a DSN env var
(`DATABASE_URL_TEST=postgres://…`). The tag keeps `go test ./…` fast and
safe without a database.
- Create **per-feature-lane databases** — a shared test DB accumulates
cross-lane pollution: leaked triggers, fixed-email fixtures, orphaned
rows that fail unrelated tests.
- Keep heavyweight real-data tests (full production-shape imports) behind
their own name and skip them in quick runs (`-skip 'TestLiveDB…'`) —
minutes-long fixtures belong to CI or dedicated runs.
- Gated env vars belong in a committed `.envrc` (direnv) or a task-runner
recipe — never "the agent happened to export it".
- Open the pool once per suite (a `livePool()` helper), not per test.
- A small `/tmp` tmpfs breaks cgo test builds — `TMPDIR`/`GOTMPDIR` to a
disk-backed dir first.

## Driver gotchas worth remembering

- `[]byte` params encode as `bytea` — inserting into `jsonb` fails. Send
`string` and let the driver marshal text.
- A `$N` placeholder pinned to a type by an INSERT column list breaks
`nullif($N,'')` used in a later clause — split into separate params.
- Correlated subqueries need the outer table alias — a wrong alias
silently aggregates the whole table instead of one row's children.
- Long tests inside a serialization lock (advisory lock, sequence row)
starve every other writer — keep lock scope short or skip the lock in
fixture-heavy tests.

## Migration discipline

- Parallel branches collide on sequential migration numbers — check open
branches before claiming a number; renumber at merge if two lanes took
the same one.
- A prod DB can contain a manually applied `if not exists` patch without
the version row — verify the object exists instead of re-applying.
- FK hardening order: `ADD CONSTRAINT … NOT VALID` → clean orphans →
`VALIDATE CONSTRAINT`.
- New indexes ship with `EXPLAIN (ANALYZE)` evidence on production-shaped
data — a seq scan on a tiny table is the correct plan, not a regression.
31 changes: 31 additions & 0 deletions references/handoff.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Handoff

Session-close convention. Read before reporting "done" on any multi-session
project.

## What gets written

- **Handoff doc** — `HANDOFF.md` at repo root (work queues) or
`docs/<area>/handoff-<date>.md` (feature closeouts). Contents:
- shipped: commits, PR numbers, deployed SHAs, schema/migration version
- pending: ordered queue, each item with the smallest pointer that
resumes it (issue id, file, failing test)
- gotchas learned this session that cost time
- env state: which deploys are live, which migrations applied manually,
which env vars are set where
- blocked-on-user: decisions only the user can make, stated explicitly
- **Mail/report draft** — when the work has a stakeholder awaiting an
answer, draft it to a file. Draft, never send.
- **Memory closeout** — durable one-line facts to the memory repo if the
project uses one; the handoff doc is the long form, memory is the index.

## Rules

- Write the handoff **before** the final summary — the summary links the
file.
- A handoff is resumption-complete: a cold agent should continue without
re-reading chat history. Test: could you resume this in 3 weeks?
- Open items stay open in text — mark `[added]`, `[pending]`, `[blocked]`
rather than deleting lines that are still true.
- `git fetch` before claiming a bug is real — a parallel session may have
landed it already.
34 changes: 34 additions & 0 deletions references/release-train.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Release train

Release-mechanics conventions. Read before tagging, releasing, or
publishing artifacts. Each repo encodes its flow differently — document
the repo's flow once and follow it verbatim; do not generalize between
repos.

## What to pin down per repo

- **The version source of truth** — a single constant/file that the
release workflow reads (`Version` constant, `versionName`/`versionCode`,
`package.json`). Bump it in the release commit, never ad-hoc at tag
time.
- **Tag semantics** — if one repo ships multiple artifacts
(server/desktop/mobile), decide what `v*` tags cover and use
platform-scoped tags (`android-v*`, `desktop-v*`) for single-platform
releases. Annotate them.
- **The trigger** — tag push vs release PR merge vs manual deploy script.
Write it down; "how do I ship this repo" should be a one-line answer.
- **Changelog discipline** — release notes/CHANGELOG entries land in the
release commit, not after. A changelog is the audit trail; backfill
rather than leave gaps.
- **Lockfiles** — committed lockfiles for every ecosystem the release
builds (Rust, JS, Go modules); a gitignored lockfile means deps float on
every CI run and releases are not reproducible.

## Self-updating artifacts

- When a fleet pulls a signed update manifest from release assets, the
release must publish **manifest + signature** — a release that ships the
image but not the manifest leaves every install behind silently.
- Version-stamp the built artifact at build time (`--build-arg
VERSION=…`); an unstamped "dev" build can neither self-update nor be
distinguished from a release in the field.
65 changes: 65 additions & 0 deletions references/ship-verify.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Ship & Verify

Deploy-and-verify discipline. Read before any deploy, release verification,
or "it's live" claim. The recurring failure mode: **trusting a stamp
instead of the artifact**.

## Ground rules

- A version stamp is not ground truth. Env-var version labels, image tags,
and deploy dashboards all lie when a build reused an old snapshot.
Verify by checking **served artifacts** — grep served JS chunks for a
feature string, run the binary's `--version`, read `activeDeployments`
from the platform API — never the label.
- Deploy from a **clean worktree at the target sha**. Deploy CLIs snapshot
the working tree; a dirty checkout ships someone else's uncommitted
work.
- A successful "queued"/"building" response proves nothing. Follow the
deployment to `SUCCESS`, then verify the artifact.
- After agent-driven sessions, sweep for leaked processes
(`ss -tlnp` / `lsof -i`) — spawned workers and verify stacks leak dev
servers and API processes. Kill strays before reporting done.

## Platform pitfalls (seen in production)

- Upload-context bugs: running a deploy CLI from the repo root uploads the
wrong context — run it from the service directory or the repo's deploy
script.
- "Bare" subcommands mutate: `… domain` may **create** a domain where you
expected a list; prefer the explicit `… list` form.
- Env vars set via the platform CLI sit **staged** — they bake into the
build only on the next deploy. Always redeploy after changing them.
- Services may not auto-deploy on merge to main — know which of yours do,
and deploy the web SPA explicitly; an API-only deploy leaves the SPA
stale.
- A smoke probe that accepts *any* version label can pass on the previous
build — verify the label yourself.
- Stuck initializing deploys can hold the build slot; cancel them through
the platform's API when the UI won't.
- Deploy builds that queue and build server-side make the local follow
command time out — poll the deployment list instead.

## Local verify stacks

- Dev servers started for verification die with the parent shell — run
them detached (`setsid nohup …`).
- Off-loopback browser automation cannot reach `localhost` — bind the dev
server to `0.0.0.0` and use the LAN IP.
- Auth-walled APIs behind a clean-profile browser: run a localhost shim
that injects `Authorization: Bearer <token>` rather than fighting CORS,
cookies, or TLS to the real backend.
- `BrowserRouter` is not hash routing — deep-link `/route/:id`, not `#/`.

## Build environment

- A small `/tmp` tmpfs breaks cgo and linkers (`disk quota exceeded`) —
point `TMPDIR`/`GOTMPDIR` at a disk-backed dir before Go builds or push
hooks that compile.
- Push hooks needing repo `node_modules` fail in fresh git worktrees —
push from the main checkout or install in the worktree first.

## UI verification gate

- UI-visible changes are not done without a screenshot at phone (~390px)
and desktop (~1440px) widths. Zero horizontal overflow is the pass bar
for layout sweeps.
Loading
Loading