@haus-tech/haus-workflow 0.25.1 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.26.1](https://github.com/WeAreHausTech/haus-workflow/compare/v0.26.0...v0.26.1) (2026-06-15)
+
+## [0.26.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.25.1...v0.26.0) (2026-06-15)
+
+### Features
+
+- **catalog:** exempt agent content from the only-npx-tsx rule ([#107](https://github.com/WeAreHausTech/haus-workflow/issues/107)) ([e335ecc](https://github.com/WeAreHausTech/haus-workflow/commit/e335eccd9e33e70781f3172cc96952fc070c28a9))
+
+### Bug Fixes
+
+- **scanner:** detect php stack so php-gated catalog items are recommendable ([#109](https://github.com/WeAreHausTech/haus-workflow/issues/109)) ([4daa09e](https://github.com/WeAreHausTech/haus-workflow/commit/4daa09e2ef2e5133f43437b5a6e73277b8c6ab69))
+
 ## [0.25.1](https://github.com/WeAreHausTech/haus-workflow/compare/v0.25.0...v0.25.1) (2026-06-15)
 
 ## [0.25.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.24.1...v0.25.0) (2026-06-12)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haus Tech AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -119,6 +119,7 @@ var validation_rules_default = {
   ],
   allowedNpxPattern: { source: "\\bnpx\\s+tsx\\b", flags: "i" },
   anyNpxPattern: { source: "\\bnpx\\s+\\S+", flags: "i" },
+  npxTsxOnlyExemptTypes: ["agent"],
   httpUrlPattern: { source: "^http:\\/\\/", flags: "i" },
   placeholderPattern: { source: "\\bTODO\\b|\\bPLACEHOLDER\\b", flags: "i" },
   allowedStacks: [
@@ -239,6 +240,7 @@ var REQUIRED_SKILL_FRONTMATTER = validation_rules_default.requiredSkillFrontmatt
 var RISKY_INSTALL_PATTERNS = validation_rules_default.riskyInstallPatterns.map(toRegExp);
 var ALLOWED_NPX_PATTERN = toRegExp(validation_rules_default.allowedNpxPattern);
 var ANY_NPX_PATTERN = toRegExp(validation_rules_default.anyNpxPattern);
+var NPX_TSX_ONLY_EXEMPT_TYPES = validation_rules_default.npxTsxOnlyExemptTypes ?? [];
 var HTTP_URL_PATTERN = toRegExp(validation_rules_default.httpUrlPattern);
 var PLACEHOLDER_PATTERN = toRegExp(validation_rules_default.placeholderPattern);
 var ALLOWED_STACKS = validation_rules_default.allowedStacks;
@@ -317,13 +319,14 @@ ${extractUseWhenSection(text)}`;
 // src/catalog/ingest-catalog.ts
 function validateCatalogItem(item, content2) {
   const label = item.id;
+  const checkNonTsxNpx = !NPX_TSX_ONLY_EXEMPT_TYPES.includes(item.type);
   const lines = content2.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line2 = lines[i] ?? "";
     if (RISKY_INSTALL_PATTERNS.some((re) => re.test(line2))) {
       return { ok: false, reason: `${label}: risky install pattern at line ${i + 1}` };
     }
-    if (ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
+    if (checkNonTsxNpx && ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
       return { ok: false, reason: `${label}: disallowed npx at line ${i + 1}` };
     }
   }
@@ -2471,6 +2474,11 @@ var STACK_RULES = [
     stack: ["backend", "graphql"],
     any: [fileEndsWith(".graphql"), fileEndsWith("schema.graphql")]
   },
+  // PHP (Composer-managed) — broad language signal so php-tooling catalog items
+  // (e.g. the php-reviewer agent gated on { stack: 'php' }) are recommendable on any
+  // Composer project. Placed before laravel/wordpress so 'php' precedes the
+  // framework-specific stacks in the backend bucket.
+  { stack: ["backend", "php"], any: [fileEndsWith("composer.json")] },
   { stack: ["backend", "laravel"], any: [dep("laravel/framework")] },
   { stack: ["backend", "laravel"], any: [fileIncludes("app/Providers/"), fileIncludes("routes/")] },
   { stack: ["backend", "wordpress"], any: [fileEndsWith("wp-config.php"), dep("roots/wordpress")] },
@@ -4386,12 +4394,19 @@ function auditTemplateContent(manifestDir, absPath, itemId) {
   failures.push(...auditForbiddenTagsInText(text, `${itemId}: ${rel}`));
   return failures;
 }
+var DIR_ITEM_TYPE = {
+  skills: "skill",
+  agents: "agent",
+  templates: "template",
+  commands: "command"
+};
 function auditMarkdownContent(manifestDir) {
   const failures = [];
   const dirs = ["skills", "agents", "templates", "commands"];
   for (const dir of dirs) {
     const abs = path26.join(manifestDir, dir);
     if (!fs20.existsSync(abs)) continue;
+    const checkNonTsxNpx = !NPX_TSX_ONLY_EXEMPT_TYPES.includes(DIR_ITEM_TYPE[dir] ?? "");
     walkMd(abs, (file) => {
       const text = fs20.readFileSync(file, "utf8");
       const rel = path26.relative(manifestDir, file);
@@ -4401,7 +4416,7 @@ function auditMarkdownContent(manifestDir) {
         if (RISKY_INSTALL_PATTERNS.some((re) => re.test(line2))) {
           failures.push(`${rel}:${i + 1}: risky install pattern`);
         }
-        if (ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
+        if (checkNonTsxNpx && ANY_NPX_PATTERN.test(line2) && !ALLOWED_NPX_PATTERN.test(line2)) {
           failures.push(`${rel}:${i + 1}: disallowed npx (only npx tsx allowed)`);
         }
       }

package/library/catalog/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.6.5",
+  "version": "2.7.0",
   "items": [
     {
       "id": "haus.nextjs-patterns",
@@ -1911,6 +1911,323 @@
       "originUrl": "https://github.com/pcvelz/superpowers/blob/48f5123e18a1a92dfba962da8dc2509391c821ee/commands/onboard.md",
       "pinnedRef": "48f5123e18a1a92dfba962da8dc2509391c821ee",
       "ecosystem": "superpowers"
+    },
+    {
+      "id": "haus.ecc-react-reviewer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/react-reviewer.md",
+      "title": "React Reviewer",
+      "purpose": "Expert React/JSX code reviewer specializing in hook correctness, render performance, server/client component boundaries, accessibility, and React-specific security. Use for any change touching .tsx/.jsx files or React component logic. MUST BE USED for React projects.",
+      "whenToUse": "Expert React/JSX code reviewer specializing in hook correctness, render performance, server/client component boundaries, accessibility, and React-specific security. Use for any change touching .tsx/.jsx files or React component logic. MUST BE USED for React projects.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "review", "react"],
+      "repoRoles": [],
+      "tokenEstimate": 2856,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/react-reviewer.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "react",
+      "requiresAny": [
+        {
+          "stack": "react"
+        },
+        {
+          "dependency": "react"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-react-build-resolver",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/react-build-resolver.md",
+      "title": "React Build Resolver",
+      "purpose": "Diagnose and fix React build failures across Vite, webpack, Next.js, CRA, Parcel, esbuild, and Bun. Handles JSX/TSX compile errors, hydration mismatches, server/client component boundary failures, missing types, and bundler-specific configuration issues with minimal, surgical changes. MUST BE USED when a React build fails.",
+      "whenToUse": "Diagnose and fix React build failures across Vite, webpack, Next.js, CRA, Parcel, esbuild, and Bun. Handles JSX/TSX compile errors, hydration mismatches, server/client component boundary failures, missing types, and bundler-specific configuration issues with minimal, surgical changes. MUST BE USED when a React build fails.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "react"],
+      "repoRoles": [],
+      "tokenEstimate": 2801,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/react-build-resolver.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "react",
+      "requiresAny": [
+        {
+          "stack": "react"
+        },
+        {
+          "dependency": "react"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-php-reviewer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/php-reviewer.md",
+      "title": "PHP Reviewer",
+      "purpose": "Expert PHP code reviewer specializing in PSR-12 compliance, PHP type system, Eloquent ORM patterns, security, and performance. Use for all PHP code changes. MUST BE USED for PHP projects.",
+      "whenToUse": "Expert PHP code reviewer specializing in PSR-12 compliance, PHP type system, Eloquent ORM patterns, security, and performance. Use for all PHP code changes. MUST BE USED for PHP projects.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "review", "php"],
+      "repoRoles": [],
+      "tokenEstimate": 1431,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/php-reviewer.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "php",
+      "requiresAny": [
+        {
+          "stack": "php"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-csharp-reviewer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/csharp-reviewer.md",
+      "title": "C# Reviewer",
+      "purpose": "Expert C# code reviewer specializing in .NET conventions, async patterns, security, nullable reference types, and performance. Use for all C# code changes. MUST BE USED for C# projects.",
+      "whenToUse": "Expert C# code reviewer specializing in .NET conventions, async patterns, security, nullable reference types, and performance. Use for all C# code changes. MUST BE USED for C# projects.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "review", "csharp", "dotnet"],
+      "repoRoles": [],
+      "tokenEstimate": 1426,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/csharp-reviewer.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "dotnet",
+      "requiresAny": [
+        {
+          "stack": "dotnet"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-database-reviewer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/database-reviewer.md",
+      "title": "Database Reviewer",
+      "purpose": "PostgreSQL database specialist for query optimization, schema design, security, and performance. Use PROACTIVELY when writing SQL, creating migrations, designing schemas, or troubleshooting database performance. Incorporates Supabase best practices.",
+      "whenToUse": "PostgreSQL database specialist for query optimization, schema design, security, and performance. Use PROACTIVELY when writing SQL, creating migrations, designing schemas, or troubleshooting database performance. Incorporates Supabase best practices.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "review", "database"],
+      "repoRoles": [],
+      "tokenEstimate": 1336,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/database-reviewer.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "database",
+      "requiresAny": [
+        {
+          "stack": "postgresql"
+        },
+        {
+          "stack": "mysql"
+        },
+        {
+          "stack": "mariadb"
+        },
+        {
+          "stack": "mssql"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-e2e-runner",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/e2e-runner.md",
+      "title": "E2E Runner",
+      "purpose": "End-to-end testing specialist using Vercel Agent Browser (preferred) with Playwright fallback. Use PROACTIVELY for generating, maintaining, and running E2E tests. Manages test journeys, quarantines flaky tests, uploads artifacts (screenshots, videos, traces), and ensures critical user flows work.",
+      "whenToUse": "End-to-end testing specialist using Vercel Agent Browser (preferred) with Playwright fallback. Use PROACTIVELY for generating, maintaining, and running E2E tests. Manages test journeys, quarantines flaky tests, uploads artifacts (screenshots, videos, traces), and ensures critical user flows work.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "testing"],
+      "repoRoles": [],
+      "tokenEstimate": 1274,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/e2e-runner.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "testing",
+      "requiresAny": [
+        {
+          "stack": "playwright"
+        },
+        {
+          "dependency": "@playwright/test"
+        }
+      ]
+    },
+    {
+      "id": "haus.ecc-performance-optimizer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/performance-optimizer.md",
+      "title": "Performance Optimizer",
+      "purpose": "Performance analysis and optimization specialist. Use PROACTIVELY for identifying bottlenecks, optimizing slow code, reducing bundle sizes, and improving runtime performance. Profiling, memory leaks, render optimization, and algorithmic improvements.",
+      "whenToUse": "Performance analysis and optimization specialist. Use PROACTIVELY for identifying bottlenecks, optimizing slow code, reducing bundle sizes, and improving runtime performance. Profiling, memory leaks, render optimization, and algorithmic improvements.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "quality"],
+      "repoRoles": [],
+      "tokenEstimate": 3367,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/performance-optimizer.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "ecc",
+      "default": true
+    },
+    {
+      "id": "haus.ecc-refactor-cleaner",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/ecc/refactor-cleaner.md",
+      "title": "Refactor Cleaner",
+      "purpose": "Dead code cleanup and consolidation specialist. Use PROACTIVELY for removing unused code, duplicates, and refactoring. Runs analysis tools (knip, depcheck, ts-prune) to identify dead code and safely removes it.",
+      "whenToUse": "Dead code cleanup and consolidation specialist. Use PROACTIVELY for removing unused code, duplicates, and refactoring. Runs analysis tools (knip, depcheck, ts-prune) to identify dead code and safely removes it.",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "quality"],
+      "repoRoles": [],
+      "tokenEstimate": 670,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "ecc-affaanm",
+      "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/.kiro/agents/refactor-cleaner.md",
+      "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
+      "ecosystem": "ecc",
+      "default": true
+    },
+    {
+      "id": "haus.oh-my-claudecode-test-engineer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/oh-my-claudecode/test-engineer.md",
+      "title": "Test Engineer",
+      "purpose": "Test strategy, integration/e2e coverage, flaky test hardening, TDD workflows",
+      "whenToUse": "Test strategy, integration/e2e coverage, flaky test hardening, TDD workflows",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "testing"],
+      "repoRoles": [],
+      "tokenEstimate": 1656,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "omcc-yeachanheo",
+      "originUrl": "https://github.com/yeachan-heo/oh-my-claudecode/blob/50f6ff05eb5d9ebed66f05d8c4580c0b119f37af/agents/test-engineer.md",
+      "pinnedRef": "50f6ff05eb5d9ebed66f05d8c4580c0b119f37af",
+      "ecosystem": "oh-my-claudecode",
+      "default": true
+    },
+    {
+      "id": "haus.oh-my-claudecode-designer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/oh-my-claudecode/designer.md",
+      "title": "Designer",
+      "purpose": "UI/UX Designer-Developer for stunning interfaces (Sonnet)",
+      "whenToUse": "UI/UX Designer-Developer for stunning interfaces (Sonnet)",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "frontend"],
+      "repoRoles": [],
+      "tokenEstimate": 2407,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "omcc-yeachanheo",
+      "originUrl": "https://github.com/yeachan-heo/oh-my-claudecode/blob/50f6ff05eb5d9ebed66f05d8c4580c0b119f37af/agents/designer.md",
+      "pinnedRef": "50f6ff05eb5d9ebed66f05d8c4580c0b119f37af",
+      "ecosystem": "oh-my-claudecode",
+      "default": true
+    },
+    {
+      "id": "haus.oh-my-claudecode-tracer",
+      "version": "1.0.0",
+      "source": "curated",
+      "type": "agent",
+      "path": "agents/oh-my-claudecode/tracer.md",
+      "title": "Tracer",
+      "purpose": "Evidence-driven causal tracing with competing hypotheses, evidence for/against, uncertainty tracking, and next-probe recommendations",
+      "whenToUse": "Evidence-driven causal tracing with competing hypotheses, evidence for/against, uncertainty tracking, and next-probe recommendations",
+      "whenNotToUse": "Do not use when a more specific skill or command applies.",
+      "tags": ["agent", "quality"],
+      "repoRoles": [],
+      "tokenEstimate": 3004,
+      "installMode": "copy-selected",
+      "reviewStatus": "approved",
+      "riskLevel": "low",
+      "useMode": "copy",
+      "license": "MIT",
+      "licenseConfidence": "high",
+      "originSourceId": "omcc-yeachanheo",
+      "originUrl": "https://github.com/yeachan-heo/oh-my-claudecode/blob/50f6ff05eb5d9ebed66f05d8c4580c0b119f37af/agents/tracer.md",
+      "pinnedRef": "50f6ff05eb5d9ebed66f05d8c4580c0b119f37af",
+      "ecosystem": "oh-my-claudecode",
+      "default": true
     }
   ]
 }

package/library/catalog/validation-rules.json

@@ -25,6 +25,7 @@
   ],
   "allowedNpxPattern": { "source": "\\bnpx\\s+tsx\\b", "flags": "i" },
   "anyNpxPattern": { "source": "\\bnpx\\s+\\S+", "flags": "i" },
+  "npxTsxOnlyExemptTypes": ["agent"],
   "httpUrlPattern": { "source": "^http:\\/\\/", "flags": "i" },
   "placeholderPattern": { "source": "\\bTODO\\b|\\bPLACEHOLDER\\b", "flags": "i" },
   "allowedStacks": [

package/library/global/commands/haus-cloneandsetup.md

@@ -34,7 +34,7 @@ Specify the least. Infer the rest from the repo's stack + these conventions, and
 
 - **IMPORTANT — never install anything without asking first; global/system tools especially** (Homebrew, Docker, Laravel Herd, global `npm`/`composer` packages). Detect what's already present; if something required is missing, name it, say why it's needed, and get an explicit **yes** before installing. Prefer the least-invasive option, and don't switch or override tools the dev already has.
 - **PHP / WordPress sites are served by the developer's own PHP environment.** If they already have one — detect `valet`, `herd`, `ddev`, or `php` on PATH — **use it**: just satisfy the env contract (docroot → the repo's `web/`, HTTPS) and report the URL; never override what they already run. **Only when no local PHP environment exists** (a completely fresh machine) suggest installing **[Laravel Herd](https://herd.laravel.com)** as the default (asking first) and point its docroot at `web/` + `herd secure`.
-- **Databases and other services (a repo's `needs:`) run in Docker as standalone containers.** Bring each up with a **clean `docker run`** — image, host port, and env from the house convention for that service (e.g. `mysql` → `mysql:8` on `127.0.0.1:3306`, root password from generated secrets; `postgres` → `postgres:16` on `5432`). **Do not provision a `needs:` service from the repo's own `docker-compose.yml` when that compose bind-mounts repo-relative init files** (e.g. `./seed.sql`, `./docker-entrypoint-initdb.d/`): those mounts need files the guard won't let us create, and they conflate bring-up with seeding (which is the separate `seed:` step). **If Docker isn't installed** it's a prerequisite (surfaced in the Step 2 gate) — **ask before installing it** (global install). **Port-conflict caveat:** if the conventional host port is already taken, pick the next free port, use it, and **record the chosen port in the workspace `localdev.yml` `env` map** so sink repos point at the right place. A `needs:` service comes up **empty** — populating it is always the separate `seed:` step.
+- **Databases and other services (a repo's `needs:`) run in Docker as a shared, workspace-owned `docker-compose` project** — grouped and self-contained (`up`/`down` together, named volumes), namespaced per workspace instance via `COMPOSE_PROJECT_NAME` + its own host ports so the workspace can run multiple times side by side. Image/port/env per the house convention (`mysql:8`, `postgres:16`, …). Don't reuse a repo's own compose that bind-mounts repo-relative init files (`seed.sql`) — author the service in the workspace compose. Services come up **empty** (seeding is the separate `seed:` step); record chosen host ports in the workspace `localdev.yml` `env` map.
 - **Dependencies** install from the lockfile (Step 3).
 - A repo's `localdev.yml` carries **only what can't be inferred** — its `needs`, repo-specific `build`/`seed` commands, env keys, and URL. Detect the stack (e.g. Bedrock = `composer.json` + `web/` docroot + `wp-cli.yml`; Vendure/Node = `docker-compose.yml` + `@vendure/*`) and apply the matching convention.
 
@@ -84,7 +84,7 @@ env:
 1. **Discover** `.haus-workflow/localdev.yml` in the workspace root and each repo.
 2. **Resolve order** from the workspace `order` (repos not listed run last, in manifest order). No workspace file → manifest order.
 3. **Per repo, in order**, apply intent via the conventions:
-   - **`needs`** → bring up each service as a **standalone `docker run`** (image/port/env from conventions; **not** the repo's compose when it bind-mounts repo-relative init files) if not already running. The service comes up **empty**; record its values in the workspace `localdev.yml` `env` map. No data is created here, so no overwrite prompt at this step — data lands in `seed:`.
+   - **`needs`** → add the service to the **workspace compose project** and `docker compose up -d` if not already running (namespaced by `COMPOSE_PROJECT_NAME`, free host ports per instance; not the repo's own bind-mounting compose). Comes up **empty**; record host ports in the workspace `localdev.yml` `env` map — data lands in `seed:`.
    - **`build`** → run it (honor any node version the repo's docs note).
    - **`serve`** → for `via: herd` / PHP envs, install nothing — verify the dev's environment serves `web/`, and report the URL.
    - **`seed`** → populate the empty datastore. **Always a distinct, confirm-gated step, separate from `needs:` bring-up** (don't conflate "DB up" with "DB has data"). Before running, **check its prerequisites and report any gap instead of running blind** — e.g. WP-CLI present (for `wp` / `db:pull` seeds), the target repo's **`.env` written** (the seed reads connection values from it — done in the Env step above), the **SSH alias resolves** (for remote pulls like `dep db:pull staging-oderland`). **Confirm first** for every remote (SSH) or destructive (overwrites data) seed — every run, even on re-run. Missing prerequisite → skip with a clear message, don't guess.
@@ -112,13 +112,13 @@ env:
    - **Yes** → start each repo in the workspace `order` (its `serve.start`, e.g. `yarn dev`; bring up any remaining foreground services), run any follow-ups (e.g. `wp sync-products sync`), then **print the live URLs** (each repo's `serve.url`).
    - **No** → just print the ordered start commands + follow-ups as next steps; start nothing.
 
-**Default is "ready to run" (D2):** the preparation — datastores up (standalone `docker run`), seeds applied (confirm-gated), links, builds, each repo's `.env` written — always happens. Starting the **foreground** dev servers and the initial product sync happen **only if the user says yes** to the start prompt above; otherwise they're printed, not run.
+**Default is "ready to run" (D2):** the preparation — datastores up (workspace `docker compose` project), seeds applied (confirm-gated), links, builds, each repo's `.env` written — always happens. Starting the **foreground** dev servers and the initial product sync happen **only if the user says yes** to the start prompt above; otherwise they're printed, not run.
 
 ## Step 5 — Report and define "done"
 
 **"Done" is an explicit terminal state**, not "looks set up". The preparation reaches:
 
-- datastores up (standalone containers),
+- datastores up (workspace `docker compose` project),
 - dependencies installed and builds green,
 - links wired,
 - each repo's `.env` written from known values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {