code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/locales/en/.agents/skills/tdd-workflow/SKILL.md

@@ -1,19 +1,53 @@
 ---
 name: tdd-workflow
-description: Development strictly according to TDD (RED→GREEN→REFACTOR): formulating test cases via user journey, unit + integration tests with Vitest and Testing Library, e2e with Playwright for critical flows. Use this skill ALWAYS when you need to write tests, develop a feature via TDD, conduct a review of tests, or explain why a test is fragile. Activate upon questions "how to test X", "why the test breaks during refactoring", "what is a good test".
+description: 'Development strictly according to TDD (RED→GREEN→REFACTOR): formulating test cases via user journey, unit + integration tests with Vitest and Testing Library, e2e with Playwright for critical flows. Use this skill ALWAYS when you need to write tests, develop a feature via TDD, conduct a review of tests, or explain why a test is fragile. Activate upon questions "how to test X", "why the test breaks during refactoring", "what is a good test".'
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech: []
+topic:
+  - general
+  - testing
+triggers:
+  - TDD
+  - RED GREEN REFACTOR
+  - test first
+  - Vitest
+  - Testing Library
+  - brittle test
+  - how to test
+related:
+  - tdd-workflow-reference
+  - testing-strategy-js
+  - testing-strategy-js-reference
+  - react-beast-practices
+  - typescript-beast-practices
+  - typescript-beast-practices-reference
+  - qa-e2e-playwright
+  - tests-quality-review
+  - qa-test-integrity-audit
+  - qa-mutation-testing
+  - node-express-beast-practices
+  - dev-reference-snippets
+budget_lines: 300
+schema_version: 1
 ---
 
+
 # Skill: TDD Workflow
 
-Algorithm, examples, and antipatterns for reliable testing.
+Decision rules + canonical algorithm + checklists for reliable TDD. Full DO/DON'T code examples — in `$tdd-workflow-reference`.
 
 **Sections:**
 1. [Algorithm RED→GREEN→REFACTOR](#1-algorithm)
 2. [Formulation of test cases](#2-formulation)
-3. [Unit tests: behavior, not implementation](#3-unit)
-4. [Integration tests: HTTP + DB](#4-integration)
-5. [React components: Testing Library](#5-react)
-6. [E2E: Playwright for critical flows](#6-e2e)
+3. [Unit tests: rules](#3-unit)
+4. [Integration tests: rules](#4-integration)
+5. [React components: rules](#5-react)
+6. [E2E (Playwright): rules + levels](#6-e2e)
 7. [Antipatterns](#7-antipatterns)
 
 ---
@@ -40,308 +74,94 @@ REFACTOR: Improve code without changing behavior → tests remain green
 - [ ] Coverage ≥ project threshold (`vitest --coverage`)
 - [ ] No flakes (the test consistently passes 10 times in a row)
 
----
+### Commit discipline (tier 1-2)
 
-## 2. Formulation of test cases
+For tier 1-2 modules (see `$qa-mutation-testing` tier model), TDD phases unfold as **separate commits**:
 
-### ✅ DO: user journey template → test cases
-```
-User Journey: "A manager creates a new user in the system"
+1. **RED commit** — test added, test fails (`npm test` shows failure exactly on the tested criterion). Production code **is not changed**.
+2. **GREEN commit** — production code added/changed minimally, test became green. Existing tests stayed green. **The test itself is not modified in this commit.**
+3. **REFACTOR commit** (optional) — code or test improved, behavior unchanged, all tests stayed green.
 
-Happy path:
-  - creates a user with valid data → returns id and status 201
+**DEMO envelope for tier 1-2 requires:**
+- `RED_COMMIT_HASH` — hash of the RED commit
+- `GREEN_COMMIT_HASH` — hash of the GREEN commit
 
-Edge cases:
-  - email is already taken → returns 409 CONFLICT
-  - name is empty → returns 422 VALIDATION_ERROR
-  - email without @ → returns 422 VALIDATION_ERROR
-  - role is not from enum → returns 422 VALIDATION_ERROR
+TEST gate (`$tester`) verifies: commits exist, diff between them contains ONLY a production code change (without test modification). This is the proof that the test really caught the bug before the code fixed it.
 
-Error paths:
-  - DB is unavailable → returns 500, does not leak error details
-  - unauthorized request → returns 401
-  - authorized but not admin → returns 403
-```
+For tier 3 — discipline recommended (simplifies review and mutation testing), commit hashes optional.
 
-### ✅ DO: naming tests — "what it does under what condition"
-```ts
-// ✅ Good: the test case reads like a specification
-describe("usersService.create", () => {
-  it("returns new user id when input is valid", ...);
-  it("throws CONFLICT when email already exists", ...);
-  it("throws VALIDATION_ERROR when email is malformed", ...);
-  it("throws UNAUTHORIZED when actor is not authenticated", ...);
-});
-
-// ❌ Bad: uninformative names
-describe("usersService", () => {
-  it("works", ...);
-  it("test1", ...);
-  it("should do stuff", ...);
-});
-```
+> Full git workflow + commit message examples → `$tdd-workflow-reference` §1.
 
 ---
 
-## 3. Unit tests
-
-### ✅ DO: test behavior, not implementation details
-```ts
-// ─── Tested function ───────────────────────────────────────────
-// src/lib/pricing.ts
-export function calculateDiscount(price: number, userType: "regular" | "premium"): number {
-  if (price <= 0) throw new Error("Price must be positive");
-  const rate = userType === "premium" ? 0.2 : 0.05;
-  return Math.round(price * rate * 100) / 100;
-}
-
-// ─── Tests ────────────────────────────────────────────────────────
-// src/lib/pricing.test.ts
-import { describe, it, expect } from "vitest";
-import { calculateDiscount } from "./pricing";
-
-describe("calculateDiscount", () => {
-  // ✅ Happy path
-  it("applies 5% discount for regular users", () => {
-    expect(calculateDiscount(100, "regular")).toBe(5);
-  });
-
-  it("applies 20% discount for premium users", () => {
-    expect(calculateDiscount(100, "premium")).toBe(20);
-  });
-
-  // ✅ Edge cases
-  it("rounds to 2 decimal places", () => {
-    expect(calculateDiscount(99.99, "regular")).toBe(5); // 4.9995 → 5
-  });
-
-  // ✅ Error paths
-  it("throws when price is zero", () => {
-    expect(() => calculateDiscount(0, "regular")).toThrow("Price must be positive");
-  });
-
-  it("throws when price is negative", () => {
-    expect(() => calculateDiscount(-10, "regular")).toThrow("Price must be positive");
-  });
-});
-```
-
-### ✅ DO: mock dependencies, not details
-```ts
-// src/domain/services/users.service.test.ts
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { usersService } from "./users.service";
-import { usersRepo } from "../../data/repos/users.repo";
-
-// ✅ Mock the repository (external dependency), not ORM or SQL
-vi.mock("../../data/repos/users.repo");
-
-const mockRepo = vi.mocked(usersRepo);
+## 2. Formulation of test cases
 
-describe("usersService.create", () => {
-  beforeEach(() => vi.clearAllMocks());
+**User journey template → test cases:**
+- **User Journey**: role + action + value
+- **Happy path** — valid data → expected result
+- **Edge cases** — boundaries, duplicates, malformed inputs → specific error codes
+- **Error paths** — DB unavailable, unauthorized, no permission → 500/401/403
 
-  it("returns created user when email is not taken", async () => {
-    mockRepo.findByEmail.mockResolvedValue(null);
-    mockRepo.insert.mockResolvedValue({ id: "usr_1", email: "a@b.com", name: "Alice" });
+**Naming convention:**
+- ✅ `it("returns new user id when input is valid", ...)` — specification, not description
+- ✅ `it("throws CONFLICT when email already exists", ...)`
+- ❌ `it("works", ...)`, `it("test1", ...)`, `it("should do stuff", ...)`
 
-    const user = await usersService.create({ email: "a@b.com", name: "Alice" });
+> Full user journey template + naming examples → `$tdd-workflow-reference` §2.
 
-    expect(user.id).toBe("usr_1");
-    expect(mockRepo.insert).toHaveBeenCalledWith({ email: "a@b.com", name: "Alice" });
-  });
+---
 
-  it("throws CONFLICT when email is already taken", async () => {
-    mockRepo.findByEmail.mockResolvedValue({ id: "existing", email: "a@b.com", name: "Bob" });
+## 3. Unit tests
 
-    await expect(usersService.create({ email: "a@b.com", name: "Alice" }))
-      .rejects.toMatchObject({ code: "CONFLICT" });
+**Rules:**
+- **Test behavior, not implementation details** — what the function returns, not how it computes
+- **Happy path + edge cases + error paths** — all three categories mandatory
+- **Mock dependencies, not details** — mock repo (external layer), not ORM/SQL
+- **`vi.mocked(fn)` + `mockResolvedValue`** — type-safe mocks
+- **`vi.clearAllMocks()` in `beforeEach`** — test isolation
+- ❌ Do not check internal state (`service._isLoading`) — that is an implementation detail
 
-    expect(mockRepo.insert).not.toHaveBeenCalled(); // ✅ did not create a duplicate
-  });
-});
-```
+> Full unit-test code (pricing + mocking deps) → `$tdd-workflow-reference` §3.
 
 ---
 
 ## 4. Integration tests
 
-### ✅ DO: test the HTTP layer from route to response
-```ts
-// src/http/routes/users.routes.test.ts
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import request from "supertest";
-import { app } from "../../app";
-import { db } from "../../lib/db";
-import { seedTestUser, cleanupTestData } from "../../test/helpers";
-
-describe("POST /api/users", () => {
-  beforeAll(() => db.connect());
-  afterAll(async () => {
-    await cleanupTestData();
-    await db.disconnect();
-  });
-
-  // ✅ Happy path: check status and response shape
-  it("returns 201 and user id when input is valid", async () => {
-    const res = await request(app)
-      .post("/api/users")
-      .set("Authorization", "Bearer test-admin-token")
-      .send({ email: "new@example.com", name: "Alice" });
-
-    expect(res.status).toBe(201);
-    expect(res.body).toMatchObject({ id: expect.stringMatching(/^usr_/) });
-  });
-
-  // ✅ Validation: check error_code, not the message text (it can change)
-  it("returns 422 when email is malformed", async () => {
-    const res = await request(app)
-      .post("/api/users")
-      .set("Authorization", "Bearer test-admin-token")
-      .send({ email: "not-an-email", name: "Alice" });
-
-    expect(res.status).toBe(422);
-    expect(res.body.error_code).toBe("VALIDATION_ERROR");
-    expect(res.body.details).toBeDefined();
-  });
-
-  // ✅ Conflict
-  it("returns 409 when email already exists", async () => {
-    await seedTestUser({ email: "existing@example.com" });
-
-    const res = await request(app)
-      .post("/api/users")
-      .set("Authorization", "Bearer test-admin-token")
-      .send({ email: "existing@example.com", name: "Bob" });
-
-    expect(res.status).toBe(409);
-    expect(res.body.error_code).toBe("CONFLICT");
-  });
-
-  // ✅ Authentication
-  it("returns 401 without auth token", async () => {
-    const res = await request(app)
-      .post("/api/users")
-      .send({ email: "a@b.com", name: "Alice" });
-
-    expect(res.status).toBe(401);
-  });
-});
-```
+**Rules:**
+- **HTTP layer from route to response** — via `supertest` and `request(app)`
+- **`beforeAll` for setup**, **`afterAll` for cleanup** — connect/disconnect DB, clean data
+- **Check `error_code`, not the message text** — message may change, code is stable
+- **Cover statuses**: 201/422/409/401/403 — each scenario = its own `it`
+- **`expect.stringMatching(/^usr_/)`** — ID pattern, not exact value
+
+> Full integration-test code (POST /api/users) → `$tdd-workflow-reference` §4.
 
 ---
 
 ## 5. React components
 
-### ✅ DO: Testing Library — roles and text, not classes and id
-```tsx
-// src/components/LoginForm.test.tsx
-import { describe, it, expect, vi } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { LoginForm } from "./LoginForm";
-
-describe("LoginForm", () => {
-  it("calls onSubmit with email and password on valid submit", async () => {
-    const user = userEvent.setup();
-    const onSubmit = vi.fn().mockResolvedValue(undefined);
-    render(<LoginForm onSubmit={onSubmit} />);
-
-    // ✅ Search by role and label — like a user
-    await user.type(screen.getByLabelText("Email"), "alice@example.com");
-    await user.type(screen.getByLabelText("Password"), "password123");
-    await user.click(screen.getByRole("button", { name: "Sign in" }));
-
-    await waitFor(() => {
-      expect(onSubmit).toHaveBeenCalledWith({
-        email: "alice@example.com",
-        password: "password123",
-      });
-    });
-  });
-
-  it("shows validation error when email is empty", async () => {
-    const user = userEvent.setup();
-    render(<LoginForm onSubmit={vi.fn()} />);
-
-    await user.click(screen.getByRole("button", { name: "Sign in" }));
-
-    // ✅ Search by role alert — not by class .error-message
-    expect(screen.getByRole("alert")).toHaveTextContent(/email/i);
-  });
-
-  it("disables submit button while submitting", async () => {
-    const user = userEvent.setup();
-    // Simulate a long request
-    const onSubmit = vi.fn().mockImplementation(() => new Promise(() => {}));
-    render(<LoginForm onSubmit={onSubmit} />);
-
-    await user.type(screen.getByLabelText("Email"), "alice@example.com");
-    await user.type(screen.getByLabelText("Password"), "password123");
-    await user.click(screen.getByRole("button", { name: "Sign in" }));
-
-    expect(screen.getByRole("button", { name: /signing in/i })).toBeDisabled();
-  });
-});
-```
-
-### ✅ DO: test custom hooks via renderHook
-```ts
-import { renderHook, act } from "@testing-library/react";
-import { useDebounce } from "./useDebounce";
+**Rules:**
+- **Testing Library — roles and text, not classes and id** — `getByRole`, `getByLabelText`, `getByText`
+- **`userEvent.setup()`** in every test — isolated user input
+- **`async/await` + `waitFor`** for async assertions
+- **`renderHook` + `act`** for custom hooks
+- **`vi.useFakeTimers()` / `vi.advanceTimersByTimeAsync()`** for tests with delay
+- ❌ Do not use `container.querySelector`, `getByTestId` (when semantics is available)
 
-describe("useDebounce", () => {
-  it("returns initial value immediately", () => {
-    const { result } = renderHook(() => useDebounce("initial", 300));
-    expect(result.current).toBe("initial");
-  });
-
-  it("debounces value update", async () => {
-    vi.useFakeTimers();
-    const { result, rerender } = renderHook(({ v }) => useDebounce(v, 300), {
-      initialProps: { v: "a" },
-    });
-
-    rerender({ v: "b" });
-    expect(result.current).toBe("a"); // has not updated
-
-    await act(() => vi.advanceTimersByTimeAsync(300));
-    expect(result.current).toBe("b"); // has updated
-
-    vi.useRealTimers();
-  });
-});
-```
+> Full code for LoginForm + useDebounce → `$tdd-workflow-reference` §5.
 
 ---
 
 ## 6. E2E (Playwright)
 
-### ✅ DO: only for critical user flows
-```ts
-// e2e/auth.spec.ts
-import { test, expect } from "@playwright/test";
+**Rules:**
+- **Only for critical user flows** — login, payment, key CRUD
+- **`page.getByRole` + `getByLabel`** — semantic selectors (as in RTL)
+- **`expect(page).toHaveURL(...)`** — wait for navigation, not just element presence
+- **Do not duplicate unit logic** — if it can be covered at unit/integration, do not write E2E
 
-// ✅ E2E covers the full flow that cannot be adequately unit-tested
-test("user can log in and see dashboard", async ({ page }) => {
-  await page.goto("/login");
+### What to test at what level
 
-  await page.getByLabel("Email").fill("alice@example.com");
-  await page.getByLabel("Password").fill("password123");
-  await page.getByRole("button", { name: "Sign in" }).click();
-
-  // ✅ Wait for navigation, not just the presence of an element
-  await expect(page).toHaveURL("/dashboard");
-  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
-});
-
-test("unauthenticated user is redirected to login", async ({ page }) => {
-  await page.goto("/dashboard");
-  await expect(page).toHaveURL("/login");
-});
-```
-
-### Rule: what to test at what level
 | Level | Speed | What it covers | When |
 |---|---|---|---|
 | Unit | ~1ms | Pure logic, utilities, hooks | Always |
@@ -349,105 +169,38 @@ test("unauthenticated user is redirected to login", async ({ page }) => {
 | Component | ~50ms | React components, forms, UX | Always |
 | E2E | ~5s | Critical end-to-end user flows | Only key flows |
 
+> Full Playwright code (auth.spec.ts) → `$tdd-workflow-reference` §6.
+
 ---
 
 ## 7. Antipatterns
 
-### ❌ Test checks implementation, not behavior
-```ts
-// ❌ Bad: test knows about an internal variable
-it("sets isLoading to true", () => {
-  const service = new UserService();
-  service.fetchUser("1");
-  expect(service._isLoading).toBe(true); // internal detail
-});
-
-// ✅ Good: test checks what the user/calling code sees
-it("shows loading state while fetching", async () => {
-  render(<UserProfile userId="1" />);
-  expect(screen.getByRole("status")).toBeInTheDocument(); // spinner
-});
-```
-
-### ❌ Fragile selectors
-```ts
-// ❌ Bad: will break upon CSS refactoring or DOM structure change
-screen.getByTestId("submit-btn-v2");       // testId is an implementation detail
-container.querySelector(".btn-primary");   // CSS class
-document.getElementById("form-submit");    // id
-
-// ✅ Good: semantic selectors — how the user interacts
-screen.getByRole("button", { name: "Sign in" });
-screen.getByLabelText("Email");
-screen.getByText("Save");
-```
-
-### ❌ Dependency of tests on each other
-```ts
-// ❌ Bad: test 2 breaks if test 1 did not run
-let createdUserId: string;
-
-it("creates user", async () => {
-  const user = await usersService.create(...);
-  createdUserId = user.id; // global variable
-});
-
-it("deletes user", async () => {
-  await usersService.delete(createdUserId); // depends on the test above
-});
-
-// ✅ Good: each test is isolated via beforeEach / fixtures
-describe("usersService.delete", () => {
-  let userId: string;
-  beforeEach(async () => {
-    const user = await usersService.create(...); // its own fixture
-    userId = user.id;
-  });
-
-  it("removes user from DB", async () => {
-    await usersService.delete(userId);
-    const found = await usersRepo.findById(userId);
-    expect(found).toBeNull();
-  });
-});
-```
-
-### ❌ Ignored error paths
-```ts
-// ❌ Bad: only happy path — the most important thing is not covered
-describe("payment.process", () => {
-  it("processes valid payment", ...);
-  // No tests for: insufficient funds, network failed, invalid card
-});
-
-// ✅ Good: error paths are mandatory for critical logic
-describe("payment.process", () => {
-  it("processes valid payment and returns transaction id", ...);
-  it("throws INSUFFICIENT_FUNDS when balance is too low", ...);
-  it("throws NETWORK_ERROR and does not charge when gateway fails", ...);
-  it("throws INVALID_CARD when card number is malformed", ...);
-});
-```
-
-### ❌ Test without assert (forever green)
-```ts
-// ❌ Bad: test is always green regardless of behavior
-it("sends email", async () => {
-  await emailService.send({ to: "a@b.com", subject: "Hi" });
-  // no expect — test says nothing
-});
-
-// ✅ Good: explicit assert
-it("sends email to correct recipient", async () => {
-  const spy = vi.spyOn(mailTransport, "send");
-  await emailService.send({ to: "a@b.com", subject: "Hi" });
-  expect(spy).toHaveBeenCalledWith(expect.objectContaining({ to: "a@b.com" }));
-});
-```
+**Rules (DON'T):**
+- ❌ **Test checks implementation, not behavior** — `expect(service._isLoading).toBe(true)`. Test what the calling code / user sees.
+- ❌ **Fragile selectors** — `getByTestId`, `querySelector('.btn')`, `getElementById`. Use `getByRole` + `getByLabelText`.
+- ❌ **Dependency of tests on each other** — `let createdUserId` between `it`. Isolate via `beforeEach` + fixtures.
+- ❌ **Ignored error paths** — only happy path for critical logic (payments, authorization). Error paths are mandatory.
+- ❌ **Test without `assert`** — forever green. Each `it` must have `expect()`.
+- ❌ **Magic values** — `expect(result).toBe(42)`. Use named constants.
+- ❌ **Async without `await`** — assertion inside `.then()` without `return`. Use `async/await`.
+- ❌ **Reverse TDD** — you write production code first, then a test to fit the existing behavior. Not TDD, this is retrofitting; RED phase is skipped. See `$qa-test-integrity-audit` for detection.
+- ❌ **One-commit RED+GREEN** — test and production code in a single commit. Impossible to record `RED_COMMIT_HASH` for DEMO envelope; proof that the test actually caught the bug is lost.
+- ❌ **Test modified in GREEN commit without TEST-CHANGED-WHY** — you changed the test so it would pass, without recording the reason. Self-confirming test, AI-gaming pattern. See `$qa-test-integrity-audit`.
+- ❌ **REFACTOR phase systematically skipped** — RED→GREEN→stop. Technical debt accumulates, tests end up being a burden rather than protection.
+
+> Full bad-example blocks + corrections → `$tdd-workflow-reference` §7.
 
 ---
 
 ## See also
-- `dev-reference-snippets` → section 1 (TDD example with slugify)
-- `react-beast-practices` → component testing (Testing Library)
-- `typescript-beast-practices` → typing mocks and fixtures
+- `$tdd-workflow-reference` — full DO/DON'T TDD code reference
+- `$testing-strategy-js` — general test strategy (pyramid, mock-table)
+- `$testing-strategy-js-reference` — testing code reference
+- `$react-beast-practices` — testable React components
+- `$typescript-beast-practices` — typing mocks and fixtures
+- `$qa-e2e-playwright` — E2E via Playwright (in depth)
+- `$tests-quality-review` — test quality review
+- `$qa-test-integrity-audit` — gaming pattern detection for TDD (reverse TDD, mock-driven, test-follows-code)
+- `$qa-mutation-testing` — Stryker / mutmut + tier-based thresholds (determine when RED/GREEN hashes are required)
+- `$node-express-beast-practices` — testable backend structure
+- `$dev-reference-snippets` — TDD example with slugify

package/domains/development/locales/en/.agents/skills/tdd-workflow/agents/kimi.yaml

@@ -1,13 +1,13 @@
-name: "tdd-workflow"
-display_name: "TDD Workflow"
-description: "Development strictly according to TDD (RED→GREEN→REFACTOR): formulating test cases via user journey, unit + integration tests with Vitest and Testing Library, e2e with Playwright for critical flows. Use this skill ALWAYS when you need to write tests, develop a feature via TDD, conduct a review of tests, or explain why a test is fragile. Activate upon questions \"how to test X\", \"why the test breaks during refactoring\", \"what is a good test\"."
-default_prompt: "Use $tdd-workflow when the task matches the \"TDD Workflow\" skill."
-triggers:
-  - "tdd-workflow"
-  - "tdd workflow"
-  - "Development strictly according to TDD (RED→GREEN→REFACTOR)"
-capabilities:
-  - "tdd"
-  - "workflow"
-tools: []
-implicit_invocation: true
+name: "tdd-workflow"
+display_name: "TDD Workflow"
+description: "Development strictly according to TDD (RED→GREEN→REFACTOR): formulating test cases via user journey, unit + integration tests with Vitest and Testing Library, e2e with Playwright for critical flows. Use this skill ALWAYS when you need to write tests, develop a feature via TDD, conduct a review of tests, or explain why a test is fragile. Activate upon questions \"how to test X\", \"why the test breaks during refactoring\", \"what is a good test\"."
+default_prompt: "Use $tdd-workflow when the task matches the \"TDD Workflow\" skill."
+triggers:
+  - "tdd-workflow"
+  - "tdd workflow"
+  - "Development strictly according to TDD (RED→GREEN→REFACTOR)"
+capabilities:
+  - "tdd"
+  - "workflow"
+tools: []
+implicit_invocation: true