npm - deuk-agent-rule - Versions diffs - 2.2.1 → 2.3.1 - Mend

deuk-agent-rule 2.2.1 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/CHANGELOG.md +177 -132
package/LICENSE +0 -0
package/README.ko.md +103 -79
package/README.md +102 -77
package/bundle/.cursorrules +7 -7
package/bundle/AGENTS.md +70 -87
package/bundle/rules/delivery-and-parallel-work.mdc +26 -26
package/bundle/rules/git-commit.mdc +24 -18
package/bundle/rules/multi-ai-workflow.mdc +0 -1
package/bundle/templates/MODULE_RULE_TEMPLATE.md +24 -0
package/bundle/templates/TICKET_TEMPLATE.md +40 -0
package/package.json +5 -3
package/scripts/changelog-polish.mjs +0 -0
package/scripts/cli-args.mjs +11 -0
package/scripts/cli-init-commands.mjs +27 -2
package/scripts/cli-init-logic.mjs +4 -0
package/scripts/cli-prompts.mjs +17 -45
package/scripts/cli-ticket-commands.mjs +206 -52
package/scripts/cli-ticket-logic.mjs +322 -46
package/scripts/cli-utils.mjs +64 -1
package/scripts/cli.mjs +20 -6
package/scripts/merge-logic.mjs +0 -0
package/scripts/sync-bundle.mjs +0 -0
package/scripts/sync-oss.mjs +3 -10
package/README.ko.pdf +0 -0

package/README.md CHANGED Viewed

@@ -1,123 +1,148 @@
 <div align="center">
   <br />
   <h1>DeukAgentRules</h1>
-  <p>High-Signal Encoding & Rule Standardization Engine</p>
+  <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>Part of the <a href="https://deukpack.app">Deuk Family</a> ecosystem.</p>
 </div>
-<div align="center">
-  <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/v/deuk-agent-rule.svg?color=black&style=flat-square" alt="NPM Version" /></a>
-  <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/dm/deuk-agent-rule.svg?color=blue&style=flat-square" alt="NPM Downloads" /></a>
-  <a href="https://github.com/joygram/DeukAgentRules"><img src="https://img.shields.io/github/stars/joygram/DeukAgentRules.svg?style=flat-square&color=orange" alt="GitHub Stars" /></a>
-  <a href="https://github.com/joygram/DeukAgentRules/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/deuk-agent-rule.svg?style=flat-square" alt="License" /></a>
-  <br /><br />
-  <a href="https://github.com/joygram/DeukAgentRules/blob/master/README.ko.md">한국어 (Korean)</a>
-</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`
-## Abstract
+**Korean:** [README.ko.md](https://github.com/joygram/DeukAgentRules/blob/master/README.ko.md)
-DeukAgentRules defines a project-agnostic rule architecture for AI engineering agents (Cursor, GitHub Copilot, Gemini/Antigravity, Claude, Windsurf, JetBrains AI). It separates persistent workflow memory from session context, reducing recurring prompt loads per session.
+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**.
-> Why DeukAgentRules?
-> The Ticket-First Workflow reduces recurring context loads into a single focused topic file per session, enabling handovers between different AI tools without re-explaining the repository.
+> **🚀 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.
 ---
-## Quick Start
+## 🛠️ Getting Started (Workspace Initialization)
-Initialize the rule system and set up the local workspace in one step:
+Install and initialize the package once at the project root.
 ```bash
+npm install deuk-agent-rule
 npx deuk-agent-rule init
 ```
-- Interactive Setup: On the first run, the CLI guides you to select your primary stack and the AI agents you use. (See the System Selection Guide for a detailed list of available stacks and tools).
-- Safe Updates: Subsequent runs safely append necessary templates without touching your custom extensions. Use --interactive to reconfigure.
+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 `npx deuk-agent-rule init` to refresh the rules.
+- Suppress interactive prompts in CI or script environments by appending the `--non-interactive` flag.
----
-## The Ticket-First Workflow
+### 🔄 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
+npx deuk-agent-rule init --non-interactive
+```
-Multiple AI agents share context through a single Markdown ticket, reducing per-session prompt overhead.
+---
-### The 6-Phase Workflow
+## 🎯 The Ticket Workflow
-| Phase | Actor | Action |
-|---|---|---|
-| 1. Explore & Plan | Reasoning AI | Analyze codebase, propose implementation plan |
-| 2. Decide | User | Review and approve the plan |
-| 3. Ticket (Registration) | Reasoning AI | Write approved plan to .deuk-agent-ticket/ |
-| 4. Execute | IDE Agent | Read ticket, code strictly within scope |
-| 5. Post-Test Risk Analysis | IDE Agent | Mandatory artifact risk analysis after testing |
-| 6. Report & Close | User + Agent | Review risk report, then npx deuk-agent-rule ticket close --latest |
+Running `npx 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).
-### Detailed Workflow Walkthrough
+The optimal **3-Step AI Coding Sequence** utilizing these sandbox folders is as follows.
-Phase 1: Explore & Plan
-```
-[User]   "Analyze storage module"
-[Agent]  (Analyzes codebase, proposes direction)
-[User]   "Plan and design for the analyzed content."
-[Agent]  (Saves ticket to .deuk-agent-ticket/main/storage-20260406.md)
-```
+### [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.
-Phase 2: Execution & Verification
-```
-[User]   "Proceed" (or "Proceed with [Ticket #]")
-[Agent]  (Reads the ticket, implements changes, self-checks, and reports)
-[User]   "Verify issues, defects, and potential errors."
-[Agent]  (Runs tests, confirms compliance and finds defects)
+```bash
+npx 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.
-### Keyword-Based Prompt Examples
+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.
-| Intent | Keyword Input |
-|---|---|
-| Analysis | Analyze [Topic/Module] |
-| Plan | Plan and design for the analyzed content. |
-| Proceed | Proceed [Ticket #] (or latest if omitted) |
-| Verify | Verify issues, defects, and potential errors. |
-| Check | /ticket |
+### [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."*
----
+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).
-### CLI Reference (Optional)
+### [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.
+To track tickets manually from the terminal, run:
 ```bash
-npx deuk-agent-rule ticket create --topic login-api --project MyProject --content "## Task: ..."
 npx deuk-agent-rule ticket list
-npx deuk-agent-rule ticket close --latest
 ```
-(Ticket Tutorial: docs/ticket-tutorial.md)
+```text
+📦 Agent Tickets (Direct System Scan):
+  ✅ [TICKET-DEUKUI-Button.md]
+     Title: Add Button Component
+     Target: DeukUI
+     Status: [Complete]
+  🔨 [TICKET-ui-refactoring.md]
+     Title: Plugin UI Refactoring
+     Target: DeukUI
+     Status: [In Progress]
+```
 ---
-## Architecture & Configuration (How It Works)
+## 🤖 AI Agent Prompting Guide
-The CLI supports advanced parameters for CI environments and explicit structural control, utilizing a non-destructive injection mechanism to avoid user conflicts.
-For a detailed technical overview of how we safely sandbox injected rules, see the How It Works Guide (docs/how-it-works.md).
+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.**
-### Core Configuration
+### 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."*
-| Flag | Purpose |
-|------|---------|
-| --non-interactive | CI/Headless mode; applies defaults/saved config without prompting |
-| --tag <id> | Overrides the default marker region (<!-- <id>:begin -->) |
-| --agents inject | Smart injection into existing AGENTS.md (or skip, overwrite) |
-| --rules prefix | Updates .cursor/rules via intelligent file prefixing |
+### 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."*
 ---
-## License & Ecosystem
-Part of the DeukPack Ecosystem. Licensed under Apache-2.0.
-For issues, contributions, and community discussions, visit the GitHub Repository (https://github.com/joygram/DeukAgentRules).
+## ⚙️ CLI Reference & Advanced Options
+Advanced commands for workflow automation and target control.
+### 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**.
+| Command | Description / Natural Language Prompt Example |
+|--------|------|
+| `npx deuk-agent-rule ticket create ...` | Generates a new ticket document (accepts `--group`, `--project`, `--submodule`) <br>💬 *"Create new ticket (topic: refactor)"* |
+| `npx deuk-agent-rule ticket list` | Lists and displays active tickets (`--archived`, `--all`, `--json` supported) <br>💬 *"Ticket list"* |
+| `npx deuk-agent-rule ticket use --latest ...` | Returns only the file path of the most recent ticket <br>💬 *"Recent ticket path"* |
+| `npx deuk-agent-rule ticket close ...` | Soft-closes a target ticket by locking its status to completed without moving the file <br>💬 *"Close this ticket"* |
+| `npx deuk-agent-rule ticket upgrade` | Migrates legacy ticket structures to V2 (YAML FM) and triggers submodule DEFRAG <br>💬 *"Upgrade tickets to v2"* |
+| `npx deuk-agent-rule ticket archive ...` | Securely moves completed tickets to `archive/` and updates INDEX <br>💬 *"Archive this ticket (attach report)"* |
+| `npx 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 |
+| `--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`).

package/bundle/.cursorrules CHANGED Viewed

@@ -1,7 +1,7 @@
-# Cursor — AGENTS.md is authoritative
-You MUST read and strictly follow the workflows, rules, and ticket formats defined in AGENTS.md at the repository root before writing or modifying any code. If AGENTS.md is not yet in your context for this task, open it and use it.
-Precedence: Repository root AGENTS.md defines project rules (structure, constraints, tickets). .cursor/rules/*.mdc files add editor-specific behavior (for example token discipline and multi-tool handoff). If anything conflicts, follow AGENTS.md for project facts and tickets.
-Do not assume stacks or repo layouts (microservices, api-gateway, OpenAPI-only workflows) unless they appear in this repository and AGENTS.md.
+# Cursor — AGENTS.md is authoritative
+You MUST read and strictly follow the workflows, rules, and ticket formats defined in AGENTS.md at the repository root before writing or modifying any code. If AGENTS.md is not yet in your context for this task, open it and use it.
+Precedence: Repository root AGENTS.md defines project rules (structure, constraints, tickets). .cursor/rules/*.mdc files add editor-specific behavior (for example token discipline and multi-tool handoff). If anything conflicts, follow AGENTS.md for project facts and tickets.
+Do not assume stacks or repo layouts (microservices, api-gateway, OpenAPI-only workflows) unless they appear in this repository and AGENTS.md.

package/bundle/AGENTS.md CHANGED Viewed

@@ -1,87 +1,70 @@
-# Project Agent Rules
-## Identity & Highest Priority
-Senior software engineer. Correctness, minimal diffs, safety.
-HIGHEST PRIORITY: Agents MUST NEVER use expressions that emphasize dramatic effects or imply absolute completeness/perfection when writing any document or ticket. Keep all output strictly factual, calm, and dry.
-HARD RULE: Never use Markdown word emphasis (bold **, italic *, etc.) in any generated content. Keep the text uniformly plain.
-## Definitive Workflow (Explore -> Decide -> Execute)
-1. Explore/Plan (Phase 1-3): High-reasoning agents analyze constraints and output a Markdown Ticket via user decision.
-2. Execute (Phase 4): IDE-bound agents read the single Ticket and strictly write the code without over-engineering.
-3. Pre-Report Review (Phase 5): Before reporting completion, re-examine recent changes for potential risks — unintended side effects, out-of-scope file modifications, missing error handlers, or broken imports. Document any identified risk before reporting; do not suppress it.
-4. Verify & Close (Phase 6): Test execution results. If verified, close the ticket (npx deuk-agent-rule ticket close). If failed, revert to Phase 1.
-- Priority Ticket Generation: When encountering a new issue or scope creep, explicitly create a fresh Ticket before coding to prevent context window degradation.
-- Slash Commands & Selection UI: Recognize /ticket [keyword] to query active tickets. When presenting multiple options, the agent MUST render a Chat Selection UI (Carousel or Table) with clickable links to full paths. Do not simply output text or CLI instructions.
-## Communication (Tone & Style)
-- Strict Tone Constraints: Calm, Senior, Analytical, High-Signal.
-- No Exaggeration (Crucial): Absolutely no sensational language, fake satisfaction, or overly cheerful filler. State facts and results dryly. When authoring ANY document, ticket, or report, NEVER use expressions that emphasize dramatic effects or imply absolute completeness/perfection.
-- HARD RULE: No Markdown word emphasis (bold, italic) in any communication or documentation.
-- Korean Language Preference: When conversing in Korean, use concise polite endings (-요 style) rather than rigid declarative or formal military styles (-다/까 style). Keep it professional but accessible.
-## 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.
-## Delivery, portfolio, and parallel work
-- Prefer one PR or session outcome = one vertical slice: integrated, buildable, and demo-able for that slice unless the user explicitly requests a broad-only refactor.
-- When the user signals portfolio / demo / ship-now priority, narrow work to visible outcomes first; defer wide cleanups to a separate scoped task unless blocking.
-- Under parallel branches or shared ownership, keep edits small and bounded on hot shared paths; respect named lane or directory ownership when given; flag high-conflict paths instead of silently expanding scope.
-- Default to minimal refactor: satisfy the task with the smallest structural change; split optional large refactors into a follow-up ticket instead of bundling them.
-## IDE Branding
-No editor or vendor tool branding in code, docs, README, commits, or published artifacts.
-## Ticket 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]
-```
-## Ticket persistence (internal implementation docs)
-Default local directory: npx deuk-agent-rule init creates .deuk-agent-ticket/ at the repo root and appends it to .gitignore so persisted tickets are not committed by default. Remove or adjust that ignore rule if your team versions tickets in git.
-When a ticket should outlive the chat — for example the user asks to save it, it is the authoritative spec for a follow-up session or another implementer, or the team keeps structured tickets in-repo — write it as a Markdown file under internal implementation documentation (implementation notes, not end-user or marketing docs). Prefer the unified .deuk-agent-ticket/ directory, where both the index (TICKET_LIST.md) and the topic files are centralized. Otherwise use an existing convention such as <product-or-feature>/internal/*.md or docs/internal/*.md. If the user names a path, use it. Reuse the same section structure as Ticket format above. If only an inline paste is needed, skip creating a file unless the user asks to save.
-Plan-style UI (optional): Some editors surface plan documents separately from normal Markdown. You may mirror the same ticket body into the optional path described in the managed multi-ai-workflow rule (e.g. .cursor/plans/deuk-ticket.plan.md) while keeping the canonical file under .deuk-agent-ticket/. If both exist, keep them in sync.
-After saving (chat): Include one dedicated line with the full repo-root-relative path, e.g. Path: .deuk-agent-ticket/sub/container-unified-20260329-120000.md — not only a bare filename inside prose.
-Optional last line in the file: e.g. <!-- Ticket (repo-relative): path/from/root.md --> as an HTML comment on the very last line.
-Language: Write the body of persisted tickets in the user’s language — the language they use in the conversation (or their stated preference) — unless they ask for a specific language (for example English-only for an external partner).
-Before substantive work: Before implementation, fixes, or other non-trivial repo changes, check persisted tickets in the locations above (including .deuk-agent-ticket/ and any project-specific internal paths). If the file .deuk-agent-ticket/TICKET_LIST.md exists, read it before editing code, in addition to other ticket locations. Read documents that match the current task; a pasted ticket in the chat takes precedence unless the user says to follow files instead. Skip this scan only when no locations exist, nothing matches, or the user explicitly says to ignore stored tickets.
-Producing tickets: When saving a durable ticket for another agent, write the Ticket format body to topic files under .deuk-agent-ticket/, then update .deuk-agent-ticket/TICKET_LIST.md as index (or use CLI ticket create). In chat, include one line with the full path, e.g. Path: .deuk-agent-ticket/sub/container-unified-20260329-120000.md using repo-relative paths (no file:// URLs).
-Ticket links (full path): Whenever you link or cite a persisted ticket file — in Ticket format sections, chat, or Markdown — use the full path from the repository root (for example .deuk-agent-ticket/TICKET_LIST.md, project_i/foo/internal/ticket.md). Do not use a bare filename (LATEST.md alone) or an ambiguous partial path. In monorepos, include every prefix segment so the path is unique in the workspace. Markdown: put the full path in the link target, e.g. [ticket](.deuk-agent-ticket/TICKET_LIST.md) (repo-relative).
+<!-- deuk-agent-rule:begin -->
+# Project Agent Rules
+## Identity
+- **[COMMUNICATION TONE STRICT RULE]**
+  - You are a Senior Fullstack Systems Engineer specializing in Unity/C#, WebApp architectures, and High-Performance C++ Server development.
+  - Your communication must be strictly dry, concise, and technical.
+  - You MUST NOT use emojis, exclamation marks(!), or dramatic language (e.g., "대참사", "완벽하게", "시한폭탄").
+  - Do not attempt to "wow" the user with your tone.
+  - For Korean responses, use polite '해요체(-요)' instead of formal '하십시오체(-다/까)'.
+- **핸드오프 저장 후 채팅**: 파일로 남긴 뒤 채팅에 **`Path: \`루트기준/전체/경로.md\``** 형태로 **한 줄**을 반드시 넣어 다음 세션이 동일 파일을 연다.
+- **플랜 UI(선택)**: 플랜 전용 패널에 같은 문서를 띄우려면, 관리 중인 **multi-ai-workflow** 규칙에 적힌 **선택적 미러 경로**(예: `.cursor/plans/*.plan.md`)에 동일 본문을 둘 수 있다. 정본은 지정된 티켓 폴더를 유지하고 두 곳 내용을 맞출 것.
+English sections above are canonical for tooling; this block is a short Korean mirror for the same rules.
+## Ticket format & Submodule Isolation
+When handing work between tools or people—especially in an environment with multiple submodules like DeukUI, DeukPack, etc.—you **MUST NOT** use free-form markdown.
+You **MUST** use the official Ticket Skeleton Template located at:
+`<Current Repo Root>/.deuk-agent-templates/TICKET_TEMPLATE.md`
+**Hard Rules**:
+- **No hotpath LINQ (금지)**: Update 루프에서 LINQ, boxing, frame allocation 없음
+- **Root Cleanliness (하드룰)**: 작업용 스크립트(`fix_*.py`, `tmp_*.js` 등)를 워크스페이스 루트에 직접 생성하지 마십시오. 모든 일시적 스크립트는 `tmp/scripts/` 또는 `tmp/` 폴더 내에 생성해야 합니다.
+- **C++ Server Hard Rules**:
+    - **No Raw Pointers**: Use `std::unique_ptr` or `std::shared_ptr` for resource ownership.
+    - **Header Cleanliness**: Keep `#include` minimum in headers; use forward declarations where possible.
+    - **Async Safety**: Every shared resource in the logic loop strictly requires a mutex or atomic protection.
+- **WebApp / Frontend**:
+    - **Protocol Integrity**: Never hardcode JSON structures; always use `DeukPack` generated JS/TS codecs for communication.
+- **Ticket format (필수)**: 멀티스텝은 `.deuk-agent-templates/TICKET_TEMPLATE.md` (또는 활성 서브모듈의 템플릿) 사용
+By **creating a ticket using the CLI** (`npx deuk-agent-rule ticket create --topic <name>`), you ensure that:
+1. The **Target Submodule** is explicitly locked.
+2. The agent is forced to read specific **Module Rules** (e.g., `.deuk-agent-templates/MODULE_RULE_TEMPLATE.md`).
+3. Execution happens in explicit **Phases** to prevent context bleed.
+## DeukPack Codec & IDL Strict Rules (득팩 코어 체재 하드 룰)
+- **IDL Field Syntax (앵글 브래킷)**: 득팩의 필드 정의는 `1> int32 id` 형식을 따릅니다. Thrift 레거시 문법인 `:`(콜론), 세미콜론(`;`), `i32`, `i64`를 더 이상 문서나 코드에 사용하지 마십시오. 오로지 `id> type name` 및 `int32`, `int64` 표준 명칭을 강제합니다.
+- **Unified Pack API**: 과거의 `DeukPackSerializer`, `DeukPackEngine`, `WriteWithOverrides`, `toJsonWithOverrides` 등은 모두 폐기되었습니다. 모든 코드에는 `DeukPackCodec` 식별자와 유니파이드 API(`byte[] bin = Dto.Hero.Pack(format, fieldIds, overrides)`, `hero.UnpackFrom(bin)`)만 사용해야 합니다.
+- **Namespace Requirement**: Every `.deuk` schema MUST explicitly declare a namespace (e.g., `namespace Dto`). Never define global structs without a namespace. Code examples MUST use the fully qualified namespace path (e.g., `Dto.Hero.Pack()`).
+## AI Model Compliance & Selection Policy
+**Model Over-alignment vs Compliance (High vs Flash)**
+- **Flash/Fast Models**: Highly instruct-tuned for strict mechanical task execution. Due to a smaller parameter footprint and less internal "world knowledge", they explicitly follow literal agent rules and format templates exactly as instructed.
+- **High/Pro Models**: Possess vast world knowledge and are optimized for helpfulness. This often leads to "overthinking" (prioritizing a helpful or natural answer over rigid, arbitrary constraints), resulting in frequent rule violations like ignoring length limits or template structures. They also experience attention dilution in deep analysis tasks.
+**Assignment Strategy**:
+1. **Flash Models**: Use for strict template filling, simple code generation, porting, and repetitive ticket execution (`.deuk-agent-ticket/*`) where strict compliance is mandatory.
+2. **High/Pro Models**: Use for architectural planning, deep legacy code comprehension, complex bug squashing, and creative solutions. Supply heavy failure warnings in the prompt to force formatting compliance.
+## 🔗 Ticket Framework & Execution Strategy
+When given a ticket, you MUST run commands and write code **strictly within the boundaries** of the `[Target Submodule]` defined in the `TICKET-XXX.md`.
+1. **Create the Ticket**: ALWAYS use `npx deuk-agent-rule ticket create --topic <name>` to generate a new ticket. **DO NOT** manually create `.md` files or copy templates directly to bypass the CLI.
+2. **Read the Ticket**: ALWAYS use `npx deuk-agent-rule ticket use --latest` (or `npx deuk-agent-rule ticket list`) to locate and read the active ticket. DO NOT manually parse INDEX.json or scan directories.
+3. **Fill the Ticket (CRITICAL)**: The newly created ticket already contains YAML Front Matter (`--- id: ... ---`). **DO NOT** overwrite the entire file when adding your plan. ALWAYS use partial file editing tools or append text carefully to preserve the existing YAML Front Matter. Erasing the Front Matter corrupts the ticketing index.
+4. **Execute Phase**: Process only the checklist for the **Current Phase**. Do not hallucinate or wander into other architectural areas.
+5. **Update Status**: Mark checkboxes (`[x]`) as tasks are completed.
+6. **Archive on Completion**: When all phases are completed, append the execution report at the bottom under a `## 📜 Execution Report` header. **Then, YOU MUST execute `npx deuk-agent-rule ticket archive <ticket-id>` (or `--latest`)** to properly close and archive the ticket. DO NOT attempt to manually `mv` files.
+All Tickets are volatile and strictly local. Do not attempt to version them or mirror them to obsolete plan directories.
+<!-- deuk-agent-rule:end -->

package/bundle/rules/delivery-and-parallel-work.mdc CHANGED Viewed

@@ -1,26 +1,26 @@
----
-description: Vertical slices, portfolio priority, parallel-branch ownership, scoped refactors
-alwaysApply: true
----
-# Delivery, portfolio, and parallel work
-## Default shape of work
-- Prefer one PR (or one agent session outcome) = one vertically integrated slice: buildable, runnable, and demo-able end-to-end for that slice. Do not treat “wide refactors with no user-visible behavior” as the default unit of delivery unless the user explicitly asks for that.
-- When the user states portfolio, demo, or ship-this-week priority, treat that as scope authority: narrow the task to what improves the visible outcome first; defer broad cleanups to a follow-up ticket unless they are blocking the slice.
-## Parallel branches and file ownership
-- Assume other branches or developers may be editing the same repo. Before touching widely shared files (large pages, shared lib/, config roots), minimize blast radius: prefer a small, well-bounded edit over sweeping moves in the same change set.
-- If the user names an owner branch, feature lane, or file ownership (e.g. “UI lane owns components/, gameplay owns lib/game/”), stay inside that boundary unless they explicitly expand it.
-- When parallel work is likely, call out touched paths that are high-merge-conflict risk so the user can coordinate; do not silently expand into those files without need.
-## Refactor discipline
-- Shrink refactor scope by default: extract or adjust only what the current task requires. If a larger refactor is tempting, split it: (1) minimal change that satisfies the task, (2) optional follow-up task in ticket format.
-- Do not use “while we’re here” to rename, reformat, or reorganize unrelated modules.
-## Interaction with tickets
-- If a ticket or user message defines Files to modify and Constraints, those win; this rule file narrows how you plan and execute within that envelope — it does not override explicit file lists.
+---
+description: Vertical slices, portfolio priority, parallel-branch ownership, scoped refactors
+alwaysApply: true
+---
+# Delivery, portfolio, and parallel work
+## Default shape of work
+- Prefer **one PR (or one agent session outcome) = one vertically integrated slice**: buildable, runnable, and **demo-able** end-to-end for that slice. Do not treat “wide refactors with no user-visible behavior” as the default unit of delivery unless the user explicitly asks for that.
+- When the user states **portfolio, demo, or ship-this-week priority**, treat that as **scope authority**: narrow the task to what improves the visible outcome first; defer broad cleanups to a follow-up ticket unless they are blocking the slice.
+## Parallel branches and file ownership
+- Assume **other branches or developers may be editing the same repo**. Before touching widely shared files (large pages, shared `lib/`, config roots), **minimize blast radius**: prefer a small, well-bounded edit over sweeping moves in the same change set.
+- If the user names an **owner branch, feature lane, or file ownership** (e.g. “UI lane owns `components/`, gameplay owns `lib/game/`”), **stay inside that boundary** unless they explicitly expand it.
+- When parallel work is likely, **call out** touched paths that are high-merge-conflict risk so the user can coordinate; do not silently expand into those files without need.
+## Refactor discipline
+- **Shrink refactor scope by default**: extract or adjust only what the current task requires. If a larger refactor is tempting, split it: **(1)** minimal change that satisfies the task, **(2)** optional follow-up task in ticket format.
+- Do not use “while we’re here” to rename, reformat, or reorganize unrelated modules.
+## Interaction with tickets
+- If a ticket or user message defines **Files to modify** and **Constraints**, those win; this rule file **narrows** how you plan and execute within that envelope — it does not override explicit file lists.

package/bundle/rules/git-commit.mdc CHANGED Viewed

@@ -1,18 +1,24 @@
----
-description: Commit message formatting (Plain text only)
-alwaysApply: true
----
-# Git Commit Rules
-Apply only when writing commit messages or staging summaries. Output must consume minimal tokens; content must be high-signal for search and review.
-- First line only: Imperative mood, under 72 characters, no trailing period.
-- Optional type(scope): summary — feat, fix, refactor, docs, chore, etc. Use a single word for scope (directory or module).
-- Body: Only when requested by the user or when changes span multiple topics. Use a maximum of 3 bullet points, each under 80 characters.
-- What to include: Describe what changed in one sentence (behavior, contract, compatibility). Mark risky changes with a prefix (e.g., BREAKING or migration note).
-- What to exclude: Do not restate diffs, list filenames, use filler like "updated/improved", use emojis, provide long tutorials, or provide bilingual translations (use one project language). Never use the word "sync" in the commit title; use specific words like "release", "update", or "apply".
-- For single-topic commits, use a one-line title only.
-- For large staging areas, summarize the title and only add a body if the user explicitly requests it.
+---
+description: Git 커밋 메시지 — 짧고 의미 있게(저비용 출력)
+alwaysApply: false
+---
+# Git commit messages (agent)
+커밋 메시지·스테이징 요약을 쓸 때만 적용. **출력은 최소 토큰**, 내용은 **검색·리뷰에 쓸 만한 정보**만.
+## 형식 (기본)
+- **첫 줄만**: 명령형, **72자 이내**, 마침표 없음.
+- **선택** `type(scope): summary` — `feat` `fix` `refactor` `docs` `chore` 등; `scope`는 디렉터리·모듈 한 단어.
+- **본문**: 사용자가 요청하거나 변경이 여러 주제일 때만. 그때도 **불릿 최대 3줄**, 각 80자 이내.
+## 쓸 것 / 쓰지 말 것
+- **쓸 것**: 무엇이 바뀌었는지 한 문장(동작·계약·호환). 위험한 변경이면 한 단어로 표시(`BREAKING` 또는 마이그레이션 한 줄).
+- **쓰지 말 것**: diff 재서술, 파일 목록 나열, “업데이트함/개선함” 같은 빈 말, 이모지, 장문 튜토리얼, 영어·한국어 이중 번역(팀 언어 하나만). 커밋 메시지 제목(Title)에 "sync" 단어 사용 금지 (대신 "release", "update", "apply" 등으로 구체적으로 표현).
+## 비용
+- 한 커밋 주제면 **제목 한 줄로 끝낸다.**
+- 스테이징이 크면 제목은 요약하고, 본문은 **사용자가 본문 달라고 할 때만** 추가한다.

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

@@ -36,7 +36,6 @@ When the user asks to prepare work for another tool:
 3. Do not include editor-specific instructions (token budgets, local rule file paths).
 4. When the ticket must persist (user asks to save or document it, or it is the canonical next-step spec), create or update a Markdown file under internal implementation documentation (see AGENTS.md, Ticket persistence). Prefer the unified .deuk-agent-ticket/ directory for both the index (TICKET_LIST.md) and the topic files; init gitignores .deuk-agent-ticket/ by default. Use the same ticket template; do not place this in public README/landing unless the project explicitly treats this as its internal log. In Markdown links and backtick citations, use the full path from the repository root — never a bare filename.
 5. After writing a persisted ticket, in chat include one dedicated line with the full repo-root-relative path so the next session can open it unambiguously, for example: `Path: .deuk-agent-ticket/sub/container-unified-20260329-120000.md` (same path you used in the file). Repeat the full path in links elsewhere in the same message if helpful.
-6. Optional last line inside the persisted file (improves search and skim): `<!-- Ticket (repo-relative): path/from/repo/root.md -->` on the very last line.
 7. Write persisted ticket content in the user's conversation language (e.g., Korean) unless they specify another language. When using Korean, follow the concise polite style (-요) as described in AGENTS.md.
 ## Context Preservation (New Issues)

package/bundle/templates/MODULE_RULE_TEMPLATE.md ADDED Viewed

@@ -0,0 +1,24 @@
+# Submodule Agent Rules: [Module Name]
+> **[CAUTION FOR AI AGENTS]**
+> When the Ticket Document `Target Submodule` matches this module, you MUST strictly adhere to the following architectural conventions and rules. Do not cross-pollinate rules from other submodules.
+## 📁 Repository Boundary
+- **Path Root:** `[e.g., DeukUI/ or DeukPackKits/]`
+- **Allowed Tech Stack:** `[e.g., React, TypeScript, CSS Modules | C#, Unity 2022]`
+## 🏗️ Core Architecture & Conventions
+1. **Naming Conventions:**
+   - [e.g., Use PascalCase for C# files, kebab-case for TS files.]
+2. **State Management:**
+   - [e.g., Do NOT use global Redux state; pass props or use React Context localized.]
+3. **Prohibited Patterns:**
+   - [e.g., Absolutely forbidden to use LINQ inside `Update()` functions.]
+   - [e.g., Absolutely forbidden to overwrite `index.js` generated files.]
+## 🛠️ Build & Test Protocol
+- **To build this module:** `[e.g., npm run build:plugin --prefix DeukUI]`
+- **To test this module:** `[e.g., npm run test:ui]`
+## 🔗 Ticket Instructions
+Always enforce that generated `Tickets` intended for this module include this rule file in their `[Context Files]` section.

package/bundle/templates/TICKET_TEMPLATE.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Task: [Task Title / Ticket Number]
+> **[CAUTION FOR AI AGENTS]**
+> You are operating within a locked multi-module monorepo.
+> 1. Restrict absolutely all analysis, file creation, and modifications to the declared **[Target Submodule]** below.
+> 2. Read the files listed in **[Context Files]** before doing ANY code generation.
+> 3. DO NOT leak configuration, logic, or dependencies from other submodules.
+## 🎯 Scope Bounds
+- **Target Submodule:** `[e.g., DeukUI | DeukPack | DeukNavigation]`
+- **Context Files:**
+  - `[e.g., DeukAgentRules/templates/MODULE_RULE_TEMPLATE.md]`
+  - `[e.g., path/to/your/specific/rules.md]`
+## 📁 Files to Modify
+- `path/from/root/to/target1`: [Specific instructions. Don't write 'refactor', describe WHAT to refactor.]
+- `path/from/root/to/target2`: [Instructions...]
+## 🏗️ Design Decisions (For Context)
+- [Why are we doing this? E.g., "To isolate the IR Layout bindings from DOM events"]
+- [What pattern to use?]
+## 🛑 Strict Constraints (Rules to never break)
+- [e.g., Do NOT remove existing @ts-nocheck headers]
+- [e.g., MUST retain C# [SerializeField] directives]
+- [e.g., Do NOT import Vue logic into DeukPack]
+## 🔄 Phased Execution Steps
+> Agent: Do NOT attempt to do Phase 3 before Phase 1 is fully tested. Use separate chat messages per phase if the task is large.
+1. [Phase 1> Setup / Parsing]
+2. [Phase 2> Core Logic Change]
+3. [Phase 3> Cleanup / Verification]
+## ✅ Verification / QA
+- [e.g., Check CLI command output `npm run test`]
+- [e.g., Validate Inspector mounts properly in Figma]