@torus-engineering/tas-kit 1.11.1 → 1.12.0

package/.claude/skills/ai-regression-testing/SKILL.md

@@ -1,364 +0,0 @@
----
-name: ai-regression-testing
-description: |
-  Auto-invoke when an AI agent has modified API routes or backend logic, when a bug
-  is found and needs a regression test written, or when running bug-check workflows
-  on AI-generated code. Especially valuable when a sandbox/mock mode exists —
-  enables fast, DB-free API testing to catch sandbox/production path mismatches.
-origin: ECC
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-# AI Regression Testing
-
-Testing patterns specifically designed for AI-assisted development, where the same model writes code and reviews it — creating systematic blind spots that only automated tests can catch.
-
-## When to Activate
-
-- AI agent (Claude Code, Cursor, Codex) has modified API routes or backend logic
-- A bug was found and fixed — need to prevent re-introduction
-- Project has a sandbox/mock mode that can be leveraged for DB-free testing
-- Running `/tas-verify` or post-fix review workflows after code changes
-- Multiple code paths exist (sandbox vs production, feature flags, etc.)
-
-## The Core Problem
-
-When an AI writes code and then reviews its own work, it carries the same assumptions into both steps. This creates a predictable failure pattern:
-
-```
-AI writes fix → AI reviews fix → AI says "looks correct" → Bug still exists
-```
-
-**Real-world example** (observed in production):
-
-```
-Fix 1: Added notification_settings to API response
-  → Forgot to add it to the SELECT query
-  → AI reviewed and missed it (same blind spot)
-
-Fix 2: Added it to SELECT query
-  → TypeScript build error (column not in generated types)
-  → AI reviewed Fix 1 but didn't catch the SELECT issue
-
-Fix 3: Changed to SELECT *
-  → Fixed production path, forgot sandbox path
-  → AI reviewed and missed it AGAIN (4th occurrence)
-
-Fix 4: Test caught it instantly on first run PASS:
-```
-
-The pattern: **sandbox/production path inconsistency** is the #1 AI-introduced regression.
-
-## Sandbox-Mode API Testing
-
-Most projects with AI-friendly architecture have a sandbox/mock mode. This is the key to fast, DB-free API testing.
-
-### Setup (Vitest + Next.js App Router)
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from "vitest/config";
-import path from "path";
-
-export default defineConfig({
-  test: {
-    environment: "node",
-    globals: true,
-    include: ["__tests__/**/*.test.ts"],
-    setupFiles: ["__tests__/setup.ts"],
-  },
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "."),
-    },
-  },
-});
-```
-
-```typescript
-// __tests__/setup.ts
-// Force sandbox mode — no database needed
-process.env.SANDBOX_MODE = "true";
-process.env.NEXT_PUBLIC_SUPABASE_URL = "";
-process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY = "";
-```
-
-### Test Helper for Next.js API Routes
-
-```typescript
-// __tests__/helpers.ts
-import { NextRequest } from "next/server";
-
-export function createTestRequest(
-  url: string,
-  options?: {
-    method?: string;
-    body?: Record<string, unknown>;
-    headers?: Record<string, string>;
-    sandboxUserId?: string;
-  },
-): NextRequest {
-  const { method = "GET", body, headers = {}, sandboxUserId } = options || {};
-  const fullUrl = url.startsWith("http") ? url : `http://localhost:3000${url}`;
-  const reqHeaders: Record<string, string> = { ...headers };
-
-  if (sandboxUserId) {
-    reqHeaders["x-sandbox-user-id"] = sandboxUserId;
-  }
-
-  const init: { method: string; headers: Record<string, string>; body?: string } = {
-    method,
-    headers: reqHeaders,
-  };
-
-  if (body) {
-    init.body = JSON.stringify(body);
-    reqHeaders["content-type"] = "application/json";
-  }
-
-  return new NextRequest(fullUrl, init);
-}
-
-export async function parseResponse(response: Response) {
-  const json = await response.json();
-  return { status: response.status, json };
-}
-```
-
-### Writing Regression Tests
-
-The key principle: **write tests for bugs that were found, not for code that works**.
-
-```typescript
-// __tests__/api/user/profile.test.ts
-import { describe, it, expect } from "vitest";
-import { createTestRequest, parseResponse } from "../../helpers";
-import { GET, PATCH } from "@/app/api/user/profile/route";
-
-// Define the contract — what fields MUST be in the response
-const REQUIRED_FIELDS = [
-  "id",
-  "email",
-  "full_name",
-  "phone",
-  "role",
-  "created_at",
-  "avatar_url",
-  "notification_settings",  // ← Added after bug found it missing
-];
-
-describe("GET /api/user/profile", () => {
-  it("returns all required fields", async () => {
-    const req = createTestRequest("/api/user/profile");
-    const res = await GET(req);
-    const { status, json } = await parseResponse(res);
-
-    expect(status).toBe(200);
-    for (const field of REQUIRED_FIELDS) {
-      expect(json.data).toHaveProperty(field);
-    }
-  });
-
-  // Regression test — this exact bug was introduced by AI 4 times
-  it("notification_settings is not undefined (BUG-R1 regression)", async () => {
-    const req = createTestRequest("/api/user/profile");
-    const res = await GET(req);
-    const { json } = await parseResponse(res);
-
-    expect("notification_settings" in json.data).toBe(true);
-    const ns = json.data.notification_settings;
-    expect(ns === null || typeof ns === "object").toBe(true);
-  });
-});
-```
-
-### Testing Sandbox/Production Parity
-
-The most common AI regression: fixing production path but forgetting sandbox path (or vice versa).
-
-```typescript
-// Test that sandbox responses match the expected contract
-describe("GET /api/user/messages (conversation list)", () => {
-  it("includes partner_name in sandbox mode", async () => {
-    const req = createTestRequest("/api/user/messages", {
-      sandboxUserId: "user-001",
-    });
-    const res = await GET(req);
-    const { json } = await parseResponse(res);
-
-    // This caught a bug where partner_name was added
-    // to production path but not sandbox path
-    if (json.data.length > 0) {
-      for (const conv of json.data) {
-        expect("partner_name" in conv).toBe(true);
-      }
-    }
-  });
-});
-```
-
-## Integrating Tests into Bug-Check Workflow
-
-### Workflow Integration with TAS Kit
-
-Pair with `/tas-bug` for bug tracking and `/tas-verify` for post-fix verification.
-
-```
-User: "/tas-bug" or reports a bug
-  │
-  ├─ Step 1: npm run test
-  │   ├─ FAIL → Bug found mechanically (no AI judgment needed)
-  │   └─ PASS → Continue
-  │
-  ├─ Step 2: npm run build
-  │   ├─ FAIL → Type error found mechanically
-  │   └─ PASS → Continue
-  │
-  ├─ Step 3: AI code review (with known blind spots in mind)
-  │   └─ Findings reported
-  │
-  └─ Step 4: For each fix, write a regression test
-      └─ Next bug-check catches if fix breaks
-```
-
-## Common AI Regression Patterns
-
-### Pattern 1: Sandbox/Production Path Mismatch
-
-**Frequency**: Most common (observed in 3 out of 4 regressions)
-
-```typescript
-// FAIL: AI adds field to production path only
-if (isSandboxMode()) {
-  return { data: { id, email, name } };  // Missing new field
-}
-// Production path
-return { data: { id, email, name, notification_settings } };
-
-// PASS: Both paths must return the same shape
-if (isSandboxMode()) {
-  return { data: { id, email, name, notification_settings: null } };
-}
-return { data: { id, email, name, notification_settings } };
-```
-
-**Test to catch it**:
-
-```typescript
-it("sandbox and production return same fields", async () => {
-  // In test env, sandbox mode is forced ON
-  const res = await GET(createTestRequest("/api/user/profile"));
-  const { json } = await parseResponse(res);
-
-  for (const field of REQUIRED_FIELDS) {
-    expect(json.data).toHaveProperty(field);
-  }
-});
-```
-
-### Pattern 2: SELECT Clause Omission
-
-**Frequency**: Common with Supabase/Prisma when adding new columns
-
-```typescript
-// FAIL: New column added to response but not to SELECT
-const { data } = await supabase
-  .from("users")
-  .select("id, email, name")  // notification_settings not here
-  .single();
-
-return { data: { ...data, notification_settings: data.notification_settings } };
-// → notification_settings is always undefined
-
-// PASS: Use SELECT * or explicitly include new columns
-const { data } = await supabase
-  .from("users")
-  .select("*")
-  .single();
-```
-
-### Pattern 3: Error State Leakage
-
-**Frequency**: Moderate — when adding error handling to existing components
-
-```typescript
-// FAIL: Error state set but old data not cleared
-catch (err) {
-  setError("Failed to load");
-  // reservations still shows data from previous tab!
-}
-
-// PASS: Clear related state on error
-catch (err) {
-  setReservations([]);  // Clear stale data
-  setError("Failed to load");
-}
-```
-
-### Pattern 4: Optimistic Update Without Proper Rollback
-
-```typescript
-// FAIL: No rollback on failure
-const handleRemove = async (id: string) => {
-  setItems(prev => prev.filter(i => i.id !== id));
-  await fetch(`/api/items/${id}`, { method: "DELETE" });
-  // If API fails, item is gone from UI but still in DB
-};
-
-// PASS: Capture previous state and rollback on failure
-const handleRemove = async (id: string) => {
-  const prevItems = [...items];
-  setItems(prev => prev.filter(i => i.id !== id));
-  try {
-    const res = await fetch(`/api/items/${id}`, { method: "DELETE" });
-    if (!res.ok) throw new Error("API error");
-  } catch {
-    setItems(prevItems);  // Rollback
-    alert("削除に失敗しました");
-  }
-};
-```
-
-## Strategy: Test Where Bugs Were Found
-
-Don't aim for 100% coverage. Instead:
-
-```
-Bug found in /api/user/profile     → Write test for profile API
-Bug found in /api/user/messages    → Write test for messages API
-Bug found in /api/user/favorites   → Write test for favorites API
-No bug in /api/user/notifications  → Don't write test (yet)
-```
-
-**Why this works with AI development:**
-
-1. AI tends to make the **same category of mistake** repeatedly
-2. Bugs cluster in complex areas (auth, multi-path logic, state management)
-3. Once tested, that exact regression **cannot happen again**
-4. Test count grows organically with bug fixes — no wasted effort
-
-## Quick Reference
-
-| AI Regression Pattern | Test Strategy | Priority |
-|---|---|---|
-| Sandbox/production mismatch | Assert same response shape in sandbox mode |  High |
-| SELECT clause omission | Assert all required fields in response |  High |
-| Error state leakage | Assert state cleanup on error |  Medium |
-| Missing rollback | Assert state restored on API failure |  Medium |
-| Type cast masking null | Assert field is not undefined |  Medium |
-
-## DO / DON'T
-
-**DO:**
-- Write tests immediately after finding a bug (before fixing it if possible)
-- Test the API response shape, not the implementation
-- Run tests as the first step of every bug-check
-- Keep tests fast (< 1 second total with sandbox mode)
-- Name tests after the bug they prevent (e.g., "BUG-R1 regression")
-
-**DON'T:**
-- Write tests for code that has never had a bug
-- Trust AI self-review as a substitute for automated tests
-- Skip sandbox path testing because "it's just mock data"
-- Write integration tests when unit tests suffice
-- Aim for coverage percentage — aim for regression prevention

package/.claude/skills/architecture-decision-records/SKILL.md

@@ -1,184 +0,0 @@
----
-name: architecture-decision-records
-description: |
-  Auto-invoke when user says "ADR this", "record this decision", "we decided to use X over Y",
-  or "the reason we're doing X instead of Y is...". Also when choosing between significant
-  alternatives (framework, database, pattern, API design) and reaching a conclusion.
-  When user asks "why did we choose X?" — read existing ADRs in docs/adr/.
-origin: ECC
-allowed-tools: Read, Write, Bash, Glob
----
-
-# Architecture Decision Records
-
-Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.
-
-## When to Activate
-
-- User explicitly says "let's record this decision" or "ADR this"
-- User chooses between significant alternatives (framework, library, pattern, database, API design)
-- User says "we decided to..." or "the reason we're doing X instead of Y is..."
-- User asks "why did we choose X?" (read existing ADRs)
-- During planning phases when architectural trade-offs are discussed
-
-## ADR Format
-
-Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development:
-
-```markdown
-# ADR-NNNN: [Decision Title]
-
-**Date**: YYYY-MM-DD
-**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
-**Deciders**: [who was involved]
-
-## Context
-
-What is the issue that we're seeing that is motivating this decision or change?
-
-[2-5 sentences describing the situation, constraints, and forces at play]
-
-## Decision
-
-What is the change that we're proposing and/or doing?
-
-[1-3 sentences stating the decision clearly]
-
-## Alternatives Considered
-
-### Alternative 1: [Name]
-- **Pros**: [benefits]
-- **Cons**: [drawbacks]
-- **Why not**: [specific reason this was rejected]
-
-### Alternative 2: [Name]
-- **Pros**: [benefits]
-- **Cons**: [drawbacks]
-- **Why not**: [specific reason this was rejected]
-
-## Consequences
-
-What becomes easier or more difficult to do because of this change?
-
-### Positive
-- [benefit 1]
-- [benefit 2]
-
-### Negative
-- [trade-off 1]
-- [trade-off 2]
-
-### Risks
-- [risk and mitigation]
-```
-
-## Workflow
-
-### Capturing a New ADR
-
-When a decision moment is detected:
-
-1. **Initialize (first time only)** — if `docs/adr/` does not exist, ask the user for confirmation before creating the directory, a `README.md` seeded with the index table header (see ADR Index Format below), and a blank `template.md` for manual use. Do not create files without explicit consent.
-2. **Identify the decision** — extract the core architectural choice being made
-3. **Gather context** — what problem prompted this? What constraints exist?
-4. **Document alternatives** — what other options were considered? Why were they rejected?
-5. **State consequences** — what are the trade-offs? What becomes easier/harder?
-6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment
-7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files.
-8. **Update the index** — append to `docs/adr/README.md`
-
-### Reading Existing ADRs
-
-When a user asks "why did we choose X?":
-
-1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
-2. If it exists, scan `docs/adr/README.md` index for relevant entries
-3. Read matching ADR files and present the Context and Decision sections
-4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
-
-### ADR Directory Structure
-
-```
-docs/
-└── adr/
-    ├── README.md              ← index of all ADRs
-    ├── 0001-use-nextjs.md
-    ├── 0002-postgres-over-mongo.md
-    ├── 0003-rest-over-graphql.md
-    └── template.md            ← blank template for manual use
-```
-
-### ADR Index Format
-
-```markdown
-# Architecture Decision Records
-
-| ADR | Title | Status | Date |
-|-----|-------|--------|------|
-| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
-| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
-| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |
-```
-
-## Decision Detection Signals
-
-Watch for these patterns in conversation that indicate an architectural decision:
-
-**Explicit signals**
-- "Let's go with X"
-- "We should use X instead of Y"
-- "The trade-off is worth it because..."
-- "Record this as an ADR"
-
-**Implicit signals** (suggest recording an ADR — do not auto-create without user confirmation)
-- Comparing two frameworks or libraries and reaching a conclusion
-- Making a database schema design choice with stated rationale
-- Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
-- Deciding on authentication/authorization strategy
-- Selecting deployment infrastructure after evaluating alternatives
-
-## What Makes a Good ADR
-
-### Do
-- **Be specific** — "Use Prisma ORM" not "use an ORM"
-- **Record the why** — the rationale matters more than the what
-- **Include rejected alternatives** — future developers need to know what was considered
-- **State consequences honestly** — every decision has trade-offs
-- **Keep it short** — an ADR should be readable in 2 minutes
-- **Use present tense** — "We use X" not "We will use X"
-
-### Don't
-- Record trivial decisions — variable naming or formatting choices don't need ADRs
-- Write essays — if the context section exceeds 10 lines, it's too long
-- Omit alternatives — "we just picked it" is not a valid rationale
-- Backfill without marking it — if recording a past decision, note the original date
-- Let ADRs go stale — superseded decisions should reference their replacement
-
-## ADR Lifecycle
-
-```
-proposed → accepted → [deprecated | superseded by ADR-NNNN]
-```
-
-- **proposed**: decision is under discussion, not yet committed
-- **accepted**: decision is in effect and being followed
-- **deprecated**: decision is no longer relevant (e.g., feature removed)
-- **superseded**: a newer ADR replaces this one (always link the replacement)
-
-## Categories of Decisions Worth Recording
-
-| Category | Examples |
-|----------|---------|
-| **Technology choices** | Framework, language, database, cloud provider |
-| **Architecture patterns** | Monolith vs microservices, event-driven, CQRS |
-| **API design** | REST vs GraphQL, versioning strategy, auth mechanism |
-| **Data modeling** | Schema design, normalization decisions, caching strategy |
-| **Infrastructure** | Deployment model, CI/CD pipeline, monitoring stack |
-| **Security** | Auth strategy, encryption approach, secret management |
-| **Testing** | Test framework, coverage targets, E2E vs integration balance |
-| **Process** | Branching strategy, review process, release cadence |
-
-## Integration with Other Skills
-
-- **Planner agent**: when the planner proposes architecture changes, suggest creating an ADR
-- **Code reviewer agent**: flag PRs that introduce architectural changes without a corresponding ADR

package/.claude/skills/benchmark/SKILL.md

@@ -1,98 +0,0 @@
----
-name: benchmark
-description: |
-  Auto-invoke when measuring performance impact of a PR, setting up performance baselines,
-  investigating "feels slow" or "it's getting slower" reports, comparing stack alternatives,
-  or validating Core Web Vitals before a launch. Requires browser MCP or direct API access
-  to target environment. SKIP if neither is available — note the gap to user.
-origin: ECC
-allowed-tools: Read, Bash
----
-
-# Benchmark — Performance Baseline & Regression Detection
-
-## When to Use
-
-- Before and after a PR to measure performance impact
-- Setting up performance baselines for a project
-- When users report "it feels slow"
-- Before a launch — ensure you meet performance targets
-- Comparing your stack against alternatives
-
-## How It Works
-
-### Mode 1: Page Performance
-
-Measures real browser metrics via browser MCP:
-
-```
-1. Navigate to each target URL
-2. Measure Core Web Vitals:
-   - LCP (Largest Contentful Paint) — target < 2.5s
-   - CLS (Cumulative Layout Shift) — target < 0.1
-   - INP (Interaction to Next Paint) — target < 200ms
-   - FCP (First Contentful Paint) — target < 1.8s
-   - TTFB (Time to First Byte) — target < 800ms
-3. Measure resource sizes:
-   - Total page weight (target < 1MB)
-   - JS bundle size (target < 200KB gzipped)
-   - CSS size
-   - Image weight
-   - Third-party script weight
-4. Count network requests
-5. Check for render-blocking resources
-```
-
-### Mode 2: API Performance
-
-Benchmarks API endpoints:
-
-```
-1. Hit each endpoint 100 times
-2. Measure: p50, p95, p99 latency
-3. Track: response size, status codes
-4. Test under load: 10 concurrent requests
-5. Compare against SLA targets
-```
-
-### Mode 3: Build Performance
-
-Measures development feedback loop:
-
-```
-1. Cold build time
-2. Hot reload time (HMR)
-3. Test suite duration
-4. TypeScript check time
-5. Lint time
-6. Docker build time
-```
-
-### Mode 4: Before/After Comparison
-
-Run before and after a change to measure impact:
-
-```
-/benchmark baseline    # saves current metrics
-# ... make changes ...
-/benchmark compare     # compares against baseline
-```
-
-Output:
-```
-| Metric | Before | After | Delta | Verdict |
-|--------|--------|-------|-------|---------|
-| LCP | 1.2s | 1.4s | +200ms | WARNING: WARN |
-| Bundle | 180KB | 175KB | -5KB | ✓ BETTER |
-| Build | 12s | 14s | +2s | WARNING: WARN |
-```
-
-## Output
-
-Stores baselines in `docs/benchmarks/` as JSON. Git-tracked so the team shares baselines.
-
-## Integration
-
-- CI: run `/benchmark compare` on every PR
-- Pair with `/canary-watch` for post-deploy monitoring
-- Pair with `/browser-qa` for full pre-ship checklist