From a94c57221277c07c0558e0cff86749d79eec5f09 Mon Sep 17 00:00:00 2001 From: Tomas Dvorak Date: Thu, 5 Nov 2026 21:32:07 +0100 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20add=20references/t3code.md=20?= =?UTF-8?q?=E2=80=94=20full=20T3=20Code=20capability=20map=20and=20usage?= =?UTF-8?q?=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers the t3 CLI surface, the t3-code MCP toolset (preview browser, delegation, thread control plane, scheduling, environments, PR watch, devices, secrets), provider discovery, recipes, and known limits. SKILL.md workflow step 6 and the orchestration stack row now point at it. Authored By: TDvorak --- SKILL.md | 4 +- references/t3code.md | 167 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 references/t3code.md diff --git a/SKILL.md b/SKILL.md index b9c5175..8460925 100644 --- a/SKILL.md +++ b/SKILL.md @@ -26,7 +26,7 @@ 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. +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. Invoke `ponytail` (default `full`) on every response — shortest working diff, stdlib first, no speculative abstractions. Mark shortcuts `// ponytail: , `. 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). @@ -53,7 +53,7 @@ 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 ` create+enter, `wt merge`, `wt remove`, `wt list` (status/CI), `wt switch pr:`; 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 --worktree --branch --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 --worktree --branch --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 `); **actionlint** — workflow YAML lint; `shellcheck` — shell script lint. `ciwatch` covers the remote side | — | | 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 | — | diff --git a/references/t3code.md b/references/t3code.md new file mode 100644 index 0000000..5e62645 --- /dev/null +++ b/references/t3code.md @@ -0,0 +1,167 @@ +# T3 Code — capability map and usage guide + +Read before orchestrating threads, delegating agents, using the preview browser, scheduling work, or touching remote environments. Companion to `agent-ops.md` (dispatch decisions); this file is the full surface. + +Surface verified against `t3` CLI + the `t3-code` MCP server on 2026-11-05. T3 Code moves fast — re-check `t3 --help` and `mcp_list_tools` when something looks off. + +## What T3 Code is + +One server (data dir `~/.t3/userdata`, lock `server-owner.sqlite` — only one process may own it) fronting many agent providers. Surfaces: + +- **Desktop/web app** — the UI. `t3 app [path]` opens a project in it. +- **`t3` CLI** — headless control of the same server. Everything emits `--json` where it matters; stable exit codes. +- **`t3-code` MCP server** — the same capabilities exposed to an in-session agent as tools. +- **Vendored tools** under `~/.t3/tools/` (provider binaries, device hubs, `cloudflared`, headless Chrome for previews). +- **Scratch + worktrees**: per-thread scratch under `~/.t3/scratch/`; managed worktrees under `~/.t3/worktrees//`. + +Rule of thumb: **CLI for dispatch-and-forget lanes and scripting; MCP for in-session orchestration** (delegate, read back, steer, watch PRs) where the parent agent stays in the loop. + +## CLI surface + +### Run / serve + +| Command | What it does | +|---|---| +| `t3` / `t3 serve [cwd]` | Run the server in this terminal and open the browser. Flags: `--mode web|desktop`, `--port`, `--host`, `--lan`, `--tailscale-serve`, `--dev-url`, `--auto-bootstrap-project-from-cwd`. | +| `t3 app [path]` | Open a project in the running desktop app. | +| `t3 status [--json]` | Service install state + remote access settings (Connect, LAN). | +| `t3 up` | One-shot remote access + background service setup. `--connect` (T3 Connect via account), `--lan`, `--headless`, `--yes`. `t3 connect` is the same as `up --connect`. | +| `t3 service install|restart|uninstall|status|protect` | Background service. `protect` shields the server from agents under memory pressure. | + +### Auth / pairing / remote clients + +- `t3 pair [--scope ...] [--ttl 1h] [--tailscale]` — mint a pairing token, prints QR. **The default scope set is broad (all scopes)** — always pass `--scope` explicitly for least privilege. Scopes cover: `orchestration:read|operate`, `settings:write`, `providers:manage`, `environment:maintain`, `preview:operate`, `diagnostics:read`, `terminal:read|operate`, `source-control:write`, `filesystem:read|write`, `relay:read|write`, `access:read|write`. +- `t3 auth pairing create|list|revoke` and `t3 auth session issue|list|revoke` — one-time pairing tokens and scoped bearer sessions for headless/remote clients (`issue --token-only --json` for scripting). +- `t3 environment link --pairing-code [--access read-only|approval-required|auto-accept-edits|auto|full-access]` — link another machine's T3 server; `list`, `unlink` to manage. Agents here can then run threads there. + +### Projects + +- `t3 project add [--title]` — register a repo. Register each repo individually; parent dirs are not projects. +- `t3 project remove|rename`, plus MCP `t3_project_create|read|update|delete|clone` for scripts/default model/icons/pinned/archived. +- Project `scripts` (set via `t3_project_create/update`) run on worktree create / settle — the T3 equivalent of worktrunk hooks (`npm install`, env copy, `runOnWorktreeCreate`, `previewUrl` + `autoOpenPreview`). + +### Threads (the workhorse) + +``` +t3 thread start [--title] [--provider P --model M] + [--worktree ] [--branch ] [--wait] [--json] +t3 thread list [--project ] [--json] +t3 thread show [--messages N] [--json] +t3 thread send [--wait] [--json] +``` + +- `--worktree` accepts a branch, tag, or commit; `--branch` names the new branch. Worktree lands in `~/.t3/worktrees//`. +- `--wait` blocks for the reply; **exit 1 = run failed, exit 2 = waiting on an answer** (a question/approval card is up — answer it in the app or via MCP `t3_pending_request`). +- `send` to a busy thread queues the message as its next turn; nothing is interrupted. `-` reads the message from stdin. +- No `--worktree` on `send`/`show` — only `start` creates worktrees. + +### Ops / diagnostics + +| Command | Purpose | +|---|---| +| `t3 doctor [--fix] [--dry-run]` | Inspect/repair the data dir; restarts the service as needed. | +| `t3 trace summary` | Summarize the server trace file: counts, rates, latency. | +| `t3 triage [--agent claude\|codex]` | Have claude/codex investigate a T3 problem and draft an issue. | +| `t3 policy show\|check\|templates` | Inspect/validate the admin managed policy; emit Win/macOS templates. | +| `t3 theme set\|show\|clear` | Environment-wide theme defaults pushed to clients. | +| `t3 browser setup` | Prepare a Linux host for the headless preview browser (Chrome sandbox, libs, fonts). | +| `t3 update [version] [--channel stable\|nightly\|preview]` / `t3 uninstall` | Self-update / remove (projects and threads kept). | + +## MCP surface (`t3-code`) + +### Preview browser — `preview_*` + +In-app browser pane automation for THIS thread's tabs. `t3_preview_list` shows tabs; only `runtime:'server'` tabs are automatable — desktop-app tabs are the user's, say so and stop. + +- Lifecycle: `preview_open` (`url` or `target:{kind:'environment-port',port,path?}` for dev servers; `open=false` for background; `reuseExistingTab=false` + returned `tabId` when running parallel subagents), `preview_navigate`, `t3_preview_close`, `preview_status`, `preview_dialog` (accept/dismiss prompts). +- Perception: `preview_snapshot` (accessibility tree + elements + screenshot size; refs die on navigation — re-snapshot), `preview_evaluate` (JS, bounded result), `preview_wait_for` (locator/text/url conditions). +- Action: `preview_act` — `click|type|hover|select|drag|upload|press|scroll`; target via `locator='aria-ref='` from the snapshot, `x`+`y` for coordinates, `paths` for file uploads, `key`+`modifiers` for keys. +- Emulation/verification: `preview_resize` (`fill|freeform|preset` — presets include iphone-*, pixel-*, ipad-*, desktop-1440x900), `preview_set_appearance` (dark/light/system), `preview_recording_start|stop` (returns local file path). +- `html_preview` (render check → PNG + console output) and `html_render` (show a finished HTML page inline in the reply; use theme CSS vars, fluid widths, fixed pixel chart heights, no `vh`/`height:100%`). + +### Delegation — child agents + +- `orchestrator_capabilities` — providers, models, options, runtime modes. **Call first**; `search` finds models beyond the short list. +- `delegate_task` — one child agent, `task` only (no parent history). Key params: `target:{providerInstanceId, model, options:[{id,value}], environmentId, projectId}` (target another linked machine), `isolation:'shared'|'worktree'`, `mode:'async'|'wait'` (wait has a default timeout — a timeout does NOT cancel the child), `role` (implementation/research/review/design/test/general), `runtimeMode`/`interactionMode`. +- `task_status` (workState: working / waiting_for_children / result_available — a finished turn with live children is NOT done; reading the summary marks it delivered), `task_cancel`. +- `create_threads` — batch up to ~20 top-level threads in this checkout (not delegation; inherits project/branch/worktree). +- `t3_thread_launch` — one top-level thread bound to a workspace: `workspaceStrategy` `root|existing_worktree|worktree` (with `baseRef`, `startFromOrigin`, `branch`, `worktreePath`), `scratch:true` for no-project, `modelSelection`, `runtimeMode`, `interactionMode`, `message` (large limit), up to 8 attachments, `clientRequestId` for safe retries. + +Providers depend on what is installed/authed on the machine — query `orchestrator_capabilities` rather than assuming a catalog. Disabled providers report a `constraints` reason. + +### Thread control plane — `t3_thread_*` + friends + +- Read: `t3_thread_list` (filter statuses/titleContains/settled/snoozed, `allProjects`, paging), `t3_thread_read` (`view:messages|activity`, paginate with `afterPosition`/`nextPosition`, cut-off text via `itemId`+`textOffset`), `t3_thread_search` (title/branch/PR/project then message text; skips subagents). +- Write: `t3_thread_send` (`mode:auto|queue|steer|restart` — steer = mid-turn update, restart = interrupt+restart; sending to a finished child thread starts a fresh task and returns its `taskId`), `t3_thread_update` (rename/regenerate title), `t3_thread_interrupt`, `t3_thread_wait` (`untilDelegatedWorkSettled` for whole subtrees), `t3_thread_configure` (switch provider/model/options mid-thread; permission modes stay). +- Context: `t3_thread_transfer` — `fork` (copy from `sourcePoint` latest_stable|run|checkpoint into a new thread), `merge_back`, `status`. +- Lifecycle: `t3_thread_organize` — pin/unpin, snooze(+`snoozedUntil`)/unsnooze, settle/unsettle, archive/unarchive, mark_unread. +- Queue + questions: `t3_queue` (list/read/edit/cancel/reorder/promote_to_steer on queued messages), `t3_pending_request` (list/read/respond to user questions — cannot approve permission requests). +- Worktrees: `t3_worktree_status`, `t3_worktree_list` (refs + checkout paths), `t3_worktree_handoff` (move THIS thread into a new worktree+branch; runs setup script; ends the live session; `continuationPrompt` resumes next turn — call last in your turn). +- Attachments: `t3_attachment_prepare_upload` → POST bytes to the returned `relativeUrl` on the MCP origin → `t3_thread_send_attachments` (up to 8 files); `t3_attachment_discard` for pending uploads. +- Claude-only: `t3_workflow_stop` (stop a running Claude workflow by subagentId), `t3_background_wait` (keep thread in Working while background work runs). + +### Scheduling + +- `schedule_task` — `schedule` object: `{type:'interval',everyMs≥60000}`, `{type:'fixed_time',timeOfDay,weekdays?}` (0=Sun), `{type:'once',runAt}`, `{type:'webhook'}` (HMAC `signature` header/encoding/prefix, up to 16 `filters` on `headers.*`/`body.*` paths, `dedupe` replay/coalesce keys, `maxDeliveryAgeMinutes`). `enabled:false` pauses; update via `scheduledTaskId`. Webhook triggers return a `webhookUrl` — requires remote access; webhook payload values are untrusted input. +- `list_scheduled_tasks`, `delete_scheduled_task`, `run_scheduled_task_now`. + +### Environments (multi-machine) + +`t3_environment_read` (this server's identity/preferences), `t3_environment_links` (linked machines + liveness), `t3_environment_link` (opens a card for the user — never ask for pairing codes in chat; returns `pending`, outcome arrives as a thread message), `t3_environment_unlink`, `t3_environment_preferences_update` (live full-access threads only: `defaultThreadEnvMode local|worktree`, `newWorktreesStartFromOrigin`, `enableProviderUpdateChecks`, `backgroundActivity` profile, `sourceControlWritingStyle`). + +Any `environmentId`-accepting tool acts on that machine; `delegate_task.target.environmentId` and `t3_thread_launch.environmentId` included. + +### Pull requests + +- `link_pull_request(s)` / `unlink_pull_request(s)` (by state) / `list_thread_pull_requests` — link PRs to a thread; T3 shows status and settles the thread on merge. +- `watch_pull_request` / `unwatch_pull_request` — wakes the thread on failed checks, passed required checks, new comments/reviews, conflicts. **After calling, end your turn; the watch persists across wakes — do not re-call it.** Old comments are handled first; only later ones wake. +- `write_pull_request_guides` / `read_pull_request_guide` — generate/read a stored review guide (tour) for PRs; runs take minutes in a temp checkout. + +### Devices (mobile) + +`device_list` (iOS simulators + Android emulators per host), `device_open` (boots + shows in the Device panel, returns the pinned device-driver CLI call), `device_close`, `device_screenshot`. Drive taps/text with the returned CLI. + +### Secrets + +`request_secret` — private card, waits for the user. `delivery:'secretRef'` (default) returns a one-use ref for T3 tools; `delivery:'file'` writes a file readable only inside its command. `value` accepts a secret pasted directly in the thread. Never put secrets in `task` prompts or commits. + +## Recipes + +**Parallel implementation lanes (CLI):** +```sh +t3 project add ~/path/to/repo # once per repo +t3 thread start "" --worktree main --branch feat/x --wait --json +t3 thread list --project --json # poll; t3 thread show --messages 20 +``` + +**In-session fan-out (MCP):** `delegate_task` per lane with `isolation:'worktree'`, `mode:'async'`; collect via completion wakes, `task_status` for stragglers, `task_cancel` to stop. Pick models via `orchestrator_capabilities` — cheap model for research/review lanes, strong model for implementation. + +**PR babysitting:** open the PR, `link_pull_requests`, `watch_pull_request`, end turn. Each wake: handle new comments/checks, push fixes, let the watch persist. Merge decision stays yours. + +**Scheduled agent work:** `schedule_task` with `fixed_time`+`weekdays` for standups/digests, `interval` for polling, `webhook` for event-driven runs. Test with `run_scheduled_task_now`. + +**Remote machine work:** `t3 pair` on the remote → `t3 environment link` here → threads/`delegate_task` with that `environmentId`. + +**Secrets mid-run:** `request_secret` opens a card; use `secretRef` or `file` delivery — never ask the user to paste secrets into chat text. + +## Cannot do / sharp edges + +- No `--worktree` on `t3 thread send`; only `start` creates worktrees. To move a live thread: `t3_worktree_handoff` (MCP) — ends the session, call last. +- Child agents get `task` only — no parent history. Write self-contained prompts; no secrets. +- `delegate_task` `mode:'wait'` times out without cancelling; check `task_status` after. +- `task_status` marks a result delivered on read — don't poll it speculatively. +- `preview_*` cannot touch the user's local desktop tabs — only `runtime:'server'` tabs. +- `t3_workflow_stop`/`t3_background_wait` are Claude-provider only. +- `t3_pending_request.respond` answers questions; it cannot approve permission requests. +- `t3_project_delete` keeps the folder on disk; `force:true` needed for non-empty. +- Scheduled webhook payloads are untrusted — validate before acting on them. +- One server owns the userdata dir; app-vs-service conflict shows as `ServerAlreadyRunningError` / "This home is unavailable" → `t3 doctor`. +- Thread children do not inherit the parent session's memory or context — write durable outcomes to the repo or a memory store. + +## Verify on your machine + +- `t3 status --json` — service + remote access state. +- `t3 thread list --json` — projects/threads actually present. +- `orchestrator_capabilities` (MCP) — real provider/model catalog for your installs. +- `t3 environment list` — linked machines and liveness. +- `t3 pair --help` — scope list for your version. From fdca4ef9bc75ac547da9f91bdaa2c79162b34fae Mon Sep 17 00:00:00 2001 From: Tomas Dvorak Date: Sun, 8 Nov 2026 22:11:31 +0100 Subject: [PATCH 2/3] docs: add KERN self-hosted CI to stack table and toolchain reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit KERN (github.com/Dvorinka/kern) is the self-hosted GH Actions-compatible CI used across TDvorak repos — workflows run unmodified, results land as check runs on PRs. Documented the kern CLI surface and pointers to the upstream porting ledger. Authored By: TDvorak Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- SKILL.md | 1 + references/toolchain.md | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/SKILL.md b/SKILL.md index 8460925..21c4541 100644 --- a/SKILL.md +++ b/SKILL.md @@ -55,6 +55,7 @@ Persistent memory lives in a dedicated git repo following the [Agent Memory Repo | Worktrees | **worktrunk (`wt`)** — git worktree lifecycle for parallel agent work: `wt switch -c ` create+enter, `wt merge`, `wt remove`, `wt list` (status/CI), `wt switch pr:`; 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 --worktree --branch --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 `); **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 | — | diff --git a/references/toolchain.md b/references/toolchain.md index 167df46..e8d5f03 100644 --- a/references/toolchain.md +++ b/references/toolchain.md @@ -78,6 +78,13 @@ A rule without a machine checking it is a wish. Applies to every project. - **actionlint** — static lint for workflow YAML (undefined matrix keys, `run:` shell errors via embedded shellcheck). Wire into lefthook on `.github/workflows/**` paths in repos that ship workflows. - **shellcheck** — lint every committed `.sh` and hook script before push; it flags the quoting/exit-code bugs that only fail on the machine that matters. +## Self-hosted CI — KERN + +- **KERN** (https://github.com/Dvorinka/kern) — self-hosted, GitHub Actions-compatible CI: Go API + Postgres control plane, containerized job execution across a Linux/Windows/macOS runner fleet, GitHub App webhooks in, check runs + commit statuses back out on the PR. Standard `.github/workflows/` YAML runs unmodified. +- `kern` CLI (install from the repo): `kern doctor` health probe, `kern runs` / `kern runs logs -f` to watch runs, `kern lint` compiles workflows offline with no server, `kern hooks install` writes a pre-push hook that runs `kern lint`. +- Agent surface: streamable-HTTP MCP endpoint at `/api/v1/mcp` (run lifecycle, logs, runners, secrets) — tool matrix in `docs/connect.md` upstream. +- Repo porting ledger and known gaps (arm64 images, `vars` context, docker-on-fork-PRs) live in the KERN repo at `docs/porting.md` — check it before moving a repo's CI over. + ## HTTP debugging — mitmproxy - `mitmproxy` interactive / `mitmdump` headless — capture, inspect, replay HTTP(S) when the bug is on the wire: webhooks, third-party APIs, mobile-app traffic. Point the client at `http://localhost:8080` with the mitm CA installed. From 294916f1a5d83817fe14c807f8b0ce6b6951cb59 Mon Sep 17 00:00:00 2001 From: Tomas Dvorak Date: Fri, 13 Nov 2026 14:01:57 +0100 Subject: [PATCH 3/3] docs: add five ops references (ship-verify, go-dbtest, release-train, upstream-port-sweep, handoff) Generalized deploy/verify, DB-test, release, fork-sync and handoff playbooks distilled from real session failures; wired into the workflow list and README layout. Authored By: TDvorak --- README.md | 6 +++ SKILL.md | 9 +++-- references/go-dbtest.md | 47 ++++++++++++++++++++++ references/handoff.md | 31 +++++++++++++++ references/release-train.md | 34 ++++++++++++++++ references/ship-verify.md | 65 +++++++++++++++++++++++++++++++ references/upstream-port-sweep.md | 39 +++++++++++++++++++ 7 files changed, 228 insertions(+), 3 deletions(-) create mode 100644 references/go-dbtest.md create mode 100644 references/handoff.md create mode 100644 references/release-train.md create mode 100644 references/ship-verify.md create mode 100644 references/upstream-port-sweep.md diff --git a/README.md b/README.md index 22ac265..c322324 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SKILL.md b/SKILL.md index 21c4541..71559c4 100644 --- a/SKILL.md +++ b/SKILL.md @@ -27,9 +27,12 @@ Persistent memory lives in a dedicated git repo following the [Agent Memory Repo 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. Read `references/t3code.md` for the full T3 Code surface (CLI, MCP tools, providers, scheduling, PR watch, limits). -7. Invoke `ponytail` (default `full`) on every response — shortest working diff, stdlib first, no speculative abstractions. Mark shortcuts `// ponytail: , `. -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). +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: , `. +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) diff --git a/references/go-dbtest.md b/references/go-dbtest.md new file mode 100644 index 0000000..350cd5a --- /dev/null +++ b/references/go-dbtest.md @@ -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. diff --git a/references/handoff.md b/references/handoff.md new file mode 100644 index 0000000..c006399 --- /dev/null +++ b/references/handoff.md @@ -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//handoff-.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. diff --git a/references/release-train.md b/references/release-train.md new file mode 100644 index 0000000..8c530eb --- /dev/null +++ b/references/release-train.md @@ -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. diff --git a/references/ship-verify.md b/references/ship-verify.md new file mode 100644 index 0000000..f4466e5 --- /dev/null +++ b/references/ship-verify.md @@ -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 ` 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. diff --git a/references/upstream-port-sweep.md b/references/upstream-port-sweep.md new file mode 100644 index 0000000..9ffa6f7 --- /dev/null +++ b/references/upstream-port-sweep.md @@ -0,0 +1,39 @@ +# Upstream port sweep + +The fork-maintenance loop for keeping a downstream fork current with +upstream. Read before syncing issues/PRs across repos. + +## Rules + +- **Never touch upstream.** All work lands in the fork; upstream is + read-only reference. +- Keep a ledger (`PORTS.md` / `HANDOFF.md`) with per-item state: + ported `` / covered-by `#X` / skipped (reason) / open. +- License-incompatible PRs are a deliberate skip — record the reason, do + not port. + +## Loop + +1. Fetch upstream open issues + PRs above the last recorded maximum. + Issues with no ledger row are "new" even if old — sweep them anyway. +2. For each PR: fetch the diff → `git apply` (or `--reject` + manual + merge). Port with a commit referencing the upstream number. Batch + trivially related PRs into one commit when they touch the same area. +3. Dedup against history first — many "new" items are already fixed by an + earlier port; verify in the current code, then ledger `covered-by`. +4. Mirror issues get verify → port → close-with-verdict. Keep standing + tracker issues open forever. +5. **Suite must be green before push.** Repair pre-existing baseline + failures first and record them; known environmental failures are + sanctioned, everything else is a regression you own. +6. Push and record the head sha in the ledger. + +## Gotchas + +- Cross-repo PRs merge fine — check whether a later PR is stacked on an + earlier one before ordering merges. +- CI on main may be red for unrelated reasons (a platform job broken by an + earlier merge) — identify whether your sweep introduced it before + claiming green. +- A port that lands in test-only code still needs the full suite — + detector/fixture regressions hide in ported tests.