start-vibing-stacks 1.0.0

package/stacks/_shared/skills/debugging-patterns/SKILL.md

@@ -0,0 +1,39 @@
+# Debugging Patterns
+
+## Universal Approach
+
+1. **Read the error** — fully, including stack trace
+2. **Reproduce** — confirm you can trigger it
+3. **Isolate** — minimal reproduction
+4. **Fix** — one change at a time
+5. **Test** — verify fix, add regression test
+6. **Document** — add to domain attention points
+
+## Stack-Specific Tools
+
+### PHP
+```bash
+# Error logs
+tail -f /var/log/php/error.log
+# Xdebug
+php -dxdebug.mode=debug script.php
+# Built-in server with errors
+php -S localhost:8000 -d display_errors=1
+```
+
+### Node.js
+```bash
+# Debug mode
+node --inspect script.js
+# Verbose logging
+DEBUG=* node script.js
+```
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| `var_dump` / `console.log` everywhere | Use proper debugger |
+| Fix symptom, not cause | Trace to root cause |
+| Skip writing test for fix | Always add regression test |
+| Leave debug code in commit | Clean before commit |

package/stacks/_shared/skills/docker-patterns/SKILL.md

@@ -0,0 +1,47 @@
+# Docker Patterns
+
+## PHP (PHP-FPM + Nginx)
+
+```dockerfile
+FROM php:8.3-fpm-alpine
+
+RUN apk add --no-cache \
+    libzip-dev \
+    && docker-php-ext-install pdo_mysql zip opcache
+
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+COPY . /var/www/html
+WORKDIR /var/www/html
+
+RUN composer install --no-dev --optimize-autoloader
+RUN chown -R www-data:www-data /var/www/html
+
+EXPOSE 9000
+CMD ["php-fpm"]
+```
+
+## Node.js (Multi-stage)
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+## Rules
+
+1. **Multi-stage builds** — smaller images
+2. **Alpine base** — minimal attack surface
+3. **.dockerignore** — exclude node_modules, .git
+4. **Non-root user** — security
+5. **Health checks** — always include

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -0,0 +1,35 @@
+# Git Workflow
+
+## Branch Naming
+
+```
+feature/short-description
+fix/bug-description
+refactor/what-changed
+chore/maintenance-task
+```
+
+## Commit Format (Conventional)
+
+```
+type(scope): description
+
+Body explaining what and why.
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Flow
+
+1. Create branch from main: `git checkout -b feature/name`
+2. Work, commit incrementally
+3. When done: merge to main, delete branch
+4. Push main to remote
+
+## Rules
+
+- NEVER force push main
+- ALWAYS conventional commits
+- ALWAYS end on main branch
+- ONE feature per branch

package/stacks/nodejs/stack.json

@@ -0,0 +1,87 @@
+{
+  "id": "nodejs",
+  "name": "Node.js / TypeScript",
+  "icon": "📦",
+  "runtime": "Bun / Node.js 20+",
+  "minVersion": "20.0.0",
+  "packageManager": "bun|npm|pnpm",
+  "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+  "testExtensions": ["*.test.ts", "*.spec.ts", "*.test.tsx"],
+  "detectFiles": ["package.json", "tsconfig.json", "bun.lockb", "next.config.js"],
+  "commands": {
+    "test": "bun run test",
+    "lint": "bun run lint",
+    "format": "bun run format",
+    "serve": "bun run dev",
+    "build": "bun run build",
+    "typecheck": "bun run typecheck"
+  },
+  "qualityGates": [
+    { "name": "TypeCheck", "command": "bun run typecheck", "required": true, "order": 1 },
+    { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
+    { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 4 }
+  ],
+  "frameworks": [
+    { "id": "nextjs", "name": "Next.js (App Router)", "icon": "▲", "detectFiles": ["next.config.js", "next.config.ts", "next.config.mjs"] },
+    { "id": "nuxt", "name": "Nuxt", "icon": "💚", "detectFiles": ["nuxt.config.ts"] },
+    { "id": "astro", "name": "Astro", "icon": "🚀", "detectFiles": ["astro.config.mjs"] },
+    { "id": "express", "name": "Express", "icon": "⚡" },
+    { "id": "fastify", "name": "Fastify", "icon": "🏎️" },
+    { "id": "vanilla", "name": "Vanilla Node.js", "icon": "📄" }
+  ],
+  "databases": [
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "sqlite", "name": "SQLite (Turso / libSQL)", "icon": "📁" },
+    { "id": "redis", "name": "Redis (Upstash)", "icon": "🔴" },
+    { "id": "none", "name": "None", "icon": "❌" }
+  ],
+  "frontendOptions": [
+    { "id": "react-tailwind", "name": "React 19+ / TailwindCSS 4+", "icon": "⚛️" },
+    { "id": "vue", "name": "Vue.js / Nuxt", "icon": "💚" },
+    { "id": "svelte", "name": "Svelte / SvelteKit", "icon": "🔥" },
+    { "id": "shadcn", "name": "shadcn/ui + Tailwind", "icon": "🎨" },
+    { "id": "none", "name": "API only — no frontend", "icon": "❌" }
+  ],
+  "deployTargets": [
+    { "id": "vercel", "name": "Vercel", "icon": "▲" },
+    { "id": "docker", "name": "Docker", "icon": "🐳" },
+    { "id": "vps-ssh", "name": "VPS (SSH)", "icon": "☁️" },
+    { "id": "railway", "name": "Railway", "icon": "🚂" },
+    { "id": "fly", "name": "Fly.io", "icon": "✈️" },
+    { "id": "netlify", "name": "Netlify", "icon": "🌐" }
+  ],
+  "skills": [
+    "typescript-strict",
+    "react-patterns",
+    "nextjs-app-router",
+    "zod-validation",
+    "vitest-testing"
+  ],
+  "requirements": [
+    {
+      "name": "Node.js",
+      "command": "node",
+      "versionFlag": "--version",
+      "minVersion": "20.0.0",
+      "installCommand": {
+        "macos": "brew install node",
+        "linux": "curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs"
+      },
+      "versionRegex": "v?(\\d+\\.\\d+\\.\\d+)"
+    },
+    {
+      "name": "Bun",
+      "command": "bun",
+      "versionFlag": "--version",
+      "minVersion": "1.0.0",
+      "installCommand": {
+        "macos": "brew install oven-sh/bun/bun",
+        "linux": "curl -fsSL https://bun.sh/install | bash"
+      },
+      "versionRegex": "(\\d+\\.\\d+\\.\\d+)"
+    }
+  ]
+}

package/stacks/php/config/quality-gates.json

@@ -0,0 +1,23 @@
+{
+  "gates": {
+    "phpstan": {
+      "command": "vendor/bin/phpstan analyse --level=6",
+      "description": "PHPStan static analysis (level 6)",
+      "required": true,
+      "order": 1
+    },
+    "phpunit": {
+      "command": "vendor/bin/phpunit",
+      "description": "PHPUnit tests",
+      "required": true,
+      "order": 2
+    },
+    "csFixer": {
+      "command": "vendor/bin/php-cs-fixer fix --dry-run --diff",
+      "description": "PHP-CS-Fixer code style",
+      "required": false,
+      "order": 3
+    }
+  },
+  "runAll": "vendor/bin/phpstan analyse --level=6 && vendor/bin/phpunit"
+}

package/stacks/php/skills/composer-workflow/SKILL.md

@@ -0,0 +1,78 @@
+# Composer Workflow
+
+## Requirements
+
+- **Composer >= 2.0**
+- **PHP >= 8.3**
+
+## Essential Commands
+
+```bash
+composer install              # Install from lock file (CI/deploy)
+composer update               # Update dependencies (dev only)
+composer require package/name # Add dependency
+composer require --dev pkg    # Add dev dependency
+composer dump-autoload -o     # Optimize autoloader (production)
+```
+
+## composer.json Structure
+
+```json
+{
+    "name": "vendor/project",
+    "type": "project",
+    "require": {
+        "php": ">=8.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0",
+        "phpstan/phpstan": "^2.0",
+        "friendsofphp/php-cs-fixer": "^3.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "test": "phpunit",
+        "lint": "phpstan analyse --level=6",
+        "format": "php-cs-fixer fix",
+        "check": [
+            "@lint",
+            "@test"
+        ]
+    },
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {}
+    }
+}
+```
+
+## PSR-4 Autoloading
+
+```
+src/
+├── Controllers/
+│   └── UserController.php    → App\Controllers\UserController
+├── Services/
+│   └── UserService.php       → App\Services\UserService
+├── Models/
+│   └── User.php              → App\Models\User
+└── Middleware/
+    └── AuthMiddleware.php     → App\Middleware\AuthMiddleware
+```
+
+## Rules
+
+1. **Always commit composer.lock**
+2. **Never edit vendor/**
+3. **Use `composer install` in CI/production** (not update)
+4. **PHP >= 8.3 in require** — enforce minimum version
+5. **PSR-4 autoloading** — no manual includes

package/stacks/php/skills/php-patterns/SKILL.md

@@ -0,0 +1,119 @@
+# PHP 8.3+ Patterns
+
+## Version Requirements
+
+- **PHP >= 8.3** — MANDATORY. Do not use deprecated patterns.
+- **Composer >= 2.0** — For dependency management.
+- Use strict types: `declare(strict_types=1);` in EVERY file.
+
+## Modern PHP Features (USE THESE)
+
+### Typed Properties & Constructor Promotion
+
+```php
+class User {
+    public function __construct(
+        private readonly string $name,
+        private readonly string $email,
+        private readonly int $age,
+    ) {}
+}
+```
+
+### Enums
+
+```php
+enum Status: string {
+    case Active = 'active';
+    case Inactive = 'inactive';
+    case Suspended = 'suspended';
+}
+```
+
+### Readonly Classes (8.2+)
+
+```php
+readonly class UserDTO {
+    public function __construct(
+        public string $name,
+        public string $email,
+    ) {}
+}
+```
+
+### Typed Class Constants (8.3+)
+
+```php
+class Config {
+    public const string APP_NAME = 'MyApp';
+    public const int MAX_RETRIES = 3;
+}
+```
+
+### Match Expression
+
+```php
+$result = match($status) {
+    'active' => handleActive(),
+    'inactive' => handleInactive(),
+    default => throw new \InvalidArgumentException("Unknown status: {$status}"),
+};
+```
+
+### Named Arguments
+
+```php
+$response = new Response(
+    content: $html,
+    status: 200,
+    headers: ['Content-Type' => 'text/html'],
+);
+```
+
+### Null-safe Operator
+
+```php
+$country = $user?->address?->country?->name;
+```
+
+### Fibers (8.1+)
+
+```php
+$fiber = new Fiber(function (): void {
+    $value = Fiber::suspend('fiber started');
+    echo "Resumed with: {$value}";
+});
+```
+
+## FORBIDDEN Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| `$var = isset($x) ? $x : $default` | `$var = $x ?? $default` |
+| `function foo($x)` (no types) | `function foo(string $x): void` |
+| `array()` | `[]` |
+| `mysql_*` functions | PDO or Doctrine |
+| Global variables | Dependency injection |
+| `eval()` | Never use eval |
+| Untyped properties | Always type properties |
+
+## Error Handling
+
+```php
+try {
+    $result = riskyOperation();
+} catch (SpecificException $e) {
+    logger()->error('Operation failed', [
+        'error' => $e->getMessage(),
+        'trace' => $e->getTraceAsString(),
+    ]);
+    throw new DomainException('Friendly message', 0, $e);
+}
+```
+
+## PSR Standards
+
+- **PSR-4**: Autoloading
+- **PSR-7**: HTTP Messages (if not using framework)
+- **PSR-12**: Coding Style
+- **PSR-15**: HTTP Handlers

package/stacks/php/skills/phpstan-analysis/SKILL.md

@@ -0,0 +1,68 @@
+# PHPStan Static Analysis
+
+## Setup
+
+```bash
+composer require --dev phpstan/phpstan
+```
+
+## Configuration (phpstan.neon)
+
+```neon
+parameters:
+    level: 6
+    paths:
+        - src
+        - app
+    excludePaths:
+        - vendor
+        - storage
+        - bootstrap/cache
+    checkMissingIterableValueType: false
+```
+
+## Levels
+
+| Level | What it checks |
+|-------|---------------|
+| 0 | Basic checks (unknown classes, functions) |
+| 1 | Possibly undefined variables, return types |
+| 2 | Unknown methods on all expressions |
+| 3 | Return types, property types |
+| 4 | Dead code, always true/false |
+| 5 | Argument types |
+| **6** | **MINIMUM for this project** — strict types |
+| 7 | Union types |
+| 8 | Nullable types everywhere |
+| 9 | Mixed type restrictions |
+
+## Running
+
+```bash
+vendor/bin/phpstan analyse                    # Default config
+vendor/bin/phpstan analyse --level=6 src/     # Specific level & path
+vendor/bin/phpstan analyse --generate-baseline # Generate baseline for legacy code
+```
+
+## Common Fixes
+
+```php
+// ❌ PHPStan error: Parameter $data has no type hint
+function process($data) {}
+
+// ✅ Fixed
+function process(array $data): void {}
+
+// ❌ PHPStan error: Method returns mixed
+function getData() { return $this->db->query(); }
+
+// ✅ Fixed
+/** @return array<string, mixed> */
+function getData(): array { return $this->db->query(); }
+```
+
+## Rules
+
+1. **Level 6 minimum** — no exceptions
+2. **Fix errors, don't ignore** — use baseline only for legacy code
+3. **Run before commit** — part of quality gates

package/stacks/php/skills/phpunit-testing/SKILL.md

@@ -0,0 +1,122 @@
+# PHPUnit Testing Skill
+
+## Setup
+
+```bash
+composer require --dev phpunit/phpunit
+```
+
+## Test File Location
+
+```
+tests/
+├── Unit/
+│   ├── Services/
+│   │   └── UserServiceTest.php
+│   └── Helpers/
+│       └── StringHelperTest.php
+├── Feature/
+│   └── Api/
+│       └── UserApiTest.php
+└── phpunit.xml
+```
+
+## Test Template
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Services;
+
+use PHPUnit\Framework\TestCase;
+use App\Services\UserService;
+
+final class UserServiceTest extends TestCase
+{
+    private UserService $service;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->service = new UserService();
+    }
+
+    public function testCreateUserWithValidData(): void
+    {
+        // Arrange
+        $data = ['name' => 'John', 'email' => 'john@test.com'];
+
+        // Act
+        $user = $this->service->create($data);
+
+        // Assert
+        $this->assertSame('John', $user->name);
+        $this->assertSame('john@test.com', $user->email);
+    }
+
+    public function testCreateUserThrowsOnInvalidEmail(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid email');
+
+        $this->service->create(['name' => 'John', 'email' => 'invalid']);
+    }
+
+    /**
+     * @dataProvider invalidDataProvider
+     */
+    public function testCreateUserRejectsInvalidData(array $data, string $expectedError): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage($expectedError);
+
+        $this->service->create($data);
+    }
+
+    public static function invalidDataProvider(): array
+    {
+        return [
+            'empty name' => [['name' => '', 'email' => 'a@b.com'], 'Name required'],
+            'empty email' => [['name' => 'John', 'email' => ''], 'Email required'],
+            'null data' => [[], 'Name required'],
+        ];
+    }
+}
+```
+
+## Mocking
+
+```php
+public function testServiceCallsRepository(): void
+{
+    $repo = $this->createMock(UserRepository::class);
+    $repo->expects($this->once())
+         ->method('save')
+         ->with($this->isInstanceOf(User::class))
+         ->willReturn(true);
+
+    $service = new UserService($repo);
+    $result = $service->create(['name' => 'John', 'email' => 'j@t.com']);
+
+    $this->assertTrue($result);
+}
+```
+
+## Running
+
+```bash
+vendor/bin/phpunit                          # All tests
+vendor/bin/phpunit tests/Unit/              # Unit only
+vendor/bin/phpunit --filter testCreateUser  # Specific test
+vendor/bin/phpunit --coverage-text          # With coverage
+```
+
+## Rules
+
+1. **One assertion concept per test**
+2. **Descriptive method names**: `testMethodName_Scenario_ExpectedResult`
+3. **Use data providers** for multiple inputs
+4. **setUp/tearDown** for shared state
+5. **Never skip tests** in commits

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -0,0 +1,80 @@
+# PHP Security Scan
+
+## OWASP Top 10 for PHP
+
+### A01 - Broken Access Control
+
+```php
+// ❌ NEVER trust user input for authorization
+$userId = $_GET['user_id'];
+$user = User::find($userId);
+
+// ✅ Use authenticated session
+$user = Auth::user();
+```
+
+### A02 - Cryptographic Failures
+
+```php
+// ❌ NEVER
+md5($password);
+sha1($password);
+
+// ✅ ALWAYS
+password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
+password_verify($input, $hash);
+```
+
+### A03 - Injection
+
+```php
+// ❌ SQL Injection
+$db->query("SELECT * FROM users WHERE id = {$_GET['id']}");
+
+// ✅ Prepared statements (PDO)
+$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
+$stmt->execute([':id' => $id]);
+
+// ✅ Prepared statements (MySQLi)
+$stmt = $db->prepare("SELECT * FROM users WHERE id = ?");
+$stmt->bind_param('i', $id);
+$stmt->execute();
+```
+
+### A07 - XSS Prevention
+
+```php
+// ❌ Raw output
+echo $userInput;
+
+// ✅ Always escape
+echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
+
+// ✅ In templates (Blade)
+{{ $userInput }}  // Auto-escaped
+{!! $trustedHtml !!}  // Only for trusted content
+```
+
+## Security Checklist
+
+- [ ] All SQL uses prepared statements
+- [ ] All output is escaped (htmlspecialchars)
+- [ ] CSRF tokens on all forms
+- [ ] Passwords use password_hash/verify
+- [ ] File uploads validated (type, size, extension)
+- [ ] Sessions use httpOnly + secure cookies
+- [ ] Input validated before processing
+- [ ] No `eval()`, `exec()` with user input
+- [ ] No `extract()` on user data
+- [ ] Headers: X-Content-Type-Options, X-Frame-Options, CSP
+
+## Sensitive Data Patterns (FORBIDDEN)
+
+| Pattern | Risk |
+|---------|------|
+| `$_GET` used directly in SQL | SQL Injection |
+| `echo $_POST[...]` | XSS |
+| `md5()` / `sha1()` for passwords | Weak hashing |
+| `eval($userInput)` | RCE |
+| `include $_GET['page']` | LFI/RFI |
+| `serialize()` user data | Object injection |