@su-record/vibe 3.2.1 → 3.2.2

package/skills/{vercel-react-best-practices → vibe.react-best-practices}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vercel-react-best-practices
+name: vibe.react-best-practices
 invocation: [auto]
 tier: core
 description: "React/Next.js performance gotchas from Vercel engineering. Non-intuitive pitfalls that LLMs commonly miss."

package/skills/vibe.regress/SKILL.md

@@ -28,11 +28,11 @@ user-invocable: true
 
 ## Process
 
-Load skill `regress` with subcommand: `$ARGUMENTS`
+Execute the bundled implementation below with subcommand: `$ARGUMENTS`
 
 The `regress` skill performs registration, generation, and clustering.
 
-**Core steps** (see `skills/regress/SKILL.md` for details):
+**Core steps** (see `skills/vibe.regress/SKILL.md` for details):
 
 1. Parse subcommand
 2. Read/write `.vibe/regressions/<slug>.md` (frontmatter schema enforced)
@@ -73,3 +73,183 @@ feature: login
 ---
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled implementation
+
+
+# vibe.regress — Regression Auto-Evolution
+
+**Purpose**: never fix the same bug twice. Each fix grows a preventive test.
+
+## Why this exists
+
+A classic vibe-coding weakness: LLMs reintroduce bugs of the same class. Regression tests are the only mechanical defense. But if the human has to write the test every time, it gets skipped — so automate.
+
+## Characterization — lock behavior first
+
+Before modifying legacy or untested code whose behavior is uncertain (large files without tests, complex branching, API contracts), **lock current behavior first, then change**:
+
+1. Generate characterization tests over the public surface — snapshot the **actual** output (`toMatchSnapshot()`), not what you think it should be. Do NOT fix bugs while locking: a wrong value gets locked as-is; the goal is regression detection, not correctness.
+2. Run them — all must pass against the unmodified code. A failure means the characterization is wrong: fix the test, never the code.
+3. Make the change incrementally, re-running after each step. Unexpected failure = regression, stop and investigate.
+4. Reconcile: update snapshots only for **intentionally** changed behavior, and add new tests for the new behavior.
+
+Skip this for code you just wrote, already-well-tested code, or trivial changes — write regular unit tests instead. Test file naming/stack detection follows `generate` (below).
+
+## Storage Contract
+
+```
+.vibe/regressions/
+  <bug-slug>.md       # one file per bug
+  _cluster-<tag>.md   # shared-test design produced by `cluster`
+```
+
+### Frontmatter schema (strict)
+
+```yaml
+slug: string            # kebab-case, globally unique
+symptom: string         # one line, user-facing
+root-cause-tag: enum    # only the allowed tags below
+fix-commit: string      # git hash (or "pending")
+test-path: string       # generated test file path (or "pending")
+status: open | test-generated | resolved
+registered: YYYY-MM-DD
+feature: string         # related feature name (matches SPEC)
+```
+
+### Allowed `root-cause-tag` values
+
+Clustering depends on this, so use **only the predefined set**:
+
+- `timezone` — timezone / DST / off-by-one in time
+- `nullability` — null / undefined / empty handling
+- `concurrency` — race conditions
+- `boundary` — off-by-one, edge values
+- `encoding` — charset, URL encoding, escaping
+- `validation` — missing input validation
+- `auth` — authn/authz logic
+- `state-sync` — client/server state mismatch
+- `integration` — external API call failure
+- `type-narrow` — TypeScript type narrowing mistake
+- `other` — when nothing fits (add new tags later)
+
+**Rule**: if a new tag is needed, do not force-fit into an existing one — register as `other`. Once `other` reaches 3 entries, propose adding a new tag.
+
+## Subcommands
+
+### 1. `register "<symptom>"` — manual registration
+
+Most calls are automatic; manual use is rare (bugs found outside `/vibe.verify`, or production incidents).
+
+**Steps**:
+1. `getCurrentTime` for today's date
+2. `git log -1 --format=%H` for current commit hash (fix-commit candidate)
+3. Conversation extracts:
+   - Reproduction steps (Given/When/Then)
+   - Root-cause paragraph
+   - Fix description
+4. `root-cause-tag` is **inferred from the allowed set, then confirmed with the user**. If unclear → `other`.
+5. Generate slug: kebab-case keywords from the symptom; on collision append `-2`
+6. Write `.vibe/regressions/<slug>.md` (status: `open`)
+
+### 2. `generate <slug>` — generate preventive test
+
+**Steps**:
+1. Read bug file
+2. Detect test stack:
+   - From `package.json` `devDependencies`: prefer `vitest` over `jest`
+   - If neither → **ask user, then stop**
+3. Decide test location:
+   - Sibling `__tests__/` next to the implementation file, OR
+   - The project's existing test dir (vitest config `test.include`)
+4. File name: `<original-file>.regression.test.ts`
+5. Body: render `templates/test-vitest.md` or `templates/test-jest.md`
+6. Update bug frontmatter: `test-path`, `status: test-generated`
+7. **Run the test immediately** — should fail (if not yet fixed) or pass (if fixed). Record outcome in frontmatter.
+
+### 3. `list` — open items
+
+```
+/vibe.regress list                 # status != resolved
+/vibe.regress list --feature login # filter by feature
+/vibe.regress list --tag timezone  # filter by tag
+```
+
+Terminal table:
+
+```
+SLUG                              FEATURE   TAG         STATUS           AGE
+login-jwt-expiry-off-by-one       login     timezone    test-generated   3d
+cart-stock-race-double-deduct     cart      concurrency open             1d
+```
+
+### 4. `import` — backfill from git log
+
+**Steps**:
+1. `git log --grep='^fix:' --format='%H|%s|%ci' --since=<last-import-date>`
+   - `last-import-date` lives in `.vibe/regressions/.import-cursor` (defaults to 90 days ago)
+2. For each commit:
+   - If a bug file with the same `fix-commit` already exists → **skip**
+   - Otherwise infer symptom + root-cause-tag from message/diff (LLM call)
+   - Write a new bug file (status: `resolved` — already fixed)
+3. Update `.import-cursor`
+4. Suggest `generate` for newly imported entries
+
+**Note**: only `fix:` commits are considered. Projects not using Conventional Commits can override with `--grep-pattern`.
+
+### 5. `cluster` — promote recurring patterns
+
+**Steps**:
+1. Aggregate `root-cause-tag` across all bug files
+2. **A tag with ≥3 entries** becomes a cluster candidate
+3. For each candidate:
+   - Feed the 3 reproductions to an LLM to extract the common cause and shared test cases
+   - Write `_cluster-<tag>.md` (links to the original bug slugs)
+   - Propose a shared test skeleton at `<project-test-dir>/_cluster-<tag>.regression.test.ts` (create only with user approval)
+4. Original bug files are **not deleted** — history preserved
+
+**Important**: `cluster` is never automatic. Users invoke it explicitly to avoid premature abstraction.
+
+## Integration with /vibe.verify
+
+When `/vibe.verify` fails it calls:
+
+```
+Load skill `vibe.regress` with: register --from-verify
+  <feature>: {feature-name}
+  <scenario>: {failed-scenario}
+  <error>: {error-message}
+  <location>: {file:line}
+```
+
+`--from-verify` behavior:
+- symptom = scenario name + error summary
+- feature = forwarded feature name
+- root-cause-tag = inferred from error pattern (default `other` if unclear)
+- status = `open`
+- **Skip user confirmation** — the user is already attentive in a verify-failure context, and friction must be minimized
+
+## Integration with /vibe.run
+
+At the start of `/vibe.run "<feature>"`:
+
+1. Filter `.vibe/regressions/*.md` for `feature: <feature-name>` + `status != resolved`
+2. If any open items:
+   ```
+   ⚠️  Open regressions for this feature:
+     - login-jwt-expiry-off-by-one (timezone, 3d old)
+     - login-session-leak (auth, 1w old)
+
+   Fix these before adding new behavior? [y/N]
+   ```
+3. `y` → chain to `/vibe.regress generate` for items not yet test-generated
+4. `N` → continue (ultrawork mode auto-`N`, records TODO)
+
+## Done Criteria
+
+- [ ] Subcommand-less invocation prints usage
+- [ ] Frontmatter schema strictly enforced (missing fields rejected)
+- [ ] `root-cause-tag` outside the allowed set → warn + force `other`
+- [ ] After `generate`, the test is **actually run** to verify
+- [ ] `import` deduplicates by `fix-commit` hash
+- [ ] `cluster` does nothing under 3 entries (false-positive guard)

package/skills/vibe.run/SKILL.md

@@ -46,7 +46,7 @@ Execute **Scenario-Driven Implementation** with automatic quality verification.
 ### Pre-Run Regression Check (MANDATORY, before implementation starts)
 
 ```
-Load skill `regress` with: list --feature "{feature-name}"
+Load skill `vibe.regress` with: list --feature "{feature-name}"
 ```
 
 - Open regressions exist → automationLevel confirm: ask user; autonomous: auto-invoke `/vibe.regress generate <slug>`
@@ -452,3 +452,390 @@ Keep under 20 lines. Save key lessons via `core_save_memory`. Update `claude-pro
 ---
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled internal: arch-guard
+
+
+# Arch Guard — Architecture Boundary Test Generator
+
+> **Principle**: "Mechanical enforcement over documentation." If a rule exists only in docs, it will be violated. Turn architecture constraints into failing tests.
+
+## When to Use
+
+| Scenario | Signal |
+|----------|--------|
+| `vibe init` / `vibe update` | Auto-generate for detected stack |
+| New layer/module added | Boundaries need enforcement |
+| Architecture violation found in review | Prevent recurrence with test |
+| "Services should not import UI" type rules | Turn into automated check |
+
+## Core Flow
+
+```
+DETECT → INFER → GENERATE → VERIFY
+```
+
+### Step 1: DETECT — Identify Project Architecture
+
+Analyze the project to determine its layer structure:
+
+```
+Parallel exploration:
+- Agent 1: Scan directory structure (src/, app/, lib/, etc.)
+- Agent 2: Read existing architecture docs (CLAUDE.md, README, ADR)
+- Agent 3: Analyze import graph (which files import what)
+```
+
+**Common patterns to detect:**
+
+| Pattern | Layers | Typical Stacks |
+|---------|--------|----------------|
+| MVC | Controller → Service → Model | Rails, NestJS, Spring |
+| Clean Architecture | UI → Application → Domain → Infrastructure | General |
+| Feature-based | Feature A ↛ Feature B internals | Next.js, React |
+| Hexagonal | Adapters → Ports → Domain | DDD projects |
+| Component hierarchy | Page → Feature → Shared → UI Primitives | Frontend |
+
+### Step 2: INFER — Define Boundary Rules
+
+From detected structure, generate rules:
+
+```typescript
+// Rule format
+interface ArchRule {
+  name: string;           // "service-no-ui-import"
+  from: string;           // Glob pattern: "src/services/**"
+  cannotImport: string[]; // ["src/components/**", "src/pages/**"]
+  canImport: string[];    // ["src/models/**", "src/utils/**"]
+  reason: string;         // "Services must be UI-agnostic"
+}
+```
+
+**Default rules by stack:**
+
+| Stack | Rule |
+|-------|------|
+| Next.js / React | `components/` cannot import from `pages/` or `app/` |
+| Next.js / React | `lib/` cannot import from `components/` |
+| NestJS | `*.service.ts` cannot import from `*.controller.ts` |
+| NestJS | `*.module.ts` is the only valid cross-boundary import |
+| General TS | `src/domain/` cannot import from `src/infra/` |
+| General TS | No circular dependencies between top-level dirs |
+| Python Django | `models.py` cannot import from `views.py` |
+| Python FastAPI | `schemas/` cannot import from `routers/` |
+
+### Step 3: GENERATE — Create Test File
+
+Output: `tests/arch-guard.test.ts` (or equivalent for stack)
+
+```typescript
+/**
+ * Architecture Boundary Tests
+ * Generated by arch-guard skill
+ *
+ * These tests enforce architectural constraints mechanically.
+ * If a test fails, it means an import violates the intended architecture.
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+// Helper: extract imports from a file
+function extractImports(filePath: string): string[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const importRegex = /(?:import|require)\s*\(?['"]([^'"]+)['"]\)?/g;
+  const imports: string[] = [];
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+  return imports;
+}
+
+// Helper: resolve relative import to absolute path
+function resolveImport(fromFile: string, importPath: string): string {
+  if (importPath.startsWith('.')) {
+    return path.resolve(path.dirname(fromFile), importPath);
+  }
+  return importPath; // external package
+}
+
+// Helper: glob files matching pattern
+function globFiles(pattern: string, baseDir: string): string[] {
+  // Use fast-glob or manual recursive scan
+  // Implementation depends on available dependencies
+}
+
+describe('Architecture Boundaries', () => {
+  // GENERATED RULES GO HERE
+  // Each rule becomes a test case:
+
+  it('services cannot import UI components', () => {
+    const serviceFiles = globFiles('src/services/**/*.ts', process.cwd());
+    const violations: string[] = [];
+
+    for (const file of serviceFiles) {
+      const imports = extractImports(file);
+      for (const imp of imports) {
+        const resolved = resolveImport(file, imp);
+        if (resolved.includes('/components/') || resolved.includes('/pages/')) {
+          violations.push(`${file} imports ${imp}`);
+        }
+      }
+    }
+
+    expect(violations).toEqual([]);
+  });
+});
+```
+
+### Step 4: VERIFY — Run and Fix
+
+1. Run the generated tests: `npx vitest run tests/arch-guard.test.ts`
+2. If violations found:
+   - Report each violation with file:line
+   - Suggest fix (move shared code to appropriate layer)
+   - Do NOT auto-fix — violations need human review
+
+## Output Files
+
+| File | Purpose |
+|------|---------|
+| `tests/arch-guard.test.ts` | Executable boundary tests |
+| `.vibe/arch-rules.json` | Machine-readable rules (for CI) |
+
+## Customization
+
+Users can add custom rules to `.vibe/arch-rules.json`:
+
+```json
+{
+  "rules": [
+    {
+      "name": "no-direct-db-in-handlers",
+      "from": "src/handlers/**",
+      "cannotImport": ["src/db/**"],
+      "reason": "Handlers must use services, not direct DB access"
+    }
+  ]
+}
+```
+
+The test generator reads this file and adds custom rules to the test suite.
+
+## Integration
+
+- `vibe init` → auto-detect and generate initial arch-guard tests
+- `vibe update` → refresh rules if directory structure changed
+- Pre-commit hook → run arch-guard tests before commit
+- `vibe.review` (skill) → code-reviewer (focus: architecture) checks against arch-rules.json
+
+## Bundled internal: exec-plan
+
+
+# ExecPlan — Self-Contained Execution Plan Generator
+
+> **Principle**: "If the agent can't see it, it doesn't exist." Every decision, file path, pattern, and verification step must be explicit in the plan — no implicit knowledge allowed.
+
+## When to Use
+
+Before `/vibe.run`, generate an ExecPlan to make execution deterministic:
+
+| Scenario | Signal |
+|----------|--------|
+| Complex SPEC (3+ phases) | Agent needs long autonomous execution |
+| Team/multi-agent execution | Multiple agents need shared understanding |
+| Context window pressure | Plan survives `/new` session handoff |
+| Unfamiliar codebase | Agent can't rely on implicit knowledge |
+
+## Core Flow
+
+```
+SPEC + Feature → ANALYZE → RESOLVE → GENERATE → PERSIST
+```
+
+### Step 1: ANALYZE — Extract Everything Needed
+
+Read the SPEC and Feature files, then extract:
+
+```
+For each Phase → For each Scenario:
+  1. Requirements (REQ-* IDs)
+  2. Given/When/Then conditions
+  3. Affected files (MUST exist — verify with Glob)
+  4. Dependencies (imports, packages)
+  5. Existing patterns to follow (read actual code, don't assume)
+```
+
+**Parallel exploration** (3+ agents):
+- Agent 1: Map all file paths mentioned/implied in SPEC → verify they exist
+- Agent 2: For each affected file, extract current interfaces/types/exports
+- Agent 3: Find existing patterns (naming conventions, error handling, test structure)
+
+### Step 2: RESOLVE — Eliminate All Ambiguity
+
+For every decision point in the SPEC, resolve it NOW:
+
+| Ambiguity | Resolution |
+|-----------|------------|
+| "Add validation" | → Which fields? What rules? What error messages? |
+| "Handle errors" | → Which error codes? What response format? |
+| "Follow existing pattern" | → Copy the ACTUAL pattern code into the plan |
+| "Update tests" | → Which test file? What test framework? What assertions? |
+
+**Rule**: If you'd need to "figure it out later", resolve it now. The plan must be executable by an agent with ZERO codebase knowledge.
+
+### Step 3: GENERATE — Write the ExecPlan
+
+Output format: `.vibe/specs/{feature-name}-execplan.md`
+
+```markdown
+# ExecPlan: {feature-name}
+
+## Meta
+- SPEC: .vibe/specs/{name}.md
+- Feature: .vibe/features/{name}.feature
+- Generated: {timestamp}
+- Phases: {count}
+- Scenarios: {count}
+
+## Pre-flight Checks
+- [ ] `npm run build` passes
+- [ ] `npx vitest run` passes (baseline)
+- [ ] Required files exist: {list}
+
+## Phase {N}: {phase-name}
+
+### Environment
+- Files to modify: {exact paths}
+- Files to create: {exact paths}
+- Dependencies to add: {package@version}
+- Patterns to follow: (inline code snippets from codebase)
+
+### Scenario {N}.{M}: {scenario-name}
+
+**Given**: {precondition}
+→ Setup: {exact code/commands to establish precondition}
+
+**When**: {action}
+→ Implement: {step-by-step implementation instructions}
+  - File: {path}
+  - Location: after line containing `{anchor text}`
+  - Code: (inline snippet)
+  - Imports needed: {list}
+
+**Then**: {expected result}
+→ Verify:
+  - Command: `{test command}`
+  - Expected: {output/behavior}
+  - Fallback: {what to do if verification fails}
+
+### Phase {N} Gate
+- [ ] Build: `npm run build`
+- [ ] Tests: `npx vitest run {relevant-test-files}`
+- [ ] Type check: `npx tsc --noEmit`
+
+## Completion Criteria
+- Coverage threshold: ≥95%
+- All scenarios passing
+- No regressions in existing tests
+- RTM: `generateTraceabilityMatrix("{feature-name}")`
+```
+
+### Step 4: PERSIST — Save and Link
+
+1. Save ExecPlan to `.vibe/specs/{feature-name}-execplan.md`
+2. Save session context: `save_memory("execplan-{feature}", {summary})`
+3. Output execution command:
+
+```
+Ready to execute:
+  /vibe.run "{feature-name}" ultrawork
+
+Or hand off to new session:
+  /vibe.continue
+  → Load: .vibe/specs/{feature-name}-execplan.md
+```
+
+## Quality Checks
+
+| Check | Criteria |
+|-------|----------|
+| No implicit knowledge | Every file path verified with Glob |
+| No "figure it out" | Every decision resolved with actual code |
+| Survives handoff | Plan readable without any prior context |
+| Inline patterns | Actual code snippets, not "follow existing pattern" |
+| Verification steps | Every scenario has a concrete verification command |
+
+## Anti-patterns
+
+- "See the existing implementation" → Copy the relevant code inline
+- "Follow the pattern in X" → Show the actual pattern
+- "Standard error handling" → Specify exact error codes and messages
+- "Update tests accordingly" → Name the test file, framework, and assertions
+
+## Bundled internal: restraint
+
+
+# Restraint — Don't Write It, Don't Tune It (Yet)
+
+Two constraints, one gate:
+
+- **No premature code.** New abstractions must be *pulled* by a demonstrated
+  need, never pushed by "might need it later." Once the code exists, deleting
+  it costs more than never writing it.
+- **No premature optimization.** Performance work must be *pulled* by a
+  measurement, never by a hunch.
+
+## The YAGNI Ladder (code axis)
+
+Satisfy the need at the **highest** rung that covers it; lower rungs are
+blocked while a higher one applies:
+
+1. **Not needed** — the requirement doesn't ask for it → don't build it
+2. **Stdlib / built-ins** already do it (`crypto`, `Intl`, `pathlib`, …)
+3. **Native platform feature** does it (`<input type="date">`, CSS `:has()`, DB constraints)
+4. **Already-installed dependency** covers it — check the lockfile, don't guess
+5. **One line** — a single expression; no new file, no class
+6. **Minimal code** — only now, and nothing for "later"
+
+Tie-break: native beats a one-liner; stdlib beats a dependency. Generalize
+only when a *second* caller exists.
+
+## Pike's Rules (optimization axis)
+
+- You can't tell where a program spends its time — bottlenecks surprise.
+  **Measure; don't guess.**
+- Don't tune until one part *measurably* overwhelms the rest.
+- Fancy algorithms are slow when n is small — and n is usually small.
+  Ask "what's n?" before "what's the Big-O?"
+- Simple algorithms + the right data structures beat clever code. Data dominates.
+
+Optimization is justified only when ALL hold: a measured bottleneck exists →
+it dominates runtime → the fix is the simplest change addressing it → you
+re-measure after.
+
+## Blocked Impulses
+
+| Impulse | Constraint | Counter |
+|---|---|---|
+| helper / utility / wrapper / manager class | rungs 1–5 | a stdlib call or one line usually suffices |
+| config system for one value | rung 1 | a `const` is the config |
+| generic `Processor(strategy, validator…)` | rung 1 | one concrete function until a second caller exists |
+| "add a cache here" / "parallelize this" | measure first | is this path even hot? Often it's I/O |
+| swap in a B-tree / trie / skip list | what's n? | O(n²) with n=100 is microseconds |
+| "this loop looks slow" | measure first | the bottleneck is probably elsewhere |
+
+## Overrides — Restraint Never Erodes These
+
+1. **Security and trust-boundary work are requirements**, not optional
+   complexity. Input validation, auth checks, escaping stay in — "one line"
+   is no excuse to drop them.
+2. **Deliberate simplifications get a comment + upgrade path**, so the next
+   reader sees a *choice*, not an oversight:
+
+   ```ts
+   // Global lock is enough at current throughput.
+   // Switch to per-account locking if write contention shows up.
+   const lock = new Mutex();
+   ```

package/skills/{arch-guard → vibe.run/internal/arch-guard}/templates/violation-report.md

@@ -48,6 +48,6 @@ For each violation, choose one:
 ## Next Steps
 
 1. Fix all violations in the table above
-2. Re-run: `node skills/arch-guard/scripts/check-boundaries.js {{RULES_FILE}} {{SRC_DIR}}`
+2. Re-run: `node skills/vibe.arch-guard/scripts/check-boundaries.js {{RULES_FILE}} {{SRC_DIR}}`
 3. Commit clean state: `git commit -m "fix: resolve arch-guard boundary violations"`
 4. Add to CI: run check-boundaries.js in pre-commit or CI pipeline

package/skills/{seo-checklist → vibe.seo-checklist}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seo-checklist
+name: vibe.seo-checklist
 invocation: [auto]
 tier: core
 description: "SEO gotchas for web development — easy-to-miss items that hurt search ranking. Covers meta tags, Open Graph, structured data (JSON-LD), sitemap, robots.txt, canonical URLs, and Naver/Google-specific requirements. Use when building or reviewing any public-facing web page, landing page, or marketing site. Must use this skill when user mentions SEO, search ranking, meta tags, or when deploying a web app that needs to be discoverable."