Parallel T3 worktrees#

Each agent uses a distinct Git worktree and branch with its own installed workspace dependencies. Resolve the base from current issue/PR handoffs; do not copy an old planning branch as a universal starting point.

Setup#

Use the pnpm version in package.json. The exact Node pin is also declared through devEngines.runtime: pnpm installs a project runtime and records its checksum in the lockfile, so scripts use the pinned Node without changing the machine's active Node installation. From the new worktree:

pnpm worktree:setup
pnpm workflow:context

Setup uses only built-in Node APIs before dependencies exist, performs a frozen install, and installs the pinned Playwright Chromium. It does not change the machine's Node selection, credentials, T3 configuration, or another worktree. On Linux provision Chromium's system libraries with pnpm exec playwright install --with-deps chromium.

The repository's t3.json defaults new threads to worktrees and declares pnpm worktree:setup with runOnWorktreeCreate: true and async: false, so setup completes before the agent starts. This follows T3's native worktree setup contract. It also exposes dev and verification actions. Existing project/environment action overrides may need to import the repository actions in T3's project settings; the branch used to create the worktree must contain this configuration. The same setup command works independently in a worktree terminal.

Serve and verify#

Dependency installation registers .githooks/pre-commit for this worktree through Git's worktree configuration. Run pnpm hooks:install to register it in an existing checkout. CI and source archives skip registration. The hook runs the same gate as pnpm check:commit and blocks the commit on any failure. Staged-file formatting and strict typed linting run in parallel with the dedicated critical test suite, starting tests immediately. Checks never fix or stage files. An eight-second shared deadline fails closed and terminates owned process trees, including lingering test workers; all lanes drain and the worktree lock is released before returning. It requires tracked changes and untracked files to be staged (or set aside/ignored) so unstaged fixes cannot mask a broken commit. Critical tests run against that staged working-tree snapshot; formatting and lint inspect changed staged files. The hook does not stash, format, or stage files, and preserves their contents.

tooling/workflow/commit-gate.mts owns this policy for both the hook and CLI. It acquires worktree ownership before admission and compares the working-tree fingerprint and staged index before and after checks. An index-only change also blocks the commit. The hook only clears Git's inherited repository environment and delegates; gate tests exercise real Git fixtures and children through the same module, including admission failure, snapshot mutation, parallel completion, deadline cancellation and ownership release.

Commit scheduling and ordinary workflows share child lifetime handling in tooling/workflow/process.mts. Commit cancellation stops child trees immediately. Ordinary POSIX cancellation requests graceful shutdown, then force-stops the owned process group after one second, even if its leader has already exited. Windows child trees stop immediately because generic Node signals cannot provide graceful shutdown there. Owned in-process servers still close gracefully. Commands wait for cancellation cleanup and log draining before returning. The hook invokes the installed project Node runtime directly, avoiding package-manager startup overhead. A missing project runtime blocks the commit with setup guidance; it never falls back to an unpinned machine runtime. The one-shot lint child explicitly selects TypeScript's single-run mode, retaining the same typed rules and projects without starting watch programs. Imported staged-file checks retain watch behavior for tests that lint successive versions of a file.

pnpm test:commit runs the same bounded critical suite independently. Mark fast critical Vitest tests or suites with { tags: ['commit'] }, and register their files in tooling/workflow/commit.config.mts. The runner filters to the tag; the config uses at most two workers and sets one-second test/hook and half-second teardown timeouts. Keep it free of browser startup, builds, network calls and slow fixtures. Workspace imports in this suite must resolve to current source through explicit public-entry aliases; never certify stale build outputs. Removing all matching tests must not become a passing gate.

The normal-commit target is under ten seconds, including hook overhead. Large staged changes or slow machines can hit the deadline and block a commit; this does not permit skipping failing or unfinished checks. Full builds, types, unused-code, architecture and browser checks still run through pnpm verify before handoff and in Linux PR CI. The complete quality policy still applies to every authored file and prototype; the commit hook is a fast feedback gate.

Full verification runs formatting and one build before up to three bounded lanes overlap lint/rule tests, types/quality/workflow tests, and the main tests/browser checks. Browser and consumer artifact writers remain serial. Every lane drains before the worktree lock is released, including on failure. Machines with at most two available CPUs use two lanes to limit contention. CI browser suites use two workers; local suites retain Playwright's CPU-based default. Native Windows checks are available through pnpm check:compatibility and the explicit manual dispatch described in GitHub checks.

pnpm dev:examples

Startup builds reporting and its workspace prerequisites in dependency order, including in a fresh worktree with no existing build outputs. The process binds an OS-allocated loopback port and prints the actual URL, identity endpoint, and run directory. Append playground/, playground/branding/, or plain-html/ to that URL. pnpm prototype:theming similarly serves the browser fixture and branding/ route. Ports are chosen by the listening server, not a probe that releases a port before use.

When T3's preview runs on another machine, its loopback address is not this worktree's machine. Set SNAGBADGER_HOST to a specific interface address reachable from that preview before starting the command (PowerShell: $env:SNAGBADGER_HOST = '192.168.1.142'). Use the printed URL in the owned tab. The default remains loopback; changing the host exposes the development server on that interface. A host setting does not create a network route, tunnel, or firewall rule. If the preview cannot reach that address, record the connectivity blocker and do not mark T3 preview evidence as passed. Keep automated local browser verification and the pending preview review separate.

Each T3 thread owns its tab and uses its own printed URL. Always target that tab explicitly. Different live ports provide different origins, isolating cookies, local storage, IndexedDB and service-worker scope across worktrees. Tabs sharing an origin still share browser storage; use isolated Playwright contexts for automated runs, and keep the assigned server running throughout T3 review. Avoid retaining credentials or test data in browser state; keep fixtures deterministic. Distinct tabs alone are not an isolation guarantee.

Stop the server with Ctrl+C before running pnpm verify in the same worktree. Supported setup, dev, build, unit, consumer and browser commands acquire a worktree-local ownership lock. Nested gate commands inherit the same token. A second conflicting command fails clearly instead of overwriting builds. Use another worktree for concurrent work. Raw internal *:checks scripts and direct package build commands are implementation details; run the guarded entry points.

Verification starts its own servers and passes their actual URLs to the tests. Each browser run writes to test-results/workflow/<run-id>/ with its source/commit identity, server URLs, browser results, and failure evidence. Vite dev caches also belong to that run. Builds remain worktree-local and guarded. Sharing pnpm's content-addressed store and installed browser binaries is supported; sharing mutable node_modules, output directories, user data profiles or run directories is not.

The maintained command recipes live in tooling/workflow/workflow.mts. Its private lifecycle owns lock inheritance, run identity, source checks, evidence completion and resource cleanup; the CLI and browser entry select recipes. Regression checks cross those command entries with real local processes and listeners, including failure after partial startup and interrupted child execution.

tooling/workflow/completion.mts binds maintained recipes and compatibility comparison completion to one final source snapshot. Records retain the initial source and add finalSource, commandCode, resultCode, unchanged and completedAt. A changed source fails returned status even when the command succeeded. Existing nonbrowser workflow code keeps its raw-command meaning; browser/parity code reflects returned status. Thrown recipes write terminal failure evidence before propagating the original error. Candidate comparison exit codes remain findings rather than replacement quality gates. Completion does not alter locks, resource cleanup or artifact retention.

Recovery and isolation proof#

The helpers close only servers they created. Never terminate arbitrary processes by port. After an interrupted command, inspect the owner JSON inside the test-results/workflow.lock/ directory, its PID/token, and the partial run record. pnpm workflow:unlock <owner-token> removes only a matching lock whose recorded process is dead; a live or mismatched owner is rejected. Token-specific owner files prevent simultaneous recovery attempts from deleting a replacement lock. PID reuse can conservatively block recovery. If a process died between creating the directory and writing its owner file, inspect that empty directory and confirm no setup/build/dev process owns the worktree before removing the empty directory; never force-delete an active-looking lock.

pnpm test:workflow creates two actual Git worktrees in an owned temporary repository and checks concurrent browser pages, source identities, distinct origins/storage, occupied-port rejection, independent shutdown, and source-change detection. It also tests worktree locks and failed/stale/missing handoff evidence. These are regression checks for tooling, not a synthetic agent-performance benchmark. Full real-worktree clean installs and gates are required in the implementation handoff.