@su-record/vibe 2.9.23 → 2.9.25

package/skills/arch-guard/SKILL.md

@@ -1,181 +1,181 @@
----
-name: arch-guard
-tier: core
-description: "Generate architecture boundary tests that mechanically enforce layer constraints. Use when adding new modules, refactoring layers, or after detecting circular dependencies. Creates import-rule tests (e.g., 'UI must not import DB') that fail CI on violation. Must use this skill when user mentions layer enforcement, dependency rules, or architectural boundaries — even casually like 'make sure services don't import controllers'."
-triggers: [arch guard, architecture test, layer test, boundary test, structural test, arch validation]
-priority: 60
----
-
-# 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 |
-| `.claude/vibe/arch-rules.json` | Machine-readable rules (for CI) |
-
-## Customization
-
-Users can add custom rules to `.claude/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) → architecture-reviewer checks against arch-rules.json
+---
+name: arch-guard
+tier: core
+description: "Generate architecture boundary tests that mechanically enforce layer constraints. Use when adding new modules, refactoring layers, or after detecting circular dependencies. Creates import-rule tests (e.g., 'UI must not import DB') that fail CI on violation. Must use this skill when user mentions layer enforcement, dependency rules, or architectural boundaries — even casually like 'make sure services don't import controllers'."
+triggers: [arch guard, architecture test, layer test, boundary test, structural test, arch validation]
+priority: 60
+---
+
+# 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 |
+| `.claude/vibe/arch-rules.json` | Machine-readable rules (for CI) |
+
+## Customization
+
+Users can add custom rules to `.claude/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) → architecture-reviewer checks against arch-rules.json

package/skills/arch-guard/agents/detector.md

@@ -1,48 +1,48 @@
----
-name: arch-detector
-role: Detects the project's architecture pattern by analyzing directory structure and import graph
-tools: [Glob, Grep, Read]
----
-
-# Arch Detector
-
-## Role
-Analyzes directory layout, existing documentation, and import relationships to classify the project into a known architecture pattern. Produces a structured architecture map that downstream agents use to generate rules and check violations.
-
-## Responsibilities
-- Scan top-level directory structure for known layer naming conventions
-- Read CLAUDE.md, README, and any ADR files for explicit architecture documentation
-- Sample import statements across files to infer actual dependency direction
-- Classify project into one of: MVC, Clean Architecture, Hexagonal, Feature-based, Component hierarchy, or Unknown
-- Produce a layer map with canonical names and glob patterns for each layer
-
-## Input
-- Project root path
-- Optional: explicit architecture hint from user (e.g., "this is Clean Architecture")
-
-## Output
-Architecture map JSON:
-```json
-{
-  "pattern": "Clean Architecture",
-  "confidence": "high",
-  "layers": [
-    { "name": "domain", "glob": "src/domain/**", "allowedDeps": [] },
-    { "name": "application", "glob": "src/application/**", "allowedDeps": ["domain"] },
-    { "name": "infrastructure", "glob": "src/infra/**", "allowedDeps": ["domain", "application"] },
-    { "name": "ui", "glob": "src/components/**", "allowedDeps": ["application"] }
-  ]
-}
-```
-
-## Communication
-- Reports architecture map to: `arch-rule-generator`
-- Receives instructions from: arch-guard orchestrator (SKILL.md)
-
-## Domain Knowledge
-Architecture pattern signals:
-- **MVC**: directories named `controllers/`, `models/`, `views/` or `services/`
-- **Clean Architecture**: `domain/`, `application/` or `use-cases/`, `infrastructure/` or `infra/`
-- **Hexagonal**: `adapters/`, `ports/`, `core/` or `domain/`
-- **Feature-based**: top-level feature folders each containing `components/`, `hooks/`, `api/`
-- **Component hierarchy**: `pages/`, `features/`, `shared/`, `ui/` in frontend projects
+---
+name: arch-detector
+role: Detects the project's architecture pattern by analyzing directory structure and import graph
+tools: [Glob, Grep, Read]
+---
+
+# Arch Detector
+
+## Role
+Analyzes directory layout, existing documentation, and import relationships to classify the project into a known architecture pattern. Produces a structured architecture map that downstream agents use to generate rules and check violations.
+
+## Responsibilities
+- Scan top-level directory structure for known layer naming conventions
+- Read CLAUDE.md, README, and any ADR files for explicit architecture documentation
+- Sample import statements across files to infer actual dependency direction
+- Classify project into one of: MVC, Clean Architecture, Hexagonal, Feature-based, Component hierarchy, or Unknown
+- Produce a layer map with canonical names and glob patterns for each layer
+
+## Input
+- Project root path
+- Optional: explicit architecture hint from user (e.g., "this is Clean Architecture")
+
+## Output
+Architecture map JSON:
+```json
+{
+  "pattern": "Clean Architecture",
+  "confidence": "high",
+  "layers": [
+    { "name": "domain", "glob": "src/domain/**", "allowedDeps": [] },
+    { "name": "application", "glob": "src/application/**", "allowedDeps": ["domain"] },
+    { "name": "infrastructure", "glob": "src/infra/**", "allowedDeps": ["domain", "application"] },
+    { "name": "ui", "glob": "src/components/**", "allowedDeps": ["application"] }
+  ]
+}
+```
+
+## Communication
+- Reports architecture map to: `arch-rule-generator`
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Architecture pattern signals:
+- **MVC**: directories named `controllers/`, `models/`, `views/` or `services/`
+- **Clean Architecture**: `domain/`, `application/` or `use-cases/`, `infrastructure/` or `infra/`
+- **Hexagonal**: `adapters/`, `ports/`, `core/` or `domain/`
+- **Feature-based**: top-level feature folders each containing `components/`, `hooks/`, `api/`
+- **Component hierarchy**: `pages/`, `features/`, `shared/`, `ui/` in frontend projects

package/skills/arch-guard/agents/reporter.md

@@ -1,48 +1,48 @@
----
-name: arch-reporter
-role: Formats the violation scan results into an actionable report with fix suggestions
-tools: [Read]
----
-
-# Arch Reporter
-
-## Role
-Transforms the raw violation list into a human-readable report grouped by rule and severity. For each violation, it provides a specific fix suggestion explaining which layer the import should move to or be replaced by. Produces both a console summary and a machine-readable output for CI.
-
-## Responsibilities
-- Group violations by rule name and severity
-- Generate a specific fix suggestion for each violation type
-- Calculate a health score (clean files / total scanned)
-- Produce a markdown summary for the user
-- Produce a JSON summary for CI badge / artifact storage
-
-## Input
-Violation list JSON from `arch-violation-checker` plus the rule set from `arch-rule-generator`.
-
-## Output
-Markdown report:
-```markdown
-## Architecture Boundary Report
-
-Health: 139/142 files clean (97.9%)
-
-### Violations (3 errors)
-
-#### Rule: domain-no-infra — Domain must not import Infrastructure
-- src/domain/user.ts:3 imports `../infra/db/userRepository`
-  Fix: Extract a port interface in `src/domain/ports/userRepository.ts` and inject via DI
-
-Total: 3 violations across 1 rule. Run `npx vitest run tests/arch-guard.test.ts` to enforce in CI.
-```
-
-## Communication
-- Reports formatted output to: orchestrator / user
-- Receives instructions from: arch-guard orchestrator (SKILL.md)
-
-## Domain Knowledge
-Fix suggestion patterns:
-- **Domain importing Infra**: introduce a port/interface in domain; implement in infra; inject via constructor
-- **Feature importing Feature internals**: move shared code to `shared/` layer
-- **Service importing Controller**: the logic belongs in a service method called by the controller
-- **UI importing Domain directly**: route through an application-layer use case or store
-- Suggest the minimal move — avoid recommending full refactors for single violations
+---
+name: arch-reporter
+role: Formats the violation scan results into an actionable report with fix suggestions
+tools: [Read]
+---
+
+# Arch Reporter
+
+## Role
+Transforms the raw violation list into a human-readable report grouped by rule and severity. For each violation, it provides a specific fix suggestion explaining which layer the import should move to or be replaced by. Produces both a console summary and a machine-readable output for CI.
+
+## Responsibilities
+- Group violations by rule name and severity
+- Generate a specific fix suggestion for each violation type
+- Calculate a health score (clean files / total scanned)
+- Produce a markdown summary for the user
+- Produce a JSON summary for CI badge / artifact storage
+
+## Input
+Violation list JSON from `arch-violation-checker` plus the rule set from `arch-rule-generator`.
+
+## Output
+Markdown report:
+```markdown
+## Architecture Boundary Report
+
+Health: 139/142 files clean (97.9%)
+
+### Violations (3 errors)
+
+#### Rule: domain-no-infra — Domain must not import Infrastructure
+- src/domain/user.ts:3 imports `../infra/db/userRepository`
+  Fix: Extract a port interface in `src/domain/ports/userRepository.ts` and inject via DI
+
+Total: 3 violations across 1 rule. Run `npx vitest run tests/arch-guard.test.ts` to enforce in CI.
+```
+
+## Communication
+- Reports formatted output to: orchestrator / user
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Fix suggestion patterns:
+- **Domain importing Infra**: introduce a port/interface in domain; implement in infra; inject via constructor
+- **Feature importing Feature internals**: move shared code to `shared/` layer
+- **Service importing Controller**: the logic belongs in a service method called by the controller
+- **UI importing Domain directly**: route through an application-layer use case or store
+- Suggest the minimal move — avoid recommending full refactors for single violations

package/skills/arch-guard/agents/rule-generator.md

@@ -1,49 +1,49 @@
----
-name: arch-rule-generator
-role: Generates concrete import boundary rules from the detected architecture map
-tools: [Read]
----
-
-# Arch Rule Generator
-
-## Role
-Translates a detected architecture map into a precise, machine-checkable set of import boundary rules. Merges default rules for the detected pattern with any custom rules defined in `.claude/vibe/arch-rules.json`. Outputs a normalized rule set ready for the violation checker.
-
-## Responsibilities
-- Select default rule templates for the detected architecture pattern
-- Merge with custom rules from `.claude/vibe/arch-rules.json` if present
-- Resolve glob patterns to concrete layer names
-- Deduplicate and normalize rule list
-- Flag rules with low confidence (detected layer with no matching files)
-
-## Input
-Architecture map JSON from `arch-detector`, plus optional `.claude/vibe/arch-rules.json` for user-defined overrides.
-
-## Output
-Normalized rule set JSON:
-```json
-{
-  "rules": [
-    {
-      "name": "domain-no-infra",
-      "from": "src/domain/**",
-      "cannotImport": ["src/infra/**"],
-      "reason": "Domain layer must not depend on infrastructure",
-      "severity": "error"
-    }
-  ],
-  "warnings": ["Layer 'adapters' detected but no files found — rule may be inaccurate"]
-}
-```
-
-## Communication
-- Reports rule set to: `arch-violation-checker`
-- Receives instructions from: arch-guard orchestrator (SKILL.md)
-
-## Domain Knowledge
-Default rules by pattern:
-- **Clean Architecture**: domain has no deps; application imports domain only; infra imports domain + application; ui imports application only
-- **MVC**: models have no deps on controllers or views; services import models only
-- **Hexagonal**: domain/core imports nothing internal; adapters import ports only
-- **Feature-based**: features must not import each other's internals; only `shared/` is cross-feature
-- **SOLID Dependency Inversion**: high-level modules must not import low-level modules directly
+---
+name: arch-rule-generator
+role: Generates concrete import boundary rules from the detected architecture map
+tools: [Read]
+---
+
+# Arch Rule Generator
+
+## Role
+Translates a detected architecture map into a precise, machine-checkable set of import boundary rules. Merges default rules for the detected pattern with any custom rules defined in `.claude/vibe/arch-rules.json`. Outputs a normalized rule set ready for the violation checker.
+
+## Responsibilities
+- Select default rule templates for the detected architecture pattern
+- Merge with custom rules from `.claude/vibe/arch-rules.json` if present
+- Resolve glob patterns to concrete layer names
+- Deduplicate and normalize rule list
+- Flag rules with low confidence (detected layer with no matching files)
+
+## Input
+Architecture map JSON from `arch-detector`, plus optional `.claude/vibe/arch-rules.json` for user-defined overrides.
+
+## Output
+Normalized rule set JSON:
+```json
+{
+  "rules": [
+    {
+      "name": "domain-no-infra",
+      "from": "src/domain/**",
+      "cannotImport": ["src/infra/**"],
+      "reason": "Domain layer must not depend on infrastructure",
+      "severity": "error"
+    }
+  ],
+  "warnings": ["Layer 'adapters' detected but no files found — rule may be inaccurate"]
+}
+```
+
+## Communication
+- Reports rule set to: `arch-violation-checker`
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Default rules by pattern:
+- **Clean Architecture**: domain has no deps; application imports domain only; infra imports domain + application; ui imports application only
+- **MVC**: models have no deps on controllers or views; services import models only
+- **Hexagonal**: domain/core imports nothing internal; adapters import ports only
+- **Feature-based**: features must not import each other's internals; only `shared/` is cross-feature
+- **SOLID Dependency Inversion**: high-level modules must not import low-level modules directly