deuk-agent-rule 1.0.1

package/README.ko.md

@@ -0,0 +1,79 @@
+# DeukAgentRules (득에이전트룰스)
+
+**npm 패키지:** `deuk-agent-rule` · **CLI:** `deuk-agent-rule`
+
+**English:** [README.md](README.md)
+
+Cursor, Copilot, Gemini 등 여러 에이전트·도구를 함께 쓸 때를 위한 `AGENTS.md`·`.cursor/rules` 버전 관리형 템플릿. 핸드오프·간결 응답으로 비용·성능을 개선합니다.
+
+## 워크스페이스 초기화
+
+설치만으로는 파일이 바뀌지 않습니다. **대상 프로젝트 루트**에서 CLI를 실행하거나 `--cwd`로 경로를 줍니다.
+
+```bash
+npm install deuk-agent-rule
+npx deuk-agent-rule init
+```
+
+첫 적용 흐름:
+
+1. `AGENTS.md`를 둘 프로젝트 루트로 이동.
+2. `npm install deuk-agent-rule` (devDependency 권장 가능).
+3. `npx deuk-agent-rule init` — 마커가 없으면 끝에 `<!-- deuk-agent-rule:begin -->` … `<!-- deuk-agent-rule:end -->` 블록을 붙이고 안쪽을 번들 템플릿으로 채움. `.mdc`는 `.cursor/rules/`에 복사(이름 충돌 시 기본 **prefix**).
+
+패키지 업데이트 후:
+
+```bash
+npm update deuk-agent-rule
+npx deuk-agent-rule init
+```
+
+`AGENTS.md`에서는 **마커 안**만 다시 갱신되고, 바깥 내용은 유지됩니다.
+
+### `init` 파라미터
+
+플래그는 모두 `init` **뒤**에 둡니다. 예: `npx deuk-agent-rule init --cwd ../다른레포 --dry-run`
+
+| 플래그 | init 기본값 | 설명 |
+|--------|-------------|------|
+| `--cwd <path>` | 현재 디렉터리 | `AGENTS.md`·`.cursor/rules/`를 쓸 레포 루트. |
+| `--dry-run` | 끔 | 쓰기 없이 할 일만 출력. |
+| `--backup` | 끔 | 덮어쓰기 전 같은 이름에 `.bak` 저장. |
+| `--tag <id>` | `deuk-agent-rule` | `<!-- <id>:begin -->` ~ `<!-- <id>:end -->` 마커 쌍. |
+| `--marker-begin` / `--marker-end` | (`--tag` 권장) | 임의 마커 문자열, **둘 다** 필요. |
+| `--agents <mode>` | `inject` | `inject` — 마커 안만 갱신(마커 없으면 블록 추가). `skip` — `AGENTS.md` 건드리지 않음. `overwrite` — 전체 교체(주의). |
+| `--rules <mode>` | `prefix` | `prefix` — 있으면 `deuk-agent-rule-foo.mdc`로 추가. `skip` — 스킵. `overwrite` — 덮어쓰기. |
+| `--append-if-no-markers` | 끔 | `merge`에서 주로 사용. |
+
+예시:
+
+```bash
+npx deuk-agent-rule init --cwd /path/to/repo
+npx deuk-agent-rule init --dry-run
+npx deuk-agent-rule init --tag mycompany --rules overwrite
+npx deuk-agent-rule init --agents skip --rules prefix
+npx deuk-agent-rule init --backup
+```
+
+### 동작 모델
+
+- **관리 구역**: 마커 쌍 **사이**만 패키지가 갱신.
+- **`.mdc`**: 별도 파일로 복사; 기본 `prefix`로 기존 파일 보호.
+
+### 번들에 포함되는 규칙
+
+- **`multi-ai-workflow.mdc`** — `alwaysApply: true`
+- **`git-commit.mdc`** — `alwaysApply: false`
+
+### `merge` (엄격)
+
+옵션은 동일. 마커가 없으면 `inject`는 실패(`--append-if-no-markers` 없을 때). 기본 `--rules skip`.
+
+### 주의
+
+- `alwaysApply: true` 규칙이 겹치면 컨텍스트가 길어질 수 있음.
+- `postinstall`에서 `init` 자동 실행은 권장하지 않음.
+
+## 버전
+
+배포 전 `package.json`의 `version` 상향.

package/README.md

@@ -0,0 +1,80 @@
+# DeukAgentRules
+
+**npm package:** `deuk-agent-rule` · **CLI:** `deuk-agent-rule`
+
+**한국어:** [README.ko.md](README.ko.md)
+
+Versioned templates for `AGENTS.md` and `.cursor/rules` for Cursor, Copilot, Gemini and similar agents: shared handoff format, concise execution, stronger cost-efficiency and responsiveness.
+
+## Initialize a workspace
+
+Install does nothing until you run the CLI from the **target repository root** (or pass `--cwd`).
+
+```bash
+npm install deuk-agent-rule
+npx deuk-agent-rule init
+```
+
+Typical first run:
+
+1. `cd` into your project root (where `AGENTS.md` should live).
+2. `npm install deuk-agent-rule` (devDependency is fine).
+3. `npx deuk-agent-rule init` — appends `<!-- deuk-agent-rule:begin -->` … `<!-- deuk-agent-rule:end -->` if missing, fills the inner region with the bundled template, and copies `.mdc` files under `.cursor/rules/` (default **prefix** on name clash).
+
+After a package upgrade:
+
+```bash
+npm update deuk-agent-rule
+npx deuk-agent-rule init
+```
+
+Only the **marker region** in `AGENTS.md` is replaced again; your text outside the markers stays.
+
+### `init` parameters
+
+All flags go **after** `init` (e.g. `npx deuk-agent-rule init --cwd ../other-repo --dry-run`).
+
+| Flag | Default (init) | Description |
+|------|----------------|-------------|
+| `--cwd <path>` | current directory | Root of the repo to modify (`AGENTS.md`, `.cursor/rules/`). |
+| `--dry-run` | off | Print planned actions; do not write files. |
+| `--backup` | off | Write `*.bak` next to any file that would be overwritten. |
+| `--tag <id>` | `deuk-agent-rule` | HTML comment markers: `<!-- <id>:begin -->` … `<!-- <id>:end -->`. |
+| `--marker-begin <s>` / `--marker-end <s>` | (use `--tag` instead) | Custom marker strings; **both** required if either is set. |
+| `--agents <mode>` | `inject` | `inject` — update only inside markers (or append block if no markers). `skip` — do not change `AGENTS.md`. `overwrite` — replace entire `AGENTS.md` with the bundle (use with care). |
+| `--rules <mode>` | `prefix` | `prefix` — if `foo.mdc` exists, write `deuk-agent-rule-foo.mdc`. `skip` — skip existing names. `overwrite` — replace on clash. |
+| `--append-if-no-markers` | off | Rare for `init` (init already appends when markers are missing). Same flag is mainly for `merge`. |
+
+Examples:
+
+```bash
+npx deuk-agent-rule init --cwd /path/to/repo
+npx deuk-agent-rule init --dry-run
+npx deuk-agent-rule init --tag mycompany --rules overwrite
+npx deuk-agent-rule init --agents skip --rules prefix
+npx deuk-agent-rule init --backup
+```
+
+### Product model
+
+- **Managed block in `AGENTS.md`**: Between `<!-- deuk-agent-rule:begin -->` and `<!-- deuk-agent-rule:end -->` (or your `--tag`) — `init` / `merge` replace **only** that inner content with the bundled template.
+- **Updates**: Re-run `init` after `npm update` to refresh the managed block idempotently.
+- **`.mdc`**: Copied as **separate files**; default `prefix` avoids overwriting your existing rules.
+
+### Bundled rules
+
+- **`multi-ai-workflow.mdc`** — `alwaysApply: true`
+- **`git-commit.mdc`** — `alwaysApply: false`
+
+### `merge` (stricter)
+
+Same flags; **`AGENTS.md` `inject` fails if markers are missing** unless `--append-if-no-markers`. Default **`--rules skip`**.
+
+### Caveats
+
+- Multiple `alwaysApply: true` rule files (yours + prefixed copies) all apply — trim duplicates if context grows too large.
+- Do **not** run `init` from `postinstall` without an explicit team decision.
+
+## Versioning
+
+Bump `version` in `package.json` before publishing.

package/bundle/AGENTS.md

@@ -0,0 +1,51 @@
+# Project Agent Rules
+
+## Identity
+
+Senior software engineer. Correctness, minimal diffs, safety.
+
+## Code Quality
+
+- Minimal diffs: keep existing conventions, public API, and serialized/config shapes stable unless the task requires a deliberate change.
+- Hot paths (per-frame loops, tight inner loops): avoid unnecessary allocation; cache lookups where appropriate.
+- Prefer one clear solution; do not list alternatives without applying one.
+- Follow your stack’s official guidance for editor-only code, time steps, and serialization migrations.
+
+## Documentation
+
+- User-facing docs: product behavior, compatibility, packaging, and security — not internal runbooks pasted verbatim.
+- Changelog entries: factual, consumer-relevant changes only.
+
+## Cost-effective sessions
+
+- Prefer **short, high-signal** answers and patches; avoid filler, long tutorials, and repeating context the user already has unless they ask for depth.
+- **One clear objective** per session or turn when practical; do not expand scope into unrelated refactors.
+- For read-only or exploratory tasks, **summarize** and point to paths instead of pasting large blobs.
+
+## IDE Branding
+
+No editor or vendor tool branding in code, docs, README, commits, or published artifacts.
+
+## 요약 (한국어)
+
+- **정체성**: 시니어 소프트웨어 엔지니어. 정확성, 최소 diff, 안전.
+- **코드 품질**: 관례·공개 API·직렬화 형태를 불필요하게 흔들지 않음. 핫패스에서 불필요한 할당 지양, 스택 공식 가이드를 따름.
+- **문서**: 사용자에게 보이는 동작·호환·패키징·보안 위주. 내부 절차 전문을 그대로 붙여 넣지 않음.
+- **브랜딩**: 코드·문서·README·커밋·배포물에 에디터·벤더 도구 이름을 넣지 않음.
+- **비용·효율**: 짧고 신호가 큰 답·패치 위주; 불필요한 장문·동일 맥락 반복 지양. 한 번에 목표 하나. 읽기 전용 작업은 요약과 경로 위주.
+
+English sections above are canonical for tooling; this block is a short Korean mirror for the same rules.
+
+## Handoff format
+
+When handing work between tools or people, use:
+
+```markdown
+## Task: [title]
+### Files to modify
+- `path/to/file`: [what to change]
+### Design decisions
+- [decision]
+### Constraints
+- [constraint]
+```

package/bundle/rules/git-commit.mdc

@@ -0,0 +1,24 @@
+---
+description: Git 커밋 메시지 — 짧고 의미 있게(저비용 출력)
+alwaysApply: false
+---
+
+# Git commit messages (agent)
+
+커밋 메시지·스테이징 요약을 쓸 때만 적용. **출력은 최소 토큰**, 내용은 **검색·리뷰에 쓸 만한 정보**만.
+
+## 형식 (기본)
+
+- **첫 줄만**: 명령형, **72자 이내**, 마침표 없음.
+- **선택** `type(scope): summary` — `feat` `fix` `refactor` `docs` `chore` 등; `scope`는 디렉터리·모듈 한 단어.
+- **본문**: 사용자가 요청하거나 변경이 여러 주제일 때만. 그때도 **불릿 최대 3줄**, 각 80자 이내.
+
+## 쓸 것 / 쓰지 말 것
+
+- **쓸 것**: 무엇이 바뀌었는지 한 문장(동작·계약·호환). 위험한 변경이면 한 단어로 표시(`BREAKING` 또는 마이그레이션 한 줄).
+- **쓰지 말 것**: diff 재서술, 파일 목록 나열, “업데이트함/개선함” 같은 빈 말, 이모지, 장문 튜토리얼, 영어·한국어 이중 번역(팀 언어 하나만).
+
+## 비용
+
+- 한 커밋 주제면 **제목 한 줄로 끝낸다.**
+- 스테이징이 크면 제목은 요약하고, 본문은 **사용자가 본문 달라고 할 때만** 추가한다.

package/bundle/rules/multi-ai-workflow.mdc

@@ -0,0 +1,34 @@
+---
+description: Handoff format rules for multi-AI workflow
+alwaysApply: true
+---
+
+# Multi-AI Workflow
+
+## Receiving Handoff from Other Tools
+
+When the user pastes a design or plan from another assistant or planning tool:
+
+1. Parse the **handoff format** (see `AGENTS.md`, heading **Handoff format**).
+2. Validate file paths exist before modifying.
+3. Execute changes as specified — do not redesign unless the user asks.
+4. Report back in the same handoff format for further iteration.
+
+## Producing Handoff for Other Tools
+
+When the user asks to prepare work for another tool:
+
+1. Output the handoff format with concrete file paths and change descriptions.
+2. Include any constraints or dependencies.
+3. Do not include editor-specific instructions (token budgets, local rule file paths).
+
+## Role: Execution
+
+In this workflow the agent's primary role is **execution** — applying concrete changes across multiple files. For design, analysis, or planning, defer to the user's chosen tool when they indicate.
+
+## Cost awareness (effective use of context)
+
+- Keep sessions **focused** — one clear objective per session when possible.
+- Prefer **concise** handoffs and replies: concrete paths, decisions, and diffs over narrative padding.
+- For read-only analysis, prefer **summaries** and scoped excerpts over dumping whole files; use lightweight review modes when the product offers them.
+- When producing handoffs for *other* tools, omit local-only tuning hints (see **Producing Handoff** above); still stay efficient in your own responses here.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "deuk-agent-rule",
+  "version": "1.0.1",
+  "description": "DeukAgentRules: generic AGENTS.md + .cursor rule templates with init/merge CLI (npm name: deuk-agent-rule).",
+  "license": "UNLICENSED",
+  "files": [
+    "bundle/**/*",
+    "scripts/**/*.mjs",
+    "README.md",
+    "README.ko.md"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-bundle.mjs",
+    "prepack": "node scripts/sync-bundle.mjs",
+    "merge:dry": "node scripts/cli.mjs merge --dry-run --cwd .. --agents skip",
+    "sync:oss": "node scripts/sync-oss.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "deuk-agent-rule": "./scripts/cli.mjs"
+  }
+}

package/scripts/cli.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import {
+  applyAgents,
+  applyRules,
+  readBundleAgents,
+  resolveMarkers,
+} from "./merge-logic.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..");
+const bundleRoot = join(pkgRoot, "bundle");
+
+function printHelp() {
+  console.log(
+    "DeukAgentRules (npm: deuk-agent-rule) — AGENTS.md + .cursor/rules templates\n\nUsage:\n  npx deuk-agent-rule init   [options]\n  npx deuk-agent-rule merge  [options]\n\nPrimary flow:\n  npm install deuk-agent-rule\n  npx deuk-agent-rule init\n\nOptions:\n  --cwd <path>\n  --dry-run\n  --backup\n  --tag <id>\n  --marker-begin <string>\n  --marker-end <string>\n\ninit defaults: agents inject (append markers if missing), rules prefix\nmerge defaults: agents inject (fail if no markers unless --append-if-no-markers), rules skip\n\nAlso:\n  --agents skip|overwrite|inject\n  --rules skip|overwrite|prefix\n  --append-if-no-markers\n\nKorean: package README.ko.md\n",
+  );
+}
+
+function parseArgs(argv) {
+  const out = {
+    cwd: process.cwd(),
+    dryRun: false,
+    backup: false,
+    tag: undefined,
+    markerBegin: undefined,
+    markerEnd: undefined,
+    agents: undefined,
+    rules: undefined,
+    appendIfNoMarkers: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") {
+      out.cwd = argv[++i];
+      if (!out.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--backup") out.backup = true;
+    else if (a === "--tag") {
+      out.tag = argv[++i];
+      if (out.tag == null) throw new Error("--tag requires a value");
+    } else if (a === "--marker-begin") {
+      out.markerBegin = argv[++i];
+      if (out.markerBegin == null) throw new Error("--marker-begin requires a value");
+    } else if (a === "--marker-end") {
+      out.markerEnd = argv[++i];
+      if (out.markerEnd == null) throw new Error("--marker-end requires a value");
+    } else if (a === "--agents") {
+      out.agents = argv[++i];
+      if (!out.agents) throw new Error("--agents requires skip|overwrite|inject");
+    } else if (a === "--rules") {
+      out.rules = argv[++i];
+      if (!out.rules) throw new Error("--rules requires skip|overwrite|prefix");
+    } else if (a === "--append-if-no-markers") out.appendIfNoMarkers = true;
+    else if (a === "-h" || a === "--help") {
+      printHelp();
+      process.exit(0);
+    } else {
+      throw new Error("Unknown argument: " + a);
+    }
+  }
+  return out;
+}
+
+function validateMode(name, v, allowed) {
+  if (!allowed.includes(v)) {
+    throw new Error("Invalid " + name + ": " + v + " (allowed: " + allowed.join(", ") + ")");
+  }
+}
+
+function runInit(opts) {
+  const markers = resolveMarkers({
+    tag: opts.tag,
+    markerBegin: opts.markerBegin,
+    markerEnd: opts.markerEnd,
+  });
+  const agentsMode = opts.agents ?? "inject";
+  validateMode("agents", agentsMode, ["skip", "overwrite", "inject"]);
+
+  const rulesMode = opts.rules ?? "prefix";
+  validateMode("rules", rulesMode, ["skip", "overwrite", "prefix"]);
+
+  const bundleContent = readBundleAgents(bundleRoot);
+  const targetAgents = join(opts.cwd, "AGENTS.md");
+  const targetRules = join(opts.cwd, ".cursor", "rules");
+
+  const agentsResult = applyAgents({
+    targetPath: targetAgents,
+    bundleContent,
+    markers,
+    flavor: "init",
+    appendIfNoMarkers: opts.appendIfNoMarkers,
+    dryRun: opts.dryRun,
+    backup: opts.backup,
+    agentsMode,
+  });
+  console.log("AGENTS.md: " + agentsResult.action + (agentsResult.mode ? " (" + agentsResult.mode + ")" : ""));
+
+  const ruleActions = applyRules({
+    bundleRulesDir: join(bundleRoot, "rules"),
+    targetRulesDir: targetRules,
+    rulesMode,
+    dryRun: opts.dryRun,
+    backup: opts.backup,
+  });
+  for (const r of ruleActions) {
+    console.log("rule " + r.action + ": " + (r.dest || r.src) + (r.reason ? " (" + r.reason + ")" : ""));
+  }
+}
+
+function runMerge(opts) {
+  const markers = resolveMarkers({
+    tag: opts.tag,
+    markerBegin: opts.markerBegin,
+    markerEnd: opts.markerEnd,
+  });
+  const agentsMode = opts.agents ?? "inject";
+  validateMode("agents", agentsMode, ["skip", "overwrite", "inject"]);
+
+  const rulesMode = opts.rules ?? "skip";
+  validateMode("rules", rulesMode, ["skip", "overwrite", "prefix"]);
+
+  const bundleContent = readBundleAgents(bundleRoot);
+  const targetAgents = join(opts.cwd, "AGENTS.md");
+  const targetRules = join(opts.cwd, ".cursor", "rules");
+
+  const agentsResult = applyAgents({
+    targetPath: targetAgents,
+    bundleContent,
+    markers,
+    flavor: "merge",
+    appendIfNoMarkers: opts.appendIfNoMarkers,
+    dryRun: opts.dryRun,
+    backup: opts.backup,
+    agentsMode,
+  });
+  console.log("AGENTS.md: " + agentsResult.action + (agentsResult.mode ? " (" + agentsResult.mode + ")" : ""));
+
+  const ruleActions = applyRules({
+    bundleRulesDir: join(bundleRoot, "rules"),
+    targetRulesDir: targetRules,
+    rulesMode,
+    dryRun: opts.dryRun,
+    backup: opts.backup,
+  });
+  for (const r of ruleActions) {
+    console.log("rule " + r.action + ": " + (r.dest || r.src) + (r.reason ? " (" + r.reason + ")" : ""));
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const sub = argv[0];
+  if (!sub || sub === "-h" || sub === "--help") {
+    printHelp();
+    process.exit(0);
+  }
+
+  const rest = argv.slice(1);
+  if (sub === "help") {
+    printHelp();
+    process.exit(0);
+  }
+
+  let opts;
+  try {
+    opts = parseArgs(rest);
+  } catch (e) {
+    console.error(e.message || e);
+    printHelp();
+    process.exit(1);
+  }
+
+  if (!existsSync(bundleRoot)) {
+    console.error(
+      "Missing bundle/ (run from published package or run npm run sync in deuk-agent-rule when developing in the monorepo).",
+    );
+    process.exit(1);
+  }
+
+  try {
+    if (sub === "init") {
+      runInit(opts);
+    } else if (sub === "merge") {
+      runMerge(opts);
+    } else {
+      console.error("Unknown command: " + sub);
+      printHelp();
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(e.message || e);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/merge-logic.mjs

@@ -0,0 +1,203 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "fs";
+import { join } from "path";
+
+export const DEFAULT_TAG = "deuk-agent-rule";
+
+export function resolveMarkers(o) {
+  const hasBegin = o.markerBegin != null && o.markerBegin !== "";
+  const hasEnd = o.markerEnd != null && o.markerEnd !== "";
+  if (hasBegin !== hasEnd) {
+    throw new Error("Use both --marker-begin and --marker-end, or neither.");
+  }
+  if (hasBegin && hasEnd) {
+    if (o.markerBegin === o.markerEnd) {
+      throw new Error("--marker-begin and --marker-end must differ.");
+    }
+    return { begin: o.markerBegin, end: o.markerEnd };
+  }
+  const id = o.tag && o.tag.trim() ? o.tag.trim() : DEFAULT_TAG;
+  return {
+    begin: "<!-- " + id + ":begin -->",
+    end: "<!-- " + id + ":end -->",
+  };
+}
+
+export function findMarkerRegion(content, begin, end) {
+  const i = content.indexOf(begin);
+  if (i === -1) return null;
+  const j = content.indexOf(end, i + begin.length);
+  if (j === -1) {
+    throw new Error(
+      "Found begin marker but no matching end marker after it.\n  begin: " + begin + "\n  end: " + end,
+    );
+  }
+  const innerStart = i + begin.length;
+  const innerEnd = j;
+  return { innerStart, innerEnd };
+}
+
+export function applyAgents(opts) {
+  const {
+    targetPath,
+    bundleContent,
+    markers,
+    flavor,
+    appendIfNoMarkers,
+    dryRun,
+    backup,
+    agentsMode,
+  } = opts;
+
+  if (agentsMode === "skip") {
+    return {
+      action: "skip",
+      reason: existsSync(targetPath)
+        ? "agents mode skip (file exists)"
+        : "agents mode skip",
+    };
+  }
+
+  if (agentsMode === "overwrite") {
+    const prev = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+    if (dryRun) {
+      return { action: "would-write", path: targetPath, mode: "overwrite" };
+    }
+    if (backup && existsSync(targetPath)) {
+      copyFileSync(targetPath, targetPath + ".bak");
+    }
+    writeFileSync(targetPath, bundleContent, "utf8");
+    return { action: "write", path: targetPath, mode: "overwrite", hadPrevious: !!prev };
+  }
+
+  const existing = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+  const region = findMarkerRegion(existing, markers.begin, markers.end);
+
+  if (region) {
+    const inner = bundleContent.trimEnd() + (bundleContent.endsWith("\n") ? "" : "\n");
+    const next =
+      existing.slice(0, region.innerStart) +
+      "\n" +
+      inner +
+      existing.slice(region.innerEnd);
+    if (dryRun) {
+      return { action: "would-write", path: targetPath, mode: "inject-region" };
+    }
+    if (backup && existsSync(targetPath)) {
+      copyFileSync(targetPath, targetPath + ".bak");
+    }
+    writeFileSync(targetPath, next, "utf8");
+    return { action: "write", path: targetPath, mode: "inject-region" };
+  }
+
+  const allowAppend =
+    appendIfNoMarkers || flavor === "init";
+
+  if (!allowAppend) {
+    const hint = [
+      "",
+      "No marker region found. Add a pair like:",
+      "",
+      markers.begin,
+      "",
+      markers.end,
+      "",
+      "Or run: npx deuk-agent-rule init   (appends markers once)",
+      "Or pass: --append-if-no-markers",
+      "",
+    ].join("\n");
+    throw new Error(
+      "Inject mode requires markers in " + targetPath + " or use --append-if-no-markers." + hint,
+    );
+  }
+
+  const inner = bundleContent.trimEnd() + (bundleContent.endsWith("\n") ? "" : "\n");
+  const block = "\n" + markers.begin + "\n\n" + inner + "\n" + markers.end + "\n";
+  const next = existing ? existing.replace(/\s*$/, "") + block : markers.begin + "\n\n" + inner + "\n" + markers.end + "\n";
+
+  if (dryRun) {
+    return {
+      action: "would-write",
+      path: targetPath,
+      mode: flavor === "init" ? "append-markers-init" : "append-markers",
+    };
+  }
+  if (backup && existsSync(targetPath)) {
+    copyFileSync(targetPath, targetPath + ".bak");
+  }
+  writeFileSync(targetPath, next, "utf8");
+  return {
+    action: "write",
+    path: targetPath,
+    mode: flavor === "init" ? "append-markers-init" : "append-markers",
+  };
+}
+
+export function applyRules(opts) {
+  const {
+    bundleRulesDir,
+    targetRulesDir,
+    rulesMode,
+    filePrefix = "deuk-agent-rule-",
+    dryRun,
+    backup,
+  } = opts;
+
+  if (!existsSync(bundleRulesDir)) {
+    throw new Error("Bundle rules directory missing: " + bundleRulesDir);
+  }
+
+  const actions = [];
+  mkdirSync(targetRulesDir, { recursive: true });
+
+  for (const name of readdirSync(bundleRulesDir)) {
+    if (!name.endsWith(".mdc")) continue;
+    const src = join(bundleRulesDir, name);
+    let destPath = join(targetRulesDir, name);
+
+    if (rulesMode === "skip" && existsSync(destPath)) {
+      actions.push({ action: "skip", src, dest: destPath, reason: "exists" });
+      continue;
+    }
+
+    if (rulesMode === "prefix" && existsSync(destPath)) {
+      destPath = join(targetRulesDir, filePrefix + name);
+      if (existsSync(destPath)) {
+        actions.push({
+          action: "skip",
+          src,
+          dest: destPath,
+          reason: "prefixed target also exists",
+        });
+        continue;
+      }
+    }
+
+    if (dryRun) {
+      actions.push({ action: "would-copy", src, dest: destPath });
+      continue;
+    }
+
+    if (backup && existsSync(destPath)) {
+      copyFileSync(destPath, destPath + ".bak");
+    }
+    copyFileSync(src, destPath);
+    actions.push({ action: "copy", src, dest: destPath });
+  }
+
+  return actions;
+}
+
+export function readBundleAgents(bundleRoot) {
+  const p = join(bundleRoot, "AGENTS.md");
+  if (!existsSync(p)) {
+    throw new Error("Bundle AGENTS.md missing: " + p);
+  }
+  return readFileSync(p, "utf8");
+}

package/scripts/sync-bundle.mjs

@@ -0,0 +1,44 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..");
+
+/** Public npm bundle: generic template only (no monorepo paths or internal handoffs). */
+const publishDir = join(pkgRoot, "publish");
+const publishRulesDir = join(publishDir, "rules");
+const rulesDest = join(pkgRoot, "bundle", "rules");
+const agentsSrc = join(publishDir, "AGENTS.md");
+const agentsDest = join(pkgRoot, "bundle", "AGENTS.md");
+
+if (!existsSync(publishDir)) {
+  throw new Error("Missing publish template dir: " + publishDir);
+}
+if (!existsSync(publishRulesDir)) {
+  throw new Error("Missing publish/rules: " + publishRulesDir);
+}
+if (!existsSync(agentsSrc)) {
+  throw new Error("Missing publish/AGENTS.md: " + agentsSrc);
+}
+
+if (existsSync(rulesDest)) {
+  rmSync(rulesDest, { recursive: true });
+}
+mkdirSync(rulesDest, { recursive: true });
+for (const name of readdirSync(publishRulesDir)) {
+  if (!name.endsWith(".mdc")) continue;
+  copyFileSync(join(publishRulesDir, name), join(rulesDest, name));
+}
+
+const agentsBody = readFileSync(agentsSrc, "utf8");
+writeFileSync(agentsDest, agentsBody, "utf8");
+console.log("deuk-agent-rule: synced bundle from publish/ template.");

package/scripts/sync-oss.mjs

@@ -0,0 +1,78 @@
+/**
+ * Populates ../DeukAgentRulesOSS for the public GitHub repo.
+ * Run: cd deuk-agent-rule && npm run sync:oss
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..");
+const repoRoot = join(pkgRoot, "..");
+const ossRoot = join(repoRoot, "DeukAgentRulesOSS");
+const ossPublic = join(pkgRoot, "oss-public");
+
+/** Set DEUK_AGENT_RULES_OSS_REPO to override, e.g. https://github.com/you/DeukAgentRulesOSS */
+const OSS_REPO =
+  process.env.DEUK_AGENT_RULES_OSS_REPO || "https://github.com/joygram/DeukAgentRules";
+
+function gitBase() {
+  let u = OSS_REPO.trim().replace(/\.git$/i, "").replace(/\/$/, "");
+  if (!u.startsWith("http")) return u;
+  return u;
+}
+
+const base = gitBase();
+const gitUrl = base.startsWith("http") ? "git+" + base + ".git" : base;
+
+mkdirSync(join(ossRoot, "scripts"), { recursive: true });
+mkdirSync(join(ossRoot, "publish"), { recursive: true });
+
+cpSync(join(pkgRoot, "publish"), join(ossRoot, "publish"), { recursive: true, force: true });
+cpSync(join(pkgRoot, "scripts", "cli.mjs"), join(ossRoot, "scripts", "cli.mjs"), { force: true });
+cpSync(join(pkgRoot, "scripts", "merge-logic.mjs"), join(ossRoot, "scripts", "merge-logic.mjs"), {
+  force: true,
+});
+cpSync(join(pkgRoot, "scripts", "sync-bundle.mjs"), join(ossRoot, "scripts", "sync-bundle.mjs"), {
+  force: true,
+});
+
+if (!existsSync(ossPublic)) {
+  throw new Error("Missing oss-public/: " + ossPublic);
+}
+cpSync(join(pkgRoot, "README.md"), join(ossRoot, "README.md"), { force: true });
+cpSync(join(pkgRoot, "README.ko.md"), join(ossRoot, "README.ko.md"), { force: true });
+cpSync(join(ossPublic, "RELEASING.md"), join(ossRoot, "RELEASING.md"), { force: true });
+cpSync(join(ossPublic, "RELEASING.ko.md"), join(ossRoot, "RELEASING.ko.md"), { force: true });
+cpSync(join(ossPublic, "GITHUB_DESCRIPTION.md"), join(ossRoot, "GITHUB_DESCRIPTION.md"), {
+  force: true,
+});
+
+const srcPkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+const outPkg = {
+  ...srcPkg,
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: gitUrl,
+  },
+  bugs: {
+    url: base.startsWith("http") ? base + "/issues" : base,
+  },
+  homepage: base.startsWith("http") ? base + "#readme" : base,
+  files: ["LICENSE", "bundle/**/*", "scripts/**/*.mjs", "README.md", "README.ko.md"],
+};
+delete outPkg.private;
+if (outPkg.scripts && outPkg.scripts["merge:dry"]) {
+  const { "merge:dry": _md, ...r2 } = outPkg.scripts;
+  outPkg.scripts = r2;
+}
+if (outPkg.scripts && outPkg.scripts["sync:oss"]) {
+  const { "sync:oss": _drop, ...rest } = outPkg.scripts;
+  outPkg.scripts = rest;
+}
+
+writeFileSync(join(ossRoot, "package.json"), JSON.stringify(outPkg, null, 2) + "\n", "utf8");
+
+console.log("deuk-agent-rule: synced OSS tree at " + ossRoot);
+console.log("  Override repo URL: DEUK_AGENT_RULES_OSS_REPO=https://github.com/org/DeukAgentRulesOSS");