@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/bin/lib/seed-ai-local-team.js

@@ -0,0 +1,435 @@
+/**
+ * Seed consumer `.ai.local/team/` (shared across Cursor, Claude, Mavis, OpenCode).
+ * Living task slugs are never overwritten. `clean` must not own this tree.
+ *
+ * Legacy `.<tool>/team/` migration is non-destructive: every non-`README.md`
+ * entry is migrated and backed up before it is removed, deletion happens only
+ * after the copies are verified, and symlinked paths are refused rather than
+ * followed (they would let `rmSync` escape the resolved `--cwd`).
+ */
+const fs = require('fs');
+const path = require('path');
+
+const LEGACY_TOOLS = ['cursor', 'claude', 'mavis', 'opencode'];
+const POINTER_README = `# Agent team artifacts moved
+
+Runtime artifacts now live at \`.ai.local/team/\` (shared across Cursor, Claude, Mavis, and OpenCode).
+
+This leftover directory is safe to delete.
+`;
+
+function destTeamRoot(cwd) {
+  return path.join(cwd, '.ai.local', 'team');
+}
+
+function warn(message) {
+  console.warn(`Warning: ${message}`);
+}
+
+function hasConsumerTaskSlugs(tasksDir) {
+  if (!fs.existsSync(tasksDir) || !fs.statSync(tasksDir).isDirectory()) {
+    return false;
+  }
+  return fs.readdirSync(tasksDir, { withFileTypes: true }).some(
+    (entry) => entry.isDirectory() && !entry.name.startsWith('.'),
+  );
+}
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Copy a file or directory tree without ever following a symlink.
+ *
+ * @returns {{ copied: string[], skippedLinks: string[] }} relative paths, `.` for a plain file source
+ */
+function copyTree(src, dest) {
+  const copied = [];
+  const skippedLinks = [];
+  const visit = (from, to, rel) => {
+    const stat = fs.lstatSync(from);
+    if (stat.isSymbolicLink()) {
+      skippedLinks.push(rel);
+      return;
+    }
+    if (stat.isDirectory()) {
+      fs.mkdirSync(to, { recursive: true });
+      for (const name of fs.readdirSync(from)) {
+        visit(path.join(from, name), path.join(to, name), rel === '.' ? name : `${rel}/${name}`);
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      copyFile(from, to);
+      copied.push(rel);
+      return;
+    }
+    skippedLinks.push(rel);
+  };
+  visit(src, dest, '.');
+  return { copied, skippedLinks };
+}
+
+/** Relative file paths under a file-or-directory path, without following symlinks. */
+function listTree(target) {
+  const out = [];
+  const visit = (from, rel) => {
+    const stat = fs.lstatSync(from);
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(from)) {
+        visit(path.join(from, name), rel === '.' ? name : `${rel}/${name}`);
+      }
+      return;
+    }
+    out.push(rel);
+  };
+  visit(target, '.');
+  return out.sort();
+}
+
+function sameContent(a, b) {
+  const aStat = fs.lstatSync(a);
+  const bStat = fs.lstatSync(b);
+  if (aStat.isDirectory() !== bStat.isDirectory()) {
+    return false;
+  }
+  if (!aStat.isDirectory()) {
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  }
+  const aFiles = listTree(a);
+  const bFiles = listTree(b);
+  if (aFiles.length !== bFiles.length || aFiles.some((rel, i) => rel !== bFiles[i])) {
+    return false;
+  }
+  return aFiles.every((rel) =>
+    fs.readFileSync(path.join(a, rel)).equals(fs.readFileSync(path.join(b, rel))),
+  );
+}
+
+/** `notes.md` + `__from-claude` → `notes__from-claude.md`; directories get a plain suffix. */
+function suffixedName(name, tool, isDirectory) {
+  const suffix = `__from-${tool}`;
+  if (isDirectory) {
+    return `${name}${suffix}`;
+  }
+  const ext = path.extname(name);
+  return ext ? `${path.basename(name, ext)}${suffix}${ext}` : `${name}${suffix}`;
+}
+
+function freeDestination(dir, name, tool, isDirectory) {
+  let candidate = path.join(dir, suffixedName(name, tool, isDirectory));
+  let n = 2;
+  while (fs.existsSync(candidate)) {
+    const base = suffixedName(name, tool, isDirectory);
+    const ext = isDirectory ? '' : path.extname(base);
+    const stem = ext ? path.basename(base, ext) : base;
+    candidate = path.join(dir, `${stem}-${n}${ext}`);
+    n += 1;
+  }
+  return candidate;
+}
+
+/**
+ * Copy `src` to `preferredDest`; on collision keep both by writing the source to a
+ * `__from-<tool>` sibling. Never overwrites an existing destination.
+ *
+ * @returns {{ ok: boolean, copiedSomething: boolean }}
+ */
+function migrateEntry(src, preferredDest, tool, label) {
+  const isDirectory = fs.lstatSync(src).isDirectory();
+  if (fs.existsSync(preferredDest)) {
+    if (sameContent(src, preferredDest)) {
+      return { ok: true, copiedSomething: false };
+    }
+    const alternate = freeDestination(
+      path.dirname(preferredDest),
+      path.basename(preferredDest),
+      tool,
+      isDirectory,
+    );
+    const result = copyTree(src, alternate);
+    if (result.skippedLinks.length > 0) {
+      warn(
+        `${label}: ${result.skippedLinks.length} symlinked path(s) not migrated; left the source in place`,
+      );
+      return { ok: false, copiedSomething: result.copied.length > 0 };
+    }
+    warn(
+      `${label}: destination ${path.basename(preferredDest)} already exists with different content; kept the legacy copy as ${path.basename(alternate)}`,
+    );
+    return { ok: true, copiedSomething: true };
+  }
+  const result = copyTree(src, preferredDest);
+  if (result.skippedLinks.length > 0) {
+    warn(
+      `${label}: ${result.skippedLinks.length} symlinked path(s) not migrated; left the source in place`,
+    );
+    return { ok: false, copiedSomething: result.copied.length > 0 };
+  }
+  return { ok: true, copiedSomething: true };
+}
+
+/** Copy `src` under the timestamped backup root and verify the copy before the caller deletes. */
+function backupEntry(src, backupDest, label) {
+  const result = copyTree(src, backupDest);
+  if (result.skippedLinks.length > 0) {
+    warn(`${label}: symlinked path(s) could not be backed up; left the source in place`);
+    return false;
+  }
+  if (!fs.existsSync(backupDest)) {
+    warn(`${label}: backup copy is missing; left the source in place`);
+    return false;
+  }
+  const expected = listTree(src);
+  const actual = listTree(backupDest);
+  if (expected.length !== actual.length || expected.some((rel, i) => rel !== actual[i])) {
+    warn(`${label}: backup copy is incomplete; left the source in place`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Make `.ai.local/.rollback/` self-ignoring so a consumer cannot accidentally
+ * commit migration backups. A `.gitignore` inside the directory is used instead
+ * of appending to the consumer's root `.gitignore`: the CLI never edits that
+ * file, and this works even in a repo that has no `.gitignore` at all.
+ */
+function ensureRollbackIgnored(rollbackRoot) {
+  const ignoreFile = path.join(rollbackRoot, '.gitignore');
+  if (fs.existsSync(ignoreFile)) {
+    return;
+  }
+  fs.mkdirSync(rollbackRoot, { recursive: true });
+  fs.writeFileSync(
+    ignoreFile,
+    [
+      '# Backups written by @bonesofspring/ai-rules when it migrated a legacy',
+      '# `.<tool>/team/` into `.ai.local/team/`. Local safety net — never commit.',
+      '# Safe to delete once you have confirmed the migration.',
+      '*',
+      '',
+    ].join('\n'),
+  );
+}
+
+function copyTemplates(presetTeamSrc, dest) {
+  if (!presetTeamSrc || !fs.existsSync(presetTeamSrc)) {
+    return;
+  }
+  const readme = path.join(presetTeamSrc, 'README.md');
+  if (fs.existsSync(readme)) {
+    copyFile(readme, path.join(dest, 'README.md'));
+  }
+  const fixturesSrc = path.join(presetTeamSrc, 'fixtures');
+  if (fs.existsSync(fixturesSrc)) {
+    copyTree(fixturesSrc, path.join(dest, 'fixtures'));
+  }
+  const gitkeepSrc = path.join(presetTeamSrc, 'tasks', '.gitkeep');
+  if (fs.existsSync(gitkeepSrc) && !hasConsumerTaskSlugs(path.join(dest, 'tasks'))) {
+    copyFile(gitkeepSrc, path.join(dest, 'tasks', '.gitkeep'));
+  }
+}
+
+/**
+ * Seed `.ai.local/conventions.md` (the living-conventions file the overlay probes)
+ * from the preset template. Never overwrites an existing consumer file.
+ */
+function seedConventions(presetTeamSrc, cwd) {
+  if (!presetTeamSrc) {
+    return false;
+  }
+  const template = path.join(path.dirname(presetTeamSrc), 'ai-local', 'conventions.md');
+  if (!fs.existsSync(template)) {
+    return false;
+  }
+  const dest = path.join(cwd, '.ai.local', 'conventions.md');
+  if (fs.existsSync(dest)) {
+    return false;
+  }
+  copyFile(template, dest);
+  console.log('Seeded .ai.local/conventions.md');
+  return true;
+}
+
+/**
+ * Resolve a legacy `.<tool>/team` directory, refusing symlinks and anything whose
+ * real path escapes the resolved `cwd`. `rmSync` through a link would delete the
+ * target, which lives outside the install scope.
+ */
+function resolveLegacyTeamDir(cwd, tool) {
+  const teamDir = path.join(cwd, `.${tool}`, 'team');
+  let stat;
+  try {
+    stat = fs.lstatSync(teamDir);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) {
+    warn(`.${tool}/team is a symlink; refused to migrate or delete through it`);
+    return null;
+  }
+  if (!stat.isDirectory()) {
+    return null;
+  }
+  const cwdReal = fs.realpathSync(path.resolve(cwd));
+  const teamReal = fs.realpathSync(teamDir);
+  if (teamReal !== cwdReal && !teamReal.startsWith(cwdReal + path.sep)) {
+    warn(`.${tool}/team resolves outside ${cwdReal}; refused to migrate or delete it`);
+    return null;
+  }
+  return teamDir;
+}
+
+function migrateLegacyTool(tool, teamDir, cwd, dest, backupRoot) {
+  let copiedSomething = false;
+  const deletable = [];
+  let refused = 0;
+
+  for (const dirent of fs.readdirSync(teamDir, { withFileTypes: true })) {
+    const name = dirent.name;
+    if (name === 'README.md') {
+      continue;
+    }
+    const src = path.join(teamDir, name);
+    if (fs.lstatSync(src).isSymbolicLink()) {
+      warn(`.${tool}/team/${name} is a symlink; left it in place`);
+      refused += 1;
+      continue;
+    }
+
+    // `tasks/` is migrated child-by-child so slugs merge across tools. Dot-prefixed
+    // slugs and loose files under `tasks/` are entries like any other.
+    if (name === 'tasks' && fs.lstatSync(src).isDirectory()) {
+      let allOk = true;
+      fs.mkdirSync(path.join(dest, 'tasks'), { recursive: true });
+      for (const child of fs.readdirSync(src)) {
+        const childSrc = path.join(src, child);
+        if (fs.lstatSync(childSrc).isSymbolicLink()) {
+          warn(`.${tool}/team/tasks/${child} is a symlink; left it in place`);
+          allOk = false;
+          continue;
+        }
+        const outcome = migrateEntry(
+          childSrc,
+          path.join(dest, 'tasks', child),
+          tool,
+          `.${tool}/team/tasks/${child}`,
+        );
+        copiedSomething = copiedSomething || outcome.copiedSomething;
+        allOk = allOk && outcome.ok;
+      }
+      if (allOk) {
+        deletable.push(name);
+      } else {
+        refused += 1;
+      }
+      continue;
+    }
+
+    const preferredDest =
+      name === 'conventions.md'
+        ? path.join(cwd, '.ai.local', 'conventions.md')
+        : path.join(dest, name);
+    const outcome = migrateEntry(src, preferredDest, tool, `.${tool}/team/${name}`);
+    copiedSomething = copiedSomething || outcome.copiedSomething;
+    if (outcome.ok) {
+      deletable.push(name);
+    } else {
+      refused += 1;
+    }
+  }
+
+  // Back up first, verify, then delete — never the other way round.
+  let removed = 0;
+  for (const name of deletable) {
+    const src = path.join(teamDir, name);
+    if (!backupEntry(src, path.join(backupRoot, tool, name), `.${tool}/team/${name}`)) {
+      refused += 1;
+      continue;
+    }
+    fs.rmSync(src, { recursive: true, force: true });
+    removed += 1;
+  }
+
+  if (refused > 0) {
+    warn(
+      `.${tool}/team still holds ${refused} entr${refused === 1 ? 'y' : 'ies'} the migration could not account for; left the directory in place`,
+    );
+  } else {
+    fs.writeFileSync(path.join(teamDir, 'README.md'), POINTER_README);
+  }
+  return { copiedSomething, removed };
+}
+
+function migrateLegacyTeams(cwd, dest) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupRoot = path.join(cwd, '.ai.local', '.rollback', `legacy-team-${stamp}`);
+  let migrated = false;
+  let backedUp = 0;
+
+  for (const tool of LEGACY_TOOLS) {
+    const teamDir = resolveLegacyTeamDir(cwd, tool);
+    if (!teamDir) {
+      continue;
+    }
+    const result = migrateLegacyTool(tool, teamDir, cwd, dest, backupRoot);
+    migrated = migrated || result.copiedSomething;
+    backedUp += result.removed;
+  }
+
+  if (backedUp > 0) {
+    ensureRollbackIgnored(path.dirname(backupRoot));
+    console.log(
+      `Backed up ${backedUp} legacy team entr${backedUp === 1 ? 'y' : 'ies'} → ${path.relative(cwd, backupRoot)} (git-ignored; safe to delete once the migration looks right)`,
+    );
+  }
+  return migrated;
+}
+
+/**
+ * @param {{ cwd: string, presetTeamSrc?: string }} options
+ * @returns {{ created: boolean, migrated: boolean, refreshed: boolean, conventionsSeeded: boolean }}
+ */
+function seedAiLocalTeam({ cwd, presetTeamSrc }) {
+  const dest = destTeamRoot(cwd);
+  const destExisted = fs.existsSync(dest);
+  const destHasSlugs = hasConsumerTaskSlugs(path.join(dest, 'tasks'));
+  const hadLegacy = LEGACY_TOOLS.some((tool) =>
+    fs.existsSync(path.join(cwd, `.${tool}`, 'team')),
+  );
+
+  if (!destExisted && !hadLegacy && (!presetTeamSrc || !fs.existsSync(presetTeamSrc))) {
+    console.log('Skipped .ai.local/team seed (preset team/ missing)');
+    return { created: false, migrated: false, refreshed: false, conventionsSeeded: false };
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+  const migrated = migrateLegacyTeams(cwd, dest);
+  copyTemplates(presetTeamSrc, dest);
+  const conventionsSeeded = seedConventions(presetTeamSrc, cwd);
+
+  if (migrated) {
+    console.log('Migrated legacy .{tool}/team → .ai.local/team');
+  }
+
+  if (!destExisted && !hadLegacy) {
+    console.log('Seeded .ai.local/team/');
+    return { created: true, migrated: false, refreshed: false, conventionsSeeded };
+  }
+
+  if (destHasSlugs || destExisted) {
+    console.log(
+      destHasSlugs
+        ? 'Refreshed .ai.local/team templates (tasks preserved)'
+        : 'Refreshed .ai.local/team (no consumer task slugs)',
+    );
+    return { created: false, migrated, refreshed: true, conventionsSeeded };
+  }
+
+  return { created: false, migrated, refreshed: false, conventionsSeeded };
+}
+
+module.exports = { seedAiLocalTeam, destTeamRoot };

package/bin/mavis-install.js

@@ -202,7 +202,7 @@ function restoreRollback(overwritten, created, rollbackRoot, mavisRoot, mavisExi
 }
 
 function cmdInitMavis({ preset, cwdOption, helpers }) {
-  const { resolveTargetCwd, seedDocsSpecsIfAbsent, installMcpJson, getPackageRoot } = helpers;
+  const { resolveTargetCwd, seedDocsSpecsIfAbsent, seedAiLocalTeam, installMcpJson, getPackageRoot } = helpers;
   const packageRoot = getPackageRoot();
   const cwd = resolveTargetCwd(cwdOption);
   const contract = loadContract(packageRoot);
@@ -211,7 +211,6 @@ function cmdInitMavis({ preset, cwdOption, helpers }) {
   if (releasedStacks.length > 0 && !releasedStacks.includes(stack)) {
     console.error(`Preset "${stack}" for mavis is not released yet.`);
     console.error(`Released stacks: ${releasedStacks.join(', ')}`);
-    console.error('Additional stacks ship after the pilot human gate (WP-F).');
     process.exit(1);
   }
   const sourceBase = path.join(packageRoot, contract.sourceRoot, stack);
@@ -290,6 +289,15 @@ function cmdInitMavis({ preset, cwdOption, helpers }) {
     if (seeded && !docsSpecsExisted) {
       created.add(docsSpecsDir);
     }
+    const teamDest = path.join(cwd, '.ai.local', 'team');
+    const teamExisted = fs.existsSync(teamDest);
+    const teamResult = seedAiLocalTeam({
+      cwd,
+      presetTeamSrc: path.join(sourceBase, 'team'),
+    });
+    if (teamResult.created && !teamExisted) {
+      created.add(teamDest);
+    }
 
     throwIfPhase('manifest');
     const managedFiles = {};

package/bin/opencode-install.js

@@ -297,7 +297,7 @@ function restoreRollback(overwritten, created, rollbackRoot, managedRoot, rootEx
 }
 
 function cmdInitOpencode({ preset, cwdOption, helpers }) {
-  const { resolveTargetCwd, seedDocsSpecsIfAbsent, getPackageRoot } = helpers;
+  const { resolveTargetCwd, seedDocsSpecsIfAbsent, seedAiLocalTeam, getPackageRoot } = helpers;
   const packageRoot = getPackageRoot();
   const cwd = resolveTargetCwd(cwdOption);
   const contract = loadContract(packageRoot);
@@ -381,6 +381,15 @@ function cmdInitOpencode({ preset, cwdOption, helpers }) {
     if (seeded && !docsSpecsExisted) {
       created.add(docsSpecsDir);
     }
+    const teamDest = path.join(cwd, '.ai.local', 'team');
+    const teamExisted = fs.existsSync(teamDest);
+    const teamResult = seedAiLocalTeam({
+      cwd,
+      presetTeamSrc: path.join(sourceBase, 'team'),
+    });
+    if (teamResult.created && !teamExisted) {
+      created.add(teamDest);
+    }
 
     throwIfPhase('manifest');
     const managedFiles = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -53,7 +53,9 @@
     "check:opencode-adapter-map": "node scripts/check-opencode-adapter-map.mjs --self-test",
     "check:opencode-token-budget": "node scripts/check-opencode-token-budget.mjs",
     "check:opencode-local-overlay": "node scripts/check-opencode-local-overlay.mjs",
-    "test:opencode-context-budget": "node scripts/test-opencode-context-budget.mjs"
+    "test:opencode-context-budget": "node scripts/test-opencode-context-budget.mjs",
+    "generate:mavis": "node scripts/generate-mavis.mjs",
+    "generate:opencode": "node scripts/generate-opencode.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/README.md

@@ -1,48 +1,33 @@
 # Shared preset core (`presets/_shared`)
 
-Stack-agnostic **prose and checklists** for all installable presets: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (`cursor/<stack>`, `claude/<stack>`).
-
-**Not an installable preset.** CLI `init` copies only under `presets/cursor/<name>/` or `presets/claude/<name>/` — this sibling is never shipped to consumer apps.
-
-## Layers
+Stack-agnostic prose for all installable stacks. **Not an `--preset`.** `init` copies only `presets/<platform>/<stack>/`.
 
 ```text
-Core (_shared/core)     → stack-agnostic prose
-Stack (cursor|claude/<stack>) → domain / tooling deltas
-Platform adapter        → .mdc frontmatter | .md + paths:
+_shared/core  →  cursor/<stack>   (SoT)
+              →  claude/<stack>   (twin, same PR)
+              →  mavis/<stack>    (generated)
+              →  opencode/<stack> (generated)
 ```
 
-See meta-rules: `core/meta/preset-layering.md`, `preset-twin-sync.md`, `preset-token-budget.md`, `preset-pr-checklist.md`, `preset-no-cross-stack-leakage.md`.
-
-**Contributing:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md) (full guide: layers, SoT, new stack, platform artifacts, PR checklist).
-
-## Sync model
-
-1. Edit core under `core/**` when changing shared principles.
-2. Update every consumer that carries `<!-- shared-core: <path> -->` in the **same PR**.
-3. Cursor `presets/cursor/<stack>/` is SoT per stack; Claude twins are derived in the same PR.
-4. Dogfood: `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (packages → root `.cursor/`).
-
-### Sync modes (marker semantics)
-
-| Mode | Marker | Adapter body | Typical stems |
-|------|--------|--------------|---------------|
-| **Embed** | `<!-- shared-core: … -->` | Core prose + optional `## Stack notes` only for deltas | `quality/*`, `meta/preset-*`, thin review/intake aliases |
-| **Lineage** | same marker | **Stack-specific** body; core is abstract SoT / checklist reference | `architecture/feature-delivery-workflow`, `architecture/reference-features.template`, `agent-team/agent-team-orchestrator` |
+Meta-rules: `core/meta/preset-*.md`. Guide: [`docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md).
 
-Do **not** expect lineage adapters to byte-match core. Embed adapters should match core after stripping frontmatter and `## Stack notes` — verify with `scripts/check-shared-core-drift.sh`.
+## Sync
 
-## Folder map
+1. Edit `core/**` for shared principles.
+2. Update every `<!-- shared-core: … -->` consumer in the **same PR**.
+3. **Embed** adapters must match core (minus frontmatter / `## Stack notes`). **Lineage** adapters are stack-specific; do not expect a byte match.
+4. Gate: `scripts/check-shared-core-drift.sh`. Dogfood: `scripts/sync-dogfood-cursor.sh`.
 
-| Dir | Contents |
-|-----|----------|
-| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage`; embed `debug-investigation`; inline-embed `verification-before-completion` (no standalone adapter — shipped via `agents/feature-developer.md` + `agents/build-verifier.md` + `skills/debug-investigation/SKILL.md`) |
-| `core/agent-team/` | Orchestrator + intake (pipeline language); lineage `task-classification` |
-| `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
-| `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist; lineage `receiving-code-review` |
-| `core/testing/` | Test principles: behavior vs. implementation, locale-aware titles, isolation/mocks, fixture reuse, e2e scenario ↔ test traceability, page objects, PREFIX-XXX identifiers, selector priority |
-| `core/meta/` | Author-facing preset meta-rules |
+`/task` templates live in each stack’s `team/` and seed **`.ai.local/team/`** — not this folder.
 
-## CLI note
+## Folders
 
-Do **not** nest `_shared` under `cursor/` or `claude/`. Do not pass `_shared` as `--preset`.
+| Dir | What |
+|-----|------|
+| `core/quality/` | Slim always-on quality; requestable discipline / design / MCP |
+| `core/agent-team/` | Orchestrator, intake, classification, artifact + metrics contracts |
+| `core/architecture/` | Feature-delivery, reference-features, product-specs |
+| `core/review/` | MR review, retro, mockup, UX |
+| `core/testing/` | Unit/e2e principles |
+| `core/meta/` | Author-facing preset rules |
+| `assets/docs-specs/` | `init` seed for absent `docs/specs/` |

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -1,9 +1,6 @@
 # Agent artifact contracts
 
-Each pipeline slug has one context index and receipt ledger:
-
-- Cursor: `.cursor/team/tasks/<slug>/artifact-manifest.json`
-- Claude: `.claude/team/tasks/<slug>/artifact-manifest.json`
+Each pipeline slug has one context index and receipt ledger at `.ai.local/team/tasks/<slug>/artifact-manifest.json`.
 
 Markdown remains the narrative evidence. The manifest identifies authoritative inputs and outputs; it does not duplicate report contents or replace `pipeline.json`, `status.json`, or `metrics.json`.
 
@@ -109,7 +106,7 @@ A producer finishes its step by upserting only its owned artifact entry and term
 | `api-contract-reviewer` | `api-contract-review` | `api-contract-review.md` |
 | `qa-tester` / unit or e2e planners | stack-native test IDs | plan/spec paths named in the agent prompt |
 | `tech-writer` | `documentation` | `documentation.md` |
-| `openspec-author` | `openspec-change` | `openspec/changes/<change-id>/**`, optional `.cursor/team/tasks/<slug>/openspec-change.md` |
+| `openspec-author` | `openspec-change` | `openspec/changes/<change-id>/**`, optional `.ai.local/team/tasks/<slug>/openspec-change.md` |
 | `qa-tester` | `qa` | stack-native (e.g. `qa-report.md`, `qa-screenshot.png`) |
 | `unit-test-planner` | `unit-test-plan` | `unit-test-plan.md` |
 | `unit-test-generator` | `unit-test-spec` | `*.spec.ts` / `*.test.ts` / `*Tests.swift` |
@@ -158,10 +155,7 @@ Optional JSON on the producer receipt and, for `feature-developer`, YAML frontma
 
 ## Memlog
 
-Optional append-only file beside slug artifacts:
-
-- Cursor: `.cursor/team/tasks/<slug>/.memlog.md`
-- Claude: `.claude/team/tasks/<slug>/.memlog.md`
+Optional append-only file beside slug artifacts: `.ai.local/team/tasks/<slug>/.memlog.md`.
 
 Agent-written chronological markdown (`## YYYY-MM-DD` headings). Suggested line tags: `decision`, `assumption`, `override`, `event`, `claim`. Writers: `task-analyst`, `feature-developer`. `/task-continue` may read it. The hook does **not** parse memlog and does **not** treat it as `status.json` / `metrics.json`.
 

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -1,6 +1,6 @@
 # Agent team orchestrator
 
-Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.cursor/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.ai.local/team/tasks/<slug>/`.
 
 Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
 
@@ -99,7 +99,7 @@ Do not calculate durations in agents. For parallel steps, never attribute a stop
 
 ## Artifact context index and receipts
 
-Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
+Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. The full schema and completion conventions live in **agent-artifact-contracts**.
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest points to authoritative paths and records producer, status, timestamps, outcome, and evidence paths.

package/presets/_shared/core/architecture/reference-features.template.md

@@ -32,7 +32,7 @@ After init the team maintains **local** gotchas, patterns, and decisions in a co
 | Patterns | Local patterns beyond the reference table |
 | Decisions | Short ADR links / product decisions that affect code |
 
-Path pointer and stack tables — in the preset adapter (`team/conventions.md`). The file is **not** always-on.
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
 
 ## Related rules
 

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -7,8 +7,8 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
-- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
-- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
+- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
+- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.