tx-agent-kit

Long-running (multi-hour) adversarial hunt for P0/P1/P2 bugs across the codebase. Mixes codebase observation, mechanical linting, real test + telemetry verification, and parallel skeptic sub-agents that must REFUTE each candidate before it is accepted. Fixes verified bugs on a branch off main with surgical per-bug commits, re-runs gates, and writes a dated report to the Desktop. Never pushes or merges. Use when you want a deep, autonomous bug-finding-and-fixing pass.

Diagnose and durably eliminate flaky/intermittent test failures (passes locally but fails CI, rotates between tests, red only under load). Reproduce under contention, instrument the real state instead of guessing, root-cause by signal not duration, fix at the source, validate multi-run. Use when a test is flaky, CI is intermittently red, or fixing one flake unmasks others.

Safely prune dead local branches, git worktrees, and remote branches in this repo. Use when asked to "prune dead branches", "clean up worktrees", "delete merged branches", "tidy up git", or after a batch of PRs has merged. Knows this repo merges via squash, so it verifies death by PR state, not just git ancestry.

Reduce test-suite wall-clock (dev + CI) without losing coverage or telemetry. Measure the phase breakdown first, then apply proven levers (parallelize turbo, narrow imports vs barrels, lazy-load heavy graphs, pool/worker config, DB pool sizing) and capture the before/after delta. Use when tests are slow, CI time is high, or to set/check a perf baseline. Composes with the read-only test-perf and test-census skills.

Census the repo's tests by TYPE, not by name. Classifies every tracked test file via content heuristics into unit / integration / react-component / e2e (plus a separate db pgTAP count), in precedence order so buckets are mutually exclusive. Use when the user asks "what kinds of tests do we have", "how many component vs integration tests", "what's our e2e coverage", or wants a per-area test-type breakdown.

Snapshot test-suite timings in this repo. Runs the unit and/or integration suites (or a single integration project) and reports wall-clock time, Vitest's own phase breakdown (transform/setup/import/tests/environment), and the slowest test files. Use when the user asks "how slow are the tests", "where does the test time go", wants a perf baseline, or wants to check the suite hasn't regressed.

Build and use the VCR (Video Cassette Recorder) test caching system for AI integration tests. Use when adding new AI tests, converting existing RUN_LIVE_INTEGRATION tests to cached replay, or managing cassette recordings.

Generate a detailed design document via `tx doc add design`. Covers architecture, interfaces, data model, invariants, failure modes, verification, and testing strategy. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Reads companion PRD automatically to map EARS requirements to invariants. Output lands in specs/design/<name>.md.

Generate a system overview spec via `tx doc add overview`. Produces an architectural overview covering problem, scope, components, data flows, and non-goals. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Output lands in specs/<name>.md with tx-managed frontmatter.

Generate a detailed Product Requirements Document via `tx doc add prd`. Uses EARS requirement syntax with traceable IDs, acceptance criteria, and non-functional requirements. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Designed to be created alongside a companion `/design-doc`. Output lands in specs/prd/<name>.md.

Generate a detailed design document via `tx doc add design`. Covers architecture, interfaces, data model, invariants, failure modes, verification, and testing strategy. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Reads companion PRD automatically to map EARS requirements to invariants. Output lands in specs/design/<name>.md.

Generate a system overview spec via `tx doc add overview`. Produces an architectural overview covering problem, scope, components, data flows, and non-goals. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Output lands in specs/<name>.md with tx-managed frontmatter.

Generate a detailed Product Requirements Document via `tx doc add prd`. Uses EARS requirement syntax with traceable IDs, acceptance criteria, and non-functional requirements. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Designed to be created alongside a companion `/design-doc`. Output lands in specs/prd/<name>.md.

Use git worktrees to isolate parallel agent tasks in this repository.

Turn a design spec into an explicit tx task graph with `tx decompose`, then refine the graph using normal tx task and dependency primitives.

Add a new domain event type to the transactional outbox system. Use when adding events like invitation.accepted, user.deleted, or any new aggregate event.

Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

Produce a DEEP, massive briefing that re-establishes full mental context on a piece of work just completed on a branch — every critical workflow with its own code snippets, verbatim test titles, spine files, data paths, new tests, and open follow-ups. Use when returning to a branch after a break, picking up someone else's work, or handing off work to another agent. Length is NOT capped; scannability is the measure — the briefing must have a Workflow Index for jumping, and every workflow must include a code snippet.

End-to-end spec implementation with agent swarms. Analyzes a design spec, identifies gaps, implements with TDD, then runs adversarial review-fix loops until clean. Use when a design doc exists and you need to build or complete the implementation.

Audit all design docs against the canonical system design for coverage, drift, duplication, interfaces, YAML schema, self-containment, and dependency graph validity. Use when adding new subsystems, verifying spec quality, or preparing for task decomposition.

Generate a system-level design document via `tx doc add design`. Covers cross-cutting architecture, service boundaries, data flows, scalability, and deployment topology. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Use for system-wide or multi-domain designs (vs /design-doc for feature-scoped).

Work the main tx queue: initialize, create tasks, inspect work, claim tasks, and complete them. Use when working in Claude Code and the user needs tx commands from this area.

Create, patch, lint, discover, trace, and complete docs-first specs. Use when working in Claude Code and the user needs tx commands from this area.

Guide for implementing domain entities, services, and ports following the project's DDD conventions.

Guide for implementing permission-based UI gating in the web app.

End-to-end spec implementation with agent swarms. Analyzes a design spec, identifies gaps, implements with TDD, then runs adversarial review-fix loops until clean.

Generate a system-level design document via `tx doc add design`. Covers cross-cutting architecture, service boundaries, data flows, scalability, and deployment topology. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Use for system-wide or multi-domain designs (vs /design-doc for feature-scoped).

Work the main tx queue: initialize, create tasks, inspect work, claim tasks, and complete them. Use when working in Codex and the user needs tx commands from this area.

Create, patch, lint, discover, trace, and complete docs-first specs. Use when working in Codex and the user needs tx commands from this area.

Implement and verify design doc invariants by annotating tests and source code with [INV-*] / @spec tags, then driving tx spec coverage from BUILD toward HARDEN (100% FCI). Works with any design doc that has an invariants block.

Implement and verify design doc invariants by annotating tests and source code with [INV-*] / @spec tags, then driving tx spec coverage from BUILD toward HARDEN (100% FCI). Works with any design doc that has an invariants block.

Audit and clean unused files, dependencies, and manifest issues with Knip in this repository. Use when running `pnpm lint:knip` or `pnpm lint:knip:strict`, triaging findings, fixing real hygiene issues, or deciding whether a Knip finding should become a targeted ignore in `.knip.jsonc`.

Scaffold a new package in the monorepo with correct workspace wiring, TypeScript config, and path aliases.

Scaffold a new package in the monorepo with correct workspace wiring, TypeScript config, and path aliases.

Manage data retention policies for database tables. Use when adding a new table to automated pruning, modifying retention periods, or understanding which tables are excluded.

Debug failures by correlating traces, logs, and metrics in this repository.

Deploy this repository to Mac Studio k3s (staging/prod) and optional GKE from the same image artifact, with Cloudflare tunnel reconcile/check on Mac deploys.

Generate this repository CRUD layers using the repository scaffold and invariants.

Write this repository integration tests against Docker-backed infrastructure.

Create additive Postgres migrations for this repository database changes.