heymark 1.0.1

package/README.md

@@ -0,0 +1,220 @@
+# Heymark
+
+AI 코딩 도구의 컨벤션을 중앙에서 관리하고, 각 도구 형식으로 자동 변환하는 시스템.
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Tech Stack](#tech-stack)
+4. [Publishing](#publishing)
+5. [Integration](#integration)
+6. [Getting Started](#getting-started)
+7. [Tool Support](#tool-support)
+
+## Overview
+
+프로젝트마다 AI 도구별 규칙 파일을 따로 작성하면 관리가 파편화된다.
+이 시스템은 단일 진실 공급원(Single Source of Truth) 원칙에 따라, 한 곳에서 작성한 규칙을 여러 AI 도구 형식으로 자동 변환한다.
+규칙을 한 번만 작성하면 Cursor, Claude Code, GitHub Copilot, OpenAI Codex 등에서 즉시 사용할 수 있다.
+
+## Features
+
+- **단일 소스 관리**: 마크다운 파일 하나로 모든 AI 도구의 규칙 통합 관리
+- **자동 형식 변환**: 4종 AI 도구의 네이티브 형식으로 자동 변환 (YAML frontmatter, AGENTS.md 등)
+- **선택적 변환**: 특정 도구만 선택하여 변환 가능
+- **NPM 패키지 배포**: NPM registry를 통한 public 배포로 간편한 설치 및 버전 관리
+- **플러그인 구조**: 변환 모듈 추가만으로 새 도구 지원 확장
+
+## Tech Stack
+
+- **Runtime**: Node.js
+- **Language**: JavaScript
+- **Core**: File system API, YAML frontmatter parsing
+
+## Publishing
+
+패키지 관리자용 가이드 (일반 사용자는 [Integration](#integration) 참고).
+
+### 초기 설정 (한 번만)
+
+```bash
+# NPM 로그인
+npm login
+# Username: your-npm-username
+# Email: your-email@example.com
+```
+
+### 배포 프로세스
+
+```bash
+# 1. 규칙 수정 후 테스트
+node scripts/sync.js --preview
+
+# 2. 버전 업데이트 (자동으로 Git 태그 생성)
+npm version patch  # 또는 minor, major
+
+# 3. GitHub에 푸시
+git push --follow-tags  # 커밋과 태그를 함께 푸시
+
+# 4. NPM에 배포
+npm publish
+```
+
+**버전 관리:**
+
+- `patch` (1.0.0 → 1.0.1): 버그 수정, 오타 수정
+- `minor` (1.0.0 → 1.1.0): 새 규칙 추가, 기능 개선
+- `major` (1.0.0 → 2.0.0): 호환성 깨지는 변경
+
+**Git 태그 설명:**
+
+- `npm version` 명령어는 자동으로 Git 태그를 생성합니다
+- `git push --follow-tags`: 일반 커밋과 태그를 함께 푸시 (추천)
+- 또는 `git push && git push --tags`: 커밋 푸시 후 모든 태그 푸시
+
+## Integration
+
+### Installation
+
+```bash
+# 패키지 설치
+npm install --save-dev heymark
+```
+
+### 초기 설정 (규칙 소스 = 원격 GitHub 저장소)
+
+규칙은 **원격 GitHub 저장소(Public/Private)** 에서 읽습니다.  
+최초 1회만 설정하면 됩니다.
+
+```bash
+# 규칙 소스 설정 (프로젝트 루트에 .heymark.json 생성)
+npx heymark init <GitHub-저장소-URL>
+```
+
+예시:
+
+```bash
+# HTTPS (Private이면 Git credential/토큰 설정 필요)
+npx heymark init https://github.com/org/my-rules.git
+
+# SSH (Private 저장소 권장)
+npx heymark init git@github.com:org/my-rules.git
+
+# 저장소 안에서 .md가 하위 폴더에 있을 때
+npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
+```
+
+설정은 프로젝트 루트의 `.heymark.json`에 저장됩니다. 이후 `heymark` 실행 시 해당 저장소를 clone/pull 한 뒤 `.md` 파일들을 변환합니다.
+
+### Usage with npx
+
+설치 없이 바로 실행하거나, 설치 후 npx로 실행할 수 있습니다.  
+규칙은 **원격 GitHub 저장소**에서 가져오며, 해당 저장소 안의 마크다운 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
+
+```bash
+# .heymark.json에 설정된 외부 규칙 저장소에서 가져와 모든 도구 형식으로 변환 (기존 생성 파일 삭제 후 새로 생성)
+npx heymark
+
+# 이번에만 다른 외부 저장소 사용 (.heymark.json 무시)
+npx heymark --source https://github.com/org/other-rules.git
+
+# 특정 도구만 변환
+npx heymark -t cursor,claude
+
+# 미리보기 (파일 생성 없이 변환 결과만 확인)
+npx heymark --preview
+
+# 이전에 생성된 도구별 파일 삭제
+npx heymark --clean
+
+# 도움말
+npx heymark --help
+```
+
+**설치 없이 바로 사용:**
+
+```bash
+# 설치 없이 최신 버전으로 실행
+npx heymark@latest
+```
+
+**패키지 업데이트:**
+
+```bash
+npm update heymark
+npx heymark
+```
+
+**동작 방식:**
+
+- 기본적으로 기존 생성된 파일을 삭제한 후 새로 생성합니다
+- 이를 통해 이전 버전의 파일이 남지 않고 깔끔하게 동기화됩니다
+
+## Getting Started
+
+규칙을 작성하고 로컬에서 테스트하는 방법.
+
+### Writing Rules
+
+규칙 소스 디렉터리(외부 레포)에 마크다운 파일 작성. YAML frontmatter로 메타데이터 정의:
+
+```markdown
+---
+description: "AI assistant behavior guidelines"
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: true
+---
+
+# Rule Title
+
+Rule content...
+```
+
+### Local Testing
+
+```bash
+# 규칙 소스 설정 (최초 1회, GitHub 저장소 URL)
+node scripts/sync.js init https://github.com/org/my-rules.git
+
+# 모든 도구 형식으로 변환
+node scripts/sync.js
+
+# 이번에만 다른 저장소 사용
+node scripts/sync.js --source https://github.com/org/other-rules.git
+
+# 특정 도구만 변환
+node scripts/sync.js -t cursor,claude
+
+# 미리보기 (파일 생성 없이 확인)
+node scripts/sync.js --preview
+
+# 생성된 파일 삭제
+node scripts/sync.js --clean
+```
+
+## Tool Support
+
+### Supported Tools
+
+| Tool           | Output Format               | Key Features                    |
+| :------------- | :-------------------------- | :------------------------------ |
+| Cursor         | `.cursor/rules/*.mdc`       | YAML frontmatter, glob 매칭     |
+| Claude Code    | `.claude/skills/*/SKILL.md` | 스킬 디렉토리 구조              |
+| GitHub Copilot | `.github/instructions/*.md` | applyTo 패턴 매칭               |
+| OpenAI Codex   | `AGENTS.md`                 | 단일 파일 병합 (Agent Rules v1) |
+
+### Adding New Tools
+
+변환 모듈을 추가하면 자동 인식된다. 필수 export 인터페이스:
+
+```javascript
+module.exports = {
+    name: "Tool Name",
+    output: "output/path/pattern",
+    generate(rules, projectRoot) {
+        /* ... */
+    },
+    clean(ruleNames, projectRoot) {
+        /* ... */
+    },
+};
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "heymark",
+    "version": "1.0.1",
+    "description": "Centralized AI coding tool conventions with auto-conversion to multiple formats",
+    "main": "scripts/sync.js",
+    "bin": {
+        "heymark": "scripts/sync.js"
+    },
+    "scripts": {
+        "sync": "node scripts/sync.js",
+        "init": "node scripts/sync.js init",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "ai",
+        "coding",
+        "conventions",
+        "cursor",
+        "claude",
+        "copilot",
+        "codex",
+        "rules"
+    ],
+    "author": {
+        "name": "i2na",
+        "email": "yena.e121@gmail.com",
+        "url": "https://github.com/i2na"
+    },
+    "contributors": [
+        {
+            "name": "yezzero",
+            "email": "yeyeonggim06@gmail.com",
+            "url": "https://github.com/yezzero"
+        }
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "files": [
+        "scripts/",
+        "rules/",
+        "README.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/MosslandOpenDevs/heymark.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/rules/ai-behavior.md

@@ -0,0 +1,87 @@
+---
+description: "AI assistant behavior: surgical code changes, communication style, and commenting philosophy"
+alwaysApply: true
+---
+
+# AI Behavior
+
+## Code Modification
+
+- Modify **only** lines directly causing the problem; change the **minimum** required
+- **Never** refactor, reorganize, or reformat unrelated code
+- Maintain original file structure, patterns, and coding style
+- Implement only when **100% certain**; ask clarifying questions if insufficient context
+- Present multiple options with trade-offs when several valid solutions exist
+- Provide **full, exact code** for all changed lines
+- Use `// ... existing code` only for truly unchanged sections
+- Never use placeholders (`// TODO: implement`) or omit error handling
+- Favor clarity over cleverness; use early returns for error conditions
+
+## Commenting
+
+Code must be self-documenting. Add comments **only** with approved tags:
+
+| Tag             | Usage                                        |
+| :-------------- | :------------------------------------------- |
+| `@note`         | Critical context or non-obvious behavior     |
+| `@todo(owner):` | Future work with assigned owner (mandatory)  |
+| `@wip`          | Temporary code, remove before merge          |
+| `@deprecated`   | Marked for removal, must specify alternative |
+
+- English only, lowercase after tags, one line max
+- **Prohibited:** decorative separators (`// ===`, `// ---`), obvious statements, chatty explanations, uncommented dead code
+
+## Communication
+
+| Context                 | Language |
+| :---------------------- | :------- |
+| User-facing             | Korean   |
+| Code, comments, commits | English  |
+
+- **Tone:** Direct, concise. No filler, no hedging ("maybe", "possibly"), no pleasantries
+- **Structure:** Root cause (1-2 sentences) → Solution (code) → Reasoning (only if non-obvious)
+
+**Bad:** "안녕하세요! 도와드리겠습니다. 이 문제는 여러 원인이 있을 수 있는데..."
+**Good:** "`userId`가 `number | undefined`인데 `string`을 기대합니다. 타입 가드를 추가합니다."
+
+## Anti-Defensive Coding
+
+Write for the **expected successful flow**. Trust TypeScript compiler-enforced types. Let errors propagate naturally unless catching is required.
+
+**Avoid:**
+
+- Redundant null checks: `if (data && data.user && data.user.name)`
+- Unnecessary fallbacks: `const name = user?.name || "Unknown"`
+- Blanket try-catch around every function
+- Runtime type checks for TS-enforced types: `if (typeof id === 'number')`
+
+**Exceptions** — defensive code IS appropriate at:
+
+- Public API boundaries (user input, external API responses)
+- Security or financial operations
+- Known unreliable sources (legacy systems, third-party APIs)
+
+```typescript
+// ❌ Over-defensive
+function getUserEmail(userId: number): string {
+    try {
+        if (!userId || typeof userId !== "number") return "";
+        const user = database.getUser(userId);
+        if (!user || !user.email || typeof user.email !== "string") return "";
+        return user.email || "no-email@example.com";
+    } catch {
+        return "";
+    }
+}
+
+// ✅ Happy path
+function getUserEmail(userId: number): string {
+    return database.getUser(userId).email;
+}
+```
+
+## Decision Priority
+
+When rules conflict: **Security** > **User requirements** > **This guide** > **Language conventions** > **Preference**
+
+When uncertain: ask clarifying questions, state assumptions explicitly, admit knowledge gaps.

package/rules/code-conventions.md

@@ -0,0 +1,98 @@
+---
+description: "TypeScript and React naming conventions, file structure, and type patterns"
+globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx"
+alwaysApply: true
+---
+
+# TypeScript & React Conventions
+
+## File Naming
+
+| Type              | Convention               | Example                |
+| :---------------- | :----------------------- | :--------------------- |
+| Utility / Service | `kebab-case.ts`          | `user-service.ts`      |
+| React Component   | `PascalCase.tsx`         | `DashboardLayout.tsx`  |
+| CSS Module        | `PascalCase.module.scss` | `Button.module.scss`   |
+| Test              | `*.test.ts(x)`           | `user-service.test.ts` |
+| Type Definition   | `*.types.ts`             | `api.types.ts`         |
+| Constants         | `*.constants.ts`         | `routes.constants.ts`  |
+
+## Code Naming
+
+| Element        | Convention             | Example                  |
+| :------------- | :--------------------- | :----------------------- |
+| Variable       | `camelCase`            | `userName`, `isActive`   |
+| Function       | `camelCase`            | `getUserData()`          |
+| Constant       | `UPPER_SNAKE_CASE`     | `API_BASE_URL`           |
+| Private member | `_camelCase`           | `_internalCache`         |
+| Boolean        | `is/has/should` prefix | `isLoading`, `hasAccess` |
+| Component      | `PascalCase`           | `UserCard`               |
+| Hook           | `use` prefix           | `useAuth()`              |
+| HOC            | `with` prefix          | `withAuth()`             |
+| Event handler  | `handle` prefix        | `handleSubmit()`         |
+| Render helper  | `render` prefix        | `renderHeader()`         |
+
+## Types & Interfaces
+
+| Type       | Convention              | Example                     |
+| :--------- | :---------------------- | :-------------------------- |
+| Interface  | `I` + PascalCase        | `IUser`, `IApiResponse`     |
+| Type alias | `T` + PascalCase        | `TConfig`, `TRequestBody`   |
+| Enum       | `E` + PascalCase        | `EUserRole`, `EStatus`      |
+| Props      | ComponentName + `Props` | `ButtonProps`, `ModalProps` |
+| Generic    | Single uppercase        | `T`, `K`, `V`               |
+
+Usage: **Interface** → object shapes, **Type alias** → unions/intersections, **Enum** → fixed value sets (string values in `UPPER_CASE`)
+
+```typescript
+interface IUser {
+    id: number;
+    email: string;
+    role: EUserRole;
+}
+
+type TApiResponse<T> = TSuccessResponse<T> | TErrorResponse;
+
+enum EUserRole {
+    Admin = "ADMIN",
+    User = "USER",
+    Guest = "GUEST",
+}
+```
+
+- Avoid `any`; use `unknown` or generics
+- Explicit return types for public API functions
+- Use type guards for runtime narrowing
+
+## File Structure
+
+Import order (separate each group with a blank line):
+
+1. React / framework (`react`, `next`)
+2. External libraries (`axios`, `lodash`)
+3. Internal aliases (`@/components`, `@/hooks`)
+4. Relative imports (`./`, `../`)
+5. Type-only imports (`import type`)
+6. Styles (`.module.scss`)
+
+Within-file order: **Imports → Types → Constants → Private helpers → Public exports**
+
+## Component Pattern
+
+```typescript
+// Named function export (preferred over React.FC)
+export function UserCard({ userId }: UserCardProps) {
+    // 1. hooks
+    // 2. state (descriptive names: isLoading, userData — not loading, data)
+    // 3. effects (all deps in dependency array)
+    // 4. handlers (handleXxx)
+    // 5. render helpers (renderXxx)
+    // 6. return JSX
+}
+```
+
+## Formatting
+
+- Max **100 characters** per line
+- Prefer destructuring: `const { email, role } = user`
+- Optional chaining `?.` max 2 levels deep

package/rules/readme-writing.md

@@ -0,0 +1,69 @@
+---
+description: "README document writing guide: structure, style, and format conventions"
+globs: "README.md"
+alwaysApply: false
+---
+
+# README Writing Guide
+
+## Structure
+
+README는 다음 순서를 따른다:
+
+1. **Title** — 프로젝트를 대표하는 심플한 영어 이름
+2. **Intro** — 1-2줄 한국어 프로젝트 소개
+3. **Table of Contents** — 마크다운 테이블 형태
+4. **Overview** — 프로젝트 배경과 핵심 가치 (3-5문장)
+5. **Features** — 핵심 기능만 (추상적 설명 금지)
+6. **Tech Stack** — 핵심 기술만 (사소한 라이브러리 제외)
+7. **Getting Started** — 설치 및 실행 (최소 단계)
+
+## Format
+
+### Language
+
+- 제목, 소제목: **영어**
+- 본문: **한국어**
+- 코드, 명령어: 영어
+
+### Style
+
+- 이모지 금지
+- 장황한 설명 금지; 간결하고 공식적인 어조
+- 바뀌기 쉬운 파일명, 변수명, 경로는 언급하지 않음
+- HTML 태그 최소화
+
+### Table of Contents
+
+```markdown
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Tech Stack](#tech-stack)
+4. [Getting Started](#getting-started)
+```
+
+### Features
+
+- 실제로 **구분 가능한 대표 기능**만 나열
+- 각 기능은 한 줄 설명
+- 추상적 표현 금지: ~~"강력한 성능"~~, ~~"혁신적인 아키텍처"~~
+
+### Tech Stack
+
+- 프레임워크, 언어, 핵심 인프라만
+- 유틸 라이브러리, 개발 도구 제외
+- 테이블 또는 간단한 리스트
+
+### Getting Started
+
+- Prerequisites (필요 시만)
+- 설치 명령어 (코드 블록)
+- 실행 명령어 (코드 블록)
+
+## Anti-Patterns
+
+- 7개 이상 섹션의 장황한 README
+- 뱃지, 이모지, 장식적 요소
+- 추상적 기능 소개
+- 자주 변하는 파일명/변수명 언급
+- 불필요한 Contributing, License, Changelog 섹션

package/rules/research-workflow.md

@@ -0,0 +1,79 @@
+---
+description: "Technical research workflow for generating in-depth reports with web search and analysis"
+globs: ""
+alwaysApply: false
+---
+
+# Research Workflow
+
+Activate when user explicitly requests research ("research X", "investigate Y", "compare Z"). Not for simple coding questions, quick fact-checks, debugging, or routine implementation.
+
+## Principles
+
+- Base conclusions on **official docs, technical blogs, papers, whitepapers**
+- **Never** speculate or present assumptions as facts
+- Cite all sources with direct URLs
+- No emojis in research documents
+- Explain **how** things work, not just features; identify limitations and edge cases
+- Use clear technical language; avoid marketing language ("blazingly fast", "revolutionary")
+
+## Process
+
+### Phase 1: Multi-Angle Search (5+ queries)
+
+1. Official documentation (include version numbers and year)
+2. Technical comparisons and benchmarks
+3. Implementation guides and best practices
+4. Known issues and limitations
+5. Alternative solutions
+
+Start broad, narrow based on findings.
+
+### Phase 2: Deep Extraction
+
+Fetch full content of 3-5 critical URLs:
+- API specs, technical references
+- Architecture and system design docs
+- Benchmark data, performance analyses
+- Security advisories
+
+### Phase 3: Synthesis
+
+- Identify patterns and contradictions across sources
+- Evaluate trade-offs between approaches
+- Assess feasibility for the specific use case
+- Form architectural recommendations
+
+## Report Format
+
+```
+# [Topic]
+
+**Date:** YYYY-MM-DD
+**Scope:** [Brief description]
+**Key Finding:** [One sentence]
+
+## Executive Summary
+3-5 sentences: what, why, key findings, constraints.
+
+## [Thematic Sections]
+Organize by theme, not by source:
+- Technical Feasibility
+- Architecture Considerations
+- Performance Characteristics
+- Alternative Approaches
+
+## Conclusion
+Recommendations, next steps, risks/unknowns.
+
+## Sources
+1. [Title](URL) - Description
+```
+
+## Output
+
+- **Filename:** descriptive English, kebab-case (`redis-vs-memcached-comparison.md`)
+- **Location:** `/research/`, `/docs/research/`, or project root
+- **Format:** Markdown with code blocks, mermaid diagrams, comparison tables
+- **Language:** English, present tense, active voice, define acronyms on first use
+- Include minimal runnable code examples where relevant

package/rules/rule-writing.md

@@ -0,0 +1,71 @@
+---
+description: "Guide for creating rule documents: structure, token efficiency, and writing principles"
+globs: "rules/*.md"
+alwaysApply: false
+---
+
+# Rule Writing Guide
+
+Rules in `rules/` are consumed by AI coding assistants. Every token loads per request — **brevity is critical**.
+
+## Frontmatter
+
+```yaml
+---
+description: "One-line summary for AI relevance judgment"
+globs: "**/*.ts,**/*.tsx" # File patterns for auto-attachment (empty if N/A)
+alwaysApply: true # true = always loaded, false = conditional
+---
+```
+
+- `description`: AI가 자동 로딩 여부를 판단할 때 참조하는 요약
+- `globs`: 해당 파일 패턴 작업 시 자동 적용
+- `alwaysApply`: 항상 로드 여부
+
+## Structure
+
+1. **Title** (`# Rule Name`) — short, descriptive
+2. **Scope** (optional) — one sentence on when this rule activates
+3. **Sections** — organized by theme
+4. No redundant sections (stated rules should not be restated as checklists)
+
+## Writing Principles
+
+### Token Efficiency
+
+- Every line must be an **actionable instruction**
+- Remove meta-sentences: ~~"This rule defines how the AI should..."~~
+- Remove knowledge AI already possesses
+- **Tables** for mappings (most token-efficient format)
+- **Bullet lists** for constraints, not paragraphs
+- One code example per concept max; omit if a table already conveys it
+
+### Clarity
+
+- **Imperative voice:** "Use camelCase" not "You should use camelCase"
+- **Bold** key terms and constraints
+- Concrete examples over abstract descriptions
+- No hedging: use "always", "never", "must" — not "try to", "consider"
+
+### Completeness
+
+- Cover all conventions without redundancy
+- Include ✅/❌ examples only when the rule is counterintuitive
+- Add inline context only when the rule needs explanation
+
+## Anti-Patterns
+
+- Chatty introductions: ~~"Welcome! This document will help you..."~~
+- Redundant checklists restating earlier rules
+- Over-documenting _why_ a rule exists (unless non-obvious)
+- Emojis, excessive separators, decorative formatting
+- Stale references to specific file names or paths that change frequently
+
+## Quality Test
+
+A well-written rule document:
+
+- Can be followed by any AI without ambiguity
+- Contains **zero** filler sentences
+- Uses ≤50% tokens of a verbose equivalent
+- Handles edge cases inline, not in separate sections

package/scripts/lib/config.js

@@ -0,0 +1,62 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_FILENAME = ".heymark.json";
+
+/**
+ * rulesSource: GitHub 저장소 URL (https://github.com/org/repo 또는 git@github.com:org/repo.git)
+ * branch: 브랜치 (기본 main)
+ * rulesSourceDir: 저장소 내부에서 .md가 있는 하위 디렉터리 (기본 "" = 루트)
+ * @typedef {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} RuleBookConfig
+ */
+
+/**
+ * 프로젝트 루트에서 .heymark.json을 읽습니다.
+ * @param {string} projectRoot - 프로젝트 루트 (보통 process.cwd())
+ * @returns {RuleBookConfig | null}
+ */
+function loadConfig(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) return null;
+
+    try {
+        const raw = fs.readFileSync(configPath, "utf8");
+        const data = JSON.parse(raw);
+        if (!data || typeof data.rulesSource !== "string" || !data.rulesSource.trim()) {
+            return null;
+        }
+        return {
+            rulesSource: data.rulesSource.trim(),
+            branch: typeof data.branch === "string" && data.branch.trim() ? data.branch.trim() : "main",
+            rulesSourceDir: typeof data.rulesSourceDir === "string" ? data.rulesSourceDir.trim() : "",
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 초기 설정 파일을 생성합니다. (원격 GitHub 저장소 URL 사용)
+ * @param {string} projectRoot
+ * @param {RuleBookConfig} config - { rulesSource: repoUrl, branch?, rulesSourceDir? }
+ */
+function writeConfig(projectRoot, config) {
+    const configPath = path.join(projectRoot, CONFIG_FILENAME);
+    const toWrite = {
+        rulesSource: config.rulesSource,
+        branch: config.branch || "main",
+    };
+    if (config.rulesSourceDir) {
+        toWrite.rulesSourceDir = config.rulesSourceDir;
+    }
+    fs.writeFileSync(configPath, JSON.stringify(toWrite, null, 2), "utf8");
+    return configPath;
+}
+
+module.exports = {
+    CONFIG_FILENAME,
+    loadConfig,
+    writeConfig,
+};

package/scripts/lib/parser.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const GENERATED_MARKER = "<!-- @generated by sync-rules - DO NOT EDIT -->";
+
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) return { metadata: {}, body: content.trim() };
+
+    const metadata = {};
+    match[1].split(/\r?\n/).forEach((line) => {
+        const idx = line.indexOf(":");
+        if (idx === -1) return;
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            value = value.slice(1, -1);
+        }
+        if (value === "true") value = true;
+        else if (value === "false") value = false;
+        metadata[key] = value;
+    });
+
+    return { metadata, body: match[2].trim() };
+}
+
+function loadRules(rulesDir) {
+    if (!fs.existsSync(rulesDir)) {
+        console.error(`[Error] Rules directory not found: ${rulesDir}`);
+        console.error("  Ensure 'rules/' exists relative to the script location.");
+        process.exit(1);
+    }
+
+    const files = fs
+        .readdirSync(rulesDir)
+        .filter((f) => f.endsWith(".md"))
+        .sort();
+
+    if (files.length === 0) {
+        console.error(`[Error] No .md files found in: ${rulesDir}`);
+        process.exit(1);
+    }
+
+    return files.map((file) => {
+        const raw = fs.readFileSync(path.join(rulesDir, file), "utf8");
+        const { metadata, body } = parseFrontmatter(raw);
+        const baseName = path.basename(file, ".md");
+
+        return {
+            fileName: file,
+            name: metadata.name || baseName,
+            description: metadata.description || baseName,
+            globs: metadata.globs || "",
+            alwaysApply: metadata.alwaysApply === true,
+            metadata,
+            body,
+        };
+    });
+}
+
+function mergeRuleBodies(rules) {
+    return rules.map((r) => r.body).join("\n\n---\n\n");
+}
+
+function writeMergedFile(filePath, rules) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const content = `${GENERATED_MARKER}\n\n${mergeRuleBodies(rules)}\n`;
+    fs.writeFileSync(filePath, content);
+}
+
+module.exports = {
+    GENERATED_MARKER,
+    parseFrontmatter,
+    loadRules,
+    mergeRuleBodies,
+    writeMergedFile,
+};

package/scripts/lib/repo.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const CACHE_DIR_NAME = ".heymark-cache";
+
+/**
+ * 저장소 URL에서 캐시 폴더명으로 쓸 수 있는 문자열 추출
+ * https://github.com/org/repo -> org-repo
+ * git@github.com:org/repo.git -> org-repo
+ */
+function sanitizeRepoName(url) {
+    let s = url.trim();
+    if (s.endsWith(".git")) s = s.slice(0, -4);
+    const match = s.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\/|$)/) || s.match(/([^/]+\/[^/]+?)(?:\/|$)/);
+    if (match) {
+        return match[1].replace(/\//g, "-");
+    }
+    return s.replace(/[^a-zA-Z0-9._-]/g, "-") || "repo";
+}
+
+/**
+ * 원격 저장소를 clone 또는 pull하여, 규칙 .md가 있는 로컬 디렉터리 절대 경로를 반환합니다.
+ * Private repo는 사용자의 git 인증(SSH 키, credential)으로 접근해야 합니다.
+ * @param {string} projectRoot - 현재 프로젝트 루트
+ * @param {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} config
+ * @returns {string} - .md 파일이 있는 디렉터리의 절대 경로
+ */
+function getRulesDirFromRepo(projectRoot, config) {
+    const url = config.rulesSource;
+    const branch = config.branch || "main";
+    const subDir = config.rulesSourceDir || "";
+
+    const cacheBase = path.join(projectRoot, CACHE_DIR_NAME);
+    const repoName = sanitizeRepoName(url);
+    const clonePath = path.join(cacheBase, repoName);
+
+    if (!fs.existsSync(clonePath)) {
+        fs.mkdirSync(cacheBase, { recursive: true });
+        try {
+            execSync(`git clone --depth 1 --branch "${branch}" "${url}" "${clonePath}"`, {
+                stdio: "inherit",
+                cwd: projectRoot,
+            });
+        } catch (err) {
+            console.error("[Error] Failed to clone rules repository.");
+            console.error("  For private repos, ensure you have access (SSH key or HTTPS token).");
+            console.error("  Example: heymark init https://github.com/org/repo.git");
+            process.exit(1);
+        }
+    } else {
+        try {
+            execSync("git fetch origin && git checkout --quiet . && git pull --quiet origin " + branch, {
+                stdio: "pipe",
+                cwd: clonePath,
+            });
+        } catch (err) {
+            // pull 실패 시(네트워크 등) 기존 클론 내용으로 진행
+        }
+    }
+
+    const rulesDir = subDir ? path.join(clonePath, subDir) : clonePath;
+    if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) {
+        console.error(`[Error] Rules directory not found in repo: ${subDir || "(root)"}`);
+        process.exit(1);
+    }
+    return rulesDir;
+}
+
+module.exports = {
+    CACHE_DIR_NAME,
+    getRulesDirFromRepo,
+    sanitizeRepoName,
+};

package/scripts/sync.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadRules } = require("./lib/parser");
+const { CONFIG_FILENAME, loadConfig, writeConfig } = require("./lib/config");
+const { getRulesDirFromRepo } = require("./lib/repo");
+
+const SCRIPT_DIR = __dirname;
+const PROJECT_ROOT = process.cwd();
+
+function discoverTools() {
+    const toolsDir = path.join(SCRIPT_DIR, "tools");
+    const registry = {};
+
+    fs.readdirSync(toolsDir)
+        .filter((f) => f.endsWith(".js"))
+        .sort()
+        .forEach((file) => {
+            const key = path.basename(file, ".js");
+            registry[key] = require(path.join(toolsDir, file));
+        });
+
+    return registry;
+}
+
+function parseArgs(availableTools) {
+    const args = process.argv.slice(2);
+    const config = {
+        tools: Object.keys(availableTools),
+        clean: false,
+        preview: false,
+        help: false,
+        source: null,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (arg === "--tools" || arg === "-t") {
+            const val = args[++i];
+            if (!val) {
+                console.error("[Error] --tools requires a comma-separated list.");
+                process.exit(1);
+            }
+            config.tools = val.split(",").map((t) => t.trim().toLowerCase());
+        } else if (arg === "--clean" || arg === "-c") {
+            config.clean = true;
+        } else if (arg === "--preview" || arg === "-p") {
+            config.preview = true;
+        } else if (arg === "--source" || arg === "-s") {
+            const val = args[++i];
+            if (!val) {
+                console.error("[Error] --source requires a GitHub repository URL.");
+                process.exit(1);
+            }
+            config.source = val.trim();
+        } else if (arg === "--help" || arg === "-h") {
+            config.help = true;
+        } else {
+            console.error(`[Error] Unknown option: ${arg}`);
+            console.error("  Use --help for usage information.");
+            process.exit(1);
+        }
+    }
+
+    const invalid = config.tools.filter((t) => !availableTools[t]);
+    if (invalid.length > 0) {
+        console.error(`[Error] Unknown tool(s): ${invalid.join(", ")}`);
+        console.error(`  Available: ${Object.keys(availableTools).join(", ")}`);
+        process.exit(1);
+    }
+
+    return config;
+}
+
+function showHelp(tools) {
+    const toolLines = Object.entries(tools)
+        .map(([key, t]) => `  ${key.padEnd(10)} ${t.name.padEnd(16)} -> ${t.output}`)
+        .join("\n");
+
+    console.log(`
+AI Coding Tool Convention Sync
+
+Reads *.md from a GitHub repository (public or private) and generates
+tool-specific configuration files for various AI coding assistants.
+Same rules everywhere: A computer, B computer, same remote repo.
+
+Usage:
+  heymark init <repo-url>     Set rules source (creates ${CONFIG_FILENAME})
+  heymark [options]           Sync from configured or --source repo
+
+Options:
+  --source, -s <url>   GitHub repo URL for this run (overrides ${CONFIG_FILENAME})
+  --tools, -t <list>   Comma-separated tool names (default: all)
+  --clean, -c          Remove all generated files
+  --preview, -p        Preview what will be generated without writing
+  --help, -h           Show this help message
+
+Rules source (in order):
+  1. --source <repo-url>
+  2. ${CONFIG_FILENAME} (set via 'heymark init <repo-url>')
+  Private repos: use SSH (git@github.com:org/repo.git) or HTTPS with token.
+
+Available tools:
+${toolLines}
+
+Examples:
+  heymark init https://github.com/org/my-rules.git
+  heymark init https://github.com/org/my-rules.git --dir rules --branch main
+  heymark
+  heymark -s https://github.com/org/other-rules.git
+  heymark -t cursor,claude
+  heymark -c
+  heymark -p
+`);
+}
+
+function runInit(initArgs) {
+    const args = initArgs.slice(0);
+    const repoUrl = args[0];
+    if (!repoUrl || repoUrl.startsWith("--")) {
+        console.error("[Error] init requires a GitHub repository URL.");
+        console.error("  Example: heymark init https://github.com/org/my-rules.git");
+        console.error("  Example: heymark init git@github.com:org/my-rules.git");
+        console.error("  Optional: --branch <branch>  --dir <subdir>  (e.g. --dir rules)");
+        process.exit(1);
+    }
+    let branch = "main";
+    let rulesSourceDir = "";
+    for (let i = 1; i < args.length; i++) {
+        if ((args[i] === "--branch" || args[i] === "-b") && args[i + 1]) {
+            branch = args[++i].trim();
+        } else if ((args[i] === "--dir" || args[i] === "-d") && args[i + 1]) {
+            rulesSourceDir = args[++i].trim();
+        }
+    }
+    const config = { rulesSource: repoUrl.trim(), branch, rulesSourceDir };
+    const configPath = writeConfig(PROJECT_ROOT, config);
+    console.log(`[Init] Rules source saved to ${path.relative(PROJECT_ROOT, configPath) || configPath}`);
+    console.log(`  rulesSource: ${config.rulesSource}`);
+    if (branch !== "main") console.log(`  branch: ${branch}`);
+    if (rulesSourceDir) console.log(`  rulesSourceDir: ${rulesSourceDir}`);
+    console.log("");
+    console.log("Run 'heymark' to fetch rules from the repo and generate tool configs.");
+}
+
+function resolveRulesDir(config) {
+    const repoConfig = config.source
+        ? { rulesSource: config.source, branch: "main", rulesSourceDir: "" }
+        : loadConfig(PROJECT_ROOT);
+    if (!repoConfig) return null;
+    return getRulesDirFromRepo(PROJECT_ROOT, repoConfig);
+}
+
+function main() {
+    const args = process.argv.slice(2);
+    const subcommand = args[0];
+    if (subcommand === "init") {
+        runInit(args.slice(1));
+        return;
+    }
+
+    const tools = discoverTools();
+    const config = parseArgs(tools);
+
+    if (config.help) {
+        showHelp(tools);
+        return;
+    }
+
+    const RULES_SRC_DIR = resolveRulesDir(config);
+    if (!RULES_SRC_DIR) {
+        console.error("[Error] Rules source not set.");
+        console.error("  Run: heymark init <github-repo-url>");
+        console.error("  Example: heymark init https://github.com/org/my-rules.git");
+        console.error("  Or use: heymark --source <repo-url>");
+        process.exit(1);
+    }
+
+    const rulesRelPath = path.relative(PROJECT_ROOT, RULES_SRC_DIR) || ".";
+
+    console.log("[Sync] Starting convention sync...");
+    console.log(`  Source:  ${rulesRelPath} (from remote repo)`);
+    console.log(`  Target:  ${PROJECT_ROOT}`);
+    console.log(`  Tools:   ${config.tools.join(", ")}`);
+    console.log("");
+
+    const rules = loadRules(RULES_SRC_DIR);
+    console.log(`[Load] ${rules.length} rule(s): ${rules.map((r) => r.name).join(", ")}`);
+    console.log("");
+
+    if (config.clean) {
+        console.log("[Clean] Removing generated files...");
+        const ruleNames = rules.map((r) => r.name);
+        for (const key of config.tools) {
+            const cleaned = tools[key].clean(ruleNames, PROJECT_ROOT);
+            cleaned.forEach((p) => console.log(`  Deleted: ${p}`));
+        }
+        console.log("");
+        console.log(`[Done] Cleaned ${config.tools.length} tool(s) successfully.`);
+        return;
+    }
+
+    if (config.preview) {
+        console.log("[Preview] Would generate:");
+        for (const key of config.tools) {
+            const t = tools[key];
+            console.log(`  ${t.name.padEnd(16)} -> ${t.output} (${rules.length} rules)`);
+        }
+        return;
+    }
+
+    // Clean existing files before generating (for fresh sync)
+    console.log("[Clean] Removing existing generated files...");
+    const ruleNames = rules.map((r) => r.name);
+    for (const key of config.tools) {
+        const cleaned = tools[key].clean(ruleNames, PROJECT_ROOT);
+        if (cleaned.length > 0) {
+            cleaned.forEach((p) => console.log(`  Deleted: ${p}`));
+        }
+    }
+    console.log("");
+
+    console.log("[Generate]");
+    for (const key of config.tools) {
+        const t = tools[key];
+        const count = t.generate(rules, PROJECT_ROOT);
+        console.log(`  ${t.name.padEnd(16)} -> ${t.output} (${count} rules)`);
+    }
+
+    console.log("");
+    console.log(`[Done] ${config.tools.length} tool(s) synced successfully.`);
+}
+
+main();

package/scripts/tools/claude.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+module.exports = {
+  name: "Claude Code",
+  output: ".claude/skills/*/SKILL.md",
+
+  generate(rules, projectRoot) {
+    for (const rule of rules) {
+      const skillDir = path.join(projectRoot, ".claude", "skills", rule.name);
+      fs.mkdirSync(skillDir, { recursive: true });
+
+      const lines = [
+        "---",
+        `name: ${rule.name}`,
+        `description: "${rule.description}"`,
+        "---",
+      ];
+
+      const content = lines.join("\n") + "\n\n" + rule.body + "\n";
+      fs.writeFileSync(path.join(skillDir, "SKILL.md"), content);
+    }
+
+    return rules.length;
+  },
+
+  clean(ruleNames, projectRoot) {
+    const cleaned = [];
+
+    for (const name of ruleNames) {
+      const skillDir = path.join(projectRoot, ".claude", "skills", name);
+      if (fs.existsSync(skillDir)) {
+        fs.rmSync(skillDir, { recursive: true });
+        cleaned.push(path.join(".claude", "skills", name));
+      }
+    }
+
+    return cleaned;
+  },
+};

package/scripts/tools/codex.js

@@ -0,0 +1,24 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { writeMergedFile } = require("../lib/parser");
+
+module.exports = {
+  name: "OpenAI Codex",
+  output: "AGENTS.md",
+
+  generate(rules, projectRoot) {
+    writeMergedFile(path.join(projectRoot, "AGENTS.md"), rules);
+    return rules.length;
+  },
+
+  clean(_ruleNames, projectRoot) {
+    const filePath = path.join(projectRoot, "AGENTS.md");
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      return ["AGENTS.md"];
+    }
+    return [];
+  },
+};

package/scripts/tools/copilot.js

@@ -0,0 +1,48 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+module.exports = {
+  name: "GitHub Copilot",
+  output: ".github/instructions/*.instructions.md",
+
+  generate(rules, projectRoot) {
+    const destDir = path.join(projectRoot, ".github", "instructions");
+    fs.mkdirSync(destDir, { recursive: true });
+
+    for (const rule of rules) {
+      const globs = rule.globs
+        ? rule.globs.split(",").map((g) => g.trim())
+        : ["**"];
+
+      const applyToLines = globs.map((g) => `  - "${g}"`).join("\n");
+      const header = `applyTo:\n${applyToLines}\n---`;
+
+      const content = header + "\n\n" + rule.body + "\n";
+      fs.writeFileSync(
+        path.join(destDir, `${rule.name}.instructions.md`),
+        content
+      );
+    }
+
+    return rules.length;
+  },
+
+  clean(ruleNames, projectRoot) {
+    const cleaned = [];
+    const destDir = path.join(projectRoot, ".github", "instructions");
+
+    for (const name of ruleNames) {
+      const filePath = path.join(destDir, `${name}.instructions.md`);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        cleaned.push(
+          path.join(".github", "instructions", `${name}.instructions.md`)
+        );
+      }
+    }
+
+    return cleaned;
+  },
+};

package/scripts/tools/cursor.js

@@ -0,0 +1,41 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+module.exports = {
+  name: "Cursor",
+  output: ".cursor/rules/*.mdc",
+
+  generate(rules, projectRoot) {
+    const destDir = path.join(projectRoot, ".cursor", "rules");
+    fs.mkdirSync(destDir, { recursive: true });
+
+    for (const rule of rules) {
+      const lines = ["---", `description: "${rule.description}"`];
+      if (rule.globs) lines.push(`globs: "${rule.globs}"`);
+      lines.push(`alwaysApply: ${rule.alwaysApply}`);
+      lines.push("---");
+
+      const content = lines.join("\n") + "\n\n" + rule.body + "\n";
+      fs.writeFileSync(path.join(destDir, `${rule.name}.mdc`), content);
+    }
+
+    return rules.length;
+  },
+
+  clean(ruleNames, projectRoot) {
+    const cleaned = [];
+    const destDir = path.join(projectRoot, ".cursor", "rules");
+
+    for (const name of ruleNames) {
+      const filePath = path.join(destDir, `${name}.mdc`);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        cleaned.push(path.join(".cursor", "rules", `${name}.mdc`));
+      }
+    }
+
+    return cleaned;
+  },
+};