@jazpiper/rules-doctor 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.3.0 - 2026-02-25
+
+- Added `copilot` adapter support for `.github/copilot-instructions.md`.
+- Switched Copilot output to marker-managed mode to preserve user-authored content.
+- Added target presets for `init` (`all`, `core`, `copilot`).
+- Added `preset apply` command for applying presets to existing `.agentrules/rules.yaml`.
+- Added CI workflow template for drift detection via `rules-doctor check`.
+- Expanded tests for shared `AGENTS.md`, Copilot marker re-sync, and `--import` + preset behavior.
+- Improved README with troubleshooting and CI examples.
+
+## 0.2.0 - 2026-02-25
+
+- Added multi-target adapters for `claude`, `codex`, `cursor`, `gemini`, and `opencode`.
+- Added `init --import`, dry-run default for `sync`, drift `check`, and structural `doctor`.

package/README.md

@@ -1,10 +1,14 @@
 # @jazpiper/rules-doctor
 
-`rules-doctor` is a Node.js CLI that keeps agent instruction files in sync from one source of truth: `.agentrules/rules.yaml`.
+`rules-doctor` keeps coding-rule files in sync across multiple agent CLIs from one source of truth: `.agentrules/rules.yaml`.
 
-It is designed for multi-agent workflows where each coding CLI reads a different file format.
+It is optimized for real project adoption:
+- import existing docs (`init --import`)
+- target presets (`init --preset all|core|copilot`)
+- safe previews by default (`sync` is dry-run unless `--write`)
+- drift detection for CI (`check`)
 
-By default, commands resolve paths relative to the project root (`.git` ancestor), not the current subdirectory.
+All paths are resolved from project root (`.git` ancestor), not current subdirectory.
 
 ## Install
 
@@ -12,143 +16,169 @@ By default, commands resolve paths relative to the project root (`.git` ancestor
 npm install -D @jazpiper/rules-doctor
 ```
 
-Or run directly:
+Run with:
 
 ```bash
-npx @jazpiper/rules-doctor init
+npx rules-doctor --help
 ```
 
-## Usage
+## Quick Start
 
-### 1) Initialize rules
+### 1) Initialize (recommended with import)
 
 ```bash
-rules-doctor init
+npx rules-doctor init --import
 ```
 
-Creates `.agentrules/rules.yaml` if it does not exist.
+- Creates `.agentrules/rules.yaml`
+- Reads existing docs when found (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`)
+- Writes `.agentrules/import-report.md`
 
-- If `package.json` has scripts for `lint`, `test`, or `build`, they are inferred as:
-  - `npm run lint`
-  - `npm run test`
-  - `npm run build`
-- Missing scripts are created as TODO placeholders.
+Preset example (Copilot only):
 
-### 2) Sync generated docs
+```bash
+npx rules-doctor init --preset copilot
+```
+
+Preset meanings:
+- `all`: all built-in targets enabled
+- `core`: `claude`, `codex`, `opencode`, `cursor`, `gemini`
+- `copilot`: only `copilot` enabled
+
+Apply preset to an existing `.agentrules/rules.yaml`:
+
+```bash
+npx rules-doctor preset apply copilot --write
+```
+
+### 2) Preview changes safely
 
 ```bash
-rules-doctor sync
-rules-doctor sync --target claude
-rules-doctor sync --target codex
-rules-doctor sync --target cursor,gemini,opencode,antigravity
+npx rules-doctor sync --diff
 ```
 
-Generates/updates:
-- `CLAUDE.md` (`claude`, fully managed)
-- `AGENTS.md` (`codex`, `opencode`, marker-managed)
-- `.cursor/rules/rules-doctor.mdc` (`cursor`, fully managed)
-- `GEMINI.md` (`gemini`, fully managed)
-- `GEMINI.md` (`antigravity`, inferred-compatible mapping)
+`sync` is dry-run by default. Nothing is written yet.
 
-Managed marker block in `AGENTS.md`:
+### 3) Apply changes
 
-```md
-<!-- RULES_DOCTOR:BEGIN -->
-... managed content ...
-<!-- RULES_DOCTOR:END -->
+```bash
+npx rules-doctor sync --write
 ```
 
-If markers are missing, a new managed block is appended to the end of `AGENTS.md`.
+Optional backups:
+
+```bash
+npx rules-doctor sync --write --backup
+```
 
-### 3) Analyze docs
+### 4) Verify drift in CI/local
 
 ```bash
-rules-doctor analyze
+npx rules-doctor check
 ```
 
-Reads enabled target files from `rules.yaml`, then prints a concise report about:
-- missing markers
-- missing verify commands (`lint`/`test`/`build`)
-- obvious contradictions (simple heuristics across generated targets)
+Returns non-zero when generated targets are out of sync.
 
-`--strict` makes `analyze` fail with non-zero exit code when findings exist.
+## Supported Targets
 
-### 4) List supported adapters
+```bash
+npx rules-doctor targets list
+```
+
+Built-in adapters:
+- `claude` -> `CLAUDE.md` (full-managed)
+- `codex` -> `AGENTS.md` (marker-managed)
+- `copilot` -> `.github/copilot-instructions.md` (marker-managed, preserves existing text outside managed block)
+- `opencode` -> `AGENTS.md` (marker-managed)
+- `cursor` -> `.cursor/rules/rules-doctor.mdc` (full-managed)
+- `gemini` -> `GEMINI.md` (full-managed)
+
+## Command Reference
+
+### `init`
 
 ```bash
-rules-doctor targets list
+npx rules-doctor init [--import]
+npx rules-doctor init [--import] [--preset all|core|copilot]
 ```
 
-Shows built-in adapters and default file paths.
+### `preset apply`
 
-### 5) Directory/Path Notes
+```bash
+npx rules-doctor preset apply <all|core|copilot> [--diff] [--write]
+```
 
-- `claude`: searches `CLAUDE.md` from current directory upward; also supports `.claude/CLAUDE.md` and `.claude/rules/*.md`.
-- `codex`: looks for `AGENTS.override.md` or `AGENTS.md` from project root down to current directory.
-- `opencode`: reads project `AGENTS.md`, plus user global `~/.config/opencode/AGENTS.md`.
-- `cursor`: project rules live in `.cursor/rules/*.mdc` (legacy `.cursorrules` still exists).
-- `gemini`: uses `GEMINI.md` in workspace/ancestor directories and `~/.gemini/GEMINI.md`.
-- `antigravity`: currently mapped to `GEMINI.md` as an inferred default; verify in your environment.
+### `sync`
 
-## Rules Schema (v2 Draft)
+```bash
+npx rules-doctor sync [--target all|claude,codex,...] [--diff] [--write] [--backup]
+```
+
+### `check`
 
-`init` now creates a v2-compatible draft with `targets` configuration:
+```bash
+npx rules-doctor check [--target all|claude,codex,...] [--diff]
+```
+
+### `analyze`
+
+```bash
+npx rules-doctor analyze [--strict]
+```
+
+### `doctor`
+
+```bash
+npx rules-doctor doctor [--strict]
+```
+
+## CI Template
+
+Copy [docs/workflows/rules-doctor-check.yml](docs/workflows/rules-doctor-check.yml) to your repository as `.github/workflows/rules-doctor-check.yml`.
+It runs `npx rules-doctor check` on push and pull requests.
+
+Inline workflow example:
 
 ```yaml
-version: 2
-mission: "Ship safe changes quickly while keeping agent instructions consistent."
-workflow:
-  - "Read relevant files before editing."
-  - "Make the smallest correct change."
-  - "Run verification commands before finalizing."
-commands:
-  lint: "npm run lint"
-  test: "npm run test"
-  build: "npm run build"
-done:
-  - "Commands pass or blockers are documented."
-  - "Changed behavior is reflected in docs where needed."
-approvals:
-  mode: "ask-before-destructive"
-  notes:
-    - "Ask before destructive actions or privileged operations."
-targets:
-  claude:
-    enabled: true
-    path: "CLAUDE.md"
-  codex:
-    enabled: true
-    path: "AGENTS.md"
-  cursor:
-    enabled: true
-    path: ".cursor/rules/rules-doctor.mdc"
-  gemini:
-    enabled: true
-    path: "GEMINI.md"
-  opencode:
-    enabled: true
-    path: "AGENTS.md"
-  antigravity:
-    enabled: true
-    path: "GEMINI.md"
-```
-
-You can disable or relocate any target by editing `targets.<id>.enabled/path`.
+name: Rules Doctor Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  rules-doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx rules-doctor check
+```
+
+## Troubleshooting
+
+- `rules-doctor: command not found` after `npm install -D @jazpiper/rules-doctor`:
+  - Use `npx rules-doctor ...` (recommended for local dev dependency).
+  - Or add an npm script in your project: `"rules:check": "rules-doctor check"`, then run `npm run rules:check`.
+  - Global install (`npm i -g @jazpiper/rules-doctor`) works, but local + `npx` is safer for version consistency.
+- `init` says `rules.yaml already exists`:
+  - Use `npx rules-doctor preset apply <preset> --write` to change target defaults on an existing project.
+
+## Rules Schema (v2 Draft)
+
+See [docs/rules-v2-draft.yaml](docs/rules-v2-draft.yaml).
 
 ## Development
 
 ```bash
 npm ci
-npm run build
+npm test
 ```
 
 ## License
 
 MIT
-
-
-## CI
-
-This repo includes a GitHub Actions workflow template at `docs/workflows/ci.yml`.
-
-If you want CI, copy it to `.github/workflows/ci.yml` and push the change.

package/dist/adapters/copilot.js

@@ -0,0 +1,15 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "copilot",
+  name: "GitHub Copilot",
+  description:
+    "Manage .github/copilot-instructions.md via marker-managed section to preserve user content.",
+  defaultPath: ".github/copilot-instructions.md",
+  management: "marker",
+  markerBegin: "<!-- RULES_DOCTOR:COPILOT:BEGIN -->",
+  markerEnd: "<!-- RULES_DOCTOR:COPILOT:END -->",
+  render(rules) {
+    return ["# Copilot Instructions", "", renderManagedRulesBody(rules)].join("\n");
+  },
+};

package/dist/adapters/index.js

@@ -1,11 +1,11 @@
 const claude = require("./claude");
 const codex = require("./codex");
+const copilot = require("./copilot");
 const cursor = require("./cursor");
 const gemini = require("./gemini");
 const opencode = require("./opencode");
-const antigravity = require("./antigravity");
 
-const ADAPTERS = [claude, codex, cursor, gemini, opencode, antigravity];
+const ADAPTERS = [claude, codex, copilot, cursor, gemini, opencode];
 const ADAPTERS_BY_ID = Object.fromEntries(ADAPTERS.map((adapter) => [adapter.id, adapter]));
 
 module.exports = {

package/dist/index.js

@@ -4,17 +4,26 @@ const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs"
 const { ADAPTERS, ADAPTERS_BY_ID } = require("./adapters");
 
 const RULES_RELATIVE_PATH = ".agentrules/rules.yaml";
+const IMPORT_REPORT_RELATIVE_PATH = ".agentrules/import-report.md";
+const PRESET_NAMES = ["all", "core", "copilot"];
 
 function usage() {
   const targets = ADAPTERS.map((adapter) => adapter.id).join("|");
+  const presets = PRESET_NAMES.join("|");
   return [
     "rules-doctor",
     "",
     "Usage:",
-    "  rules-doctor init",
-    `  rules-doctor sync [--target all|${targets}|<comma-separated-targets>]`,
-    "  rules-doctor analyze",
+    `  rules-doctor init [--import] [--preset ${presets}]`,
+    `  rules-doctor preset apply <${presets}> [--diff] [--write]`,
+    `  rules-doctor sync [--target all|${targets}|<comma-separated-targets>] [--diff] [--write] [--backup]`,
+    `  rules-doctor check [--target all|${targets}|<comma-separated-targets>] [--diff]`,
+    "  rules-doctor analyze [--strict]",
+    "  rules-doctor doctor [--strict]",
     "  rules-doctor targets list",
+    "",
+    "Notes:",
+    "  - sync defaults to dry-run. Add --write to apply changes.",
   ].join("\n");
 }
 
@@ -239,6 +248,40 @@ function createDefaultRules(scripts) {
   };
 }
 
+function getPresetTargetIds(presetName) {
+  if (presetName === "all") {
+    return ADAPTERS.map((adapter) => adapter.id);
+  }
+
+  if (presetName === "core") {
+    return ["claude", "codex", "opencode", "cursor", "gemini"];
+  }
+
+  if (presetName === "copilot") {
+    return ["copilot"];
+  }
+
+  throw new Error(`Unknown preset "${presetName}". Use one of: ${PRESET_NAMES.join(", ")}`);
+}
+
+function applyTargetPreset(rules, presetName) {
+  const enabled = new Set(getPresetTargetIds(presetName));
+  const targets = rules.targets && typeof rules.targets === "object" ? rules.targets : {};
+
+  for (const adapter of ADAPTERS) {
+    const current = normalizeTargetConfig(targets[adapter.id], adapter.defaultPath);
+    targets[adapter.id] = {
+      enabled: enabled.has(adapter.id),
+      path: current.path,
+    };
+  }
+
+  return {
+    ...rules,
+    targets,
+  };
+}
+
 function normalizeTargetConfig(source, fallbackPath) {
   if (typeof source === "string" && source.trim()) {
     return { enabled: true, path: source.trim() };
@@ -275,7 +318,14 @@ function normalizeRules(input, defaults) {
 
   const targets = {};
   for (const adapter of ADAPTERS) {
-    targets[adapter.id] = normalizeTargetConfig(sourceTargets[adapter.id], defaults.targets[adapter.id].path);
+    const fallback = defaults.targets[adapter.id]
+      ? defaults.targets[adapter.id].path
+      : adapter.defaultPath;
+    const config = normalizeTargetConfig(sourceTargets[adapter.id], fallback);
+    targets[adapter.id] = {
+      enabled: typeof config.enabled === "boolean" ? config.enabled : true,
+      path: config.path,
+    };
   }
 
   for (const customId of Object.keys(sourceTargets)) {
@@ -464,43 +514,153 @@ function getTargetsFromSpec(spec) {
   return unique;
 }
 
-function parseSyncTargets(args) {
+function parseInitArgs(args) {
+  const options = {
+    importExisting: false,
+    preset: "all",
+  };
+
+  for (let index = 0; index < (args || []).length; index += 1) {
+    const arg = args[index];
+    if (arg === "--import") {
+      options.importExisting = true;
+      continue;
+    }
+
+    if (arg === "--preset") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Missing value for --preset.");
+      }
+      if (!PRESET_NAMES.includes(value)) {
+        throw new Error(`Unknown preset "${value}". Use one of: ${PRESET_NAMES.join(", ")}`);
+      }
+      options.preset = value;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option for init: ${arg}`);
+  }
+
+  return options;
+}
+
+function parsePresetArgs(args) {
   if (!args || args.length === 0) {
-    return ADAPTERS.map((adapter) => adapter.id);
+    throw new Error(`Missing preset subcommand. Use "rules-doctor preset apply <${PRESET_NAMES.join("|")}>".`);
+  }
+
+  const [subcommand, presetName, ...rest] = args;
+  if (subcommand !== "apply") {
+    throw new Error(`Unknown preset subcommand: ${subcommand}. Use "rules-doctor preset apply <preset>".`);
+  }
+
+  if (!presetName) {
+    throw new Error(`Missing preset name. Use one of: ${PRESET_NAMES.join(", ")}`);
+  }
+  if (!PRESET_NAMES.includes(presetName)) {
+    throw new Error(`Unknown preset "${presetName}". Use one of: ${PRESET_NAMES.join(", ")}`);
+  }
+
+  const options = {
+    presetName,
+    diff: false,
+    write: false,
+  };
+
+  for (const arg of rest) {
+    if (arg === "--diff") {
+      options.diff = true;
+      continue;
+    }
+    if (arg === "--write") {
+      options.write = true;
+      continue;
+    }
+    throw new Error(`Unknown option for preset apply: ${arg}`);
   }
 
-  let targetSpec = "all";
-  for (let index = 0; index < args.length; index += 1) {
+  return options;
+}
+
+function parseTargetedArgs(commandName, args, extra) {
+  const options = {
+    targetSpec: "all",
+    diff: false,
+    write: false,
+    backup: false,
+  };
+  const allowed = extra || {};
+
+  for (let index = 0; index < (args || []).length; index += 1) {
     const arg = args[index];
     if (arg === "--target") {
       const value = args[index + 1];
       if (!value) {
-        throw new Error("Missing value for --target");
+        throw new Error(`Missing value for --target (${commandName})`);
       }
-      targetSpec = value;
+      options.targetSpec = value;
       index += 1;
       continue;
     }
+    if (arg === "--diff") {
+      options.diff = true;
+      continue;
+    }
+    if (arg === "--write" && allowed.write) {
+      options.write = true;
+      continue;
+    }
+    if (arg === "--backup" && allowed.backup) {
+      options.backup = true;
+      continue;
+    }
+    throw new Error(`Unknown option for ${commandName}: ${arg}`);
+  }
 
-    throw new Error(`Unknown option for sync: ${arg}`);
+  if (options.backup && !options.write) {
+    throw new Error("--backup requires --write.");
   }
 
-  return getTargetsFromSpec(targetSpec);
+  return {
+    targetIds: getTargetsFromSpec(options.targetSpec),
+    diff: options.diff,
+    write: options.write,
+    backup: options.backup,
+  };
 }
 
 function parseAnalyzeArgs(args) {
-  if (!args || args.length === 0) {
-    return {};
-  }
+  const options = {
+    strict: false,
+  };
 
-  for (const arg of args) {
+  for (const arg of args || []) {
     if (arg === "--strict") {
-      return { strict: true };
+      options.strict = true;
+      continue;
     }
     throw new Error(`Unknown option for analyze: ${arg}`);
   }
 
-  return {};
+  return options;
+}
+
+function parseDoctorArgs(args) {
+  const options = {
+    strict: false,
+  };
+
+  for (const arg of args || []) {
+    if (arg === "--strict") {
+      options.strict = true;
+      continue;
+    }
+    throw new Error(`Unknown option for doctor: ${arg}`);
+  }
+
+  return options;
 }
 
 function getTargetConfig(rules, adapter) {
@@ -508,57 +668,535 @@ function getTargetConfig(rules, adapter) {
   return normalizeTargetConfig(source, adapter.defaultPath);
 }
 
-function initCommand(rootDir, logger) {
+function normalizeHeading(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+function parseMarkdownSections(text) {
+  const sections = {};
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  let currentHeading = null;
+  let currentLines = [];
+
+  function flush() {
+    if (!currentHeading) {
+      return;
+    }
+    const normalized = normalizeHeading(currentHeading);
+    if (!sections[normalized]) {
+      sections[normalized] = currentLines.join("\n").trim();
+    }
+  }
+
+  for (const line of lines) {
+    const heading = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      currentHeading = heading[1];
+      currentLines = [];
+      continue;
+    }
+
+    if (currentHeading) {
+      currentLines.push(line);
+    }
+  }
+
+  flush();
+  return sections;
+}
+
+function pickFirstNonEmptyLine(text) {
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return "";
+}
+
+function parseListItems(text) {
+  const items = [];
+  for (const line of text.split("\n")) {
+    const bullet = line.match(/^\s*[-*]\s+(.+?)\s*$/);
+    if (bullet) {
+      items.push(bullet[1].trim());
+      continue;
+    }
+    const numbered = line.match(/^\s*\d+\.\s+(.+?)\s*$/);
+    if (numbered) {
+      items.push(numbered[1].trim());
+    }
+  }
+  return items;
+}
+
+function unquoteValue(value) {
+  let current = value.trim();
+  if (current.startsWith("`") && current.endsWith("`")) {
+    current = current.slice(1, -1);
+  }
+  current = stripQuotes(current);
+  return current.trim();
+}
+
+function importCommandsFromText(text, commands) {
+  const merged = { ...commands };
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const commandNames = Object.keys(merged);
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    for (const name of commandNames) {
+      const direct = line.match(new RegExp(`^(?:[-*]\\s*)?${name}\\s*:\\s*(.+)$`, "i"));
+      if (direct && direct[1]) {
+        merged[name] = unquoteValue(direct[1]);
+      }
+    }
+  }
+
+  for (const name of commandNames) {
+    if (!merged[name] || merged[name].includes("TODO")) {
+      const found = text.match(new RegExp(`\\b(?:npm run|pnpm|yarn|bun)\\s+${name}\\b`, "i"));
+      if (found) {
+        merged[name] = found[0];
+      }
+    }
+  }
+
+  return merged;
+}
+
+function getSectionText(sections, aliases) {
+  for (const alias of aliases) {
+    const key = normalizeHeading(alias);
+    if (sections[key] && sections[key].trim()) {
+      return sections[key].trim();
+    }
+  }
+  return "";
+}
+
+function collectImportSources(rootDir) {
+  const candidates = [
+    { id: "claude", path: "CLAUDE.md" },
+    { id: "claude-local", path: ".claude/CLAUDE.md" },
+    { id: "codex", path: "AGENTS.md" },
+    { id: "copilot", path: ".github/copilot-instructions.md" },
+    { id: "gemini", path: "GEMINI.md" },
+    { id: "cursor", path: ".cursor/rules/rules-doctor.mdc" },
+  ];
+
+  const uniquePaths = new Set();
+  const sources = [];
+
+  for (const item of candidates) {
+    if (uniquePaths.has(item.path)) {
+      continue;
+    }
+    uniquePaths.add(item.path);
+
+    const absolutePath = resolveInRoot(rootDir, item.path);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    sources.push({
+      id: item.id,
+      path: item.path,
+      absolutePath,
+      text: readFileSync(absolutePath, "utf8"),
+    });
+  }
+
+  return sources;
+}
+
+function importRulesFromDocs(rootDir, defaults) {
+  const imported = JSON.parse(JSON.stringify(defaults));
+  const sources = collectImportSources(rootDir);
+  const notes = [];
+
+  if (sources.length === 0) {
+    return {
+      rules: imported,
+      report: "No existing docs were found. Created default rules.",
+      sources,
+    };
+  }
+
+  notes.push(`Found ${sources.length} source file(s):`);
+  for (const source of sources) {
+    notes.push(`- ${source.path}`);
+  }
+
+  for (const source of sources) {
+    const sections = parseMarkdownSections(source.text);
+
+    const missionSection = getSectionText(sections, ["mission"]);
+    if (missionSection) {
+      const mission = pickFirstNonEmptyLine(missionSection);
+      if (mission) {
+        imported.mission = mission;
+      }
+    }
+
+    const workflowSection = getSectionText(sections, ["workflow", "operational loop"]);
+    const workflow = parseListItems(workflowSection);
+    if (workflow.length > 0) {
+      imported.workflow = workflow;
+    }
+
+    const doneSection = getSectionText(sections, ["done", "done criteria"]);
+    const done = parseListItems(doneSection);
+    if (done.length > 0) {
+      imported.done = done;
+    }
+
+    const approvalsSection = getSectionText(sections, ["approvals", "approval"]);
+    if (approvalsSection) {
+      const mode = approvalsSection.match(/(?:mode|policy)\s*:\s*`?([a-z0-9_-]+)`?/i);
+      if (mode && mode[1]) {
+        imported.approvals.mode = mode[1].trim();
+      }
+      const approvalNotes = parseListItems(approvalsSection);
+      if (approvalNotes.length > 0) {
+        imported.approvals.notes = approvalNotes;
+      }
+    }
+
+    imported.commands = importCommandsFromText(source.text, imported.commands);
+  }
+
+  for (const adapter of ADAPTERS) {
+    const config = getTargetConfig(imported, adapter);
+    const absolutePath = resolveInRoot(rootDir, config.path);
+    if (existsSync(absolutePath)) {
+      imported.targets[adapter.id].enabled = true;
+    }
+  }
+
+  notes.push("Imported mission/workflow/commands/done/approvals where detected.");
+  return {
+    rules: imported,
+    report: notes.join("\n"),
+    sources,
+  };
+}
+
+function initCommand(rootDir, logger, args) {
+  const options = parseInitArgs(args);
   const rulesFile = resolve(rootDir, RULES_RELATIVE_PATH);
   if (existsSync(rulesFile)) {
     logger.log(`rules.yaml already exists: ${rulesFile}`);
-    return;
+    return 0;
   }
 
   const defaults = createDefaultRules(loadPackageScripts(rootDir));
+  let rules = defaults;
+  let importReport = "";
+
+  if (options.importExisting) {
+    const imported = importRulesFromDocs(rootDir, defaults);
+    rules = imported.rules;
+    importReport = imported.report;
+  }
+
+  rules = applyTargetPreset(rules, options.preset);
+
   ensureParentDirectory(rulesFile);
-  writeFileSync(rulesFile, stringifyRules(defaults), "utf8");
+  writeFileSync(rulesFile, stringifyRules(rules), "utf8");
   logger.log(`Created ${rulesFile}`);
+  logger.log(`Applied target preset: ${options.preset}`);
+
+  if (options.importExisting) {
+    const reportPath = resolve(rootDir, IMPORT_REPORT_RELATIVE_PATH);
+    const reportContent =
+      options.preset === "all"
+        ? `${importReport}\n`
+        : `${importReport}\n\nApplied target preset: ${options.preset}\n`;
+    writeFileSync(reportPath, reportContent, "utf8");
+    logger.log(`Import report: ${reportPath}`);
+  }
+
+  return 0;
 }
 
-function syncCommand(rootDir, logger, args) {
-  const { rules } = loadRules(rootDir);
-  const selectedTargetIds = parseSyncTargets(args);
+function presetApplyCommand(rootDir, logger, args) {
+  const options = parsePresetArgs(args);
+  const { rules, rulesFile } = loadRules(rootDir);
+  const nextRules = applyTargetPreset(
+    {
+      ...rules,
+      targets: { ...(rules.targets || {}) },
+    },
+    options.presetName,
+  );
+
+  const currentText = stringifyRules(rules);
+  const nextText = stringifyRules(nextRules);
+  const changed = currentText !== nextText;
 
-  let updated = 0;
-  for (const targetId of selectedTargetIds) {
+  logger.log("rules-doctor preset apply");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- preset: ${options.presetName}`);
+  logger.log(`- mode: ${options.write ? "write" : "dry-run"}`);
+
+  if (options.diff && changed) {
+    logger.log("\n# diff: .agentrules/rules.yaml");
+    logger.log(renderSimpleDiff(currentText, nextText));
+  }
+
+  if (!changed) {
+    logger.log("No changes required: preset already applied.");
+    return 0;
+  }
+
+  if (!options.write) {
+    logger.log("Dry-run complete: rules.yaml would be updated. Re-run with --write.");
+    return 0;
+  }
+
+  ensureParentDirectory(rulesFile);
+  writeFileSync(rulesFile, nextText, "utf8");
+  logger.log(`Updated ${rulesFile}`);
+  return 0;
+}
+
+function buildTargetPlans(rootDir, rules, targetIds) {
+  const plans = [];
+
+  for (const targetId of targetIds) {
     const adapter = ADAPTERS_BY_ID[targetId];
     const target = getTargetConfig(rules, adapter);
+    const targetPath = resolveInRoot(rootDir, target.path);
+    const fileExists = existsSync(targetPath);
+    const currentText = fileExists ? readFileSync(targetPath, "utf8") : "";
 
     if (!target.enabled) {
-      logger.log(`Skipped ${targetId} (disabled in rules.yaml).`);
+      plans.push({
+        targetId,
+        adapter,
+        enabled: false,
+        targetPath,
+        targetPathDisplay: target.path,
+        exists: fileExists,
+        currentText,
+        desiredText: currentText,
+        changed: false,
+      });
       continue;
     }
 
-    const targetPath = resolveInRoot(rootDir, target.path);
     const rendered = adapter.render(rules).trim();
-    ensureParentDirectory(targetPath);
+    const desiredText =
+      adapter.management === "marker"
+        ? upsertManagedSection(currentText, rendered, adapter.markerBegin, adapter.markerEnd)
+        : `${rendered}\n`;
+
+    plans.push({
+      targetId,
+      adapter,
+      enabled: true,
+      targetPath,
+      targetPathDisplay: target.path,
+      exists: fileExists,
+      currentText,
+      desiredText,
+      changed: desiredText !== currentText,
+    });
+  }
 
-    if (adapter.management === "marker") {
-      const existing = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
-      const updatedText = upsertManagedSection(
-        existing,
-        rendered,
-        adapter.markerBegin,
-        adapter.markerEnd,
+  return plans;
+}
+
+function renderSimpleDiff(currentText, desiredText) {
+  if (currentText === desiredText) {
+    return "";
+  }
+
+  const oldLines = currentText.replace(/\r\n/g, "\n").split("\n");
+  const newLines = desiredText.replace(/\r\n/g, "\n").split("\n");
+  const output = ["--- current", "+++ desired"];
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  const hardLimit = 120;
+  let emitted = 0;
+
+  for (let index = 0; index < maxLines; index += 1) {
+    const oldLine = oldLines[index];
+    const newLine = newLines[index];
+
+    if (oldLine === newLine) {
+      continue;
+    }
+
+    if (typeof oldLine !== "undefined") {
+      output.push(`-${oldLine}`);
+      emitted += 1;
+    }
+    if (typeof newLine !== "undefined") {
+      output.push(`+${newLine}`);
+      emitted += 1;
+    }
+
+    if (emitted >= hardLimit) {
+      output.push("... diff truncated ...");
+      break;
+    }
+  }
+
+  return output.join("\n");
+}
+
+function formatPlanSummary(plans) {
+  const changed = plans.filter((plan) => plan.changed).length;
+  const changedFiles = new Set(plans.filter((plan) => plan.changed).map((plan) => plan.targetPath)).size;
+  const enabled = plans.filter((plan) => plan.enabled).length;
+  const disabled = plans.length - enabled;
+  return { changed, changedFiles, enabled, disabled };
+}
+
+function getUniqueWritePlans(plans) {
+  const byPath = new Map();
+  const duplicates = [];
+
+  for (const plan of plans) {
+    if (!plan.enabled || !plan.changed) {
+      continue;
+    }
+
+    const existing = byPath.get(plan.targetPath);
+    if (!existing) {
+      byPath.set(plan.targetPath, plan);
+      continue;
+    }
+
+    if (existing.desiredText !== plan.desiredText) {
+      throw new Error(
+        `Conflicting outputs for ${plan.targetPathDisplay}: ${existing.targetId} and ${plan.targetId} produce different content.`,
       );
-      writeFileSync(targetPath, updatedText, "utf8");
+    }
+
+    duplicates.push({
+      targetPathDisplay: plan.targetPathDisplay,
+      winner: existing.targetId,
+      duplicate: plan.targetId,
+    });
+  }
+
+  return {
+    uniquePlans: Array.from(byPath.values()),
+    duplicates,
+  };
+}
+
+function syncCommand(rootDir, logger, args) {
+  const options = parseTargetedArgs("sync", args, { write: true, backup: true });
+  const { rules } = loadRules(rootDir);
+  const plans = buildTargetPlans(rootDir, rules, options.targetIds);
+  const summary = formatPlanSummary(plans);
+
+  logger.log("rules-doctor sync");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- selected targets: ${options.targetIds.join(", ")}`);
+  logger.log(`- mode: ${options.write ? "write" : "dry-run"}`);
+
+  for (const plan of plans) {
+    if (!plan.enabled) {
+      logger.log(`- ${plan.targetId}: disabled (${plan.targetPathDisplay})`);
+      continue;
+    }
+    if (!plan.changed) {
+      logger.log(`- ${plan.targetId}: up-to-date (${plan.targetPathDisplay})`);
+      continue;
+    }
+    logger.log(`- ${plan.targetId}: would update (${plan.targetPathDisplay})`);
+  }
+
+  if (options.diff) {
+    for (const plan of plans) {
+      if (!plan.enabled || !plan.changed) {
+        continue;
+      }
+      logger.log(`\n# diff: ${plan.targetId} (${plan.targetPathDisplay})`);
+      logger.log(renderSimpleDiff(plan.currentText, plan.desiredText));
+    }
+  }
+
+  if (!options.write) {
+    if (summary.changed === 0) {
+      logger.log("Dry-run complete: no changes.");
     } else {
-      writeFileSync(targetPath, `${rendered}\n`, "utf8");
+      logger.log(
+        `Dry-run complete: ${summary.changedFiles} file(s) would change (${summary.changed} target mappings). Re-run with --write.`,
+      );
+    }
+    return 0;
+  }
+
+  const { uniquePlans, duplicates } = getUniqueWritePlans(plans);
+  for (const duplicate of duplicates) {
+    logger.log(
+      `  note: ${duplicate.duplicate} shares output with ${duplicate.winner} at ${duplicate.targetPathDisplay}`,
+    );
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  for (const plan of uniquePlans) {
+    ensureParentDirectory(plan.targetPath);
+    if (options.backup && plan.exists) {
+      const backupPath = `${plan.targetPath}.rules-doctor.bak.${timestamp}`;
+      writeFileSync(backupPath, plan.currentText, "utf8");
+      logger.log(`  backup: ${backupPath}`);
     }
 
-    logger.log(`Updated ${targetPath} (${targetId})`);
-    updated += 1;
+    writeFileSync(plan.targetPath, plan.desiredText, "utf8");
+    logger.log(`  updated: ${plan.targetPath}`);
   }
 
-  if (updated === 0) {
-    logger.log("No files updated.");
+  logger.log(
+    `Write complete: ${uniquePlans.length} file(s) updated (${summary.changed} target mappings changed).`,
+  );
+  return 0;
+}
+
+function checkCommand(rootDir, logger, args) {
+  const options = parseTargetedArgs("check", args, { write: false, backup: false });
+  const { rules } = loadRules(rootDir);
+  const plans = buildTargetPlans(rootDir, rules, options.targetIds);
+  const summary = formatPlanSummary(plans);
+
+  logger.log("rules-doctor check");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- selected targets: ${options.targetIds.join(", ")}`);
+
+  for (const plan of plans) {
+    if (!plan.enabled) {
+      logger.log(`- ${plan.targetId}: disabled (${plan.targetPathDisplay})`);
+      continue;
+    }
+    logger.log(
+      `- ${plan.targetId}: ${plan.changed ? "drift detected" : "in sync"} (${plan.targetPathDisplay})`,
+    );
+  }
+
+  if (options.diff) {
+    for (const plan of plans) {
+      if (!plan.enabled || !plan.changed) {
+        continue;
+      }
+      logger.log(`\n# diff: ${plan.targetId} (${plan.targetPathDisplay})`);
+      logger.log(renderSimpleDiff(plan.currentText, plan.desiredText));
+    }
   }
+
+  if (summary.changed === 0) {
+    logger.log("Check complete: all selected targets are in sync.");
+    return 0;
+  }
+
+  logger.log(`Check failed: ${summary.changed} target file(s) need sync.`);
+  return 1;
 }
 
 function analyzeCommand(rootDir, logger, args) {
@@ -653,6 +1291,57 @@ function analyzeCommand(rootDir, logger, args) {
   return 0;
 }
 
+function doctorCommand(rootDir, logger, args) {
+  const options = parseDoctorArgs(args);
+  const { rules, rulesExists, rulesFile } = loadRules(rootDir, { allowMissing: true });
+  const issues = [];
+
+  logger.log("rules-doctor doctor");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- rules file: ${rulesFile}`);
+  logger.log(`- rules exists: ${rulesExists ? "yes" : "no (defaults assumed)"}`);
+
+  const pathToTargets = {};
+  for (const adapter of ADAPTERS) {
+    const target = getTargetConfig(rules, adapter);
+    const absolutePath = resolveInRoot(rootDir, target.path);
+    const exists = existsSync(absolutePath);
+    const enabledText = target.enabled ? "enabled" : "disabled";
+    logger.log(`- ${adapter.id}: ${enabledText}, path=${target.path}, file=${exists ? "found" : "missing"}`);
+
+    if (!target.enabled) {
+      continue;
+    }
+
+    const key = absolutePath;
+    if (!pathToTargets[key]) {
+      pathToTargets[key] = [];
+    }
+    pathToTargets[key].push(adapter.id);
+  }
+
+  for (const path of Object.keys(pathToTargets)) {
+    const ids = pathToTargets[path];
+    if (ids.length > 1) {
+      issues.push(`Multiple enabled targets map to the same file: ${ids.join(", ")} -> ${path}`);
+    }
+  }
+
+  logger.log("- Findings:");
+  if (issues.length === 0) {
+    logger.log("- No structural issues found.");
+    return 0;
+  }
+  for (const issue of issues) {
+    logger.log(`- ${issue}`);
+  }
+
+  if (options.strict) {
+    return 1;
+  }
+  return 0;
+}
+
 function targetsListCommand(logger) {
   logger.log("Supported targets:");
   for (const adapter of ADAPTERS) {
@@ -679,19 +1368,29 @@ function runCli(argv, options) {
     }
 
     if (command === "init") {
-      initCommand(rootDir, logger);
-      return 0;
+      return initCommand(rootDir, logger, rest);
+    }
+
+    if (command === "preset") {
+      return presetApplyCommand(rootDir, logger, rest);
     }
 
     if (command === "sync") {
-      syncCommand(rootDir, logger, rest);
-      return 0;
+      return syncCommand(rootDir, logger, rest);
+    }
+
+    if (command === "check") {
+      return checkCommand(rootDir, logger, rest);
     }
 
     if (command === "analyze") {
       return analyzeCommand(rootDir, logger, rest);
     }
 
+    if (command === "doctor") {
+      return doctorCommand(rootDir, logger, rest);
+    }
+
     if (command === "targets") {
       if (rest.length === 1 && rest[0] === "list") {
         targetsListCommand(logger);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jazpiper/rules-doctor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Node.js CLI to sync shared coding rules across multiple agent/CLI targets",
   "license": "MIT",
   "bin": {
@@ -11,11 +11,15 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "node scripts/tsup.js src/index.js --clean --dts",
-    "test": "npm run build && node --test"
+    "test": "npm run build && node --test",
+    "release:patch": "bash scripts/release.sh patch",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major"
   },
   "keywords": [
     "cli",
@@ -23,10 +27,10 @@
     "rules",
     "claude",
     "codex",
+    "copilot",
     "cursor",
     "gemini",
-    "opencode",
-    "antigravity"
+    "opencode"
   ],
   "engines": {
     "node": ">=18"

package/dist/adapters/antigravity.js

@@ -1,12 +0,0 @@
-const { renderManagedRulesBody } = require("./common");
-
-module.exports = {
-  id: "antigravity",
-  name: "Antigravity CLI",
-  description: "Generate GEMINI.md-compatible managed instruction file (inferred mapping).",
-  defaultPath: "GEMINI.md",
-  management: "full",
-  render(rules) {
-    return ["# GEMINI.md", "", renderManagedRulesBody(rules)].join("\n");
-  },
-};