forge-orkes 0.62.0 → 0.64.0

package/bin/create-forge.js

@@ -10,6 +10,26 @@ const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
 const pkgVersion = require('../package.json').version;
 
+// --- CLI flags (parsed once up front) ---
+
+// --json: machine-readable `upgrade` mode — exactly ONE JSON document on stdout
+// (the report, or an {error, reason} object on refusal); every line of human
+// prose is diverted to stderr so stdout stays parseable. --yes: auto-confirm
+// stale-framework-file removal ONLY — it never bypasses the downgrade guard
+// (that remains --force, which keeps its existing dual meaning).
+const jsonMode = process.argv.includes('--json');
+const yesMode = process.argv.includes('--yes');
+
+// Route human prose: stdout normally, stderr under --json.
+function say(...args) {
+  (jsonMode ? console.error : console.log)(...args);
+}
+
+// The only stdout write allowed in --json mode: one JSON document.
+function emitJson(doc) {
+  process.stdout.write(JSON.stringify(doc, null, 2) + '\n');
+}
+
 // --- CLAUDE.md import management ---
 
 // The framework prose lives in .forge/FORGE.md (a framework-owned file). CLAUDE.md
@@ -39,15 +59,15 @@ const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 // They are NOT in the shipped base template, so the framework-owned auto-clean
 // would otherwise delete them on upgrade. Preserve them instead.
 //
-// The npm tarball ships only bin/ + template/ — NOT experimental/ — so this route
-// cannot diff or re-sync an experimental skill against its source. Preserving
-// blindly is what silently froze them pre-0.33.0 (issue #5): a base migration that
-// changed experimental-skill behavior became a no-op. The structural fix lives
-// elsewhere — (a) the clone-based `upgrading` skill (Step 3b) offers a real
-// re-sync against experimental/*/source, and (b) load-bearing conventions are
-// promoted to base (FORGE.md) so they no longer depend on the frozen skill. Here
-// we can only PRESERVE + flag, so the report below tells the user staleness was
-// not checked and how to refresh.
+// The npm tarball ships experimental/ alongside bin/ + template/, so this route
+// CAN diff an installed experimental skill against its same-tarball source:
+// detectExperimentalStaleness() reports unchanged|stale with the differing files.
+// (Blind preservation is what silently froze these pre-0.33.0 — issue #5: a base
+// migration that changed experimental-skill behavior became a no-op.) Detection
+// only — consent for a re-sync lives in the /upgrading skill layer, and
+// load-bearing conventions are still promoted to base (FORGE.md) rather than
+// left to a frozen skill. This preserve-list gates auto-clean only; staleness
+// discovery is by directory scan of the shipped experimental/ tree.
 const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
 
 function isExperimentalSkillPath(displayPath) {
@@ -532,10 +552,14 @@ function extractDetectionBlock(guideContent) {
  * pkgVersion (this package's package.json) — never the template settings.json
  * literal, which is a placeholder the installer stamps at write time. Non-
  * interactive: the bin only warns and points at the guide; it never applies.
+ *
+ * Returns the applying guides as [{version, guide, reason}] — the human warning
+ * and the --json `migrations` key render the same findings.
  */
 function runPostUpgradeMigrationChecks(installedVersion) {
+  const found = [];
   const migrationsDir = path.join(targetDir, '.forge', 'migrations');
-  if (!fs.existsSync(migrationsDir)) return;
+  if (!fs.existsSync(migrationsDir)) return found;
 
   const installed =
     installedVersion && installedVersion !== 'unknown' ? installedVersion : '0.0.0';
@@ -558,7 +582,7 @@ function runPostUpgradeMigrationChecks(installedVersion) {
       )
       .sort((a, b) => compareVersions(a.version, b.version));
   } catch {
-    return;
+    return found;
   }
 
   for (const guide of guides) {
@@ -598,18 +622,22 @@ function runPostUpgradeMigrationChecks(installedVersion) {
       ? reasonLine.replace(/^.*MIGRATE\s*[—-]?\s*/, '').trim()
       : '';
 
-    console.log(`  ⚠  ${guide.version} migration available${reason ? ` — ${reason}` : ''}`);
-    console.log('  ─────────────────────────────────────────────────────────────');
-    console.log(`  Guide: .forge/migrations/${guide.name}`);
-    console.log(
+    const hit = { version: guide.version, guide: `.forge/migrations/${guide.name}`, reason };
+    found.push(hit);
+
+    say(`  ⚠  ${hit.version} migration available${hit.reason ? ` — ${hit.reason}` : ''}`);
+    say('  ─────────────────────────────────────────────────────────────');
+    say(`  Guide: ${hit.guide}`);
+    say(
       `         (canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/${guide.name})`
     );
-    console.log();
-    console.log('  Migrations are never applied automatically. In Claude Code:');
-    console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
-    console.log('    with the guide path as the task definition.');
-    console.log();
+    say();
+    say('  Migrations are never applied automatically. In Claude Code:');
+    say('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
+    say('    with the guide path as the task definition.');
+    say();
   }
+  return found;
 }
 
 /**
@@ -632,8 +660,87 @@ function syncFrameworkFile(srcPath, destPath, displayName, results) {
   }
 }
 
+/**
+ * Real staleness detection for opt-in experimental skills (FR-185). The tarball
+ * ships experimental/ (m10, conventions), so the bin diffs an installed
+ * experimental skill against its own same-tarball source. Discovery is by
+ * directory scan — an installed skill dir absent from the base template is a
+ * candidate; a matching {packageRoot}/experimental/{pkg}/source/skills/{name}/
+ * makes it reportable. A skill with no experimental source (a project-local
+ * skill) keeps today's preserved/removed-from-template verdicts and is not
+ * reported here. Detection ONLY: the bin never copies or overwrites an
+ * experimental skill — re-sync consent lives in the /upgrading skill (FR-186).
+ *
+ * Returns [{name, pkg, status: 'unchanged'|'stale', files: [differing .md]}].
+ */
+function detectExperimentalStaleness() {
+  const found = [];
+  const installedSkillsDir = path.join(targetDir, '.claude', 'skills');
+  const templateSkillsDir = path.join(templateDir, '.claude', 'skills');
+  const experimentalRoot = path.join(__dirname, '..', 'experimental');
+
+  let installed;
+  try {
+    installed = fs
+      .readdirSync(installedSkillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return found; // no installed skills dir — nothing to report
+  }
+
+  let pkgs = [];
+  try {
+    pkgs = fs
+      .readdirSync(experimentalRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return found; // tarball without experimental/ — nothing to diff against
+  }
+
+  for (const name of installed) {
+    if (fs.existsSync(path.join(templateSkillsDir, name))) continue; // base skill
+    for (const pkg of pkgs) {
+      const srcDir = path.join(experimentalRoot, pkg, 'source', 'skills', name);
+      if (!fs.existsSync(srcDir)) continue;
+      const destDir = path.join(installedSkillsDir, name);
+      const differing = [];
+      for (const rel of collectFiles(srcDir, '')) {
+        if (!rel.endsWith('.md')) continue;
+        const destPath = path.join(destDir, rel);
+        if (
+          !fs.existsSync(destPath) ||
+          Buffer.compare(
+            fs.readFileSync(path.join(srcDir, rel)),
+            fs.readFileSync(destPath)
+          ) !== 0
+        ) {
+          differing.push(rel);
+        }
+      }
+      found.push({
+        name,
+        pkg,
+        status: differing.length ? 'stale' : 'unchanged',
+        files: differing,
+      });
+      break; // first matching experimental pkg wins
+    }
+  }
+  return found;
+}
+
 async function upgrade() {
-  console.log('\n  Forge Upgrade\n');
+  // A --json run must be non-interactive end-to-end: a prompt would corrupt the
+  // machine-read stream, so --json without --yes is refused before any work.
+  if (jsonMode && !yesMode) {
+    console.error('  ✖ --json requires --yes (a prompt would corrupt a machine run).\n');
+    emitJson({ error: 'yes_required', reason: '--json requires --yes' });
+    process.exit(1);
+  }
+
+  say('\n  Forge Upgrade\n');
 
   // Verify Forge is installed
   const settingsPath = path.join(targetDir, SETTINGS_FILE);
@@ -641,6 +748,12 @@ async function upgrade() {
     console.error(
       '  Forge is not installed in this directory.\n  Run `npx forge-orkes` first to install.\n'
     );
+    if (jsonMode) {
+      emitJson({
+        error: 'not_installed',
+        reason: 'Forge is not installed in this directory — run `npx forge-orkes` first',
+      });
+    }
     process.exit(1);
   }
 
@@ -653,8 +766,8 @@ async function upgrade() {
     // proceed with unknown version
   }
 
-  console.log(`  Installed: v${installedVersion}`);
-  console.log(`  Available: v${pkgVersion}\n`);
+  say(`  Installed: v${installedVersion}`);
+  say(`  Available: v${pkgVersion}\n`);
 
   // Downgrade guard: refuse to roll backward (overwrites newer framework files
   // with older ones and deletes files newer versions added). Almost always a
@@ -669,6 +782,12 @@ async function upgrade() {
     console.error(`    This usually means a stale npx cache served an old forge-orkes.`);
     console.error(`    Fix:  npx forge-orkes@latest upgrade   (or clear the cache: rm -rf ~/.npm/_npx)`);
     console.error(`    To downgrade intentionally: forge-orkes upgrade --force\n`);
+    if (jsonMode) {
+      emitJson({
+        error: 'downgrade_refused',
+        reason: `installed v${installedVersion} is newer than available v${pkgVersion}`,
+      });
+    }
     process.exit(1);
   }
 
@@ -720,12 +839,9 @@ async function upgrade() {
   //     to yes (cleanup is the normal case); auto-confirms when non-interactive
   //     (CI / piped stdin) or with --force/--yes, preserving prior behavior.
   if (pendingRemovals.length > 0) {
-    const auto =
-      process.argv.includes('--force') ||
-      process.argv.includes('--yes') ||
-      !process.stdin.isTTY;
-    console.log(`  ${pendingRemovals.length} stale framework file(s) no longer in the template:`);
-    for (const c of pendingRemovals) console.log(`    ${c.displayPath}`);
+    const auto = force || yesMode || !process.stdin.isTTY;
+    say(`  ${pendingRemovals.length} stale framework file(s) no longer in the template:`);
+    for (const c of pendingRemovals) say(`    ${c.displayPath}`);
     let go = auto;
     if (!auto) {
       const ans = await prompt('  Remove these stale framework files? [Y/n] ');
@@ -743,12 +859,12 @@ async function upgrade() {
         results.removed.push(c.displayPath);
       }
     } else {
-      console.log('  Keeping stale files (skipped removal).');
+      say('  Keeping stale files (skipped removal).');
       for (const c of pendingRemovals) {
         results.preserved.push(`${c.displayPath} (stale — kept by choice)`);
       }
     }
-    console.log();
+    say();
   }
 
   // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
@@ -773,10 +889,10 @@ async function upgrade() {
   const claudeStatus = ensureClaudeMdImport();
   if (claudeStatus === 'migrated') {
     results.updated.push('CLAUDE.md');
-    console.log('  CLAUDE.md migrated: forge section extracted to .forge/FORGE.md (@import)');
+    say('  CLAUDE.md migrated: forge section extracted to .forge/FORGE.md (@import)');
   } else if (claudeStatus === 'appended') {
     results.updated.push('CLAUDE.md');
-    console.log('  CLAUDE.md: @.forge/FORGE.md import line restored');
+    say('  CLAUDE.md: @.forge/FORGE.md import line restored');
   } else if (claudeStatus === 'unchanged') {
     results.unchanged.push('CLAUDE.md');
   } else if (claudeStatus === 'created') {
@@ -791,64 +907,88 @@ async function upgrade() {
     results.unchanged.push(SETTINGS_FILE);
   }
 
+  // 5. Diff installed experimental skills against their same-tarball sources
+  //    (detection only — never written; re-sync consent lives in /upgrading).
+  const experimental = detectExperimentalStaleness();
+
   // Report results
   const totalChanges = results.updated.length + results.added.length;
-
-  if (totalChanges === 0 && results.removed.length === 0) {
-    console.log('  Already up to date.\n');
-    return;
-  }
-
-  if (results.updated.length > 0) {
-    console.log(`  Updated (${results.updated.length}):`);
-    for (const f of results.updated) {
-      console.log(`    ${f}`);
+  const upToDate = totalChanges === 0 && results.removed.length === 0;
+
+  if (upToDate) {
+    say('  Already up to date.\n');
+    // Human mode preserves the historical early exit: an up-to-date project
+    // skips the migration checks and notices entirely. --json continues so the
+    // report document always carries every contract key.
+    if (!jsonMode) return;
+  } else {
+    if (results.updated.length > 0) {
+      say(`  Updated (${results.updated.length}):`);
+      for (const f of results.updated) {
+        say(`    ${f}`);
+      }
+      say();
     }
-    console.log();
-  }
 
-  if (results.added.length > 0) {
-    console.log(`  Added (${results.added.length}):`);
-    for (const f of results.added) {
-      console.log(`    ${f}`);
+    if (results.added.length > 0) {
+      say(`  Added (${results.added.length}):`);
+      for (const f of results.added) {
+        say(`    ${f}`);
+      }
+      say();
     }
-    console.log();
-  }
 
-  if (results.removed.length > 0) {
-    console.log(`  Cleaned up (${results.removed.length}):`);
-    for (const f of results.removed) {
-      console.log(`    ${f} (removed — no longer in framework)`);
+    if (results.removed.length > 0) {
+      say(`  Cleaned up (${results.removed.length}):`);
+      for (const f of results.removed) {
+        say(`    ${f} (removed — no longer in framework)`);
+      }
+      say();
     }
-    console.log();
-  }
 
-  if (results.preserved.length > 0) {
-    console.log(`  Preserved (${results.preserved.length}):`);
-    for (const f of results.preserved) {
-      console.log(`    ${f} (kept — opt-in experimental skill; staleness not checked by npm)`);
+    if (results.preserved.length > 0) {
+      say(`  Preserved (${results.preserved.length}):`);
+      for (const f of results.preserved) {
+        say(`    ${f} (kept — opt-in experimental skill)`);
+      }
+      for (const e of experimental) {
+        say(
+          e.status === 'stale'
+            ? `    ↳ ${e.name} (${e.pkg}): stale — differs from the shipped source: ${e.files.join(', ')}`
+            : `    ↳ ${e.name} (${e.pkg}): up to date with the shipped source`
+        );
+      }
+      say(`    ↳ re-sync via /upgrading (consent-gated; the bin never overwrites these)`);
+      say();
     }
-    console.log(
-      `    ↳ The npm upgrade does not ship experimental sources, so it cannot`
-    );
-    console.log(
-      `      re-sync these. To refresh against a Forge clone, run the \`upgrading\``
-    );
-    console.log(
-      `      skill (offers a re-sync), or re-run \`experimental/<pkg>/install.sh\`.`
-    );
-    console.log();
-  }
 
-  console.log(`  Upgraded to v${pkgVersion}\n`);
+    say(`  Upgraded to v${pkgVersion}\n`);
+  }
 
   // Pass the version captured BEFORE upgradeSettings() stamped the new one, so the
   // migration range is (installed, source] against the freshly-synced guides.
-  runPostUpgradeMigrationChecks(installedVersion);
+  const migrations = runPostUpgradeMigrationChecks(installedVersion);
 
   // Presence-gated advisories (no generation, no rebase — notices only).
-  noticeCodexAdapter();
-  noticeWorktreeLag();
+  const codexAdapterPresent = noticeCodexAdapter();
+  const worktrees = noticeWorktreeLag();
+
+  if (jsonMode) {
+    emitJson({
+      schemaVersion: 1,
+      command: 'upgrade',
+      installedVersion,
+      packageVersion: pkgVersion,
+      packageRoot: path.join(__dirname, '..'),
+      results,
+      claudeMd: claudeStatus,
+      settings: settingsStatus,
+      experimental,
+      migrations,
+      codexAdapterPresent,
+      worktrees,
+    });
+  }
 }
 
 /**
@@ -857,17 +997,21 @@ async function upgrade() {
  * .claude/ sync and point to the regeneration route (/upgrading Step 4b). It
  * never generates, never writes .agents/, never adds .agents to
  * FRAMEWORK_OWNED_DIRS. Silent when no Codex adapter is present.
+ *
+ * Returns whether a Codex adapter is present — the human notice and the --json
+ * `codexAdapterPresent` key render the same finding.
  */
 function noticeCodexAdapter() {
   const hasCodex =
     fs.existsSync(path.join(targetDir, '.agents')) ||
     fs.existsSync(path.join(targetDir, '.codex'));
-  if (!hasCodex) return;
-  console.log('  Codex adapter detected (.agents/ / .codex/).');
-  console.log('    It may now be stale relative to the .claude/ source just synced.');
-  console.log('    This installer does not regenerate it (no LLM). To refresh it,');
-  console.log('    run the `/upgrading` skill — its Codex step offers regeneration');
-  console.log('    from .forge/adapters/codex-generation.md.\n');
+  if (!hasCodex) return false;
+  say('  Codex adapter detected (.agents/ / .codex/).');
+  say('    It may now be stale relative to the .claude/ source just synced.');
+  say('    This installer does not regenerate it (no LLM). To refresh it,');
+  say('    run the `/upgrading` skill — its Codex step offers regeneration');
+  say('    from .forge/adapters/codex-generation.md.\n');
+  return true;
 }
 
 /**
@@ -876,6 +1020,9 @@ function noticeCodexAdapter() {
  * branch-point framework files until rebased. The bin only NOTICES — it never
  * rebases (a rebase can conflict). Silent when there are no live forge worktrees
  * or this is not a git repo.
+ *
+ * Returns the lagging worktrees as [{path, branch}] — the human notice and the
+ * --json `worktrees` key render the same findings.
  */
 function noticeWorktreeLag() {
   let out;
@@ -885,7 +1032,7 @@ function noticeWorktreeLag() {
       stdio: ['ignore', 'pipe', 'ignore'],
     }).toString();
   } catch {
-    return; // not a git repo / git unavailable
+    return []; // not a git repo / git unavailable
   }
   const lagging = [];
   let curPath = null;
@@ -898,15 +1045,16 @@ function noticeWorktreeLag() {
       }
     }
   }
-  if (!lagging.length) return;
-  console.log(`  ${lagging.length} live Forge worktree(s) lag this upgrade:`);
+  if (!lagging.length) return lagging;
+  say(`  ${lagging.length} live Forge worktree(s) lag this upgrade:`);
   for (const w of lagging) {
-    console.log(`    ${w.path} (${w.branch})`);
+    say(`    ${w.path} (${w.branch})`);
   }
-  console.log('    They keep their branch-point framework files until rebased.');
-  console.log('    Pick up this upgrade in each:  git -C <path> rebase main');
-  console.log('    (Gitignored carve-outs like .mcp.json / experimental hooks do not');
-  console.log('     rebase — re-run the experimental installer if the upgrade changed them.)\n');
+  say('    They keep their branch-point framework files until rebased.');
+  say('    Pick up this upgrade in each:  git -C <path> rebase main');
+  say('    (Gitignored carve-outs like .mcp.json / experimental hooks do not');
+  say('     rebase — re-run the experimental installer if the upgrade changed them.)\n');
+  return lagging;
 }
 
 // --- Entry point ---
@@ -931,18 +1079,21 @@ assertSaneTargetDir();
 
 const subcommand = process.argv[2];
 
+// Shared failure path for both upgrade entries: human error on stderr; under
+// --json also emit the {error, reason} document so a machine caller always
+// gets a parseable stdout even on an unexpected failure.
+function upgradeFailed(err) {
+  console.error('Error:', err.message);
+  if (jsonMode) emitJson({ error: 'upgrade_failed', reason: err.message });
+  process.exit(1);
+}
+
 if (subcommand === 'upgrade') {
-  upgrade().catch((err) => {
-    console.error('Error:', err.message);
-    process.exit(1);
-  });
+  upgrade().catch(upgradeFailed);
 } else if (isForgeInstalled()) {
   // Auto-detect: Forge already installed, run upgrade instead
-  console.log('  Forge detected — running upgrade automatically.\n');
-  upgrade().catch((err) => {
-    console.error('Error:', err.message);
-    process.exit(1);
-  });
+  say('  Forge detected — running upgrade automatically.\n');
+  upgrade().catch(upgradeFailed);
 } else {
   install().catch((err) => {
     console.error('Error:', err.message);

package/experimental/conventions/README.md

@@ -0,0 +1,87 @@
+# Forge Conventions — Stack Convention Skills + Rules (Experimental)
+
+## Status
+
+**Experimental, opt-in.** Per [ADR-018](../../../../docs/decisions/ADR-018-lightweight-policy-layer.md), Forge core is **stack-agnostic** — it ships only the always-on `agent-discipline.md` rule and zero stack-specific conventions. Anything tied to a particular framework (Laravel, Vue, Python) would make core non-portable, so it lives here as an opt-in pack you install **only when your project's stack matches**, exactly like the `m10` orchestration pack.
+
+This pack is **not shipped on npm.** The `create-forge` tarball publishes only `bin/` + `template/` (same as `m10`). Convention packs are delivered via the dev repo or the `upgrading` skill's experimental route — clone/pull the Forge dev repo and run the installer against your project.
+
+## What it is
+
+Opt-in stack convention **skills** (heavy, task-triggered checklists) plus path-scoped **rules** (lightweight, file-path-triggered ambient reminders) for:
+
+- **Laravel / PHP** — strict types, thin controllers, Services/Actions, Eloquent, migrations, jobs, security
+- **Python** — type hints, Pydantic v2, async patterns, Django/FastAPI, DI via Protocols, tooling
+- **Vue / Inertia** — `<script setup lang="ts">`, generated-type contracts, `useForm`, accessibility
+- **Universal testing & code quality** — behaviour-not-implementation tests, function-size/magic-value discipline
+
+The skills load when a task description matches; the path-scoped rules cost **zero context** until you touch a matching file (`app/Http/**`, `**/*.vue`, `**/*.py`, …). See the rules-layer design in [ADR-018](../../../../docs/decisions/ADR-018-lightweight-policy-layer.md) and `.claude/rules/README.md` in core.
+
+These conventions are de-coupled from any single company's setup: multi-tenancy is treated as conditional ("multi-tenant apps") rather than assumed, and the Laravel layout supports both **standard** Laravel (`app/Http/**`, `app/Services/**`) and a nested **module** layout (`app/<project>/<module>/Http/**`) — the rules are dual-globbed so they fire on either.
+
+## What it installs
+
+Into the **target project's** `.claude/`:
+
+### Skills → `.claude/skills/`
+| Skill | Stack |
+|---|---|
+| `laravel-conventions/` | laravel |
+| `python-conventions/` | python |
+| `vue-conventions/` | vue |
+| `testing-standards/` | testing |
+
+### Rules → `.claude/rules/`
+| Rule | Stack | Scope (`paths:`) |
+|---|---|---|
+| `laravel-http.md` | laravel | `app/Http/**`, `app/*/*/Http/**` |
+| `laravel-services.md` | laravel | `app/Services/**`, `app/Actions/**` (+ module globs) |
+| `laravel-jobs.md` | laravel | `app/Jobs/**`, `app/*/*/Jobs/**` |
+| `laravel-migrations.md` | laravel | `database/migrations/**` (+ module glob) |
+| `vue-inertia.md` | vue | `resources/js/pages/**`, `resources/js/components/**`, `**/*.vue` |
+| `python.md` | python | `**/*.py` |
+| `code-quality.md` | universal | always-on (no `paths:`) |
+| `testing.md` | universal / testing | always-on (no `paths:`) |
+
+**Why `code-quality.md` and `testing.md` are included (and additive, not redundant with core):** core ships only `agent-discipline.md`, which covers *agent* failure modes (scope creep, phantom deps, hallucinated APIs). It does **not** cover code *shape* (function/file size, magic values, nesting) or the ambient testing floor (AAA, one-behaviour-per-test, no flaky retries). Both are universal and stack-agnostic, so they ship here as always-on rules that complement core. `agent-discipline.md` itself is **not** re-shipped — it already lives in core, so installing it again would clobber/duplicate.
+
+## Install
+
+Run from your project root (the directory containing `.forge/project.yml`):
+
+```bash
+# All stacks:
+bash experimental/conventions/install.sh
+
+# Selectively — only the stacks you use:
+bash experimental/conventions/install.sh laravel vue
+bash experimental/conventions/install.sh python
+bash experimental/conventions/install.sh testing universal
+
+# Explicit target path + stacks:
+bash experimental/conventions/install.sh /path/to/your/project laravel
+
+# Preview without writing:
+bash experimental/conventions/install.sh --dry-run laravel
+```
+
+Stacks: `laravel`, `python`, `vue`, `testing`, `universal`. No stack args = install all.
+
+**Idempotent and non-clobbering.** If a target skill or rule of the same name already exists in `.claude/`, the installer **skips it and warns** rather than overwriting — this avoids the half-install / stale-skill trap (a same-named skill present from a prior install or your own authoring is never silently replaced). To intentionally refresh a stale file, delete the existing one first, then re-run.
+
+## Uninstall
+
+```bash
+# Remove everything this pack installed:
+bash experimental/conventions/uninstall.sh
+
+# Remove only specific stacks:
+bash experimental/conventions/uninstall.sh laravel
+bash experimental/conventions/uninstall.sh /path/to/your/project vue
+```
+
+The uninstaller only touches files this pack ships; your own skills/rules are left alone. Note: `testing.md` is shared by the `testing` and `universal` stacks, so removing either stack removes it.
+
+## Selective install rationale
+
+Install only the stacks a project actually uses. A pure-Python service has no business carrying Laravel HTTP rules; a Vue+Laravel app skips `python`. Path-scoped rules cost zero context until a matching file is touched, but keeping the install scoped to your stack keeps `.claude/` clean and the skill list short.