@haus-tech/haus-workflow 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.31.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.30.0...v0.31.0) (2026-06-23)
+
+### Features
+
+- opt-in UX for tiered skills + config scaffold ([#141](https://github.com/WeAreHausTech/haus-workflow/issues/141)) ([f60207b](https://github.com/WeAreHausTech/haus-workflow/commit/f60207b78af4651656d457c6f80665bd25deaa7f)), closes [#33](https://github.com/WeAreHausTech/haus-workflow/issues/33) [#33](https://github.com/WeAreHausTech/haus-workflow/issues/33)
+
 ## [0.30.0](https://github.com/WeAreHausTech/haus-workflow/compare/v0.29.0...v0.30.0) (2026-06-22)
 
 ### Features

package/README.md

@@ -87,6 +87,10 @@ On `haus apply` / `haus update`, items **removed from the catalog** or marked
 lock hash; user-edited copies are kept. Approved items deselected via `--select` are
 not pruned.
 
+> **Upgrading from a pre-`0.30.0` CLI:** deprecated-skill pruning shipped in `0.30.0`.
+> If an older CLI left deprecated skills on disk, upgrade first
+> (`npm i -g @haus-tech/haus-workflow`) then run `haus update` to prune them.
+
 ## Internal docs
 
 [docs/SUMMARY.md](docs/SUMMARY.md) — full documentation index

package/dist/cli.js

@@ -2398,6 +2398,13 @@ async function cleanupStaleCatalogItems(root, manifestById, dryRun) {
   }
 }
 
+// src/utils/args.ts
+function parseIdList(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  return raw.flatMap((v) => v.split(",")).map((v) => v.trim()).filter((v) => v.length > 0);
+}
+
 // src/commands/apply.ts
 async function cacheHasItems() {
   const data = await readJson(path13.join(getCacheDir(), "manifest.json"));
@@ -2414,6 +2421,34 @@ async function runApply(options) {
   const root = process.cwd();
   const isDryRun = Boolean(options.dryRun) && !options.write;
   let selectedIds;
+  const explicitIds = parseIdList(options.ids);
+  if (explicitIds.length > 0) {
+    if (options.select) {
+      error("Use either --select (interactive) or --ids (explicit), not both");
+      process.exitCode = 1;
+      return;
+    }
+    const rec = await readJson(hausPath(root, "recommendation.json"));
+    const recommended = rec?.recommended ?? [];
+    const installableIds = new Set(installableRecommendedItems(recommended).map((i) => i.id));
+    const configIds = new Set(recommended.filter((i) => i.install === false).map((i) => i.id));
+    const skippedIds = new Set((rec?.skipped ?? []).map((s) => s.id));
+    for (const id of explicitIds.filter((id2) => !installableIds.has(id2))) {
+      if (configIds.has(id)) {
+        warn(`--ids: "${id}" is a config item \u2014 install it with \`haus scaffold ${id}\`. Ignoring.`);
+      } else if (skippedIds.has(id)) {
+        warn(
+          `--ids: "${id}" is not currently recommended (skipped) \u2014 add it with \`haus recommend --include ${id}\` first. Ignoring.`
+        );
+      } else {
+        warn(
+          `--ids: "${id}" is not in recommendation.json \u2014 run \`haus recommend\` (or \`--include ${id}\`) first. Ignoring.`
+        );
+      }
+    }
+    selectedIds = explicitIds.filter((id) => installableIds.has(id));
+    log(`Applying ${selectedIds.length} explicitly selected catalog item(s).`);
+  }
   if (options.select) {
     if (!process.stdin.isTTY) {
       error("--select requires an interactive terminal (stdin is not a TTY)");
@@ -3546,7 +3581,7 @@ function mergeRecommendationWarnings(context) {
 }
 
 // src/recommender/recommend.ts
-async function recommend(root, context) {
+async function recommend(root, context, opts = {}) {
   const items = await loadCatalog(root);
   const sources = await readJson(
     hausPath(root, "sources-report.json")
@@ -3719,6 +3754,8 @@ async function recommend(root, context) {
     }
   }
   applyCoInstallSuppression(recommended, skipped);
+  const includeWarnings = applyManualIncludes(opts.include ?? [], items, recommended, skipped);
+  const optInEligible = buildOptInEligible(items, skipped);
   recommended.sort((a, b) => a.id.localeCompare(b.id));
   skipped.sort((a, b) => a.id.localeCompare(b.id));
   const installableRecommended = recommended.filter((item) => item.install);
@@ -3729,7 +3766,8 @@ async function recommend(root, context) {
   return {
     recommended,
     skipped,
-    warnings: mergeRecommendationWarnings(context),
+    optInEligible,
+    warnings: [...mergeRecommendationWarnings(context), ...includeWarnings],
     estimatedContextTokens,
     selectedRules,
     skippedRules,
@@ -3815,6 +3853,80 @@ function applyCoInstallSuppression(recommended, skipped) {
     });
   }
 }
+var HARD_SKIP_CODES = /* @__PURE__ */ new Set([
+  "unsupported-policy",
+  "deprecated",
+  "curated-not-approved",
+  "curated-risk-blocked",
+  "sensitive-policy",
+  "source-trust",
+  "source-approval"
+]);
+function applyManualIncludes(include, items, recommended, skipped) {
+  const warnings = [];
+  if (include.length === 0) return warnings;
+  const byId = new Map(items.map((i) => [i.id, i]));
+  const recommendedIds = new Set(recommended.map((r) => r.id));
+  for (const id of include) {
+    const item = byId.get(id);
+    if (!item) {
+      warnings.push(`--include: unknown catalog id "${id}" (not in manifest)`);
+      continue;
+    }
+    if (recommendedIds.has(id)) continue;
+    const skipIdx = skipped.findIndex((s) => s.id === id);
+    const skipCode = skipIdx >= 0 ? skipped[skipIdx].skipReasons[0]?.code : void 0;
+    if (skipCode && HARD_SKIP_CODES.has(skipCode)) {
+      warnings.push(`--include: "${id}" cannot be force-installed (blocked by ${skipCode})`);
+      continue;
+    }
+    if (skipCode === "requires-any-unsatisfied") {
+      warnings.push(`--include: "${id}" added manually though its requiresAny gate is unsatisfied`);
+    }
+    if (skipIdx >= 0) skipped.splice(skipIdx, 1);
+    const isConfig = item.type === "config";
+    recommended.push({
+      id: item.id,
+      type: item.type,
+      reason: "manually included",
+      reasons: [
+        {
+          code: "manual-include",
+          message: "manually included via --include",
+          signal: "selection:manual"
+        }
+      ],
+      selectionMode: "manual",
+      install: !isConfig,
+      tags: item.tags,
+      ecosystem: item.ecosystem,
+      tokenEstimate: item.tokenEstimate
+    });
+    recommendedIds.add(id);
+  }
+  return warnings;
+}
+function buildOptInEligible(items, skipped) {
+  const byId = new Map(items.map((i) => [i.id, i]));
+  const eligible = [];
+  for (const entry of skipped) {
+    if (entry.skipReasons[0]?.code !== "requires-any-unsatisfied") continue;
+    const item = byId.get(entry.id);
+    if (!item?.optInTier || !item.optInGroup) continue;
+    eligible.push({
+      id: item.id,
+      type: item.type,
+      title: item.title,
+      optInTier: item.optInTier,
+      optInGroup: item.optInGroup,
+      purpose: item.purpose,
+      tokenEstimate: item.tokenEstimate,
+      requires: entry.skipReasons[0]?.signal ?? describeRequiresAny(item.requiresAny ?? [])
+    });
+  }
+  eligible.sort((a, b) => a.optInGroup.localeCompare(b.optInGroup) || a.id.localeCompare(b.id));
+  return eligible;
+}
 
 // src/commands/setup-core.ts
 async function runSetupCore(root, opts) {
@@ -4275,7 +4387,8 @@ async function runInstall(options) {
 async function runRecommend(options) {
   const root = process.cwd();
   const context = await readContextOrScan(root);
-  const result = await recommend(root, context);
+  const include = parseIdList(options.include);
+  const result = await recommend(root, context, { include });
   await writeJson(hausPath(root, "recommendation.json"), result);
   if (options.json) {
     log(JSON.stringify(result, null, 2));
@@ -4284,6 +4397,12 @@ async function runRecommend(options) {
   log("Haus recommendation ready");
   log(`Recommended: ${result.recommended.length}`);
   log(`Skipped: ${result.skipped.length}`);
+  if (result.optInEligible && result.optInEligible.length > 0) {
+    log(
+      `Opt-in available: ${result.optInEligible.length} (add with \`haus recommend --include <id>\`)`
+    );
+  }
+  for (const w of result.warnings.filter((w2) => w2.startsWith("--include:"))) log(w);
 }
 
 // src/commands/refresh.ts
@@ -4345,19 +4464,20 @@ async function scaffoldConfigItems(projectRoot, catalogRoot, items, opts = {}) {
     if (stat.isFile()) {
       const filename = path22.basename(sourcePath);
       const dest = path22.join(projectRoot, filename);
-      record(filename, await scaffoldFile(sourcePath, dest, item.id, opts));
+      record(filename, await scaffoldFile(sourcePath, dest, item.id, projectRoot, opts));
     } else if (stat.isDirectory()) {
       const entries = await fs17.readdir(sourcePath);
       for (const entry of entries) {
         const src = path22.join(sourcePath, entry);
         const dest = path22.join(projectRoot, entry);
-        record(entry, await scaffoldFile(src, dest, item.id, opts));
+        record(entry, await scaffoldFile(src, dest, item.id, projectRoot, opts));
       }
     }
   }
   return { scaffolded, skipped, skippedExisting };
 }
-async function scaffoldFile(src, dest, itemId, opts) {
+async function scaffoldFile(src, dest, itemId, projectRoot, opts) {
+  const destDisplay = path22.relative(projectRoot, dest) || path22.basename(dest);
   const srcStat = await fs17.lstat(src).catch(() => null);
   if (!srcStat) {
     warn(`Skipping ${path22.basename(src)}: source not found`);
@@ -4369,7 +4489,7 @@ async function scaffoldFile(src, dest, itemId, opts) {
   }
   const exists = await fs17.pathExists(dest);
   if (exists && !opts.force) {
-    warn(`Skipping ${path22.basename(dest)}: already exists (use --force to overwrite)`);
+    warn(`Skipping ${destDisplay}: already exists \u2014 re-run with --force to overwrite it`);
     return "skipped-exists";
   }
   if (opts.dryRun) {
@@ -4885,6 +5005,39 @@ function auditForbiddenStacks(items) {
   }
   return failures;
 }
+var OPT_IN_TIERS = /* @__PURE__ */ new Set(["workflow", "ops", "review", "design"]);
+function auditOptInMetadata(items) {
+  const failures = [];
+  for (const item of items) {
+    const hasTier = item.optInTier !== void 0;
+    const hasGroup = item.optInGroup !== void 0;
+    if (hasTier !== hasGroup) {
+      failures.push(`${item.id}: optInTier and optInGroup must be set together`);
+    }
+    if (hasTier) {
+      if (!OPT_IN_TIERS.has(item.optInTier)) {
+        failures.push(
+          `${item.id}: invalid optInTier "${item.optInTier}" (expected one of ${[...OPT_IN_TIERS].join(", ")})`
+        );
+      }
+      if (typeof item.optInGroup !== "string" || item.optInGroup.length === 0) {
+        failures.push(`${item.id}: optInGroup must be a non-empty string`);
+      }
+      if (item.default === true) {
+        failures.push(`${item.id}: opt-in items (optInTier set) must not be default:true`);
+      }
+      if (typeof item.purpose !== "string" || item.purpose.length === 0) {
+        failures.push(`${item.id}: opt-in items (optInTier set) must have a non-empty purpose`);
+      }
+    }
+    const requiresAny = Array.isArray(item.requiresAny) ? item.requiresAny : [];
+    const roleOnly = requiresAny.length > 0 && requiresAny.every((clause) => clause && clause.role);
+    if (item.default !== true && roleOnly && !hasTier) {
+      failures.push(`${item.id}: role-gated opt-in item missing optInTier/optInGroup`);
+    }
+  }
+  return failures;
+}
 function auditManifestStructure(manifestVersion, items) {
   const failures = [];
   const seenIds = /* @__PURE__ */ new Map();
@@ -5058,6 +5211,7 @@ function auditMarkdownContent(manifestDir, items) {
 function validateCatalogData(manifestDir, manifestVersion, items) {
   const failures = [
     ...auditManifestStructure(manifestVersion, items),
+    ...auditOptInMetadata(items),
     ...auditForbiddenStacks(items),
     ...auditShippedFiles(manifestDir, items),
     ...auditMarkdownContent(manifestDir, items),
@@ -5770,10 +5924,16 @@ function validateRuntimeNodeVersion() {
 validateRuntimeNodeVersion();
 program.name("haus").description("Haus AI workflow CLI").version(cliVersion());
 program.command("scan").option("--json").action(runScan);
-program.command("recommend").option("--json").action(runRecommend);
+program.command("recommend").option("--json").option(
+  "--include <ids...>",
+  "Force opt-in catalog items into the recommendation as manual selections (space- or comma-separated ids)"
+).action(runRecommend);
 program.command("setup-project").option("--json").action(runSetupProject);
 program.command("doctor").option("--hooks", "Verify .claude/settings.json matches the hook contract").action(runDoctor);
 program.command("apply").option("--dry-run").option("--write").option("--select", "Interactively select catalog items before applying").option(
+  "--ids <ids...>",
+  "Install exactly these recommended item ids non-interactively (skill backend; space- or comma-separated)"
+).option(
   "--allow-empty-cache",
   "Apply core files only when catalog cache is empty (skip catalog items without error)"
 ).option(

package/library/catalog/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.12.2",
+  "version": "2.13.1",
   "items": [
     {
       "id": "haus.agentic-workflow-standard",
@@ -619,6 +619,8 @@
       "originUrl": "https://github.com/affaan-m/ECC/blob/ec92b528471df708c2384ebbcc82b390b60f535a/skills/laravel-plugin-discovery/SKILL.md",
       "pinnedRef": "ec92b528471df708c2384ebbcc82b390b60f535a",
       "ecosystem": "laravel",
+      "optInTier": "ops",
+      "optInGroup": "Laravel plugin discovery",
       "requiresAny": [
         {
           "role": "laravel-plugins"
@@ -753,6 +755,8 @@
       "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/agents/performance-optimizer.md",
       "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
       "ecosystem": "ecc",
+      "optInTier": "review",
+      "optInGroup": "Performance review",
       "default": false,
       "requiresAny": [
         {
@@ -986,6 +990,8 @@
       "originUrl": "https://github.com/affaan-m/ECC/blob/5b173d2e6c11b976a0f13b2f59125e08956c1d47/.kiro/agents/refactor-cleaner.md",
       "pinnedRef": "5b173d2e6c11b976a0f13b2f59125e08956c1d47",
       "ecosystem": "ecc",
+      "optInTier": "review",
+      "optInGroup": "Refactor cleanup",
       "default": false,
       "requiresAny": [
         {
@@ -1015,6 +1021,8 @@
       "tags": ["agent", "review", "security"],
       "tokenEstimate": 1369,
       "ecosystem": "security",
+      "optInTier": "review",
+      "optInGroup": "Security review",
       "originUrl": "https://github.com/affaan-m/ECC/blob/ec92b528471df708c2384ebbcc82b390b60f535a/agents/security-reviewer.md",
       "requiresAny": [
         {
@@ -1374,6 +1382,8 @@
       "originUrl": "https://github.com/yeachan-heo/oh-my-claudecode/blob/50f6ff05eb5d9ebed66f05d8c4580c0b119f37af/agents/designer.md",
       "pinnedRef": "50f6ff05eb5d9ebed66f05d8c4580c0b119f37af",
       "ecosystem": "oh-my-claudecode",
+      "optInTier": "design",
+      "optInGroup": "UI design",
       "default": false,
       "requiresAny": [
         {
@@ -1437,6 +1447,8 @@
       "originUrl": "https://github.com/yeachan-heo/oh-my-claudecode/blob/50f6ff05eb5d9ebed66f05d8c4580c0b119f37af/agents/tracer.md",
       "pinnedRef": "50f6ff05eb5d9ebed66f05d8c4580c0b119f37af",
       "ecosystem": "oh-my-claudecode",
+      "optInTier": "review",
+      "optInGroup": "Incident tracing",
       "default": false,
       "requiresAny": [
         {
@@ -1609,6 +1621,8 @@
       "originUrl": "https://github.com/redis/agent-skills/blob/5ca2e1a2d82a768221e8f71a02e3ca095a37d38e/skills/redis-observability/SKILL.md",
       "pinnedRef": "5ca2e1a2d82a768221e8f71a02e3ca095a37d38e",
       "ecosystem": "redis",
+      "optInTier": "ops",
+      "optInGroup": "Redis security & observability",
       "requiresAny": [
         {
           "role": "redis-ops"
@@ -1639,6 +1653,8 @@
       "originUrl": "https://github.com/redis/agent-skills/blob/5ca2e1a2d82a768221e8f71a02e3ca095a37d38e/skills/redis-security/SKILL.md",
       "pinnedRef": "5ca2e1a2d82a768221e8f71a02e3ca095a37d38e",
       "ecosystem": "redis",
+      "optInTier": "ops",
+      "optInGroup": "Redis security & observability",
       "requiresAny": [
         {
           "role": "redis-ops"
@@ -1714,7 +1730,7 @@
     },
     {
       "id": "haus.sentry-sentry-nextjs-sdk",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "source": "curated",
       "type": "skill",
       "path": "skills/sentry/sentry-nextjs-sdk",
@@ -1724,7 +1740,7 @@
       "whenNotToUse": "Do not use when a more specific skill or command applies.",
       "tags": ["workflow", "sentry", "nextjs", "observability"],
       "repoRoles": [],
-      "tokenEstimate": 4542,
+      "tokenEstimate": 4544,
       "installMode": "copy-selected",
       "default": false,
       "reviewStatus": "approved",
@@ -1733,8 +1749,8 @@
       "license": "MIT",
       "licenseConfidence": "high",
       "originSourceId": "getsentry-sentry-for-ai",
-      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/9ab3551758913a4144517d4fafb71476a48c64f8/skills/sentry-nextjs-sdk/SKILL.md",
-      "pinnedRef": "9ab3551758913a4144517d4fafb71476a48c64f8",
+      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/bd84576db74e3e1d13361c7eda3bb303ae017b90/skills/sentry-nextjs-sdk/SKILL.md",
+      "pinnedRef": "bd84576db74e3e1d13361c7eda3bb303ae017b90",
       "ecosystem": "sentry",
       "requiresAny": [
         {
@@ -1747,7 +1763,7 @@
     },
     {
       "id": "haus.sentry-sentry-node-sdk",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "source": "curated",
       "type": "skill",
       "path": "skills/sentry/sentry-node-sdk",
@@ -1757,7 +1773,7 @@
       "whenNotToUse": "Prefer sentry-nestjs-sdk for NestJS apps using @sentry/nestjs.",
       "tags": ["workflow", "sentry", "backend", "observability"],
       "repoRoles": [],
-      "tokenEstimate": 8085,
+      "tokenEstimate": 8087,
       "installMode": "copy-selected",
       "default": false,
       "reviewStatus": "approved",
@@ -1766,8 +1782,8 @@
       "license": "MIT",
       "licenseConfidence": "high",
       "originSourceId": "getsentry-sentry-for-ai",
-      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/9ab3551758913a4144517d4fafb71476a48c64f8/skills/sentry-node-sdk/SKILL.md",
-      "pinnedRef": "9ab3551758913a4144517d4fafb71476a48c64f8",
+      "originUrl": "https://github.com/getsentry/sentry-for-ai/blob/bd84576db74e3e1d13361c7eda3bb303ae017b90/skills/sentry-node-sdk/SKILL.md",
+      "pinnedRef": "bd84576db74e3e1d13361c7eda3bb303ae017b90",
       "ecosystem": "sentry",
       "requiresAny": [
         {
@@ -2124,6 +2140,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/finishing-a-development-branch",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Git worktrees & branch finishing",
       "requiresAny": [
         {
           "role": "branch-completion"
@@ -2153,6 +2171,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/receiving-code-review",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Code review workflow",
       "requiresAny": [
         {
           "role": "code-review"
@@ -2182,6 +2202,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/requesting-code-review",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Code review workflow",
       "requiresAny": [
         {
           "role": "code-review"
@@ -2211,6 +2233,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/specifying-gates",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Quality gates",
       "requiresAny": [
         {
           "role": "user-gate"
@@ -2240,6 +2264,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/48f5123e18a1a92dfba962da8dc2509391c821ee/skills/subagent-driven-development",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Subagent-driven development",
       "pinnedRef": "48f5123e18a1a92dfba962da8dc2509391c821ee",
       "requiresAny": [
         {
@@ -2294,6 +2320,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/test-driven-development",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "TDD workflow",
       "requiresAny": [
         {
           "role": "tdd-workflow"
@@ -2323,6 +2351,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/20c0b1ed71cb073c847432fe01379f48c5278a5f/skills/using-git-worktrees",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Git worktrees & branch finishing",
       "pinnedRef": "20c0b1ed71cb073c847432fe01379f48c5278a5f",
       "requiresAny": [
         {
@@ -2427,6 +2457,8 @@
       "originSourceId": "superpowers-pcvelz",
       "originUrl": "https://github.com/pcvelz/superpowers/tree/bd000c6ec1df53449a74397f55305b22802b9a2b/skills/writing-skills",
       "ecosystem": "superpowers",
+      "optInTier": "workflow",
+      "optInGroup": "Skill authoring",
       "requiresAny": [
         {
           "role": "skill-authoring"

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

@@ -31,13 +31,37 @@ Do this in order:
    deep read discovered. You MUST run this before the next apply — `haus apply`
    does not re-calculate recommendations on its own.
 
-5. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
-   so this just adds the newly-matched helpers from step 4.
+5. **Offer optional helpers.** Read `.haus-workflow/recommendation.json` yourself
+   (never show the JSON). Two kinds of optional extras may be listed; offer only
+   the ones present, all **unchecked** by default — these are opt-in:
+   - **Optional skills & agents** (`optInEligible[]`): workflow/ops/review/design
+     helpers that don't auto-install for this stack. Group them by their
+     `optInGroup` label and present one `AskUserQuestion` option per group
+     (use each item's `purpose` and `tokenEstimate` to describe it in plain
+     language, e.g. "Code review workflow — request/receive structured reviews").
+     Collect the item ids from **all** the groups the user picked into one list
+     and run a **single** `haus recommend --include <id> <id> …` (one command with
+     every chosen id). Don't run it once per group — each run rewrites
+     `recommendation.json`, so repeated calls would drop the earlier includes.
+   - **Project config** (entries in `recommended[]` with `install: false`, e.g.
+     Haus ESLint / Prettier baselines): offer each as a plain choice ("Add the
+     Haus ESLint baseline"). On confirm, run `haus scaffold <id>`. `haus scaffold`
+     **preserves existing config files by default** and tells you when a file
+     already exists — only re-run with `haus scaffold <id> --force` if the user
+     explicitly chooses to **replace** their current config.
 
-6. **Confirm.** End with one plain-language line, for example:
+   If neither list has anything, skip this step silently — don't ask an empty
+   question.
+
+6. **Apply the rest.** Run `haus apply --write` again. It only writes what changed,
+   so this adds the newly-matched helpers from step 4 plus any opt-ins from step 5.
+
+7. **Confirm.** End with one plain-language line, for example:
    "✅ Your project is configured — I wrote your project docs, added N guardrails
-   and M coding helpers (K matched after reading your code in depth). Run
-   `/haus-doctor` any time to re-check." Fill the numbers from the apply output.
+   and M coding helpers (K matched after reading your code in depth), plus the J
+   optional helpers you chose: <name them>. Run `/haus-doctor` any time to
+   re-check." Fill the numbers from the apply output, and name the opt-ins the
+   user picked in step 5 (omit that clause if they chose none).
 
 If anything fails, explain what happened in plain language and what you'll try
 next — don't dump raw errors.

package/library/global/skills/haus-workflow/SKILL.md

@@ -26,6 +26,7 @@ The short legacy aliases still work but the names below are canonical.
 | `project:init` (`setup`, `init`)                                  | _Setup procedure below_         | project | First-time setup of an **existing** repo: adds AI skills, commands, workflow + project docs                                                                                               |
 | `project:clone [name]` (`clone`)                                  | _Clone procedure below_         | project | No name: clone a **workspace**'s repos from `repos.manifest.json`. With a `name`: find & clone one repo by name from GitHub                                                               |
 | `project:cloneandsetup [name]` (`cloneandsetup`)                  | _Clone & setup procedure below_ | project | Run `project:clone`, then set up each repo for local dev — deps, databases, cross-repo links, and env — via each repo's `.haus-workflow/localdev.yml` (+ the workspace's order/links/env) |
+| `project:add-skills` (`add-skills`, `opt-in`)                     | _Add-skills procedure below_    | project | Add optional skills, agents, or config (ESLint/Prettier) to an already-set-up project without re-running full setup                                                                       |
 | `project:refresh` (`apply`, `refresh`, `claude-md`, `regenerate`) | `haus apply --write`            | project | Re-run setup / refresh `.claude/` context + regenerate root `CLAUDE.md` import block                                                                                                      |
 | `project:doctor` (`doctor`, `check`)                              | `haus doctor`                   | project | Check for install drift                                                                                                                                                                   |
 | `update` (`upgrade`)                                              | `haus update`                   | global  | Update npm package + catalog + `~/.claude/` (also refreshes this project)                                                                                                                 |
@@ -51,6 +52,8 @@ Options:
      (no name: clone a workspace from repos.manifest.json; with a name: find & clone one repo by name from GitHub)
   5. [project] project:cloneandsetup [name] — clone repos, then set them up for local dev
      (project:clone, then per-repo deps + databases + cross-repo links + env from localdev.yml)
+  6. [project] project:add-skills — add optional skills, agents, or config to this project
+     (offers opt-in helpers matching your stack that aren't installed yet — no full re-setup)
 ```
 
 Map the user's selection to the command from the alias table, then continue to Step 2.
@@ -65,6 +68,8 @@ Run the mapped command via Bash. Quote the exact command you are running before
 
 **Exception — `project:cloneandsetup` (`cloneandsetup`):** clone followed by a per-repo setup pass, with confirmations. Skip to **Clone & setup (`project:cloneandsetup`)** under Step 3 and follow it.
 
+**Exception — `project:add-skills` (`add-skills` / `opt-in`):** a short scan → recommend → choose → apply procedure. Skip to **Add optional skills (`project:add-skills`)** under Step 3 and follow it.
+
 ## Step 3 — Post-run steps
 
 After the command completes, follow the relevant post-run steps below.
@@ -82,6 +87,31 @@ After the command completes, follow the relevant post-run steps below.
 
 1. Open and follow `~/.claude/commands/haus-cloneandsetup.md` — it runs the full `project:clone` flow, then sets up each cloned repo locally: selects the node version (`nvm install` from `.nvmrc`), enables corepack, installs JS/PHP dependencies, and seeds `.env`, confirming before each phase. It does not start servers.
 
+### Add optional skills (`project:add-skills`)
+
+For a project that's already set up but where the user wants more helpers later —
+without re-running the full `project:init` flow. Never show raw JSON; offer plain
+choices.
+
+1. Refresh the picture: run `haus scan --json` then `haus recommend` (it re-reads
+   `.haus-workflow/deep-context.json` if present).
+2. Read `.haus-workflow/recommendation.json` and `.haus-workflow/haus.lock.json`
+   yourself. Build the choices from items **not already installed** (lock ids):
+   - **Optional skills & agents** — `optInEligible[]`, grouped by `optInGroup`
+     (each carries `purpose` + `tokenEstimate` for a plain-language label).
+   - **Project config** — `recommended[]` entries with `install: false` (Haus
+     ESLint / Prettier) whose files aren't already present.
+3. If nothing is eligible, say so plainly and stop — e.g. "Everything matching
+   your stack is already installed" or "No optional helpers for this stack."
+4. Otherwise present a single `AskUserQuestion` (multi-select, all unchecked)
+   with one option per group / config item. Then:
+   - Skills/agents → `haus recommend --include <id> <id> …`, then
+     `haus apply --write`.
+   - Config → `haus scaffold <id>` (add `--force` only if the user chose to
+     replace an existing file; scaffold preserves files by default).
+5. Confirm with the names added and their combined token estimate, e.g.
+   "Added 2 optional helpers: Code review workflow, TDD workflow (~3k tokens)."
+
 ### After `haus apply --write`
 
 Verify that the root `CLAUDE.md` imports all three haus files:

package/package.json

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