deuk-agent-rule 2.5.14 → 3.3.3

package/README.md

@@ -1,209 +1,174 @@
 <div align="center">
   <br />
-  <h1>DeukAgentRules</h1>
+  <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentRules Architecture" />
+  <br />
+  <h1>DeukAgentRules v3.3.3</h1>
   <p>
     <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/v/deuk-agent-rule.svg" alt="npm version" /></a>
     <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/dt/deuk-agent-rule.svg" alt="npm downloads" /></a>
   </p>
-  <p><b>High-Signal Encoding & Rule Standardization Engine</b></p>
+  <p><b>AI coding agent guardrails for every repo</b></p>
+  <p><i>Ticketed scope, verification, and memory for Codex, Copilot, Claude Code, Cursor, and more</i></p>
   <p>Part of the <a href="https://deukpack.app">Deuk Family</a> ecosystem.</p>
+  <p><a href="README.ko.md">한국어</a> · <a href="README.md">English</a></p>
 </div>
 
-> A core module of the **Deuk Family**. Maximizes collaboration efficiency of AI agents through structured rules.
+---
 
-**npm package:** `deuk-agent-rule` · **CLI:** `deuk-agent-rule`
+**DeukAgentRules** gives AI coding agents a shared way to work through tickets, scope contracts, verification, and durable project memory.
 
-**Korean:** [README.ko.md](https://github.com/joygram/DeukAgentRules/blob/master/README.ko.md)
+It is more than a prompt pack. It is a repository-level workflow layer that standardizes collaboration through the **Hub-Spoke Architecture** and a **Ticket-Driven Execution Model** while keeping `AGENTS.md`, Copilot instructions, Cursor rules, Claude skills, and related agent surfaces aligned.
 
-A **submodule-isolated collaborative framework** designed to be used alongside various coding agents such as Cursor, GitHub Copilot, Gemini / Antigravity, Claude, Windsurf, and JetBrains AI Assistant.
-It standardizes project rules (`AGENTS.md`, `.cursor/rules`) and strongly prevents wasteful prompt token consumption and AI context hallucination through a **ticket-based workflow**.
+Ticket management lives under `.deuk-agent/`, with active work tracked in `.deuk-agent/tickets/` and related docs, plans, and archive data kept alongside it.
 
-> **🚀 Core Value:**
-> Compresses the mandatory loaded context of approx. 1,500~2,000 tokens per session down to a mere 200~300 tokens. By isolating the AI to a specific **"Target Submodule"** using exact tickets (work orders), it prevents the AI from wandering through an entire monolithic repository.
+> **Current readiness:**
+> v3.3.3 is deployment-ready for agent-driven repositories. It is currently most reliable in **OpenAI Codex** and **GitHub Copilot** workflows. Cursor, Windsurf, Claude Code, and MCP remain supported through pointer-style integration, but they should be validated per workspace before rollout. MCP server registration is separate from `init`.
 
-### 📢 What's New in v2.4
-In the latest v2.4 release, the **Dynamic Rule Assembly Engine** has been introduced. The script automatically detects your project environment (e.g., DeukRag MCP integration) and injects only the necessary context-aware rules into `AGENTS.md`.
-The CLI ticketing system has also been upgraded: running `deuk-agent-rule ticket create` now automatically scaffolds design Plan documents and links them to the ticket, heavily reinforcing the Phase-based issue tracking workflow.
+> **Architecture foundation:**
+> We have officially deprecated monolithic `.cursorrules`. v3.0 introduces the **Hub-Spoke model** where `AGENTS.md` is the single source of truth, and IDE-specific rules act as thin entry-point pointers.
 
-> **💡 RAG Engine Integration Guide (Coming Soon)**
-> We are currently preparing an advanced integration manual and feature update. This will perfectly integrate these agent rules with our internal knowledge search engine **DeukRag (MCP)**, allowing your AI agent to automatically search past tickets and internal conventions to maximize its contextual awareness and problem-solving effectiveness!
+### 🗺️ Main Features & Architecture
 
----
+DeukAgentRules brings four core capabilities to day-to-day AI engineering:
 
-## 🛠️ Getting Started (Workspace Initialization)
+1. **Zero-Copy Hub-Spoke Architecture**
+   - **Hub**: `AGENTS.md` acts as the global single source of truth.
+   - **Spoke**: IDE-specific rules (like `.cursorrules`) or `PROJECT_RULE.md` act as thin pointers.
+   - **Benefit**: Eliminates rule duplication, preventing conflicting instructions and context hallucination across different IDEs (Cursor, Copilot, Windsurf).
 
-Since this CLI tool is used frequently across multiple repositories and submodules, a **global installation is highly recommended**.
+2. **Ticket-Driven Workflow (TDW)**
+   - Guides work through a clear lifecycle: Plan → Execute → Verify → Archive.
+   - Keeps changes connected to an active ticket in `.deuk-agent/tickets/`, so scope and progress stay visible.
 
-```bash
-npm install -g deuk-agent-rule
-deuk-agent-rule init
-```
+3. **Platform Co-existence & Mode-Aware Workflow Gate**
+   - Uses strong Agent Permission Contracts (APC) through a **Mode-Aware** workflow.
+   - In **Plan Mode**, agents focus on analysis and planning artifacts before moving into approved execution.
+   - Integrates with MCP Soft Gates to keep code changes aligned with the current ticket context.
 
-> [!NOTE]
-> **Global Install Permission Troubleshooting**:
-> - **Linux/macOS**: Running `npm install -g` may result in `EACCES` permission errors. It is highly recommended to use a Node version manager (`nvm`, `fnm`, etc.) to bypass these constraints. If using the system Node installation, you may unavoidably need to use `sudo npm install -g deuk-agent-rule`.
-> - **Windows**: If Node.js is installed in a system directory like `Program Files`, you must run your terminal (PowerShell/CMD) as an **Administrator** for the global installation to complete successfully.
+4. **Zero-Token Knowledge Distillation**
+   - When a ticket is archived, it is distilled into a zero-token summary and moved to `reports/`.
+   - These reports are vectorized into DeukAgentContext, building a permanent Engineering Memory Engine without cluttering the agent's active context window.
 
-### 💡 Why Global Installation?
+### Why Not Just Instructions?
 
-> [!WARNING]
-> **Submodule Local Installation STRICTLY FORBIDDEN**: Never install `deuk-agent-rule` locally (e.g., `npm install deuk-agent-rule`) inside your target consumer submodules. Doing so creates a "Local Trap" where `npx` prioritizes the outdated local `node_modules` over the globally installed latest version, leading to severe ticket formatting errors and logic mismatches.
+The agent tooling space already has useful building blocks: `AGENTS.md`, GitHub Copilot instructions, Cursor rules, Claude skills, agent launchers, and general LLM guardrail frameworks. DeukAgentRules is positioned one layer above plain instruction sync: it turns those surfaces into a ticketed repository workflow.
 
-1. **Preventing `npx` Cache & Local Trap Issues**: Running `npx deuk-agent-rule` relies on the local npm cache and `node_modules` resolution. If a stale version is present locally, it will silently hijack the execution. This has been proven to cause severe agent hallucinations or ticket formatting errors (e.g., missing hostname sequence IDs).
-2. **Execution Speed**: The chatbot agent receives instant CLI responses without the overhead of `npx` checking for temporary package downloads.
-3. **Cross-Repository Consistency**: It allows you to reliably apply the exact same version of the agent rules across various submodules and independent microservices in the Deuk Family ecosystem.
+| Similar approach | What it helps with | DeukAgentRules adds |
+|---|---|---|
+| `AGENTS.md` open format | A predictable instruction file for coding agents | Ticket lifecycle, phase gates, verification, and archiveable memory |
+| Copilot instructions / Cursor rules / Claude memory | Tool-specific guidance | One repo-owned workflow shared across agent clients |
+| Claude or Copilot custom agents and skills | Reusable task playbooks | Skills route into scoped, ticketed execution instead of replacing the workflow |
+| Agent launchers and harnesses | Running many coding agents from one place | Lifecycle control inside the repository, independent of the chosen agent |
+| General LLM/MCP guardrails | Runtime policy checks for AI systems | Developer-facing work orders, scope contracts, Git-visible history, and closeout evidence |
 
-Upon initialization, interactive questions will ask for the project's **tech stack** and **agent tools in use**. Based on your selections, optimized markdown templates and rule files (`.cursor/rules/*`) will be automatically generated and synchronized.
-- If you don't need to change the tech stack later, simply run `deuk-agent-rule init` to refresh the rules. (If not installed globally, you can fallback to `npx deuk-agent-rule init`).
-- Suppress interactive prompts in CI or script environments by appending the `--non-interactive` flag.
+Use DeukAgentRules when you want AI coding work to stay coordinated, reviewable, and easy to carry forward across sessions and teammates.
 
-### 🔄 Updating the Rules Package
-When a new version of the agent rules or templates is released, you can sync the latest instructions to your project by updating the package and re-running `init`.
-Since your previous configurations are saved (`.deuk-agent-rule.config.json`), using the `--non-interactive` flag will quietly and cleanly overwrite the obsolete rules with the latest ones without asking any questions.
-```bash
-npm install deuk-agent-rule@latest
-deuk-agent-rule init --non-interactive
-```
+### Better Together With Karpathy-Style Skills
 
-> [!TIP]
-> **💡 Troubleshooting: Legacy Version Migration Failures**
-> If you are migrating from a very old version and `init` repeatedly fails due to corrupted configurations or heavily modified template structures, the fastest fix is to perform a clean initialization using the `--clean` flag. **(This will not affect your existing tickets.)**
-> ```bash
-> deuk-agent-rule init --clean --interactive
-> ```
+Karpathy-style skills are great at improving how an agent behaves inside a task. DeukAgentRules is great at making that task ticketed, scoped, verified, and remembered at the repository level.
 
----
+Used together, skills can improve the quality of the move, while DeukAgentRules keeps the move connected to team workflow. The result is a better session and a better project record: behavior playbooks on the front end, ticket lifecycle and DeukAgentContext memory on the back end.
 
-## 🎯 The Ticket Workflow
-
-Running `deuk-agent-rule init` deploys a **zero-touch scaffolding sandbox** at your workspace root, spawning two essential directories:
-
-1. **`.deuk-agent-templates/` (Agent Templates)**: Houses the official blueprint (`TICKET_TEMPLATE.md`) dictating how AIs must process and report tasks. Committed alongside your source code to serve as the team's rulebook.
-2. **`.deuk-agent-ticket/` (Ticket Execution Space)**: The covert space where volatile instructions (`TICKET-XXX.md`) are exchanged between agents and workers. (Automatically hidden by `.gitignore` to prevent security leaks and repository bloat).
-
-### 💡 Workflow Overview
-```mermaid
-%%{init: {"flowchart": {"htmlLabels": false}, "themeCSS": ".node text { fill: #ffffff !important; stroke: none !important; }"} }%%
-graph TD
-    classDef action fill:#2563eb,stroke:#1d4ed8,stroke-width:2px,color:#ffffff;
-    classDef phase fill:#475569,stroke:#334155,stroke-width:2px,color:#ffffff;
-    classDef decision fill:#d97706,stroke:#b45309,stroke-width:2px,color:#ffffff;
-    classDef highlight fill:#dc2626,stroke:#b91c1c,stroke-width:2px,color:#ffffff;
-
-    A(Step 1: Ticket Creation):::action --> B(Step 2: Agent Execution):::phase
-    B --> C(Step 3: Verification & Closure):::phase
-    
-    C --> D{Issues Found?}:::decision
-    
-    D -->|Yes| E(MANDATORY Follow-up Chaining):::highlight
-    E --> F(Step 4: Archiving):::action
-    D -->|No| F
-```
+### What's Next
 
-The optimal **4-Step AI Coding Sequence** utilizing these sandbox folders is as follows.
+The next step is to make this workflow even easier to see and adopt: clearer first-run checks, compact CLI/RAG reminders for agents, stronger README/npm positioning, and companion surfaces that show active ticket, phase, open-ticket count, and DeukAgentContext memory status without asking teams to switch coding agents.
 
-### [Step 1] Ticket Creation & Submodule Isolation
-Do not issue scattered, unbounded commands to your AI. Narrowing the **context** via a clear ticket is strictly required to prevent astronomical costs and accidental code corruption.
+### 📚 Detailed Documentation
+| Doc | Purpose |
+|---|---|
+| [docs/architecture.md](docs/architecture.md) | High-level system structure and visual infographics |
+| [docs/how-it-works.md](docs/how-it-works.md) | Detailed CLI mechanics, initialization lifecycle, and file roles |
+| [docs/principles.md](docs/principles.md) | Design philosophy: Hub-Spoke, Zero-Legacy, and Source Sovereignty |
+| **Korean Docs** | [README.ko.md](README.ko.md) · [docs/architecture.ko.md](docs/architecture.ko.md) |
 
-```bash
-deuk-agent-rule ticket create --topic ui-refactoring --group frontend --project DeukUI
-```
-This command instantly creates a templated `TICKET-ui-refactoring.md` file within the `.deuk-agent-ticket/` directory.
+---
 
-> [!IMPORTANT]
-> **Filling the Ticket (CRITICAL)**: The newly created ticket already contains **YAML Front Matter** (`--- id: ... ---`). **DO NOT** overwrite the entire file when adding your plan. ALWAYS append your content below the header or use partial file editing to preserve the existing YAML metadata. Erasing the Front Matter corrupts the ticketing system.
+## 🛠️ Installation & Setup
 
-The developer must simply specify the exact isolated directory path (e.g., `src/client`) inside the `[Target Submodule]` attribute at the top of the generated file.
+### 1. Global Installation (Standard User)
+To prevent `npx` cache issues and "Local Traps", a global installation is strictly required.
 
-### [Step 2] Agent Execution & Handoff (Ticket Session)
-Provide a single line of instruction to your AI chatbot (Cursor, Gemini, etc.):
-> *"Open the recently issued `.deuk-agent-ticket/TICKET-ui-refactoring.md` ticket and strictly follow the checklist within the specified target submodule."*
+```bash
+npm install -g deuk-agent-rule
+deuk-agent-rule init
+```
 
-The AI will faithfully read the defined Phases in the ticket and write optimized code while **completely blocking out unnecessary computations for unrelated server logic or sibling modules**. (This mechanism drastically reduces token costs).
+### 2. Local Source Development (Maintainer/Power User)
+v3.0 introduces a **Global CLI Proxy**. If you are developing inside the `DeukAgentRules` workspace, the global command will automatically delegate execution to your local source.
 
-### [Step 3] Status Review & Closure
-As the AI writes the code, it will simultaneously update the markup checkboxes (`[x]`) inside the ticket. If the agent's session memory limit is approaching, simply leave the ticket file saved, turn off the chat window, open a fresh session, and issue [Step 2] again. The handoff (session transfer) is seamlessly completed.
-Once all steps are accomplished, promote the Phase status to `[Phase Complete]`. Instead of manually typing terminal commands, **you can simply tell your AI chatbot via natural language prompt: "Show me the list of active tickets" or "Archive the completed tickets with reports"**, and the AI will autonomously invoke the CLI to manage them for you.
 ```bash
-deuk-agent-rule ticket list
-```
-```text
-#  STATUS   SUBMODULE   GROUP       PROJECT     CREATED                  TITLE
-1  [ ]      DeukPack    sub         global      2026-04-18T13:34:32.484Z naming-consistency
+cd ~/workspace/DeukAgentRules
+sudo npm link
+deuk-agent-rule init  # Routes to local scripts/cli.mjs automatically
 ```
 
-### [Step 4] Ticket Verification (Self-Correction)
-After all phases are marked as `[x]`, you should issue a final command to the AI:
-> *"Proceed with **Ticket Verification** for this task."*
+If you primarily work in Codex or Copilot, this is the recommended day-to-day setup. Those clients currently have the smoothest behavior with the hub-spoke and ticket-driven workflow.
 
-The AI, following the strictly defined **[TICKET VERIFICATION RULE]** in `AGENTS.md`, will then autonomously perform a 3-stage audit:
-1. **Side Effect Analysis**: Detecting potential build warnings or broken dependencies.
-2. **Convention Audit**: Re-verifying if filenames and classes perfectly match project architecture documents.
-3. **Potential Issue Reporting**: Listing breaking changes or unverified edge cases (e.g., native build constraints).
+---
 
-This final step ensures that the agent's output is not just "functional" but "production-grade" and architecturally sound.
+## 🎯 The Protocol Workflow
 
----
+The workflow is governed by a **Ticket-Driven Execution Contract**.
 
-## 🤖 AI Agent Prompting Guide
+1. **Scaffolding**: `init` deploys `.deuk-agent/templates/` and `AGENTS.md` (or local pointers like `PROJECT_RULE.md`).
+2. **Ticketing (Plan Phase)**: `ticket create --topic feature-x` generates a bounded work order in `.deuk-agent/tickets/`. During this phase, agents operate in **Plan Mode** and are restricted from mutating files.
+3. **Execution (Execute Phase)**: Once authorized, the AI agent reads the ticket, locks onto the **Target Submodule**, and executes code changes. MCP Soft Gates ensure that unauthorized modifications are blocked.
+4. **Verification**: The agent performs a side-effect audit and convention (e.g., DC-DUP) check before closure.
+5. **Archiving (Archive Phase)**: Completed tickets undergo Zero-Token Knowledge Distillation and move to `reports/` to build the **Engineering Memory Engine** via DeukAgentContext.
 
-Even after installing and initializing the package, some AI agents (Cursor, Gemini, etc.) might not actively read the rule file (`AGENTS.md`) in a fresh session. **Whenever you start a new chat session, copy and paste the following prompts to force the AI to align with the rules. This effectively eliminates hallucination and accidental scope-creep.**
+---
+
+## ⚙️ CLI Reference
 
-### 1. Force Rule Familiarization (Mandatory)
-> *"Before starting any work, please read the `AGENTS.md` (DeukAgentRules) file at the workspace root from top to bottom. Make sure you fully understand your Identity, the core project rules, and the ticket workflow. Once you have read and understood them, do NOT summarize them; simply reply 'Rules Acknowledged' and await my first instruction."*
+Delegate these to your AI agent via natural language prompts!
 
-### 2. Ticket Execution (Recommended)
-> *"Open the recently issued `.deuk-agent-ticket/TICKET-XXX.md` ticket. Restrict all your file exploration, analysis, and modifications STRICTLY to the target submodule path explicitly specified in the ticket. Do not wander into other submodules or accidentally modify unrelated files."*
+| Command | Description / Example Prompt |
+|--------|------|
+| `deuk-agent-rule init` | Synchronizes the rule Hub and Spoke pointers. <br>💬 *"Initialize project rules"* |
+| `deuk-agent-rule ticket create` | Issues a new execution contract. Use `--summary` plus `--plan-body` for a one-pass Phase 1 ticket. <br>💬 *"Create ticket: refactor-ui with filled APC"* |
+| `deuk-agent-rule ticket list` | Displays active work orders. <br>💬 *"Show active tickets"* |
+| `deuk-agent-rule ticket archive` | Securely stores completed work. <br>💬 *"Archive ticket 068"* |
+| `deuk-agent-rule skill list` | Shows first-party thin skills such as `safe-refactor`, `generated-file-guard`, and `context-recall`. |
+| `deuk-agent-rule skill add --skill safe-refactor` | Installs a skill into the local registry without changing the TDW/APC authority model. |
+| `deuk-agent-rule skill expose --platform claude` | Exposes installed skills as platform-specific thin wrappers. Supported MVP platforms: `claude`, `cursor`. |
+| `deuk-agent-rule skill lint` | Audits skill files for duplicate workflow contracts and unsafe generated-file guidance. |
+
+### Ticket File Git Hygiene
+
+- Treat `.deuk-agent/tickets/**/*.md` and `INDEX*.json` as CLI-managed lifecycle artifacts.
+- Do not commit a ticket body without the related index updates. The next session can restore the wrong active/archive state.
+- After `ticket create` fails, do not create or repair ticket files manually.
+- Do not flip ticket status by editing frontmatter directly. Use `ticket move`, `ticket close`, or `ticket archive`.
+- `telemetry.jsonl` is usually operational log noise, so it is better left out of normal code commits unless your repo intentionally tracks it.
+- When possible, commit completed work after `ticket archive` so the active/archive transition lands in one history step.
+
+For more day-to-day examples, see [docs/how-it-works.md](docs/how-it-works.md).
 
 ---
 
-## ⚙️ CLI Reference & Advanced Options
+## Related Ideas & Inspiration
 
-Advanced commands for workflow automation and target control.
+DeukAgentRules shares the same concern as guideline-first projects like
+[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills):
+AI coding agents often over-assume, over-engineer, and edit outside the requested scope.
 
-> [!NOTE]
-> **For Package Maintainers/Contributors Only - Local Development**:
-> This does not apply to general users. If you are modifying the `DeukAgentRules` source code and need to immediately test local patches bypassing the globally cached `npx deuk-agent-rule`, explicitly invoke `node ./scripts/cli.mjs`.
-> - **Linux/macOS**: Creating symlinks (`npm link`) may require `sudo` privileges. Direct script execution (`./scripts/cli.mjs`) may trigger `chmod +x` permission issues, making explicit `node` invocation the safest workaround.
-> - **Windows**: `npm link` requires Administrator rights (or Developer Mode) to create symlinks, and PowerShell execution policies may block `.cmd` wrapper scripts. Explicitly calling `node ./scripts/cli.mjs` safely bypasses these OS-level restrictions.
+Where prompt-level guideline files improve agent behavior inside one client,
+DeukAgentRules adds a repository-level workflow layer: tickets, phase gates,
+scoped permissions, verification, and archiveable engineering memory.
 
-### Ticket-based Commands
-Instead of manually typing the CLI commands below into the terminal, you can **delegate their execution to your AI chatbot by giving natural language prompt instructions**.
+The first-party skill MVP keeps that boundary explicit: skills are short
+`SKILL.md` playbooks for recurring failure patterns, while `core-rules/AGENTS.md`
+remains the workflow authority. Use `skill add` and `skill expose` to make those
+playbooks visible to Claude or Cursor without copying the full rule contract.
 
-| Command | Description / Natural Language Prompt Example |
-|--------|------|
-| `deuk-agent-rule ticket create ...` | Generates a new ticket document (accepts `--group`, `--project`, `--submodule`) <br>💬 *"Create new ticket (topic: refactor)"* |
-| `deuk-agent-rule ticket list` | Lists and displays active tickets (`--archived`, `--all`, `--json` supported) <br>💬 *"Ticket list"* |
-| `deuk-agent-rule ticket use --latest ...` | Returns only the file path of the most recent ticket <br>💬 *"Recent ticket path"* |
-| `deuk-agent-rule ticket close ...` | Soft-closes a target ticket by locking its status to completed without moving the file <br>💬 *"Close this ticket"* |
-| `deuk-agent-rule ticket upgrade` | Migrates legacy ticket structures to V2 (YAML FM) and triggers submodule DEFRAG <br>💬 *"Upgrade tickets to v2"* |
-| `deuk-agent-rule ticket archive ...` | Securely moves completed tickets to `archive/` and updates INDEX <br>💬 *"Archive this ticket (attach report)"* |
-| `deuk-agent-rule ticket reports` | Lists structurally preserved agent work reports (`reports/`) <br>💬 *"List archived reports"* |
-
-### Advanced Init Options
-| Flag | Default | Description |
-|--------|--------|------|
-| `--non-interactive` | Off | For CI/Scripts. Disables interactive UI and adopts existing `.config.json` |
-| `--interactive` | Off | Forces the interactive setup to reappear even if config already exists |
-| `--clean` | Off | Deletes legacy templates and configs before initializing |
-| `--cwd <path>` | Current dir | Adjust target workspace root (absolute/relative path) |
-| `--dry-run` | Off | Simulates the execution text in the console without generating/altering files |
-| `--backup` | Off | Safely creates `*.bak` copies of `AGENTS.md` and rule files before overwriting |
-
-## 📦 Release & Changelog Policy
-
-Before pushing any core updates, system templates, or feature changes to this package (`DeukAgentRules`), you must strictly follow this procedure to bump the version safely:
-
-1. **Apply Changes**: Complete documentation and rule script updates, then `git add` and `git commit` (Conventional Commits format recommended, e.g., `feat: ...`, `fix: ...`).
-2. **Version Bump & Automated Changelog**:
-   * Patch (Bug fixes): `npm run bump:patch`
-   * Minor (New features): `npm run bump:minor`
-   * Major (Core/Breaking changes): `npm run bump:major`
-   
-   Executing the bump command will trigger the `commit-and-tag-version` pipeline: it bumps the version in `package.json`, auto-generates the `CHANGELOG.md` log, creates a release commit, and applies the release tag.
-3. **Synchronize & Mirror (OSS Sync)**: As a final step, ask your agent to run `npm run sync:oss`. The automation script will clean the release assets and push the bundled versions to the mirror repository (`DeukAgentRulesOSS`).
+```bash
+npx deuk-agent-rule init
+npx deuk-agent-rule skill list
+npx deuk-agent-rule skill add --skill safe-refactor
+npx deuk-agent-rule skill expose --platform claude
+```
 
 ---
 
-### 🏷️ Keywords for NPM & GitHub Search
-`#cursorrules` `#copilot-instructions` `#ai-agents` `#deuk-agent` `#mcp` `#rag` `#windsurf` `#cline` `#llm-workflow` `#productivity` `#prompt-engineering` `#developer-tools`
+### 🏷️ Keywords
+`#AI-Orchestration` `#Agentic-Workflow` `#DeukFamily` `#Engineering-Intelligence` `#Zero-Legacy` `#High-Signal-Coding` `#AI-Protocol` `#CursorRules` `#CopilotInstructions` `#ClaudeCode` `#ClaudeMD` `#AgentsMD` `#AgentSkills` `#CodingAgent` `#AI-Guardrails` `#LLM-Control-Plane`

package/docs/architecture.ko.md

@@ -0,0 +1,34 @@
+# 아키텍처 (v3.0)
+
+DeukAgentRules v3.0은 AI 에이전트 워크플로우의 절대적인 일관성과 효율성을 보장하기 위해 **Hub-Spoke 아키텍처**와 **Global Execution Proxy**를 도입했습니다.
+
+## 1. Zero-Copy Hub-Spoke 아키텍처
+
+v3 모델에서 저장소 루트의 **`AGENTS.md`**는 전역적인 **Global Hub**(단일 진실 공급원, SSoT) 역할을 하며, 프로젝트 최상단의 **`PROJECT_RULE.md`**는 로컬 오버라이드를 담당하는 **Local Hub** 역할을 합니다.
+IDE별 규칙 파일(예: `.cursor/rules/*.mdc`)은 규칙 내용을 복사하지 않고 이 허브들을 가리키는 **Spoke**(최소한의 진입점) 역할만 수행하는 Zero-Copy 방식을 사용합니다.
+
+![Hub-Spoke 아키텍처](assets/architecture-v3.png)
+
+### 핵심 원칙
+- **SSoT (Single Source of Truth)**: 모든 범용 운영 규칙은 `AGENTS.md`에 정의되며, 프로젝트 특화 규칙은 `PROJECT_RULE.md`에만 작성됩니다.
+- **경량 Spoke (Zero-Copy)**: IDE 규칙은 내용을 중복해서 담지 않으며, 에이전트가 절대 경로(Absolute Path) 포인터를 통해 Hub를 읽도록 유도합니다.
+- **Zero-Legacy**: `init` 명령은 구세대(v1/v2)의 잔재를 물리적으로 제거하여 깨끗한 상태를 유지합니다.
+- **온라인 RAG 전용**: DeukAgentContext는 로컬 캐시나 또 다른 진실 공급원이 아니라 온라인 보조 기억 계층으로만 사용합니다.
+- **아카이브 보존**: 완료된 작업은 archive/knowledge로 옮겨 활성 context를 작고 최신 상태로 유지합니다.
+
+## 2. Global CLI Proxy (Kind: Src)
+
+`npx` 사용 시 발생하는 '스테일 타르볼(Stale Tarball)' 문제를 해결하기 위해 v3.0은 **Global Proxy**를 구현했습니다.
+
+### 작동 원리:
+1. `npx deuk-agent-rule` 실행 시, 패키지의 글로벌 엔트리 포인트(`bin/deuk-agent-rule.js`)가 구동됩니다.
+2. 현재 디렉터리와 상위 디렉터리를 스캔하여 **로컬 워크스페이스 소스**(`DeukAgentRules/scripts/cli.mjs`)를 자동으로 찾습니다.
+3. 소스가 발견되면 모든 명령을 로컬 소스로 **투명하게 위임(Routing)**합니다.
+4. 이를 통해 에이전트가 레지스트리의 캐시된 버전이 아닌, 현재 개발 중인 최신 로컬 규칙을 항상 사용하도록 보장합니다.
+
+## 3. 초기화 생명주기 (Init Lifecycle)
+
+1. **`migrateLegacyStructure`**: 이전 세대의 디렉터리 구조를 정리하거나 이름을 변경합니다.
+2. **`cleanSubmoduleStubs`**: 빈 서브모듈 스텁과 `.gitmodules`의 고립된 항목을 찾아 제거합니다.
+3. **`deploySpokePointers`**: Hub를 가리키는 경량 Spoke 파일들을 생성합니다.
+4. **`Smart Backup`**: 레거시 `.cursorrules`를 분석하여 사용자 커스텀 규칙이 있을 경우에만 `.bak`을 생성합니다.

package/docs/architecture.md

@@ -0,0 +1,33 @@
+# Architecture (v3.0)
+
+DeukAgentRules v3.0 introduces a **Hub-Spoke Architecture** and a **Global Execution Proxy** to ensure absolute consistency and efficiency in AI-agent workflows.
+
+## 1. Zero-Copy Hub-Spoke Architecture
+
+In the v3 model, **`AGENTS.md`** acts as the global **Hub** (the single source of truth), while **`PROJECT_RULE.md`** serves as the **Local Hub** for project-specific overrides. IDE-specific rule files (e.g., `.cursor/rules/*.mdc`) act as **Spokes** (thin entry points) that use absolute path pointers instead of duplicating rules (Zero-Copy).
+
+![Hub-Spoke Architecture](assets/architecture-v3.png)
+
+### Core Principles
+- **SSoT (Single Source of Truth)**: All operational rules are defined in `AGENTS.md`, and project-specific contexts go into `PROJECT_RULE.md`.
+- **Lightweight Spokes (Zero-Copy)**: IDE rules do not duplicate content; they use absolute paths to point the agent to the Hubs.
+- **Zero-Legacy**: The `init` command aggressively purges obsolete v1/v2 configurations.
+- **Online RAG Only**: DeukAgentContext is used as an online advisory memory layer, not as a local cache or alternate source of truth.
+- **Archive Preservation**: Completed work should move into archive/knowledge so the active context stays small and current.
+
+## 2. Global CLI Proxy (Kind: Src)
+
+To solve the "Stale Tarball" problem common with `npx`, v3.0 implements a **Global Proxy**.
+
+### How it works:
+1. When you run `npx deuk-agent-rule`, the package's global entry point (`bin/deuk-agent-rule.js`) is executed.
+2. It automatically scans the current directory and its parents for a **Local Workspace Source** (`DeukAgentRules/scripts/cli.mjs`).
+3. If found, it **transparently routes** all commands to the local source.
+4. This ensures that agents always use the latest, uncommitted local rules instead of a cached version from the registry.
+
+## 3. Initialization Lifecycle
+
+1. **`migrateLegacyStructure`**: Renames or cleans up old directory patterns.
+2. **`cleanSubmoduleStubs`**: Identifies and removes empty submodule stubs and orphans in `.gitmodules`.
+3. **`deploySpokePointers`**: Generates the thin Spoke files pointing to the Hub.
+4. **`Smart Backup`**: Analyzes legacy `.cursorrules` and creates `.bak` only if custom user rules are detected.

package/docs/how-it-works.ko.md

@@ -0,0 +1,52 @@
+# 작동 원리 (How It Works)
+
+DeukAgentRules는 **AI 엔지니어링 오케스트레이션 프로토콜**로 작동합니다. 중앙 집중식 규칙 허브와 고성능 CLI를 사용하여 에이전트가 코드베이스를 인식, 분석 및 수정하는 방식을 조정합니다.
+
+## 1. Hub-Spoke 실행 모델
+
+v3.0에서 규칙 파일은 더 이상 거대하고 독립적인 형태가 아닙니다. 컨텍스트 팽창을 최소화하기 위해 **Hub-Spoke** 모델을 사용합니다.
+
+- **Hub (`AGENTS.md`)**: 전역적으로 적용되는 중앙 프로젝트 규칙 정본 문서입니다.
+- **Local Hub (`PROJECT_RULE.md`)**: 각 워크스페이스 또는 프로젝트에 특화된 로컬 규칙을 정의하여 전역 허브를 오버라이드합니다.
+- **Spoke (`.cursor/rules/*.mdc` 등)**: 에이전트에게 허브 문서를 읽으라고 지시하는 최소한의 진입점 포인터입니다.
+- **이유**: 이를 통해 에이전트는 서로 다른 IDE 환경에서도 중복이나 오류 없이 항상 최신의 통합된 규칙을 볼 수 있습니다.
+
+## 2. Global CLI Proxy
+
+CLI(`deuk-agent-rule`)는 **소스 주권(Source Sovereignty)** 메커니즘을 사용합니다.
+
+- `npx deuk-agent-rule` 실행 시, 현재 디렉터리 내에 프로젝트 소스 코드가 포함된 워크스페이스가 있는지 확인합니다.
+- 로컬 소스가 감지되면, 실행을 글로벌 바이너리가 아닌 **로컬 스크립트로 라우팅**합니다.
+- 이를 통해 개발 중에 커밋되지 않은 최신 규칙을 에이전트가 즉시 사용할 수 있도록 보장합니다.
+
+## 3. 초기화 생명주기 (Initialization Lifecycle)
+
+`deuk-agent-rule init` 실행 시 다음 과정이 차례로 수행됩니다:
+
+1. **레거시 제거 (Legacy Purge)**: v1/v2 시절의 구형 설정 파일들을 물리적으로 제거합니다.
+2. **서브모듈 진공 청소 (Submodule Vacuum)**: 빈 서브모듈 디렉터리 스텁과 `.gitmodules`의 고립된 항목들을 정리합니다.
+3. **스마트 백업 (Smart Backup)**:
+   - 레거시 파일(`.cursorrules` 등)을 분석합니다.
+   - 사용자 커스텀 규칙이 발견되면 `*.bak` 파일을 생성합니다.
+   - 시스템 생성 내용만 있다면 파일을 즉시 삭제합니다.
+4. **허브 동기화 (Hub Sync)**: 최신 `AGENTS.md`를 배포하고 지원되는 모든 에이전트를 위한 경량 Spoke 파일들을 생성합니다.
+
+## 4. 저장소 역할 및 파일 구조
+
+| 경로 | 역할 |
+|---|---|
+| `AGENTS.md` | 주권적 전역 규칙 허브 (단일 진실 공급원) |
+| `PROJECT_RULE.md` | 로컬 프로젝트 특화 규칙 오버라이드 |
+| `.deuk-agent/config.json` | 프로젝트별 초기화 상태 정보 |
+| `.deuk-agent/tickets/` | 제한된 실행 계약서 (작업 지시서) |
+| `.deuk-agent/templates/` | 티켓 및 플랜 작성을 위한 표준화된 청사진 |
+| `bin/deuk-agent-rule.js` | 글로벌 실행 프록시 |
+
+## 5. 엄격한 Phase 기반 티켓 워크플로우 (TDW)
+
+1. **티켓 발행 (Phase 1)**: `ticket create` 또는 기존 티켓 선택을 통해 타겟 범위를 정의합니다. `--summary`와 `--plan-body`를 함께 써서 채워진 Phase 1 본문을 한 번에 넣고, placeholder 반복을 막고 싶다면 `--require-filled`를 붙입니다. `ticket next`가 진행 가능한 티켓을 찾지 못하면, 후속 티켓을 만들기 전에 최근 git history를 먼저 분석합니다.
+2. **APC 및 메인 티켓 기록**: 에이전트는 코드를 수정하기 전, 메인 티켓에 명시된 APC(Agent Permission Contract)의 `[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`을 채웁니다. 티켓은 스코프/계약/라이프사이클 체크/실행 계획/검증 결과를 맡고, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 계획 문구에 섞으면 안 됩니다.
+3. **검토 게이트**: 이슈/회귀 보고는 Phase 1 이후 멈춥니다. 사용자가 티켓 계획을 검토한 뒤 실행을 승인해야 하며, 원래 이슈 문장의 "수정", "해결" 같은 표현만으로 검토를 건너뛰면 안 됩니다.
+4. **Phase 승급**: Phase 1 계획이 검토 가능하고 사용자가 실행을 승인하면 `ticket move` 명령을 호출하여 Phase 2 (Execute)로 승급합니다.
+5. **실행 및 검증 (Phase 2)**: 격리된 경계 내에서 코드를 수정하고 검증을 수행합니다.
+6. **지식 증류 아카이빙**: 작업 완료 후 `archive` 시, 핵심 정보만 추출(Zero-Token Distillation)하여 장기 엔지니어링 메모리로 보관합니다.

package/docs/how-it-works.md

@@ -0,0 +1,71 @@
+# How It Works
+
+DeukAgentRules operates as an **AI Engineering Orchestration Protocol**. It coordinates how agents perceive, analyze, and modify your codebase using a centralized rule hub and a high-performance CLI.
+
+## 1. Hub-Spoke Execution Model
+
+In v3.0, rule files are no longer monolithic. We use a **Hub-Spoke** model to minimize context bloat.
+
+- **Global Hub (`AGENTS.md`)**: The central canonical project rule document.
+- **Local Hub (`PROJECT_RULE.md`)**: Project-specific rules that override or augment the global hub.
+- **Spokes (`.cursor/rules/*.mdc`, etc.)**: Minimal entry points that tell the agent to read the Hubs.
+- **Why**: This ensures the agent always sees the latest rules without duplication errors across different IDEs.
+
+## 2. Global CLI Proxy
+
+The CLI (`deuk-agent-rule`) uses a **Source Sovereignty** mechanism.
+
+- When you run `npx deuk-agent-rule`, the binary checks if you are inside a workspace containing the project's source code.
+- If a local source is detected, it **routes execution** to the local script.
+- This ensures that your agents are always using the latest uncommitted rules during development.
+
+## 3. Initialization Lifecycle
+
+Running `deuk-agent-rule init` triggers the following lifecycle:
+
+1. **Legacy Purge**: Physically removes old v1/v2 configuration files.
+2. **Submodule Vacuum**: Cleans up empty submodule directory stubs and orphaned entries in `.gitmodules`.
+3. **Smart Backup**:
+   - Analyzes legacy files (like `.cursorrules`).
+   - If user-added custom rules are found, it creates a `*.bak` file.
+   - If only system-generated content is found, it deletes the file.
+4. **Hub Sync**: Deploys the latest `AGENTS.md` and generates thin Spokes for all supported agents.
+
+## 4. Repository Roles & Files
+
+| Path | Role |
+|---|---|
+| `AGENTS.md` | The Sovereign Rule Hub (Canonical truth) |
+| `PROJECT_RULE.md` | Local project-specific rule overrides |
+| `.deuk-agent/config.json` | Project-specific initialization state |
+| `.deuk-agent/tickets/` | Bounded execution contracts (Work orders) |
+| `.deuk-agent/templates/` | Standardized blueprint for tickets and plans |
+| `bin/deuk-agent-rule.js` | The Global Execution Proxy |
+
+## 5. Strict Phase-Driven Workflow (TDW)
+
+1. **Issue Ticket (Phase 1)**: `ticket create` or an existing ticket defines the target scope. Use `--summary` plus `--plan-body` to place a filled Phase 1 body directly inside the ticket, and prefer `--require-filled` when you want placeholder tickets to fail fast instead of looping. If `ticket next` finds no active/open ticket, inspect recent git history before creating a follow-up ticket.
+2. **APC and Main Ticket Record**: Before modifying code, the agent fills the APC (Agent Permission Contract) blocks `[BOUNDARY]`, `[CONTRACT]`, and `[PATCH PLAN]` inside the main ticket. The main ticket owns scope, contract, lifecycle checks, execution planning, and verification outcomes. Never move execution logs, command transcripts, completion summaries, or verification results into planning prose.
+3. **Review Gate**: Issue/regression reports stop after Phase 1. The user reviews the ticket plan before execution; wording such as "fix" or "resolve" in the original issue is not approval to skip review.
+4. **Phase Transition**: After the Phase 1 plan is reviewable and the user approves execution, run `ticket move` to transition to Phase 2 (Execute).
+5. **Execute & Verify (Phase 2)**: Changes are made and verified within the isolated boundary.
+6. **Knowledge Distillation Archive**: When archiving, core information is extracted (Zero-Token Distillation) to save context tokens for long-term memory.
+
+## 6. Ticket Files in Git
+
+Ticket files are part of the repository workflow, but they should not be handled like ordinary handwritten notes.
+
+- Commit `.deuk-agent/tickets/INDEX*.json` together with the related ticket markdown changes. Leaving index updates behind can break state restoration in the next session.
+- Treat ticket markdown under `.deuk-agent/tickets/**/*.md` as CLI-owned artifacts. If `ticket create` fails, do not create or repair the file manually.
+- Editing ticket body content is fine while planning, but lifecycle state changes should go through `ticket move`, `ticket close`, and `ticket archive`, not direct frontmatter edits.
+- `telemetry.jsonl` is typically operational output rather than durable project state. Unless your repository intentionally tracks it, keep it out of ordinary code commits.
+- Prefer committing finished work after `ticket archive` so the ticket file move and archive index update stay in the same Git change.
+- When reviewing Git changes, first ask whether each ticket-related diff came from an expected CLI lifecycle step. If not, reconcile with CLI commands before committing.
+
+Useful quick checks:
+
+```bash
+git status --short
+git diff -- .deuk-agent/tickets/INDEX.json
+git diff -- .deuk-agent/tickets/INDEX.archive.*.json
+```

package/docs/principles.ko.md

@@ -0,0 +1,68 @@
+# 원칙 (Principles)
+
+이 원칙들은 **DeukAgentRules**가 추구하는 "AI 엔지니어링 오케스트레이션 프로토콜"의 설계를 규정합니다.
+
+## 1. Zero-Copy Hub-Spoke 아키텍처 (SSoT)
+
+문서와 규칙 시스템은 단일 진실 공급원(Single Source of Truth)을 가져야 하며, 불필요한 규칙 복제를 피해야 합니다.
+
+- **Global Hub**: `AGENTS.md`는 모든 정본 규칙을 포함합니다.
+- **Local Hub**: `PROJECT_RULE.md`는 프로젝트에 특화된 규칙을 정의합니다.
+- **Spoke (Zero-Copy)**: IDE별 규칙 파일은 절대 경로 포인터 역할만 수행합니다.
+- **이유**: IDE마다 규칙이 복제되고 파편화되면 에이전트의 행동이 일관성을 잃고 예측 불가능해집니다.
+
+## 2. Zero-Legacy 정책
+
+더 이상 사용되지 않는 구조를 물리적으로 제거하여 저장소의 청결을 유지합니다.
+
+- **이유**: 레거시 `.cursorrules`나 스테일한 서브모듈 스텁은 에이전트를 혼란스럽게 하고 컨텍스트 윈도우를 낭비합니다.
+- **메커니즘**: `init` 실행 시 디프리케이션 마커와 빈 스텁을 무조건적으로 청소합니다.
+
+## 3. Kind Src (소스 주권)
+
+배포된 바이너리보다 로컬 개발 소스를 우선시합니다.
+
+- **이유**: npm 등에 배포된 패키지는 로컬의 최신 규칙 업데이트를 즉시 반영하지 못할 때가 많습니다.
+- **메커니즘**: Global CLI Proxy는 로컬에 `scripts/cli.mjs`가 존재할 경우 `npx` 명령을 해당 소스로 자동 위임합니다.
+
+## 4. Smart Backup (사용자 규칙 보호)
+
+시스템 생성 파일의 노이즈는 제거하되, 사람이 작성한 소중한 콘텐츠는 존중합니다.
+
+- **이유**: 사용자가 생성된 파일 하단에 직접 커스텀 룰을 추가하는 경우가 많습니다.
+- **메커니즘**: 순수 시스템 블록만 포함된 파일만 삭제하며, 그 외의 경우에는 `*.bak`으로 백업을 생성합니다.
+
+## 5. 엄격한 Phase 기반 워크플로우 (TDW)
+
+에이전트의 실행은 반드시 티켓과 Phase에 의해 제한되어야 합니다.
+
+- **이유**: 경계가 없는 AI 에이전트는 불필요한 파일을 탐색하며 토큰을 낭비하고 범위를 벗어난 수정을 시도합니다.
+- **메커니즘**: Phase 1에서 티켓을 발행하거나 기존 티켓을 선택하고 APC(Agent Permission Contract)를 채웁니다. 계획은 메인 티켓의 compact plan에만 둡니다. 진행 가능한 티켓이 없을 때는 후속 티켓을 만들기 전에 최근 git history를 분석합니다. 티켓은 스코프, 계약, 라이프사이클 체크, 검증 결과를 맡고, 계획 문구에는 진행 체크박스, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 두지 않습니다.
+
+## 6. 변조 전 설계 (Plan Before Mutation)
+
+상태 변화가 일어나기 전에 설계가 명시적으로 선행되어야 합니다.
+
+- **이유**: 실제 코드나 설정 파일이 수정되기 전에 의도와 범위가 기록되어야 합니다. 티켓/계획 문서 자체는 기록물이며, 중복 티켓을 만들기 위한 승인 장벽이 아닙니다.
+- **메커니즘**: 코드를 작성하기 전 티켓의 APC 블록(`[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`)을 채웁니다. APC는 경계와 계약만 담습니다. 진단이나 접근 선택의 근거는 메인 티켓의 compact plan에 두고, 실행 기록의 목적지로 쓰지 않습니다.
+
+## 7. RAG를 보완하는 문서화
+
+안정적인 원칙과 동적인 지식은 함께 작동해야 합니다.
+
+- **Docs**: 안정적인 운영 모델과 가정들을 설명합니다.
+- **RAG (DeukAgentContext)**: 엔지니어링 메모리와 과거의 결정사항들을 온라인 MCP 계층을 통해서만 동기화합니다.
+- **이유**: 로컬 파일이 진실의 원천이고, RAG는 보조 기억이며, archive가 장기 이력을 보존해야 활성 context가 꼬이지 않습니다.
+
+## 8. 아카이브 보존
+
+아카이브는 선택 사항이 아니라 필수 생명주기 층입니다.
+
+- **이유**: 살아 있는 context는 작고 최신이어야 하며, 완료된 작업은 archive/knowledge로 옮겨야 활성 컨텍스트가 오염되지 않습니다.
+- **메커니즘**: ticket archive와 지식 증류를 통해 완료된 작업을 active loop에서 분리하고, 결과물을 장기 참조 자료로 유지합니다.
+
+## 9. 한/영 정합성 (Bilingual Parity)
+
+한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.
+
+- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.