Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(skills): make tdd-workflow test-runner aware (npm/pnpm/yarn/bun) (#2347)

JongHyeok Park7976e6faf246
diff --git a/.agents/skills/tdd-workflow/SKILL.md b/.agents/skills/tdd-workflow/SKILL.md
index 7e61dcef0..661a1e581 100644
--- a/.agents/skills/tdd-workflow/SKILL.md
+++ b/.agents/skills/tdd-workflow/SKILL.md
@@ -48,6 +48,34 @@ ALWAYS write tests first, then implement code to make tests pass.
## TDD Workflow Steps
+### Step 0: Detect the Test Runner
+
+Do not assume `npm test`. The commands in the steps and examples below use `<test>`, `<test-watch>`, and `<coverage>` as placeholders for the project's actual runner. Resolve them once before starting:
+
+1. **Run the package-manager detector** (ships with ECC):
+
+ ```bash
+ node scripts/setup-package-manager.js --detect
+ ```
+
+ It resolves the package manager (npm / pnpm / yarn / bun) from, in order: `CLAUDE_PACKAGE_MANAGER`, `.claude/package-manager.json`, the `package.json` `packageManager` field, the lockfile, then global config.
+
+2. **Distinguish the package manager from the test runner — they are not the same.** A project can use Bun to install dependencies yet still run Jest or Vitest. Inspect `package.json` `scripts.test` and the test files:
+ - `scripts.test` invokes `jest` / `vitest` -> run through the detected PM (`npm test`, `pnpm test`, `yarn test`, or `bun run test`).
+ - `scripts.test` is `bun test`, or test files `import { test, expect } from "bun:test"`, or there is no jest/vitest config but Bun is present -> use **Bun's native runner** (`bun test`). See [Bun Native Test Pattern](#bun-native-test-pattern-buntest) below.
+
+Runner command matrix:
+
+| Runner | `<test>` | `<test-watch>` | `<coverage>` | `<lint>` |
+|--------|----------|----------------|--------------|----------|
+| npm | `npm test` | `npm test -- --watch` | `npm run test:coverage` | `npm run lint` |
+| pnpm | `pnpm test` | `pnpm test --watch` | `pnpm test:coverage` | `pnpm lint` |
+| yarn | `yarn test` | `yarn test --watch` | `yarn test:coverage` | `yarn lint` |
+| Bun (script runs jest/vitest) | `bun run test` | `bun run test --watch` | `bun run test:coverage` | `bun run lint` |
+| Bun (native `bun:test`) | `bun test` | `bun test --watch` | `bun test --coverage` | `bun run lint` |
+
+> `bun test` (Bun's built-in runner) is **not** the same as `bun run test` (which runs the `package.json` `test` script). Picking the wrong one is a common failure — e.g. invoking Jest through `npx`/`bun run` in an ESM-only project breaks, while `bun test` runs the suite natively. Confirm which the project expects before the RED gate, then substitute `<test>` / `<coverage>` everywhere `npm test` appears below.
+
### Step 1: Write User Journeys
```
As a [role], I want to [action], so that [benefit]
@@ -82,7 +110,7 @@ describe('Semantic Search', () => {
### Step 3: Run Tests (They Should Fail)
```bash
-npm test
+<test>
# Tests should fail - we haven't implemented yet
```
@@ -98,7 +126,7 @@ export async function searchMarkets(query: string) {
### Step 5: Run Tests Again
```bash
-npm test
+<test>
# Tests should now pass
```
@@ -111,7 +139,7 @@ Improve code quality while keeping tests green:
### Step 7: Verify Coverage
```bash
-npm run test:coverage
+<coverage>
# Verify 80%+ coverage achieved
```
@@ -144,6 +172,35 @@ describe('Button Component', () => {
})
```
+### Bun Native Test Pattern (`bun:test`)
+
+When the project uses Bun's built-in runner (see [Step 0](#step-0-detect-the-test-runner)), import from `bun:test` and run with `bun test` — not `bun run test`. The API is Jest-like, so `describe` / `it` / `expect` and most matchers carry over. See the `bun-runtime` skill for runtime, install, and bundler details.
+
+```typescript
+import { describe, it, expect, mock } from 'bun:test'
+import { searchMarkets } from './search'
+
+describe('searchMarkets', () => {
+ it('returns an empty list for an empty query', async () => {
+ expect(await searchMarkets('')).toEqual([])
+ })
+
+ it('sorts results by similarity score', async () => {
+ const results = await searchMarkets('election')
+ expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
+ })
+})
+```
+
+```bash
+bun test # run once (RED/GREEN gate)
+bun test --watch # watch mode during development
+bun test --coverage # coverage report
+```
+
+- Mock modules with `mock.module(...)` / `mock(...)` from `bun:test` instead of `jest.mock(...)`.
+- Configure coverage thresholds in `bunfig.toml` under `[test]` (e.g. `coverageThreshold`) rather than the Jest `coverageThresholds` config block.
+
### API Integration Test Pattern
```typescript
import { NextRequest } from 'next/server'
@@ -292,7 +349,7 @@ jest.mock('@/lib/openai', () => ({
### Run Coverage Report
```bash
-npm run test:coverage
+<coverage>
```
### Coverage Thresholds
@@ -363,21 +420,21 @@ test('updates user', () => {
### Watch Mode During Development
```bash
-npm test -- --watch
+<test-watch>
# Tests run automatically on file changes
```
### Pre-Commit Hook
```bash
# Runs before every commit
-npm test && npm run lint
+<test> && <lint>
```
### CI/CD Integration
```yaml
# GitHub Actions
- name: Run Tests
- run: npm test -- --coverage
+ run: <coverage>
- name: Upload Coverage
uses: codecov/codecov-action@v3
```
diff --git a/skills/tdd-workflow/SKILL.md b/skills/tdd-workflow/SKILL.md
index 1e8765c48..03503df17 100644
--- a/skills/tdd-workflow/SKILL.md
+++ b/skills/tdd-workflow/SKILL.md
@@ -85,6 +85,34 @@ ALWAYS write tests first, then implement code to make tests pass.
## TDD Workflow Steps
+### Step 0: Detect the Test Runner
+
+Do not assume `npm test`. The commands in the steps and examples below use `<test>`, `<test-watch>`, and `<coverage>` as placeholders for the project's actual runner. Resolve them once before starting:
+
+1. **Run the package-manager detector** (ships with ECC):
+
+ ```bash
+ node scripts/setup-package-manager.js --detect
+ ```
+
+ It resolves the package manager (npm / pnpm / yarn / bun) from, in order: `CLAUDE_PACKAGE_MANAGER`, `.claude/package-manager.json`, the `package.json` `packageManager` field, the lockfile, then global config.
+
+2. **Distinguish the package manager from the test runner — they are not the same.** A project can use Bun to install dependencies yet still run Jest or Vitest. Inspect `package.json` `scripts.test` and the test files:
+ - `scripts.test` invokes `jest` / `vitest` -> run through the detected PM (`npm test`, `pnpm test`, `yarn test`, or `bun run test`).
+ - `scripts.test` is `bun test`, or test files `import { test, expect } from "bun:test"`, or there is no jest/vitest config but Bun is present -> use **Bun's native runner** (`bun test`). See [Bun Native Test Pattern](#bun-native-test-pattern-buntest) below.
+
+Runner command matrix:
+
+| Runner | `<test>` | `<test-watch>` | `<coverage>` | `<lint>` |
+|--------|----------|----------------|--------------|----------|
+| npm | `npm test` | `npm test -- --watch` | `npm run test:coverage` | `npm run lint` |
+| pnpm | `pnpm test` | `pnpm test --watch` | `pnpm test:coverage` | `pnpm lint` |
+| yarn | `yarn test` | `yarn test --watch` | `yarn test:coverage` | `yarn lint` |
+| Bun (script runs jest/vitest) | `bun run test` | `bun run test --watch` | `bun run test:coverage` | `bun run lint` |
+| Bun (native `bun:test`) | `bun test` | `bun test --watch` | `bun test --coverage` | `bun run lint` |
+
+> `bun test` (Bun's built-in runner) is **not** the same as `bun run test` (which runs the `package.json` `test` script). Picking the wrong one is a common failure — e.g. invoking Jest through `npx`/`bun run` in an ESM-only project breaks, while `bun test` runs the suite natively. Confirm which the project expects before the RED gate, then substitute `<test>` / `<coverage>` everywhere `npm test` appears below.
+
### Step 1: Write User Journeys
If a `*.plan.md` file was provided, extract the user journeys and acceptance criteria from that plan first. Only write new journeys for gaps the plan does not cover.
@@ -122,7 +150,7 @@ describe('Semantic Search', () => {
### Step 3: Run Tests (They Should Fail)
```bash
-npm test
+<test>
# Tests should fail - we haven't implemented yet
```
@@ -163,7 +191,7 @@ If the repository is under Git, stage the minimal fix now but defer the checkpoi
### Step 5: Run Tests Again
```bash
-npm test
+<test>
# Tests should now pass
```
@@ -191,7 +219,7 @@ Recommended commit message format:
### Step 7: Verify Coverage
```bash
-npm run test:coverage
+<coverage>
# Verify 80%+ coverage achieved
```
@@ -261,6 +289,35 @@ describe('Button Component', () => {
})
```
+### Bun Native Test Pattern (`bun:test`)
+
+When the project uses Bun's built-in runner (see [Step 0](#step-0-detect-the-test-runner)), import from `bun:test` and run with `bun test` — not `bun run test`. The API is Jest-like, so `describe` / `it` / `expect` and most matchers carry over. See the `bun-runtime` skill for runtime, install, and bundler details.
+
+```typescript
+import { describe, it, expect, mock } from 'bun:test'
+import { searchMarkets } from './search'
+
+describe('searchMarkets', () => {
+ it('returns an empty list for an empty query', async () => {
+ expect(await searchMarkets('')).toEqual([])
+ })
+
+ it('sorts results by similarity score', async () => {
+ const results = await searchMarkets('election')
+ expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
+ })
+})
+```
+
+```bash
+bun test # run once (RED/GREEN gate)
+bun test --watch # watch mode during development
+bun test --coverage # coverage report
+```
+
+- Mock modules with `mock.module(...)` / `mock(...)` from `bun:test` instead of `jest.mock(...)`.
+- Configure coverage thresholds in `bunfig.toml` under `[test]` (e.g. `coverageThreshold`) rather than the Jest `coverageThresholds` config block.
+
### API Integration Test Pattern
```typescript
import { NextRequest } from 'next/server'
@@ -409,7 +466,7 @@ jest.mock('@/lib/openai', () => ({
### Run Coverage Report
```bash
-npm run test:coverage
+<coverage>
```
### Coverage Thresholds
@@ -480,21 +537,21 @@ test('updates user', () => {
### Watch Mode During Development
```bash
-npm test -- --watch
+<test-watch>
# Tests run automatically on file changes
```
### Pre-Commit Hook
```bash
# Runs before every commit
-npm test && npm run lint
+<test> && <lint>
```
### CI/CD Integration
```yaml
# GitHub Actions
- name: Run Tests
- run: npm test -- --coverage
+ run: <coverage>
- name: Upload Coverage
uses: codecov/codecov-action@v3
```