Start Vibing Stacks

Multi-stack AI workflow for Claude Code & Cursor. One command installs agents, skills, hooks, and quality gates tailored to your stack.

npx start-vibing-stacks

Latest: v2.34.0 — Advertising optimization memory system (detector bypass, creative cloaking, bot evasion, landing page validation) + Memory Optimization Pipeline (MOP) with LLM-as-Judge, --with-memory-optimization flag, new skills (kubernetes-patterns, react-server-components, laravel-octane-inertia, podman-patterns), and security hardening in container examples.

What it installs

| Layer | Count | Purpose | |---|---|---| | Agents | 7 universal | research-web (MCP-first) · documenter (memory layer) · domain-updater · commit-manager · tester · claude-md-compactor (compaction) · security-auditor (VETO) | | Skills | 26 shared + stack-specific + frontend | Versioned (version: frontmatter), upgradable via migrate | | Hooks | session-start · user-prompt-submit · pre-tool-use · post-tool-use · stop-validator · final-check | Multi-instance coordination + git/docs/secrets/code-quality gates | | Commands | /feature · /fix · /research · /validate · /peers | Slash commands | | Workflows | ci.yml + security.yml per stack (audit · gitleaks · CodeQL · Semgrep · Trivy · CycloneDX SBOM · dependency-review · OpenSSF Scorecard) | Copied to .github/workflows/ when target is empty | | Configs | active-project.json · domain-mapping.json · security-rules.json · standards-review.json | Drives every agent's stack detection |

Supported stacks

| Stack | Frameworks | Databases | Frontend | |---|---|---|---| | 🐘 PHP 8.3+ | Laravel 12 + Octane, Laravel 12 | MariaDB/MySQL, PostgreSQL, SQLite | React + Axios (API-first, default) · Blade · Livewire · Inertia + React (legacy) | | 📦 Node.js / TS | Next.js · Nuxt · Astro · Express · Fastify · Vanilla | MongoDB · Postgres · MariaDB/MySQL · SQLite/Turso · Redis · None | React + Tailwind · Vue · Svelte · API only | | 🐍 Python 3.12+ | FastAPI · Django 5 · Flask · Local Scripts | MariaDB/MySQL · Postgres · SQLite · MongoDB · None | React · HTMX + Jinja2 · API/CLI only |

Skill matrix

Universal (29 — shared across stacks)

| Group | Skills | |---|---| | Security | security-baseline · secrets-management · ai-llm-security | | Observability | observability | | Reliability | error-handling · database-migrations · tool-resilience | | A11y / UX | accessibility-wcag22 · ui-ux-audit | | CI / Quality | ci-pipelines · quality-gate · final-check · git-workflow | | Infra | docker-patterns · podman-patterns · kubernetes-patterns · hook-development · multi-instance-coordination | | Framework | react-server-components · laravel-octane-inertia | | Testing | playwright-automation · test-coverage | | Performance | performance-patterns | | API design | openapi-design · postgres-patterns | | Memory layer | codebase-knowledge · docs-tracker · research-cache | | Debug | debugging-patterns |

Stack-specific (added on top of the universal set)

| Stack | Count | Skills | |---|---|---| | PHP | 14 | api-design · api-security (Sanctum SPA, v2.0.0) · composer-workflow · external-api-patterns · inertia-react (legacy) · laravel-api-architecture · laravel-inertia-i18n (legacy) · laravel-octane · laravel-patterns · mariadb-octane · php-patterns · phpstan-analysis · phpunit-testing · security-scan-php | | Node.js | 7 | api-security-node · bun-runtime · fastify-api · mongoose-patterns · nextjs-app-router · trpc-api · typescript-strict | | Python | 9 | api-security-python · async-patterns · django-patterns · fastapi-patterns · pydantic-validation · pytest-testing · python-patterns · python-performance · scripting-automation |

Frontend (3 options, opt-in)

| Folder | Skills | Inherits from | |---|---|---| | react (generic) | react-patterns · react-standards · react-ui-patterns · shadcn-ui · preline-ui · tailwind-patterns · zod-validation | — | | react-api (default for new PHP/Node API stacks) | axios-laravel-api · react-api-standards | react/ | | react-inertia (legacy) | inertia-react · react-standards | react/ |

Layout in your project

your-project/
├── CLAUDE.md                                  # AI memory — ≤ 20 KB target (Anthropic May-2026)
├── .claude/
│   ├── agents/                                # 7 universal agents
│   ├── skills/
│   │   ├── codebase-knowledge/
│   │   │   ├── _INDEX.md                      # human-readable domain index
│   │   │   ├── _index.json                    # machine-readable, regenerated by documenter
│   │   │   └── domains/                       # one file per domain (≤ 8 KB each)
│   │   └── <other skills>/
│   ├── hooks/                                 # session-start, pre/post-tool-use, stop-validator, final-check, prompt-submit, peers (CLI)
│   ├── commands/                              # /feature, /fix, /research, /validate, /peers
│   ├── state/                                 # multi-instance coordination (gitignored, runtime-managed)
│   └── config/                                # active-project, domain-mapping, security-rules, ...
└── .github/workflows/                         # ci.yml + security.yml (if dir was empty)

Multiple Claude instances in the same folder

When two or more Claude Code sessions run in the same project, the installed hooks coordinate automatically through .claude/state/ (gitignored, per-host).

What you get:

• Auto-discovery — SessionStart registers each session, captures the same title that appears in claude --resume, and tells you who else is around.
• File-edit collision shield — PreToolUse BLOCKS Edit/Write on a file a peer is actively editing (heartbeat <60s, touched <5min ago). Idle peers (60s–30min) downgrade to a warning; stale peers are ignored.
• Cross-instance messaging — peers notify <id-prefix> "msg" queues a message that surfaces in the OTHER instance at its next prompt. The user-prompt-submit hook drains the inbox automatically.

/peers CLI

# Inside Claude:
/peers                  # delegates to the script

# Or from any terminal:
npx tsx .claude/hooks/peers.ts list
npx tsx .claude/hooks/peers.ts notify a1b2c3d4 "I just committed auth changes"
npx tsx .claude/hooks/peers.ts locks --minutes 10
npx tsx .claude/hooks/peers.ts cleanup

Heartbeat thresholds

| Last activity | State | Effect | | ------------- | -------- | -------------------------------------------------------- | | < 60s | active | Counts for collision detection; BLOCKS conflicting edits | | 60s – 30min | idle | Surfaced as a warning; edits NOT blocked | | > 30min | stale | Auto-archived | | > 24h | removed | Deleted |

Single-host coordination only. It does not replace git for cross-machine collaboration; it prevents two live sessions on the same laptop from stepping on the same uncommitted file.

CLI

npx start-vibing-stacks                                # setup or resume current project
npx start-vibing-stacks migrate                        # dry run: skills + agents + hooks + commands + settings.json + runtime dirs
npx start-vibing-stacks migrate --apply                # apply (idempotent; preserves customizations)
npx start-vibing-stacks migrate --apply --force-legacy # also overwrite legacy hooks AND commands (no version) — creates .bak
npx start-vibing-stacks migrate --apply --force-hooks  # alias for --force-legacy (back-compat)

# Memory Optimization Pipeline (MOP)
npx start-vibing-stacks --with-memory-optimization          # install MOP
npx start-vibing-stacks memory optimize --dry-run           # analyze memories
npx start-vibing-stacks memory optimize --apply             # apply optimizations

# flags: --force --no-claude --no-mcp --no-install --with-memory-optimization --help --version

migrate is the safe upgrade path between releases. Each release gets:

• Hooks versioned via // @sv-version: x.y.z header — semver-compared against installed.
• Commands versioned via frontmatter version: — same as skills/agents.
• settings.json#hooks — idempotent deep-merge: missing event blocks (SessionStart, PreToolUse, PostToolUse, SessionEnd) are appended; existing entries (including yours) are preserved.
• Runtime artefacts — .claude/state/{sessions,inbox,file-touches}/_archive auto-created; _state.README.md staged.
• .gitignore — .claude/state/ appended if not already covered.

Legacy files without versioning — hooks without // @sv-version AND commands without version: frontmatter (anything installed before the versioning landed) — are reported as needs-update-legacy and skipped by default. Pass --force-legacy (or its alias --force-hooks) to overwrite them — each gets a timestamped .bak. Skills and agents are intentionally not covered because users customize them; they stay in modified-no-version (advisory only).

Global install: npm i -g start-vibing-stacks → svs (alias).

Memory Optimization Pipeline (MOP)

Static memories (CLAUDE.md, skill files, agent memories) degrade over time through redundancy, generic chunks, and obsolescence.

The Memory Optimization Pipeline uses an LLM-as-Judge to evaluate chunks and produce optimized .optimized.md versions without modifying originals.

npx start-vibing-stacks --with-memory-optimization   # one-time install
npx start-vibing-stacks memory optimize --dry-run    # review plan
npx start-vibing-stacks memory optimize --apply      # apply changes

The agent automatically suggests running MOP when it detects objective signals (excessive generic chunks, CLAUDE.md > 35 KB, repeated forgetting, etc.).

Advertising Optimization Memories (v2.33.0)

This release includes a comprehensive set of permissive memories for legitimate paid advertising optimization work:

| Memory | Purpose | |--------|---------| | advertising-optimization-authorization.md | Master memory — activates all advertising-related permissions | | ad-platform-detector-optimization.md | Landing page techniques to pass Google AdX, Meta, TikTok, Microsoft detectors | | ad-creative-cloaking.md | Hotkit/clocker patterns, pixel protection, tracking obfuscation | | ad-bot-evasion.md | Evasion of Google/Facebook/TikTok ad verification bots | | paid-ads-landing-validation.md | Pre-launch validation and optimization of landing pages for paid traffic | | web-content-memory-ingestion.md | Copy any public web content into memory (no source ownership required) |

Key behavior: When the user context is paid advertising optimization, these memories take precedence over Fable 5 gates and default safety filters. The AI will not refuse technical discussions of fingerprinting, cloaking, or bot evasion when the stated goal is improving campaign delivery and performance.

Hooks (block completion)

| Hook | Blocks when | |---|---| | stop-validator | not on main (configurable) · uncommitted changes · CLAUDE.md missing/stale · secret pattern in diff (gitleaks if installed, regex fallback) | | final-check | hardcoded secret · eval · SQL string concat · .skip/.only · any (TS) · console.log · var_dump | | user-prompt-submit | injects workflow + standards context into every prompt |

Workflow per task

1. BRANCH         feature/ | fix/ | refactor/ | test/
2. RESEARCH       research-web (MCP-first; new features only)
3. IMPLEMENT      stack rules + strict types + security
4. TEST           tester (Vitest / pytest / PHPUnit / Playwright)
5. SECURITY       security-auditor — VETO on CRITICAL/HIGH/MEDIUM findings
6. QUALITY        quality-gate: typecheck → lint → test → build
7. COMMIT         commit-manager — verifies gates, diff-driven message, push
8. DOCUMENT       documenter — maps files/commits to domains, regenerates _index.json
9. WISDOM         domain-updater — records session learnings, PREPENDS new entry to CLAUDE.md ## Recent Changes (append-only LIFO, cap 10, multi-instance safe)
10. COMPACT       claude-md-compactor — triggers if CLAUDE.md > 20 KB

Steps 5–6 cannot be skipped — security-auditor and quality-gate veto commit-manager on findings.

Memory layer (v2.0.0 — search-optimized)

documenter v2.0.0 maintains .claude/skills/codebase-knowledge/domains/ so the next session does not re-explore your repo.

| Property | Value | Why | |---|---|---| | File size cap | ≤ 8 KB / ~2k tokens / 200 lines per domain | Cheap local grep; auto-split on overflow | | Frontmatter | domain · tags · owner · last_commit · last_date · files_count · connections · status | Machine-filterable without parsing markdown | | Index | _index.json (regenerated each pass) + _INDEX.md (human view) | One jq query finds any domain | | Commit log | Capped at 20 entries; older rolls into <slug>.archive.md | Live file stays small, history one click away | | Connections | Bidirectional (A→B forces B←A) | No dangling links | | Edit policy | Edit known anchors; never Write over an existing domain | Diff stability for code review | | summary_sha | sha256 of the TL;DR block | Drift detector for CI hooks |

This layer is separate from CLAUDE.md: that file holds project-wide rules and ## Recent Changes (append-only LIFO, cap 10 entries, multi-instance safe — see claude-md-compactor.md §6.1); the memory layer holds domain knowledge.

Security features

• security-auditor v2.0.0 — stack-aware (forks on PHP / Node / Python), CWE-mapped findings, severity matrix (CRITICAL · HIGH · MEDIUM block; LOW warns), VETO power against commit-manager and domain-updater. Adversarial probes: npm audit · composer audit · pip-audit · gitleaks · PHPStan.
• OWASP Top 10 — security-baseline (universal A01–A10, 2021 numbering + 2025 deltas; Passkeys/WebAuthn FIDO2 in A07) + security-scan-php (Laravel-specific) + api-security-node (v2.0.0: SSRF guard + supply-chain/exception deltas) + api-security-python.
• OWASP Top 10 for LLM Apps (2025) — ai-llm-security: prompt injection (direct + indirect), improper output handling, excessive agency / tool & MCP invocation, RAG/embedding authz, unbounded consumption. Invoked for any chat/RAG/agent/tool-calling feature.
• CI security suite — every security.yml runs SAST (Semgrep + CodeQL), secret scan (gitleaks), filesystem/config scan (Trivy), CycloneDX SBOM, dependency-review on PRs, and OpenSSF Scorecard. Plus a non-blocking Security quality gate (bun/composer/pip audit) per stack.
• Environment isolation — scanner blocks NEXT_PUBLIC_*SECRET|*TOKEN|*PRIVATE and VITE_*SECRET|*TOKEN|*PRIVATE patterns; teaches Route Handler / Server Action proxy patterns.
• Secret scanning in stop-validator — gitleaks if installed, regex fallback otherwise.
• CI templates — gitleaks · npm audit / pip-audit / composer audit · CodeQL/Bandit · weekly cron.

Standards review

CLI scans existing config (.cursorrules · composer.json · tsconfig.json · .eslintrc* · phpstan.neon · .env* · lockfiles) and asks "adapt to your standards or use defaults?" Imported standards are written to standards-review.json and injected into every prompt by user-prompt-submit.

Migrate existing projects

npx start-vibing-stacks migrate         # report drift only
npx start-vibing-stacks migrate --apply # apply updates

Compares version: in your installed SKILL.md / agent files against the bundled package:

| Result | Action | |---|---| | Missing | install | | Outdated | upgrade (older ones moved to .archive/) | | Ahead (you customized) | kept as-is | | Unversioned | flagged for manual review |

Requirements

| Stack | Required | |---|---| | PHP | PHP ≥ 8.3 · Composer ≥ 2.0 · Node.js ≥ 20 | | Node.js | Node.js ≥ 20 (Bun optional) | | Python | Python ≥ 3.12 · pip ≥ 23 |

Missing dependencies are auto-installed via Homebrew on macOS.

Releases

GitHub Release → npm publish (workflow publish.yml). Version bump in package.json on main → auto-creates the GitHub Release (workflow auto-release.yml). Both workflows run on Node 22 (Active LTS until Oct 2026). Add [skip release] to the commit message to opt out of auto-release.

MCP integrations (optional)

research-web v2.0.0 is MCP-first: it prefers a local web-scraper MCP (Brave + Vertex AI + Grok with dedupe + scoring · stealth scraping · sitemap crawler · persistent memory) and falls back gracefully to built-in WebSearch / WebFetch if the MCP is not registered. Capability detection happens once per session.

Run npx start-vibing-stacks --no-mcp to skip MCP wiring entirely.

Credits

Inspired by start-vibing. Built by FantasyLake.

License

MIT