@su-record/vibe 2.8.24 → 2.8.26

package/skills/characterization-test/agents/coverage-checker.md

@@ -0,0 +1,54 @@
+---
+name: coverage-checker
+role: Verifies all public methods and edge cases are covered by characterization tests
+tools: [Read, Bash, Grep]
+---
+
+# Coverage Checker
+
+## Role
+Audits the generated characterization test file against the behavior manifest to confirm every public method, branch path, and identified edge case has a corresponding locked test. Flags gaps before the refactor begins.
+
+## Responsibilities
+- Cross-reference every public function in the manifest against test cases
+- Verify each branching path has at least one test
+- Confirm edge cases (null, empty, boundary) are all exercised
+- Run the test suite and confirm all tests pass with current code
+- Report any uncovered paths as blockers
+
+## Input
+- Behavior manifest from behavior-capturer
+- Generated test file path from test-writer
+- Project root path for running vitest
+
+## Output
+Coverage audit report:
+
+```markdown
+## Coverage Audit: {ModuleName}
+
+### Public Methods
+- functionA: covered (3 tests)
+- functionB: MISSING — no test found
+
+### Branch Paths
+- functionA happy path: covered
+- functionA null branch: covered
+- functionB error branch: MISSING
+
+### Edge Cases
+- empty string: covered
+- null input: covered
+- value > MAX: MISSING
+
+### Test Run Result
+- Passed: 12 / Failed: 0
+- Uncovered items: 2 (must fix before refactor)
+```
+
+## Communication
+- Reports findings to: orchestrator (characterization-test skill)
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+Any MISSING item is a blocker — refactor must not start until all identified behaviors are locked. Re-run test-writer for gap items rather than patching manually.

package/skills/characterization-test/agents/reporter.md

@@ -0,0 +1,50 @@
+---
+name: reporter
+role: Summarizes what behavior is locked and confirms the codebase is safe to refactor
+tools: [Read, Bash]
+---
+
+# Reporter
+
+## Role
+Produces the final summary after all characterization tests pass. Communicates to the developer exactly what is now locked, what is not covered, and what the safe refactoring boundaries are.
+
+## Responsibilities
+- Summarize total test count and what behaviors each test locks
+- List any intentionally excluded behaviors and the rationale
+- State explicit refactor safety boundaries (what can change vs. what must stay)
+- Provide the single command to run before and after any code change
+- Archive the behavior manifest alongside the test file
+
+## Input
+- Coverage audit report from coverage-checker
+- Final test run results
+- Original behavior manifest
+
+## Output
+A handoff summary printed to the user:
+
+```markdown
+## Characterization Test Report: {ModuleName}
+
+### Locked Behaviors (safe to refactor)
+- functionA: 3 cases locked (happy path, null, empty array)
+- functionB: 2 cases locked (returns string, throws on invalid)
+
+### Not Covered (refactor with caution)
+- functionC: no tests — side effects unclear, manual review required
+
+### Refactor Safety Command
+Run this before AND after changes:
+  npx vitest run src/__tests__/{module}.characterization.test.ts
+
+### Verdict
+SAFE TO REFACTOR — all public API surface locked.
+```
+
+## Communication
+- Reports findings to: user / orchestrator
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+A green characterization suite is a contract. Any failure after refactor means behavior changed — intentional or not. Distinguish between "expected failures" (intended changes) and "unexpected failures" (regressions).

package/skills/characterization-test/agents/test-writer.md

@@ -0,0 +1,49 @@
+---
+name: test-writer
+role: Generates vitest characterization tests that lock captured behavior
+tools: [Read, Write, Edit, Bash]
+---
+
+# Test Writer
+
+## Role
+Takes the behavior manifest from behavior-capturer and produces a complete vitest test file that locks the current behavior as-is. Tests capture actual output — not expected behavior — using snapshot assertions.
+
+## Responsibilities
+- Write one `describe` block per module with clearly labeled test cases
+- Cover every branching path identified in the behavior manifest
+- Use `toMatchSnapshot()` for complex return shapes, `toBe`/`toEqual` for primitives
+- Include error path tests with `toThrowErrorMatchingSnapshot()`
+- Never fix bugs — lock current behavior exactly as it is
+
+## Input
+- Behavior manifest from behavior-capturer
+- Target file path(s) and their import shapes
+- Project test config (vitest.config.ts location)
+
+## Output
+A complete test file written to `src/__tests__/{module}.characterization.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { targetFn } from '../path/to/module.js';
+
+describe('{ModuleName} characterization tests', () => {
+  it('should handle normal input', () => {
+    expect(targetFn(normalInput)).toMatchSnapshot();
+  });
+
+  it('should handle null input', () => {
+    expect(() => targetFn(null)).toThrowErrorMatchingSnapshot();
+  });
+});
+```
+
+Reports: path to generated test file and count of test cases written.
+
+## Communication
+- Reports findings to: orchestrator (characterization-test skill)
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+Characterization test rule: if the current code returns a wrong value for an input, the test must lock THAT wrong value. The goal is regression detection, not correctness. Use `vitest --run -u` to initialize snapshots on first run.

package/skills/characterization-test/rubrics/coverage-criteria.md

@@ -0,0 +1,53 @@
+# Characterization Test Coverage Criteria
+
+Coverage that MUST exist before any refactoring begins.
+
+## Mandatory Coverage (all must pass before changing code)
+
+### Public API Surface
+- [ ] Every exported function has at least one characterization test
+- [ ] Every exported class method (public) has at least one test
+- [ ] Every exported type's runtime behavior is tested where applicable
+
+### Input Coverage
+- [ ] Typical / happy-path input
+- [ ] Minimum valid input (empty string, 0, `[]`, `{}`)
+- [ ] Maximum or large input (long strings, large arrays)
+- [ ] Boundary values (off-by-one, limits)
+
+### Branch Coverage
+- [ ] Each top-level `if` branch has a dedicated test
+- [ ] Each `switch` case has a dedicated test
+- [ ] `try/catch` — both success and error paths tested
+- [ ] Short-circuit conditions (`&&`, `||`) exercised
+
+### Error Paths
+- [ ] `null` input behavior captured
+- [ ] `undefined` input behavior captured
+- [ ] Invalid type input behavior captured
+- [ ] Thrown errors match snapshot (message, type)
+
+### Side Effects
+- [ ] External calls (DB, network, filesystem) are mocked and call args verified
+- [ ] Return values from mocks are representative of real responses
+- [ ] State mutations are verified before and after
+
+## Sufficient vs. Insufficient Coverage
+
+| Situation | Sufficient? |
+|-----------|-------------|
+| 1 happy-path snapshot only | No — missing edge cases and error paths |
+| All branches covered, no error paths | No — error behavior must be locked |
+| All public exports tested | Minimum viable — add side-effect tests if any exist |
+| Snapshot exists but test not run | No — must run and pass before refactoring |
+| Test passes after code change | Confirm intentional; update snapshot with reason |
+
+## Definition of Done
+
+The characterization suite is complete when:
+
+1. All tests pass on current code without modification
+2. Every public export is exercised
+3. At least one error-path test exists per function
+4. Snapshots are committed alongside tests
+5. `npx vitest run <test-file>` exits with code 0

package/skills/characterization-test/templates/test-template.ts

@@ -0,0 +1,101 @@
+/**
+ * Characterization test template — lock existing behavior before refactoring.
+ *
+ * Instructions:
+ *   1. Replace {{MODULE_NAME}} with the module under test.
+ *   2. Replace {{IMPORT_PATH}} with the relative import path.
+ *   3. Replace {{FUNCTION_NAME}} with each public export to characterize.
+ *   4. Run once to generate snapshots: npx vitest run --update {{TEST_FILE}}
+ *   5. Verify all tests pass BEFORE making any changes to the source.
+ *
+ * IMPORTANT: Capture ACTUAL behavior, not expected/ideal behavior.
+ * If the current code has a bug, capture the buggy output — fix it separately.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// import { {{FUNCTION_NAME}} } from '{{IMPORT_PATH}}';
+
+describe('{{MODULE_NAME}} — characterization tests', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // -------------------------------------------------------------------------
+  // Happy path — normal inputs
+  // -------------------------------------------------------------------------
+
+  it('should handle typical input', () => {
+    // const result = {{FUNCTION_NAME}}({{TYPICAL_INPUT}});
+    // expect(result).toMatchSnapshot();
+  });
+
+  it('should handle minimum valid input', () => {
+    // const result = {{FUNCTION_NAME}}({{MIN_INPUT}});
+    // expect(result).toMatchSnapshot();
+  });
+
+  it('should handle maximum valid input', () => {
+    // const result = {{FUNCTION_NAME}}({{MAX_INPUT}});
+    // expect(result).toMatchSnapshot();
+  });
+
+  // -------------------------------------------------------------------------
+  // Edge cases — boundary values
+  // -------------------------------------------------------------------------
+
+  it('should handle empty string input', () => {
+    // const result = {{FUNCTION_NAME}}('');
+    // expect(result).toMatchSnapshot();
+  });
+
+  it('should handle empty array input', () => {
+    // const result = {{FUNCTION_NAME}}([]);
+    // expect(result).toMatchSnapshot();
+  });
+
+  it('should handle zero / false / null-like values', () => {
+    // const result = {{FUNCTION_NAME}}(0);
+    // expect(result).toMatchSnapshot();
+  });
+
+  // -------------------------------------------------------------------------
+  // Error paths — failure modes
+  // -------------------------------------------------------------------------
+
+  it('should handle null input', () => {
+    // expect(() => {{FUNCTION_NAME}}(null)).toThrowErrorMatchingSnapshot();
+  });
+
+  it('should handle undefined input', () => {
+    // expect(() => {{FUNCTION_NAME}}(undefined)).toThrowErrorMatchingSnapshot();
+  });
+
+  it('should handle invalid type input', () => {
+    // expect(() => {{FUNCTION_NAME}}({{INVALID_INPUT}})).toThrowErrorMatchingSnapshot();
+  });
+
+  // -------------------------------------------------------------------------
+  // Side effects — external interactions
+  // -------------------------------------------------------------------------
+
+  it('should call external dependency with correct arguments', () => {
+    // const spy = vi.spyOn({{DEPENDENCY}}, '{{METHOD}}');
+    // {{FUNCTION_NAME}}({{TYPICAL_INPUT}});
+    // expect(spy).toHaveBeenCalledWith({{EXPECTED_ARGS}});
+    // expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // Branching paths — one test per major branch
+  // -------------------------------------------------------------------------
+
+  it('should take branch A when condition is true', () => {
+    // const result = {{FUNCTION_NAME}}({{BRANCH_A_INPUT}});
+    // expect(result).toMatchSnapshot();
+  });
+
+  it('should take branch B when condition is false', () => {
+    // const result = {{FUNCTION_NAME}}({{BRANCH_B_INPUT}});
+    // expect(result).toMatchSnapshot();
+  });
+});

package/skills/claude-md-guide/rubrics/anti-patterns.md

@@ -0,0 +1,88 @@
+# CLAUDE.md Anti-Patterns
+
+## Anti-pattern 1: Discoverable Content
+
+**Symptom**: Listing things the agent can find by reading the repo.
+
+```markdown
+# Bad
+- Components are in src/components/
+- Uses React 18 with TypeScript
+- Run tests with npm test
+```
+
+```markdown
+# Good
+(delete these — they're in package.json and the repo structure)
+```
+
+## Anti-pattern 2: Instruction Overload
+
+**Symptom**: 300+ line CLAUDE.md full of best practices.
+
+LLM compliance drops to ~5% after 15+ instructions. Every line competes for attention.
+
+Fix: Keep under 150 lines. Move feature-specific rules to SPEC files.
+
+## Anti-pattern 3: Emphasis Inflation
+
+**Symptom**: IMPORTANT, CRITICAL, MUST on every other line.
+
+When everything is critical, nothing is. Reserve emphasis words for P1 rules only.
+
+## Anti-pattern 4: Past-Tense History
+
+**Symptom**: Phase tables, progress logs, "we decided to..." narratives.
+
+```markdown
+# Bad
+## Progress
+- Phase 1 ✅ Auth
+- Phase 2 ✅ Dashboard
+- Phase 3 🚧 Payments
+```
+
+This is context noise, not guidance. Delete it.
+
+## Anti-pattern 5: Technology Anchoring
+
+**Symptom**: Listing what you use instead of what to avoid.
+
+```markdown
+# Bad
+We use Zod for validation, Prisma for ORM, Tailwind for styling.
+```
+
+```markdown
+# Good
+Never use joi or yup — Zod is the only validation library.
+```
+
+Naming a technology biases the agent toward it. Only name tech in prohibitions.
+
+## Anti-pattern 6: Vague Prohibitions
+
+**Symptom**: Rules without specific triggers.
+
+```markdown
+# Bad
+- Write clean, readable code
+- Follow best practices
+- Keep functions small
+```
+
+The agent already knows these. They consume tokens and provide no new signal.
+
+## Anti-pattern 7: Missing Boundaries
+
+**Symptom**: No section on what the agent should never touch.
+
+Without explicit boundaries, agents will "helpfully" refactor generated files, edit lock files, or push to main.
+
+Always include: what's off-limits, what requires human approval first.
+
+## Anti-pattern 8: Stale Secrets/Keys
+
+**Symptom**: API keys or connection strings in CLAUDE.md.
+
+These belong in `.env` only. CLAUDE.md is committed to version control.

package/skills/claude-md-guide/templates/claude-md.md

@@ -0,0 +1,54 @@
+# {{PROJECT_NAME}}
+
+{{OPTIONAL: 1-2 sentence description. Only if project purpose is unclear from reading the code.}}
+
+## Commands
+
+{{Only non-obvious commands. Delete commands already in package.json scripts.}}
+
+- `{{COMMAND}}` — {{WHY_ORDER_MATTERS_OR_SPECIAL_FLAGS}}
+
+## Conventions
+
+{{Only what linters/formatters don't enforce automatically.}}
+
+- {{CONVENTION}} — {{e.g., "ESM only — imports need .js extension"}}
+
+## Gotchas
+
+{{Non-discoverable traps an agent will hit without being told.}}
+
+- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
+- **{{TRAP_TITLE}}.** {{Specific do/don't description.}}
+
+## Boundaries
+
+{{What the agent should never touch or always ask about first.}}
+
+Always: {{ALWAYS_DO}}
+Ask first: {{ASK_BEFORE_DOING}}
+Never: {{ABSOLUTE_PROHIBITION}}
+
+---
+
+<!--
+FILLING INSTRUCTIONS
+
+Size targets:
+- Small project (< 10 files): 20-30 lines
+- Medium project (10-50 files): 60-150 lines
+- Large project / monorepo: 100 lines root + 30 lines per package
+
+Placement priority (LLM attention is highest at top and bottom):
+- Top: most critical rules (security, never-do)
+- Middle: background context
+- Bottom: frequently violated rules
+
+For each line ask:
+1. Would the agent make a mistake without this? No → delete
+2. Does every session need this? No → move to SPEC or plan file
+3. Does a linter/hook enforce this? Yes → delete
+4. Is this discoverable from code? Yes → delete
+
+Delete this comment block before committing.
+-->

package/skills/commerce-patterns/rubrics/checkout-flow.md

@@ -0,0 +1,48 @@
+# Checkout UX Best Practices Checklist
+
+## Cart Review Step
+
+- [ ] Cart items show current price, quantity, and subtotal per line
+- [ ] Price change warning shown if item price changed since add-to-cart
+- [ ] Out-of-stock items flagged before user proceeds
+- [ ] Clear "Continue to Checkout" CTA — one primary action per step
+- [ ] Guest checkout option visible (no forced registration)
+
+## Shipping & Address Step
+
+- [ ] Address autocomplete reduces input friction
+- [ ] Saved addresses surfaced first for logged-in users
+- [ ] Shipping cost displayed before payment (no surprise at confirmation)
+- [ ] Estimated delivery date shown per shipping method
+- [ ] Address validation feedback inline, not on submit
+
+## Payment Step
+
+- [ ] Supported payment methods visible upfront (icons, labels)
+- [ ] Payment form uses browser autofill attributes (`autocomplete`)
+- [ ] Idempotency key bound to order ID — double-click safe
+- [ ] Loading state on submit button prevents double submission
+- [ ] Clear error messages distinguish user error from system error
+- [ ] PG redirect handles back-button recovery gracefully
+
+## Order Confirmation Step
+
+- [ ] Order ID prominently displayed (user can reference for support)
+- [ ] Confirmation email sent within 30 seconds of payment success
+- [ ] Summary includes: items, total, shipping address, estimated delivery
+- [ ] Clear next step (track order / continue shopping)
+- [ ] No personal payment data displayed (mask card number)
+
+## Error & Edge Cases
+
+- [ ] Stock exhausted mid-checkout: clear message, return to cart
+- [ ] Payment timeout: inform user, preserve order state for retry
+- [ ] Session expiry during checkout: preserve cart, redirect to login
+- [ ] Network failure on submit: prevent duplicate submission, show retry CTA
+
+## Accessibility & Performance
+
+- [ ] Checkout steps announced to screen readers (step X of Y)
+- [ ] Tab order logical through form fields
+- [ ] Core checkout flow works without JavaScript (progressive enhancement)
+- [ ] Page weight under 200 KB per step (no unnecessary third-party scripts)

package/skills/commerce-patterns/templates/product-schema.md

@@ -0,0 +1,85 @@
+# Product Data Schema Template
+
+## Core Product
+
+```typescript
+interface Product {
+  id: string;                        // UUID or slug — immutable after creation
+  sku: string;                       // Unique stock keeping unit
+  name: string;
+  description: string;
+  status: "ACTIVE" | "ARCHIVED" | "DRAFT";
+
+  pricing: ProductPricing;
+  inventory: ProductInventory;
+  media: ProductMedia[];
+  attributes: ProductAttribute[];    // color, size, material, etc.
+  variants: ProductVariant[];        // if applicable
+
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+## Pricing
+
+```typescript
+interface ProductPricing {
+  currency: string;                  // ISO 4217 — "KRW", "USD"
+  basePrice: number;                 // In smallest currency unit (cents/원)
+  salePrice?: number;                // null = no active sale
+  salePeriod?: { from: Date; to: Date };
+  taxRate: number;                   // 0.1 = 10%
+  taxIncluded: boolean;              // Is tax included in basePrice?
+}
+```
+
+## Inventory
+
+```typescript
+interface ProductInventory {
+  trackInventory: boolean;           // false = always in stock (digital goods)
+  stock: number;                     // Current available quantity
+  reservedStock: number;             // Locked in active checkouts
+  lowStockThreshold: number;        // Alert when stock <= this value
+  backorderAllowed: boolean;
+  reservationTtlMinutes: number;    // How long to hold reserved stock (default: 15)
+}
+```
+
+## Variant
+
+```typescript
+interface ProductVariant {
+  id: string;
+  sku: string;
+  attributes: Record<string, string>; // { color: "red", size: "M" }
+  pricing?: Partial<ProductPricing>;  // Override base pricing
+  inventory: ProductInventory;
+  active: boolean;
+}
+```
+
+## Cart Line Item (Price Snapshot)
+
+```typescript
+interface CartLineItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  // Snapshot at add-to-cart time — do not read live price from DB during checkout
+  snapshotPrice: number;
+  snapshotCurrency: string;
+  snapshotName: string;
+  addedAt: Date;
+}
+```
+
+## Usage Notes
+
+- Store `snapshotPrice` in cart to survive price changes — revalidate at checkout entry only
+- `reservedStock + stock` = total physical stock on hand
+- Use `FOR UPDATE` or atomic SQL when decrementing `stock`
+- Archive products instead of deleting — orders reference them
+- `{{CURRENCY}}` — replace with project's primary currency code
+- `{{TAX_RATE}}` — replace with applicable tax rate (e.g., `0.1` for 10% VAT)

package/skills/commit-push-pr/agents/change-analyzer.md

@@ -0,0 +1,55 @@
+---
+name: change-analyzer
+role: Analyzes git diff to understand what changed and why
+tools: [Bash, Read, Grep]
+---
+
+# Change Analyzer
+
+## Role
+Reads the full git diff and related source files to produce a structured change summary. Distinguishes between what was changed, why it was changed, and what the impact surface is — so message-writer and pr-writer have accurate material.
+
+## Responsibilities
+- Run `git diff --staged` and `git diff` to capture all pending changes
+- Categorize changes: new feature, bug fix, refactor, config, docs, test
+- Identify the primary motivation for the change (what problem does it solve)
+- List files changed grouped by concern (e.g., business logic, tests, config)
+- Flag any risky changes: deleted files, public API modifications, schema changes
+
+## Input
+- Project root path
+- Optional: SPEC or issue reference to cross-check intent
+
+## Output
+Change analysis report:
+
+```markdown
+## Change Analysis
+
+### Category
+bug-fix (primary) + refactor (secondary)
+
+### What Changed
+- src/auth.ts: added null check before JWT decode call
+- src/auth.ts: extracted `decodeToken` into standalone function
+- tests/auth.test.ts: added 2 tests for null token edge case
+
+### Why It Changed
+JWT decode was called without checking for null token, causing unhandled
+TypeError on unauthenticated requests to protected routes.
+
+### Risk Surface
+- Public API: `validateToken()` signature unchanged — safe
+- Behavior change: now returns `null` instead of throwing on invalid token
+
+### Files Changed
+- src/auth.ts (logic)
+- tests/auth.test.ts (tests)
+```
+
+## Communication
+- Reports findings to: message-writer, pr-writer
+- Receives instructions from: orchestrator (commit-push-pr skill)
+
+## Domain Knowledge
+Conventional commit categories: feat, fix, refactor, test, docs, chore, perf, ci. A change is a "fix" only if it corrects incorrect behavior. Categorize by primary intent — a bug fix with refactoring is still "fix".

package/skills/commit-push-pr/agents/message-writer.md

@@ -0,0 +1,50 @@
+---
+name: message-writer
+role: Drafts a conventional commit message from the change analysis
+tools: [Read, Bash]
+---
+
+# Message Writer
+
+## Role
+Produces a well-formed conventional commit message from the change analysis. Follows the Conventional Commits specification. Focuses on communicating the "why" in the body, not repeating the diff in the subject line.
+
+## Responsibilities
+- Write a subject line: `<type>(<scope>): <imperative summary>` under 72 characters
+- Write a body paragraph explaining motivation and context (not just what changed)
+- Add BREAKING CHANGE footer if public API or behavior changed incompatibly
+- Reference issue/ticket numbers if provided
+- Avoid generic filler ("update code", "fix stuff", "various changes")
+
+## Input
+- Change analysis report from change-analyzer
+- Optional: issue number, ticket ID, or SPEC reference
+
+## Output
+Ready-to-use commit message:
+
+```
+fix(auth): handle null token in validateToken to prevent TypeError
+
+JWT decode was called without a null guard, causing unhandled TypeErrors
+on unauthenticated requests to protected routes. Now returns null for
+invalid or missing tokens instead of throwing.
+
+Closes #142
+```
+
+Also outputs the git command to apply it:
+```bash
+git commit -m "$(cat <<'EOF'
+fix(auth): handle null token in validateToken to prevent TypeError
+...
+EOF
+)"
+```
+
+## Communication
+- Reports findings to: reviewer
+- Receives instructions from: orchestrator (commit-push-pr skill)
+
+## Domain Knowledge
+Conventional Commits spec: type(scope): subject. Types: feat, fix, refactor, test, docs, chore, perf, ci, build. Scope is the module or area affected. Subject uses imperative mood ("add" not "added"). Body wraps at 72 chars. Breaking changes go in footer as `BREAKING CHANGE: description`.