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.

2026-06-211

fix-test-flake

jamesaphoenix/tx-agent-kit

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.

2026-06-211

prune-dead-branches

jamesaphoenix/tx-agent-kit

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.

2026-06-211

speed-up-test-suite

jamesaphoenix/tx-agent-kit

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.

2026-06-211

test-census

jamesaphoenix/tx-agent-kit

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.

2026-06-211

test-perf

jamesaphoenix/tx-agent-kit

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.

2026-06-211

name	new-package
description	Scaffold a new package in the monorepo with correct workspace wiring, TypeScript config, and path aliases.
argument-hint	<category>/<package-name> (e.g. infra/queue, tooling/prettier-config)

Create a New Package

Scaffold a new package in the monorepo. The argument format is <category>/<name> where category is one of packages, infra, or tooling.

Package Categories

Category	Directory	When to use
`packages`	`packages/<name>`	Shared domain or cross-cutting packages (e.g. `contracts`, `core`, `testkit`)
`infra`	`packages/infra/<name>`	Infrastructure adapters — DB, auth, messaging, observability
`tooling`	`packages/tooling/<name>`	Dev tooling — linting, config, scaffolding

All three globs are already declared in pnpm-workspace.yaml — no workspace config changes needed.

Steps

1. Create the package directory

mkdir -p packages/<category-path>/<name>/src

Where <category-path> is empty for top-level (packages/<name>), infra for infra, or tooling for tooling.

2. Create `package.json`

File: packages/<category-path>/<name>/package.json

The package name is always @tx-agent-kit/<name> regardless of category.

{
  "name": "@tx-agent-kit/<name>",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc -b",
    "type-check": "tsc -b --pretty false",
    "lint": "eslint src --max-warnings=0",
    "test": "vitest run -c vitest.config.ts"
  },
  "devDependencies": {
    "@tx-agent-kit/vitest-config": "workspace:*"
  }
}

Add dependencies as needed (e.g. "effect": "^3.19.16", other workspace:* packages).

3. Create `tsconfig.json`

File: packages/<category-path>/<name>/tsconfig.json

The extends path varies by depth:

Category	`extends` value
`packages/<name>`	`"../../tsconfig.node.json"`
`packages/infra/<name>`	`"../../../tsconfig.node.json"`
`packages/tooling/<name>`	`"../../../tsconfig.node.json"`

{
  "extends": "<extends-path>",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

If the package depends on other workspace packages, add references:

{
  "references": [{ "path": "<relative-path-to-dependency>" }]
}

4. Create `vitest.config.ts`

File: packages/<category-path>/<name>/vitest.config.ts

import unitConfig from '@tx-agent-kit/vitest-config/unit'

export default unitConfig

5. Create `src/index.ts`

File: packages/<category-path>/<name>/src/index.ts

// @tx-agent-kit/<name>

Empty barrel export — add real exports as the package develops.

6. Add path alias to `tsconfig.base.json`

File: tsconfig.base.json

Add to compilerOptions.paths:

"@tx-agent-kit/<name>": ["packages/<category-path>/<name>/src/index.ts"]

Keep entries alphabetically sorted.

7. Run `pnpm install`

pnpm install

This wires the workspace dependency graph. Verify the new package appears in the workspace:

pnpm ls --depth 0 --filter @tx-agent-kit/<name>

8. Verify

pnpm type-check && pnpm lint && pnpm test

Wiring Checklist

After creating the package, verify these commonly forgotten steps:

tsconfig.base.json — path alias added for @tx-agent-kit/<name>
tsconfig.json — extends path correct for category depth
tsconfig.json — references added in consuming packages that depend on this one
pnpm install — run after adding any workspace:* dependencies
Barrel export — src/index.ts exists and re-exports public API

Reference Files

File	Role
`tsconfig.base.json`	Path alias registry
`tsconfig.node.json`	Base config for Node packages
`pnpm-workspace.yaml`	Workspace globs (covers `packages/`, `packages/infra/`, `packages/tooling/*`)
`packages/tooling/typescript-config/base.json`	Compiler options root
`packages/contracts/package.json`	Example top-level package
`packages/infra/auth/package.json`	Example infra package
`packages/tooling/scaffold/package.json`	Example tooling package

new-package

المزيد من هذا المستودع

المزيد من هذا المستودع

Create a New Package

Package Categories

Steps

1. Create the package directory

2. Create package.json

3. Create tsconfig.json

4. Create vitest.config.ts

5. Create src/index.ts

6. Add path alias to tsconfig.base.json

7. Run pnpm install

8. Verify

Wiring Checklist

Reference Files

Create a New Package

Package Categories

Steps

1. Create the package directory

2. Create package.json

3. Create tsconfig.json

4. Create vitest.config.ts

5. Create src/index.ts

6. Add path alias to tsconfig.base.json

7. Run pnpm install

8. Verify

Wiring Checklist

Reference Files

2. Create `package.json`

3. Create `tsconfig.json`

4. Create `vitest.config.ts`

5. Create `src/index.ts`

6. Add path alias to `tsconfig.base.json`

7. Run `pnpm install`

2. Create `package.json`

3. Create `tsconfig.json`

4. Create `vitest.config.ts`

5. Create `src/index.ts`

6. Add path alias to `tsconfig.base.json`

7. Run `pnpm install`