start-vibing-stacks 2.6.0 → 2.7.3

package/README.md

@@ -1,183 +1,131 @@
 # Start Vibing Stacks
 
-**Multi-stack AI-powered development workflow for Claude Code & Cursor.**
-
-One command to set up agents, skills, hooks, security rules, and quality gates — tailored to your stack.
+Multi-stack AI workflow for Claude Code & Cursor. One command installs agents, skills, hooks, and quality gates tailored to your stack.
 
 ```bash
 npx start-vibing-stacks
 ```
 
-## What It Does
-
-Start Vibing Stacks transforms Claude Code into a stack-aware AI partner. Instead of a generic assistant, you get an AI that understands your framework, enforces your coding standards, and blocks insecure patterns — all before a single line of code is written.
+## What It Installs
 
-```
-You run the CLI
-    ↓
-Detects your stack (PHP/Node.js) from project files
-    ↓
-Scans existing standards (.cursorrules, composer.json, tsconfig, eslint, .env)
-    ↓
-Asks: adapt to YOUR standards or use defaults?
-    ↓
-Copies 6 agents + 25-40 skills + hooks + security rules
-    ↓
-Generates CLAUDE.md with architecture, rules, FORBIDDEN patterns
-    ↓
-Launches Claude Code — fully configured
-```
+| Layer | Count | Purpose |
+|---|---|---|
+| Agents | 7 universal | research-web, documenter, domain-updater, commit-manager, tester, claude-md-compactor, **security-auditor** (VETO) |
+| Skills | 13 shared + 5–13 stack-specific + 7–9 frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
+| Hooks | `stop-validator`, `final-check`, `user-prompt-submit` | Block completion on git/docs/secrets/code-quality issues |
+| Commands | `/feature`, `/fix`, `/research`, `/validate` | Slash commands |
+| Workflows | `ci.yml` + `security.yml` per stack | Copied to `.github/workflows/` when target is empty |
 
 ## Supported Stacks
 
-### PHP 8.3+
+| Stack | Frameworks | Databases | Frontend |
+|---|---|---|---|
+| 🐘 **PHP 8.3+** | Laravel 12 + Octane, Laravel 12 | MariaDB/MySQL, PostgreSQL, SQLite | Inertia + React, Blade, Livewire, API only |
+| 📦 **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 |
 
-| Option | Choices |
-|--------|---------|
-| **Frameworks** | Laravel 12 + Octane (RoadRunner) + Inertia.js, Laravel 12 (standard) |
-| **Databases** | MySQL / MariaDB, PostgreSQL, SQLite |
-| **Frontend** | React 19 + Inertia.js + TailwindCSS 4, Blade + TailwindCSS, Livewire + Alpine.js, API only |
-| **Skills** | 13 PHP-specific (Octane, PHPStan, PHPUnit, Eloquent, API Security, Inertia i18n, ...) |
+## Universal Skills (shared across stacks)
 
-### Node.js / TypeScript
+| Skill | Topic |
+|---|---|
+| `security-baseline` | OWASP Top 10 with stack-aware examples |
+| `secrets-management` | `.env` hygiene, gitleaks, rotation playbook |
+| `observability` | Structured logs, OpenTelemetry, Sentry, PII redaction |
+| `error-handling` | Result types, error taxonomy, retry/backoff, circuit breaker |
+| `database-migrations` | Parallel change, lock timeouts, chunked backfills |
+| `accessibility-wcag22` | WCAG 2.2 AA + axe-core/Playwright |
+| `ci-pipelines` | GitHub Actions discipline + ready-to-use templates |
+| `quality-gate` · `final-check` · `git-workflow` · `docker-patterns` · `debugging-patterns` · `performance-patterns` · `playwright-automation` · `test-coverage` · `ui-ux-audit` · `codebase-knowledge` · `docs-tracker` · `research-cache` · `hook-development` | Workflow & tooling |
 
-| Option | Choices |
-|--------|---------|
-| **Frameworks** | Next.js (App Router), Nuxt, Astro, Express, Fastify, Vanilla Node.js |
-| **Databases** | MongoDB, PostgreSQL, MySQL, SQLite/Turso, Redis (Upstash), None |
-| **Frontend** | React 19 + TailwindCSS 4, Vue.js / Nuxt, Svelte / SvelteKit, API only |
-| **Skills** | 5 Node-specific (TypeScript strict, Next.js App Router, tRPC, Bun, Mongoose) + 9 frontend skills |
+Plus stack-specific: `api-security-node`, `api-security-python`, `api-security` (PHP), `typescript-strict`, `nextjs-app-router`, `trpc-api`, `bun-runtime`, `mongoose-patterns`, `pydantic-validation`, `pytest-testing`, `python-patterns`, `python-performance`, `async-patterns`, `fastapi-patterns`, `django-patterns`, `scripting-automation`, `laravel-patterns`, `laravel-octane`, `phpstan-analysis`, `phpunit-testing`, `composer-workflow`, `mariadb-octane`, `external-api-patterns`, `inertia-react`, `laravel-inertia-i18n`, `security-scan-php`, `api-design`, `php-patterns`.
 
-### Python (Coming Soon)
-
-Django, FastAPI, Flask support is planned.
-
-## What Gets Installed
+## Layout in Your Project
 
 ```
 your-project/
-├── CLAUDE.md                    # AI memory — architecture, rules, FORBIDDEN patterns
-└── .claude/
-    ├── agents/                  # 6 universal agents
-    │   ├── research-web.md      # Researches best practices before new features
-    │   ├── documenter.md        # Maps files to domains, tracks changes
-    │   ├── domain-updater.md    # Records problems, solutions, learnings
-    │   ├── commit-manager.md    # Conventional commits, merge workflow
-    │   ├── tester.md            # Creates tests (Vitest/PHPUnit/Playwright)
-    │   └── claude-md-compactor.md  # Compacts CLAUDE.md when > 40k chars
-    ├── skills/                  # 25-40 skills (stack + shared + frontend)
-    │   ├── quality-gate/        # Typecheck, lint, test validation
-    │   ├── security-scan/       # OWASP checks per language
-    │   ├── git-workflow/        # Branch management, conventional commits
-    │   ├── codebase-knowledge/  # Domain documentation system
-    │   └── ...                  # Stack-specific skills
-    ├── hooks/
-    │   ├── stop-validator.ts    # Blocks incomplete tasks (branch, git, docs)
-    │   └── user-prompt-submit.ts  # Injects workflow + standards context
-    ├── commands/                # /feature, /fix, /research, /validate
-    ├── config/
-    │   ├── active-project.json  # Stack, framework, database, skills
-    │   ├── security-rules.json  # OWASP checks + env exposure rules
-    │   ├── standards-review.json  # Imported project standards
-    │   └── ...                  # Quality gates, testing, domain mapping
-    └── settings.json            # Claude Code permissions & model config
+├── CLAUDE.md                       # AI memory: architecture, rules, FORBIDDEN
+├── .claude/
+│   ├── agents/                     # 7 universal agents
+│   ├── skills/                     # versioned skill set (stack + shared + frontend)
+│   ├── hooks/                      # stop-validator, final-check, prompt-submit
+│   ├── commands/                   # /feature, /fix, /research, /validate
+│   └── config/                     # active-project, security-rules, ...
+└── .github/workflows/              # ci.yml + security.yml (if dir was empty)
 ```
 
-## Security Features
-
-### Environment Variable Protection (Node.js)
+## CLI
 
-The tool enforces strict separation of server and client environment variables:
+```bash
+npx start-vibing-stacks                # setup or resume current project
+npx start-vibing-stacks migrate        # show outdated/missing skills
+npx start-vibing-stacks migrate --apply  # update outdated skills/agents
 
-- **Scanner**: Detects `NEXT_PUBLIC_` with sensitive words (SECRET, TOKEN, API_KEY) in `.env*` files
-- **CLAUDE.md**: FORBIDDEN rules prevent AI from exposing secrets in browser bundles
-- **Skills**: Teach API proxy patterns — external API calls must go through Route Handlers
-- **security-rules.json**: Automated detection patterns for security audits
+# flags: --force --no-claude --no-mcp --no-install --help --version
+```
 
-### PHP Security
+Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
 
-- OWASP Top 10 adapted for Laravel + Octane
-- Octane-safe patterns (no static state, no globals)
-- `env()` restriction (config files only)
-- Frontend secret isolation (Inertia props)
-- Rate limiting, CORS, CSP, encryption at rest
+## Hooks (block completion)
 
-## Standards Review
+| Hook | Blocks when |
+|---|---|
+| `stop-validator` | not on main, uncommitted changes, CLAUDE.md missing/stale, **secret pattern in diff** (gitleaks or regex) |
+| `final-check` | hardcoded secret, `eval`, SQL string concat, `.skip`/`.only`, `any`, `console.log`, `var_dump` |
+| `user-prompt-submit` | injects workflow + standards context |
 
-Before modifying anything, the CLI scans your project for existing patterns:
+## Workflow per Task
 
 ```
-Scans:  .cursorrules, composer.json, package.json, tsconfig.json,
-        eslint config, phpstan.neon, .env files, framework configs,
-        lockfiles, deploy configs, quality tool configs
-
-Detects: 50+ npm packages, 17+ Composer packages, TypeScript strict mode,
-         path aliases, ESLint config, PHPStan level, package manager,
-         deploy targets, exposed secrets in NEXT_PUBLIC_*
-
-Result:  "Adapt to your standards" or "Use plugin defaults"
-         → Saved in standards-review.json
-         → Injected into every Claude prompt via hook
+1. BRANCH       feature/ | fix/ | refactor/ | test/
+2. RESEARCH     research-web agent (new features)
+3. IMPLEMENT    stack rules + strict types + security
+4. TEST         tester agent (Vitest / pytest / PHPUnit / Playwright)
+5. SECURITY     security-auditor agent — VETO on findings
+6. DOCUMENT     documenter agent
+7. UPDATE       CLAUDE.md "Last Change" section
+8. QUALITY      typecheck → lint → test → build
+9. COMMIT       conventional commit, merge to main
 ```
 
-## CLI Options
-
-```bash
-npx start-vibing-stacks [options]
-
---force           Overwrite existing configuration
---no-claude       Skip Claude Code launch
---no-install      Skip dependency installation
---help, -h        Show help
---version, -v     Show version
-```
+## Security Features
 
-Or install globally:
+- **Environment isolation**: scanner blocks `NEXT_PUBLIC_*SECRET|*TOKEN|*PRIVATE` patterns; teaches Route Handler / Server Action proxy patterns.
+- **OWASP Top 10**: stack-aware skills cover A01–A10 (broken access control, injection, SSRF, etc.).
+- **Secret scanning** in `stop-validator` — gitleaks if installed, regex fallback otherwise.
+- **`security-auditor` agent** with VETO — runs after tester, before commit, blocks insecure code.
+- **CI templates**: gitleaks, `npm audit` / `pip-audit` / `composer audit`, CodeQL/Bandit, weekly cron.
 
-```bash
-npm install -g start-vibing-stacks
-svs  # shortcut alias
-```
+## Standards Review
 
-## How the Workflow Works
+CLI scans existing config (cursorrules, composer.json, tsconfig, eslint, phpstan, `.env*`, lockfiles) and asks **"adapt to your standards or use defaults?"** Imported standards are written to `standards-review.json` and injected into every prompt.
 
-Once configured, Claude Code follows this workflow on every task:
+## Migrate Existing Projects
 
+```bash
+npx start-vibing-stacks migrate         # report drift
+npx start-vibing-stacks migrate --apply # apply updates
 ```
-0. TODO LIST      → Creates detailed task breakdown
-1. BRANCH         → Creates feature/ | fix/ | refactor/ | test/
-2. RESEARCH       → Runs research-web agent for new features
-3. IMPLEMENT      → Follows stack rules + strict types + security
-4. TEST           → Runs tester agent (PHPUnit / Vitest / Playwright)
-5. DOCUMENT       → Runs documenter agent for modified files
-6. UPDATE         → Updates CLAUDE.md with changes
-7. QUALITY        → Runs quality gates (typecheck, lint, test, build)
-8. COMMIT         → Conventional commits, merge to main
-```
-
-The **stop-validator hook** blocks task completion if:
-- Not on `main` branch (work must be merged)
-- Uncommitted changes exist
-- CLAUDE.md wasn't updated
-- Source files lack documentation
 
-## Cursor IDE Support
-
-If `.cursorrules` is detected, the rules are automatically imported into the Claude configuration. Both AI tools work with the same context.
+Compares `version:` in your installed `SKILL.md` files against the bundled package. Missing → install. Outdated → upgrade. Ahead (you customized) → kept. Unversioned → flagged for manual review.
 
 ## Requirements
 
-| Stack | Requirements |
-|-------|-------------|
-| **PHP** | PHP >= 8.3, Composer >= 2.0, Node.js >= 18 |
-| **Node.js** | Node.js >= 18 (Bun optional) |
+| Stack | Required |
+|---|---|
+| PHP | PHP ≥ 8.3, Composer ≥ 2.0, Node.js ≥ 18 |
+| Node.js | Node.js ≥ 18 (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`). Add `[skip release]` to the commit to opt out.
+
 ## Credits
 
-Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing).
-Built by [FantasyLake](https://github.com/f1sc4ll-ai).
+Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing). Built by [FantasyLake](https://github.com/f1sc4ll-ai).
 
 ## License
 

package/dist/index.js

@@ -24,6 +24,7 @@ const PKG_VERSION = JSON.parse(readFileSync(join(CLI_ROOT, 'package.json'), 'utf
 // CLI Arguments
 // =============================================================================
 const args = process.argv.slice(2);
+const SUBCOMMAND = args[0] && !args[0].startsWith('-') ? args[0] : null;
 const FLAGS = {
     force: args.includes('--force'),
     noClaude: args.includes('--no-claude'),
@@ -31,6 +32,7 @@ const FLAGS = {
     noInstall: args.includes('--no-install'),
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
+    apply: args.includes('--apply'),
 };
 if (FLAGS.version) {
     console.log(PKG_VERSION);
@@ -40,10 +42,16 @@ if (FLAGS.help) {
     console.log(ui.LOGO);
     console.log(`
   ${chalk.bold('Usage:')}
-    npx start-vibing-stacks [options]
+    npx start-vibing-stacks [command] [options]
+
+  ${chalk.bold('Commands:')}
+    (default)         Setup or resume current project
+    migrate           Compare installed vs bundled skill/agent versions
+                      Add --apply to update outdated/missing items
 
   ${chalk.bold('Options:')}
-    --force           Overwrite existing configuration
+    --force           Overwrite existing configuration (default command)
+    --apply           Apply updates (migrate command)
     --no-claude       Skip Claude Code installation
     --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation
@@ -57,6 +65,12 @@ if (FLAGS.help) {
   `);
     process.exit(0);
 }
+// Subcommand: migrate
+if (SUBCOMMAND === 'migrate') {
+    const { runMigrate } = await import('./migrate.js');
+    await runMigrate(process.cwd(), { apply: FLAGS.apply });
+    process.exit(0);
+}
 const AVAILABLE_STACKS = [
     { id: 'php', name: 'PHP 8.3+', icon: '🐘', available: true },
     { id: 'nodejs', name: 'Node.js / TypeScript', icon: '📦', available: true },

package/dist/migrate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Start Vibing Stacks — Migrate
+ *
+ * Compares the SKILL.md / agent / hook versions installed in .claude/
+ * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ *
+ * Reports outdated, missing, and modified items. Optionally upgrades.
+ *
+ * Skill version contract:
+ *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
+ *   No frontmatter = treated as "v0" / pre-versioning.
+ */
+export interface MigrateItem {
+    kind: 'skill' | 'agent' | 'hook';
+    name: string;
+    source: string;
+    target: string;
+    bundledVersion: string;
+    installedVersion: string | null;
+    status: 'missing' | 'outdated' | 'current' | 'ahead' | 'modified-no-version';
+}
+export interface MigrateOptions {
+    apply: boolean;
+    scope?: 'skills' | 'agents' | 'hooks' | 'all';
+}
+export declare function planMigration(projectDir: string, opts: MigrateOptions): MigrateItem[];
+export declare function runMigrate(projectDir: string, opts: MigrateOptions): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,217 @@
+/**
+ * Start Vibing Stacks — Migrate
+ *
+ * Compares the SKILL.md / agent / hook versions installed in .claude/
+ * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ *
+ * Reports outdated, missing, and modified items. Optionally upgrades.
+ *
+ * Skill version contract:
+ *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
+ *   No frontmatter = treated as "v0" / pre-versioning.
+ */
+import { existsSync, readFileSync, copyFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { join, relative, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import * as semver from 'semver';
+import * as ui from './ui.js';
+const __m_filename = fileURLToPath(import.meta.url);
+const __m_dirname = dirname(__m_filename);
+const CLI_ROOT = resolve(__m_dirname, '..');
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
+const VERSION_RE = /^version:\s*["']?([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?)["']?\s*$/m;
+function parseVersion(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const content = readFileSync(file, 'utf8');
+        const fm = FRONTMATTER_RE.exec(content);
+        if (!fm)
+            return null;
+        const v = VERSION_RE.exec(fm[1] ?? '');
+        return v?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function statusOf(bundled, installed) {
+    if (installed === null)
+        return 'modified-no-version';
+    const cmp = semver.compare(installed, bundled);
+    if (cmp < 0)
+        return 'outdated';
+    if (cmp > 0)
+        return 'ahead';
+    return 'current';
+}
+function listSubdirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter(n => {
+            try {
+                return statSync(join(dir, n)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function listFiles(dir, suffix) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter(n => n.endsWith(suffix));
+    }
+    catch {
+        return [];
+    }
+}
+function listSkillSources(stack, frontendSkillsDir) {
+    const out = [];
+    const sharedDir = join(CLI_ROOT, 'stacks', '_shared', 'skills');
+    const stackDir = join(CLI_ROOT, 'stacks', stack, 'skills');
+    const frontendDir = frontendSkillsDir
+        ? join(CLI_ROOT, 'stacks', 'frontend', frontendSkillsDir, 'skills')
+        : null;
+    for (const dir of [sharedDir, stackDir, frontendDir].filter(Boolean)) {
+        for (const entry of listSubdirs(dir)) {
+            const skillPath = join(dir, entry, 'SKILL.md');
+            if (existsSync(skillPath))
+                out.push({ source: skillPath, name: entry });
+        }
+    }
+    return out;
+}
+function listAgentSources() {
+    const dir = join(CLI_ROOT, 'stacks', '_shared', 'agents');
+    return listFiles(dir, '.md').map(n => ({ source: join(dir, n), name: n }));
+}
+function listHookSources() {
+    const dir = join(CLI_ROOT, 'stacks', '_shared', 'hooks');
+    return listFiles(dir, '.ts').map(n => ({ source: join(dir, n), name: n }));
+}
+function loadProjectConfig(projectDir) {
+    const path = join(projectDir, '.claude', 'config', 'active-project.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function planMigration(projectDir, opts) {
+    const config = loadProjectConfig(projectDir);
+    if (!config) {
+        ui.error('No .claude/config/active-project.json found. Run `npx start-vibing-stacks` first.');
+        return [];
+    }
+    const items = [];
+    const scope = opts.scope ?? 'all';
+    if (scope === 'all' || scope === 'skills') {
+        for (const { source, name } of listSkillSources(config.stack, config.frontendSkillsDir)) {
+            const target = join(projectDir, '.claude', 'skills', name, 'SKILL.md');
+            const bundledVersion = parseVersion(source);
+            if (!bundledVersion)
+                continue;
+            const installedVersion = parseVersion(target);
+            const status = !existsSync(target)
+                ? 'missing'
+                : statusOf(bundledVersion, installedVersion);
+            items.push({ kind: 'skill', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    if (scope === 'all' || scope === 'agents') {
+        for (const { source, name } of listAgentSources()) {
+            const target = join(projectDir, '.claude', 'agents', name);
+            const bundledVersion = parseVersion(source);
+            if (!bundledVersion)
+                continue;
+            const installedVersion = parseVersion(target);
+            const status = !existsSync(target)
+                ? 'missing'
+                : statusOf(bundledVersion, installedVersion);
+            items.push({ kind: 'agent', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    if (scope === 'all' || scope === 'hooks') {
+        for (const { source, name } of listHookSources()) {
+            const target = join(projectDir, '.claude', 'hooks', name);
+            const bundledVersion = '0.0.0';
+            const installedVersion = existsSync(target) ? '0.0.0' : null;
+            const status = !existsSync(target) ? 'missing' : 'current';
+            items.push({ kind: 'hook', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
+    return items;
+}
+function applyOne(item) {
+    mkdirSync(dirname(item.target), { recursive: true });
+    copyFileSync(item.source, item.target);
+}
+export async function runMigrate(projectDir, opts) {
+    ui.header('🔄 Start Vibing — Migrate');
+    const items = planMigration(projectDir, opts);
+    if (items.length === 0) {
+        ui.info('Nothing to migrate.');
+        return;
+    }
+    const grouped = {
+        missing: [], outdated: [], current: [], ahead: [], 'modified-no-version': [],
+    };
+    for (const it of items)
+        grouped[it.status].push(it);
+    const summary = (label, list) => {
+        if (list.length === 0)
+            return;
+        console.log(`\n  ${label} (${list.length}):`);
+        for (const it of list.slice(0, 30)) {
+            const v = it.installedVersion ?? '–';
+            console.log(`    ${it.kind.padEnd(5)} ${it.name.padEnd(32)} installed=${v.padEnd(8)} bundled=${it.bundledVersion}`);
+        }
+        if (list.length > 30)
+            console.log(`    ... and ${list.length - 30} more`);
+    };
+    summary('MISSING', grouped.missing);
+    summary('OUTDATED', grouped.outdated);
+    summary('AHEAD (installed newer than bundled — kept)', grouped.ahead);
+    summary('UNVERSIONED (manual review)', grouped['modified-no-version']);
+    summary('CURRENT', grouped.current);
+    const upgradable = [...grouped.missing, ...grouped.outdated];
+    if (upgradable.length === 0) {
+        console.log('');
+        ui.success('Everything up to date.');
+        return;
+    }
+    if (!opts.apply) {
+        console.log('');
+        ui.info(`Run with --apply to install/update ${upgradable.length} item(s).`);
+        return;
+    }
+    console.log('');
+    for (const it of upgradable) {
+        try {
+            applyOne(it);
+            ui.success(`updated ${it.kind} ${it.name} (${it.installedVersion ?? '–'} → ${it.bundledVersion})`);
+        }
+        catch (err) {
+            ui.warn(`failed ${it.kind} ${it.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    console.log('');
+    ui.success(`Migration complete: ${upgradable.length} item(s) updated.`);
+    if (grouped['modified-no-version'].length > 0) {
+        console.log('');
+        ui.warn(`${grouped['modified-no-version'].length} unversioned local item(s) skipped — review manually.`);
+        for (const it of grouped['modified-no-version'].slice(0, 10)) {
+            console.log(`    ${relative(projectDir, it.target)}`);
+        }
+    }
+}

package/dist/setup.js

@@ -169,6 +169,16 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = `Imported ${config.standardsReview.patterns.length} project standards`;
             }
         }
+        // 11d. Copy CI workflow templates (only when target dir is empty or --force)
+        const stackWorkflowsDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'workflows');
+        if (existsSync(stackWorkflowsDir)) {
+            const ghWorkflowsDir = join(projectDir, '.github', 'workflows');
+            const targetIsEmpty = !existsSync(ghWorkflowsDir);
+            if (targetIsEmpty || options.force) {
+                copyDirRecursive(stackWorkflowsDir, ghWorkflowsDir, options.force);
+                spinner.text = 'Installed CI workflow templates';
+            }
+        }
         // 12. Copy commands
         const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
         if (existsSync(sharedCommandsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.6.0",
+  "version": "2.7.3",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/agents/claude-md-compactor.md

@@ -1,5 +1,6 @@
 ---
 name: claude-md-compactor
+version: 1.0.0
 description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars OR auto memory MEMORY.md exceeds 200 lines. Compacts while preserving critical knowledge by offloading to topic files."
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob

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

@@ -1,5 +1,6 @@
 ---
 name: commit-manager
+version: 1.0.0
 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

package/stacks/_shared/agents/documenter.md

@@ -1,5 +1,6 @@
 ---
 name: documenter
+version: 1.0.0
 description: "AUTOMATICALLY invoke AFTER any code implementation. Creates/updates domain documentation. PROACTIVELY runs after implementation."
 model: sonnet
 tools: Read, Write, Edit, Grep, Glob, Bash

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

@@ -1,5 +1,6 @@
 ---
 name: domain-updater
+version: 1.0.0
 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

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

@@ -1,5 +1,6 @@
 ---
 name: research-web
+version: 1.0.0
 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