start-vibing-stacks 1.0.0

package/stacks/_shared/agents/commit-manager.md

@@ -0,0 +1,65 @@
+---
+name: commit-manager
+description: "AUTOMATICALLY invoke as FINAL AGENT when implementation is complete. Creates conventional commits, merges to main."
+model: haiku
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills: git-workflow
+---
+
+# Commit Manager Agent
+
+You manage commits, merges, and are the FINAL agent in the workflow.
+
+## Workflow Order
+
+```
+domain-updater → commit-manager (YOU)
+```
+
+## Complete Git Flow
+
+```bash
+# 1. Check status
+git status && git diff --name-status
+
+# 2. Stage files
+git add -A
+
+# 3. Create commit
+git commit -m "type(scope): description
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# 4. Switch to main
+git checkout main
+
+# 5. Merge branch
+git merge [branch-name]
+
+# 6. Sync with remote
+git pull origin main --rebase || true
+git push origin main
+
+# 7. Delete feature branch
+git branch -d [branch-name]
+```
+
+## Conventional Commits
+
+| Type     | Use           |
+|----------|---------------|
+| feat     | New feature   |
+| fix      | Bug fix       |
+| docs     | Documentation |
+| test     | Tests         |
+| refactor | Code change   |
+| chore    | Maintenance   |
+
+## Critical Rules
+
+1. **NEVER commit without validators passing**
+2. **ALWAYS conventional commits**
+3. **NEVER force push main**
+4. **ALWAYS merge to main** — direct merge, no PRs
+5. **ALWAYS end on main branch**

package/stacks/_shared/agents/documenter.md

@@ -0,0 +1,82 @@
+---
+name: documenter
+description: "AUTOMATICALLY invoke AFTER any code implementation. Creates/updates domain documentation. PROACTIVELY runs after implementation."
+model: sonnet
+tools: Read, Write, Edit, Grep, Glob, Bash
+skills: docs-tracker, codebase-knowledge
+---
+
+# Documenter Agent
+
+You create and maintain domain documentation so Claude doesn't need to re-explore the codebase every session.
+
+## Step-by-Step
+
+### 1. Read Stack Config
+
+```bash
+cat .claude/config/active-project.json  # Know the stack, extensions
+```
+
+### 2. Detect Changed Files
+
+```bash
+git diff --name-only HEAD
+```
+
+### 3. Map Files to Domains
+
+Read `.claude/config/domain-mapping.json` for patterns.
+
+### 4. For Each Affected Domain
+
+**If exists** → Update "Last Update", add files, add commit
+**If not** → CREATE from template
+
+### 5. Domain File Template
+
+```markdown
+# {Domain Name}
+
+## Last Update
+- **Date:** {YYYY-MM-DD}
+- **Commit:** {hash}
+- **Summary:** {what changed}
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `path/file.ext` | Description |
+
+## Connections
+
+| Domain | How They Connect |
+|--------|-----------------|
+| {domain} | {description} |
+
+## Recent Commits
+
+| Hash | Date | Description |
+|------|------|-------------|
+| abc123 | YYYY-MM-DD | feat: description |
+
+## Attention Points
+
+- {Important consideration or gotcha}
+
+## Problems & Solutions
+
+### {Problem Title}
+**Problem:** {What went wrong}
+**Solution:** {How it was fixed}
+**Prevention:** {How to avoid in future}
+```
+
+## Critical Rules
+
+1. **RUN AFTER EVERY IMPLEMENTATION**
+2. **UPDATE DOMAINS, NOT JUST CLAUDE.MD**
+3. **INCLUDE COMMIT HASH**
+4. **DOCUMENT CONNECTIONS** bidirectionally
+5. **RECORD PROBLEMS** for future sessions

package/stacks/_shared/agents/domain-updater.md

@@ -0,0 +1,51 @@
+---
+name: domain-updater
+description: "AUTOMATICALLY invoke BEFORE commit-manager at session end. Records problems, solutions, and learnings in domain docs."
+model: haiku
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills: codebase-knowledge, docs-tracker
+---
+
+# Domain Updater Agent
+
+You record session LEARNINGS in domain docs. Different from documenter: documenter maps files, you record wisdom.
+
+## What You Add
+
+### 1. Problems & Solutions
+
+```markdown
+### {Date} - {Problem Title}
+**Problem:** {What went wrong}
+**Root Cause:** {Why it happened}
+**Solution:** {How it was fixed}
+**Prevention:** {How to avoid in future}
+```
+
+### 2. Attention Points
+
+```markdown
+- [YYYY-MM-DD] **Rule name** - Description of gotcha
+```
+
+### 3. Recent Commits
+
+```markdown
+| Hash | Date | Description |
+|------|------|-------------|
+| abc123 | YYYY-MM-DD | feat: what was done |
+```
+
+## Workflow Order
+
+```
+implementation → quality gates → domain-updater (YOU) → commit-manager
+```
+
+## Critical Rules
+
+1. **RUN BEFORE COMMIT** — changes included in same commit
+2. **DOCUMENT PROBLEMS** — future sessions benefit
+3. **INCLUDE SOLUTIONS** — not just what broke
+4. **PREVENTION TIPS** — how to avoid next time
+5. **DATE EVERYTHING**

package/stacks/_shared/agents/research-web.md

@@ -0,0 +1,60 @@
+---
+name: research-web
+description: "AUTOMATICALLY invoke BEFORE implementing any new feature or technology. Triggers: new feature, new technology, 'search', 'find info'. Web research specialist."
+model: sonnet
+tools: WebSearch, WebFetch, Read, Write
+skills: research-cache
+---
+
+# Research Web Agent
+
+You perform targeted web research for development questions.
+
+## Before Searching
+
+1. Read `.claude/config/active-project.json` → know the stack
+2. Check research-cache for existing results
+3. If cached & fresh → Return cached
+
+## Search Strategy
+
+```
+[topic] + [year] + [stack context]
+
+Examples (PHP):
+- "PHP 8.3 readonly classes best practices 2025"
+- "Laravel Octane RoadRunner performance tuning 2025"
+
+Examples (Node):
+- "Next.js 15 server actions best practices 2025"
+- "Bun vs Node.js performance 2025"
+```
+
+## Source Priority
+
+1. Official documentation
+2. GitHub issues/discussions
+3. Stack Overflow (recent answers)
+4. Technical blogs (verified authors)
+
+## Output Format
+
+```markdown
+## Research: [Topic]
+
+### Key Findings
+1. [Finding] - Source: [URL]
+
+### Recommendations
+- [Actionable recommendation]
+
+### Sources
+- [URL] - [Date accessed]
+```
+
+## Critical Rules
+
+1. **ALWAYS CHECK CACHE** - Avoid duplicate searches
+2. **CITE SOURCES** - Every finding needs URL
+3. **RECENT FIRST** - Prefer current year content
+4. **STACK-AWARE** - Use stack context in queries

package/stacks/_shared/agents/tester.md

@@ -0,0 +1,61 @@
+---
+name: tester
+description: "AUTOMATICALLY invoke AFTER implementing any function or utility. Creates tests using the stack-appropriate framework."
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills: test-coverage
+---
+
+# Tester Agent (Universal)
+
+You create tests using the stack-appropriate test framework.
+
+## Step 1: Read Stack Config
+
+```bash
+cat .claude/config/active-project.json
+```
+
+This tells you which framework to use:
+- **PHP** → PHPUnit
+- **Node.js/TS** → Vitest
+- **Python** → pytest
+
+## Step 2: Read Stack Test Skill
+
+Load the appropriate skill from `.claude/skills/`:
+- PHP → `phpunit-testing/SKILL.md`
+- Node → `vitest-testing/SKILL.md`
+
+## Step 3: Create Tests
+
+Follow the stack skill's patterns for:
+- File location and naming
+- Test structure (Arrange-Act-Assert)
+- Mocking patterns
+- Assertion style
+
+## Universal Rules (ALL stacks)
+
+1. **ISOLATED TESTS** — No dependencies between tests
+2. **CLEAN STATE** — Reset between tests
+3. **DESCRIPTIVE NAMES** — "should [behavior] when [condition]"
+4. **ARRANGE-ACT-ASSERT** — Clear structure
+5. **EDGE CASES** — Test null, empty, boundaries
+6. **NO .SKIP** — Never commit skipped tests
+7. **RUN AFTER WRITING** — Execute and fix failures
+
+## Running Tests
+
+Read `commands.test` from `.claude/config/active-project.json`:
+
+```bash
+# PHP
+vendor/bin/phpunit
+
+# Node.js
+bun run test
+
+# Python
+pytest
+```

package/stacks/_shared/commands/feature.md

@@ -0,0 +1,13 @@
+# /feature — Start New Feature
+
+Execute in order:
+
+1. **Research** → research-web agent (if new tech)
+2. **Plan** → Break into tasks, create TODO list
+3. **Implement** → Write code following stack patterns
+4. **Test** → tester agent (PHPUnit / Vitest / pytest)
+5. **Document** → documenter agent
+6. **Update domains** → domain-updater agent
+7. **Commit** → commit-manager agent
+
+Always read `.claude/config/active-project.json` first.

package/stacks/_shared/commands/fix.md

@@ -0,0 +1,9 @@
+# /fix — Fix Bug
+
+Execute in order:
+
+1. **Analyze** → Read error, reproduce, isolate
+2. **Fix** → Apply minimal fix
+3. **Test** → Add regression test (tester agent)
+4. **Document** → Record in domain Problems & Solutions
+5. **Commit** → commit-manager agent

package/stacks/_shared/commands/validate.md

@@ -0,0 +1,10 @@
+# /validate — Run Full Validation
+
+Read quality gates from `.claude/config/active-project.json` and run all:
+
+```bash
+# Read stack commands
+cat .claude/config/active-project.json | jq '.qualityGates'
+```
+
+Then execute each gate in order. Report pass/fail for each.

package/stacks/_shared/config/domain-mapping.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "Domain mapping - maps file patterns to documentation domains",
+  "domains": {
+    "authentication": {
+      "patterns": ["**/auth/**", "**/login/**", "**/session/**", "**/*auth*", "**/*login*"],
+      "description": "User authentication, sessions, tokens"
+    },
+    "api": {
+      "patterns": ["**/api/**", "**/routes/**", "**/routers/**", "**/controllers/**"],
+      "description": "API endpoints and routes"
+    },
+    "database": {
+      "patterns": ["**/models/**", "**/migrations/**", "**/db/**", "**/schemas/**", "**/*.model.*", "**/*.schema.*"],
+      "description": "Database models, schemas, migrations"
+    },
+    "ui-components": {
+      "patterns": ["**/components/**", "**/ui/**", "**/views/**", "**/templates/**"],
+      "description": "Reusable UI components"
+    },
+    "pages": {
+      "patterns": ["**/pages/**", "**/app/**/page.*", "**/app/**/layout.*"],
+      "description": "Page routes and layouts"
+    },
+    "utilities": {
+      "patterns": ["**/lib/**", "**/utils/**", "**/helpers/**", "**/common/**"],
+      "description": "Utility functions and helpers"
+    },
+    "testing": {
+      "patterns": ["**/tests/**", "**/*.test.*", "**/*.spec.*", "**/*Test.php"],
+      "description": "All test files"
+    },
+    "infrastructure": {
+      "patterns": ["**/docker*", "**/Dockerfile*", "**/.github/**", "**/scripts/**", "**/deploy/**"],
+      "description": "Docker, CI/CD, deployment"
+    }
+  },
+  "rules": {
+    "domainFileLocation": ".claude/skills/codebase-knowledge/domains/",
+    "requiredSections": ["Last Update", "Files", "Connections", "Recent Commits", "Attention Points"]
+  }
+}

package/stacks/_shared/config/security-rules.json

@@ -0,0 +1,31 @@
+{
+  "$comment": "Universal security rules. Agents read active-project.json for stack-specific additions.",
+  "validation": {
+    "requireOnAllRoutes": true
+  },
+  "sensitivePatterns": {
+    "forbidden": [
+      "eval(",
+      "exec(",
+      "system(",
+      "passthru(",
+      "shell_exec(",
+      "password:",
+      "passwordHash",
+      "apiKey:",
+      "secret:"
+    ]
+  },
+  "cookies": {
+    "httpOnly": true,
+    "secure": true,
+    "sameSite": "strict"
+  },
+  "owaspChecks": {
+    "a01_brokenAccessControl": true,
+    "a02_cryptographicFailures": true,
+    "a03_injection": true,
+    "a07_authenticationFailures": true,
+    "a09_securityLogging": true
+  }
+}

package/stacks/_shared/hooks/stop-validator.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Stop Validator Hook — Start Vibing Stacks (Universal)
+ *
+ * Reads active-project.json to determine stack-specific validations.
+ * Blocks task completion if:
+ * 1. Branch != main (work must be merged)
+ * 2. Git tree not clean
+ * 3. CLAUDE.md not updated
+ * 4. CLAUDE.md missing required sections
+ * 5. CLAUDE.md exceeds 40k chars
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+const CLAUDE_MD = join(PROJECT_DIR, 'CLAUDE.md');
+const ACTIVE_PROJECT = join(PROJECT_DIR, '.claude', 'config', 'active-project.json');
+const MAX_CHARS = 40000;
+
+// Load stack info
+let stackId = 'unknown';
+try {
+  if (existsSync(ACTIVE_PROJECT)) {
+    const config = JSON.parse(readFileSync(ACTIVE_PROJECT, 'utf8'));
+    stackId = config.stack || 'unknown';
+  }
+} catch {}
+
+// Source extensions per stack
+const STACK_EXTENSIONS: Record<string, Set<string>> = {
+  php: new Set(['.php', '.blade.php', '.twig']),
+  nodejs: new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs']),
+  python: new Set(['.py']),
+  go: new Set(['.go']),
+  rust: new Set(['.rs']),
+};
+
+const sourceExtensions = STACK_EXTENSIONS[stackId] || new Set(['.ts', '.js', '.php', '.py']);
+
+interface HookResult {
+  continue: boolean;
+  decision: 'approve' | 'block';
+  reason: string;
+}
+
+function cmd(command: string): string {
+  try {
+    return execSync(command, { cwd: PROJECT_DIR, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function getBranch(): string {
+  return cmd('git rev-parse --abbrev-ref HEAD') || 'unknown';
+}
+
+function getModifiedFiles(): string[] {
+  const staged = cmd('git diff --name-only --cached').split('\n').filter(Boolean);
+  const unstaged = cmd('git diff --name-only').split('\n').filter(Boolean);
+  const untracked = cmd('git ls-files --others --exclude-standard').split('\n').filter(Boolean);
+  return [...new Set([...staged, ...unstaged, ...untracked])];
+}
+
+function validate(): HookResult {
+  const branch = getBranch();
+  const isMain = branch === 'main' || branch === 'master';
+  const modified = getModifiedFiles();
+  const isClean = modified.length === 0;
+
+  // 1. Must be on main with clean tree
+  if (!isMain && modified.length > 0) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: `BLOCKED: On branch '${branch}' with ${modified.length} modified files.\n\nComplete git workflow:\n1. git add -A\n2. git commit -m "type: description"\n3. git checkout main\n4. git merge ${branch}\n5. git push origin main\n6. git branch -d ${branch}`,
+    };
+  }
+
+  if (!isMain) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: `BLOCKED: On branch '${branch}'. Switch to main:\n1. git checkout main\n2. git merge ${branch}\n3. git push origin main`,
+    };
+  }
+
+  if (!isClean) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: `BLOCKED: ${modified.length} uncommitted files:\n${modified.slice(0, 10).map(f => `  - ${f}`).join('\n')}\n\nCommit or stash before completing.`,
+    };
+  }
+
+  // 2. CLAUDE.md must exist
+  if (!existsSync(CLAUDE_MD)) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: 'BLOCKED: CLAUDE.md not found. Create it with required sections.',
+    };
+  }
+
+  const content = readFileSync(CLAUDE_MD, 'utf8');
+
+  // 3. Size check
+  if (content.length > MAX_CHARS) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: `BLOCKED: CLAUDE.md is ${content.length} chars (max ${MAX_CHARS}). Run claude-md-compactor agent.`,
+    };
+  }
+
+  // 4. Required sections
+  const required = [
+    { pattern: /^# .+/m, name: 'Project Title (H1)' },
+    { pattern: /^## Last Change/m, name: 'Last Change' },
+    { pattern: /^## Stack/m, name: 'Stack' },
+  ];
+
+  const missing = required.filter(r => !r.pattern.test(content)).map(r => r.name);
+  if (missing.length > 0) {
+    return {
+      continue: true,
+      decision: 'block',
+      reason: `BLOCKED: CLAUDE.md missing sections: ${missing.join(', ')}`,
+    };
+  }
+
+  // All good
+  return {
+    continue: false,
+    decision: 'approve',
+    reason: `ALL CHECKS PASSED ✅\nStack: ${stackId}\nBranch: ${branch}\nTree: Clean`,
+  };
+}
+
+async function main(): Promise<void> {
+  // Read stdin (hook input)
+  let hookInput: any = {};
+  try {
+    const chunks: string[] = [];
+    process.stdin.setEncoding('utf8');
+    const timeout = setTimeout(() => process.stdin.destroy(), 1000);
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    clearTimeout(timeout);
+    hookInput = JSON.parse(chunks.join('') || '{}');
+  } catch {}
+
+  // Prevent loop
+  if (hookInput.stop_hook_active) {
+    console.log(JSON.stringify({ continue: false, decision: 'approve', reason: 'Cycle detected' }));
+    process.exit(0);
+  }
+
+  const result = validate();
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
+
+main().catch(() => {
+  console.log(JSON.stringify({ continue: false, decision: 'approve', reason: 'Hook error' }));
+  process.exit(0);
+});

package/stacks/_shared/hooks/user-prompt-submit.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit Hook — Start Vibing Stacks
+ *
+ * Injects workflow instructions before each user prompt.
+ * Reads active-project.json for stack-specific context.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+const ACTIVE_PROJECT = join(PROJECT_DIR, '.claude', 'config', 'active-project.json');
+
+let stackName = 'Unknown';
+let qualityCmd = 'Run quality gates';
+try {
+  if (existsSync(ACTIVE_PROJECT)) {
+    const config = JSON.parse(readFileSync(ACTIVE_PROJECT, 'utf8'));
+    stackName = config.stack || 'Unknown';
+    // Read quality gates command from stack config
+    const stackConfig = join(PROJECT_DIR, '.claude', 'config', 'quality-gates.json');
+    if (existsSync(stackConfig)) {
+      const gates = JSON.parse(readFileSync(stackConfig, 'utf8'));
+      qualityCmd = gates.runAll || qualityCmd;
+    }
+  }
+} catch {}
+
+async function main(): Promise<void> {
+  let hookInput: any = {};
+  try {
+    const chunks: string[] = [];
+    process.stdin.setEncoding('utf8');
+    const timeout = setTimeout(() => process.stdin.destroy(), 1000);
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    clearTimeout(timeout);
+    hookInput = JSON.parse(chunks.join('') || '{}');
+  } catch {}
+
+  const prompt = hookInput.user_prompt || hookInput.prompt || '';
+  if (!prompt.trim()) {
+    console.log(JSON.stringify({ continue: true }));
+    process.exit(0);
+  }
+
+  const today = new Date().toISOString().split('T')[0];
+
+  const systemMessage = `TASK WORKFLOW (Stack: ${stackName}):
+
+0. READ both CLAUDE.md and .claude/config/active-project.json before changes.
+
+1. CREATE a detailed todo-list breaking down the request.
+   Include "Update CLAUDE.md" as final task.
+
+2. WORK through each item sequentially.
+
+3. Run quality gates: ${qualityCmd}
+
+4. COMMIT using conventional commits via commit-manager agent.
+
+5. UPDATE CLAUDE.md:
+   a. "## Last Change" (date: ${today}, branch, summary)
+   b. Update ALL affected rule/flow sections
+
+6. Run stop-validator before finishing.`;
+
+  console.log(JSON.stringify({ continue: true, systemMessage }));
+  process.exit(0);
+}
+
+main().catch(() => {
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});