@jazpiper/rules-doctor 0.2.0 → 0.3.1

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,13 @@
 # @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`)
+- 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 +15,129 @@ 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.
-
-### 2) Sync generated docs
+### 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.
+
+## Supported Targets
 
-`--strict` makes `analyze` fail with non-zero exit code when findings exist.
+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)
 
-### 4) List supported adapters
+## Command Reference
+
+### `init`
 
 ```bash
-rules-doctor targets list
+npx rules-doctor init [--import]
 ```
 
-Shows built-in adapters and default file paths.
+### `sync`
 
-### 5) Directory/Path Notes
+```bash
+npx rules-doctor sync [--target all|claude,codex,...] [--diff] [--write] [--backup]
+```
 
-- `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.
+### `check`
 
-## Rules Schema (v2 Draft)
+```bash
+npx rules-doctor check [--target all|claude,codex,...] [--diff]
+```
+
+## 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.
 
-`init` now creates a v2-compatible draft with `targets` configuration:
+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"
+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
 ```
 
-You can disable or relocate any target by editing `targets.<id>.enabled/path`.
+## 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`:
+  - Edit `.agentrules/rules.yaml` directly, then run `npx rules-doctor sync --write`.
+
+## 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 = {