ai-ops-compiler 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @ai-ops/compiler
+
+SSOT(Single Source of Truth) YAML 룰 파일을 읽어, 각 AI 도구(Claude Code, Codex, Gemini)에 맞는 Markdown 파일로 변환·설치하기 위한 **Pure 함수 라이브러리**.
+
+CLI(`@ai-ops/cli`)가 이 패키지를 조합해 실제 파일 쓰기를 수행한다.
+
+---
+
+## Architecture
+
+```
+YAML rules + presets.yaml
+         │
+         ▼
+      [loader]          YAML → Rule[] / Preset[]
+         │  resolvePresetRules → excludeRules (TUI 세부조정)
+         ▼
+      [renderer]        Rule[] → 도구별 Markdown
+         │
+         ▼
+   [install-plan]       Markdown → FileAction[] (경로 + 헤더 포함 컨텐츠)
+         │
+         ▼
+    CLI file write      FileAction[] → 실제 파일 기록
+         │
+         ▼
+   [manifest-io]        .ai-ops-manifest.json 저장
+         │
+    (next install)
+         │
+         ▼
+       [diff]           이전 Manifest vs 현재 상태 → DiffResult
+```
+
+---
+
+## `src/` 구조
+
+```
+src/
+├── schemas/
+│   ├── rule.schema.ts       Rule, RuleContent, DecisionTableEntry 타입 + Zod 스키마
+│   ├── preset.schema.ts     Preset 타입 + Zod 스키마
+│   └── manifest.schema.ts   Manifest 타입 + Zod 스키마 (설치 추적 메타데이터)
+│
+├── loader.ts                YAML 파일 읽기 → Rule[] / Preset[] 파싱
+├── renderer.ts              Rule[] → 도구별 Markdown 렌더링
+├── tool-output.ts           도구별 경로·전략 상수 (TOOL_OUTPUT_MAP, ToolId)
+├── source-hash.ts           YAML 파일 내용 기반 sourceHash 계산 + Manifest 빌더
+├── managed-header.ts        파일에 ai-ops 소유 헤더 삽입·판별·파싱·제거
+├── manifest-io.ts           .ai-ops-manifest.json 직렬화·역직렬화 + 파일 I/O
+├── diff.ts                  이전 Manifest vs 현재 상태 비교 → DiffResult
+├── install-plan.ts          renderForTool 결과 → FileAction[] (설치 계획)
+└── index.ts                 barrel export
+```
+
+---
+
+## 주요 함수
+
+### loader
+
+| 함수                                   | 설명                                                                |
+| -------------------------------------- | ------------------------------------------------------------------- |
+| `loadAllRules(rulesDir)`               | 디렉토리의 모든 `.yaml` 룰 파일 로딩                                |
+| `loadPresets(presetsPath)`             | `presets.yaml` → `Preset[]`                                         |
+| `resolvePresetRules(preset, allRules)` | preset의 rule ID 목록 → `Rule[]` (priority 정렬)                    |
+| `excludeRules(rules, excludeIds)`      | TUI 세부조정용. 사용자가 해제한 rule ID 제거 → 나머지 `Rule[]` 반환 |
+
+### renderer
+
+| 함수                           | 설명                                                       |
+| ------------------------------ | ---------------------------------------------------------- |
+| `renderForTool(toolId, rules)` | 핵심 진입점. 도구별 `ToolRenderResult` 반환                |
+| `renderClaudeCodeRule(rule)`   | 단일 Rule → Claude Code용 Markdown (path frontmatter 포함) |
+| `renderRulesToMarkdown(rules)` | Rule[] → `---` separator 단일 Markdown                     |
+| `partitionRules(rules)`        | `{ global, domain }` 분리                                  |
+
+### source-hash
+
+| 함수                          | 설명                                                      |
+| ----------------------------- | --------------------------------------------------------- |
+| `computeSourceHash(rulesDir)` | YAML 파일 내용 기반 SHA-256 → 6자리 hex. YAML 수정 감지용 |
+| `buildManifest(params)`       | Manifest 객체 생성 (generatedAt = 현재 시각)              |
+
+### managed-header
+
+| 함수                            | 설명                                                                 |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `wrapWithHeader(content, meta)` | `<!-- managed by ai-ops -->` 헤더 + sourceHash/generatedAt 메타 삽입 |
+| `isManagedFile(content)`        | ai-ops가 소유한 파일인지 판별                                        |
+| `parseManagedHeader(content)`   | 헤더에서 `{ sourceHash, generatedAt }` 추출                          |
+| `stripManagedHeader(content)`   | 헤더 제거 → 순수 컨텐츠 반환                                         |
+
+### manifest-io
+
+| 함수                            | 설명                                        |
+| ------------------------------- | ------------------------------------------- |
+| `readManifest(path)`            | `.ai-ops-manifest.json` 읽기. 없으면 `null` |
+| `writeManifest(path, manifest)` | 디렉토리 자동 생성 후 JSON 저장             |
+| `parseManifest(json)`           | JSON string → Zod 검증된 `Manifest`         |
+| `serializeManifest(manifest)`   | `Manifest` → pretty-print JSON string       |
+
+### diff
+
+| 함수                                                         | 설명                                                                          |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `computeDiff({ previous, currentRules, currentSourceHash })` | Set 비교로 `added` / `removed` 계산, `sourceHash` 비교로 `sourceChanged` 판단 |
+
+### install-plan
+
+| 함수                                               | 설명                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `buildInstallPlan({ toolId, renderResult, meta })` | 렌더링 결과 → `FileAction[]`. 각 action에 managed header 포함. 빈 content는 자동 생략 |
+
+---
+
+## 도구별 출력 파일
+
+| Tool          | 파일                                                             |
+| ------------- | ---------------------------------------------------------------- |
+| `claude-code` | `.claude/rules/{rule-id}.md` (룰당 1파일, path frontmatter 포함) |
+| `codex`       | `AGENTS.md` (global) + `AGENTS.override.md` (domain)             |
+| `gemini`      | `GEMINI.md` (global) + `GEMINI.md` (domain, 하위 폴더)           |

package/data/presets.yaml

@@ -0,0 +1,52 @@
+frontend-web:
+  description: '웹 프론트엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - naming-convention
+    - engineering-standards
+    - typescript
+    - react-typescript
+    - shadcn-ui
+    - nextjs
+    - libs-frontend-web
+
+frontend-app:
+  description: '앱 프론트엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - naming-convention
+    - engineering-standards
+    - flutter
+    - libs-frontend-app
+
+backend-ts:
+  description: 'TypeScript 백엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - naming-convention
+    - engineering-standards
+    - typescript
+    - nestjs
+    - prisma-postgresql
+    - graphql
+    - nestjs-graphql
+    - libs-backend-ts
+
+backend-python:
+  description: 'Python 백엔드 프로젝트를 위한 프리셋'
+  rules:
+    - role-persona
+    - communication
+    - code-philosophy
+    - naming-convention
+    - engineering-standards
+    - python
+    - fastapi
+    - sqlalchemy
+    - libs-backend-python

package/data/references/README.md

@@ -0,0 +1,34 @@
+# 공식문서 압축용 프롬프트
+
+```txt
+[System Role]
+You are a 'Technical Context Compressor' responsible for context window optimization in a Multi-Agent environment.
+Your objective is to maximize information density and perform lossless abstraction on the provided raw official documentation. The output must be heavily structured, machine-readable, and instantly actionable as execution rule-sets for target AI agents (e.g., Codex, Gemini).
+
+[Compression Rules]
+1. Remove Noise (Decimation): Completely eliminate narrative sentences intended for human comprehension, philosophical backgrounds, greetings, and redundantly repeated code examples.
+2. Preserve Hard Facts (Immutability): Preserve absolute exactness for file paths, CLI commands, environment variables, essential syntax (e.g., YAML frontmatter, @import), and supported string matching patterns (e.g., Glob patterns). Do not alter or omit a single byte of these factual elements.
+3. Structuring (Topology): Logically classify the configuration hierarchy, scope (Global vs. Local), and execution priority.
+4. Format (Serialization): Strictly utilize Markdown tables and tree structures to allow target agents to easily parse and map the data.
+
+[Input Documentation]
+{{Insert the raw official documentation text here}}
+
+[Output Specification]
+Strictly adhere to the Markdown template structure below for the final output.
+
+# [Technology/Feature Name] Agent Instruction Manual
+
+## 1. Core Architecture & Hierarchy
+(Briefly specify the priority tree and hierarchical structure of the configuration files. Use `>` or list formats to show precedence.)
+
+## 2. Config & Path Specs
+| Scope | Directory / Path | Capability / Purpose | Override Rules |
+| :--- | :--- | :--- | :--- |
+| ... | ... | ... | ... |
+
+## 3. Syntax & Commands (Hard Constraints)
+- Mandatory Commands:
+- Special Syntax Rules (e.g., Conditional constraints, Frontmatter):
+- Caveats & Constraints (Critical rules to prevent Fatal Errors):
+```

package/data/references/claude-code/best-practices/context-optimization.md

@@ -0,0 +1,114 @@
+# Agent Context Optimization Strategies (Claude Code)
+
+This document outlines architectural patterns and best practices for managing context payload effectively within the Claude Code environment, building on the official specification in `references/claude-code/rules.md`.
+
+## The Challenge: Context Bloat
+
+Claude Code's memory system eagerly loads CLAUDE.md files at session start (recursive lookup from CWD upward). Using `@import` to pull in domain-specific rules globally causes:
+
+1. **Token Exhaustion:** Loading Python rules while working on a React component wastes context window.
+2. **Attention Dilution:** Increased instruction density raises the likelihood of the LLM missing or misinterpreting rules.
+
+## Solution 1: Path-Scoped Rules (Claude Code Native — Preferred)
+
+Claude Code has a **native lazy-loading mechanism** that Gemini CLI lacks: `paths:` frontmatter in `.claude/rules/*.md`.
+
+Rules are automatically activated **only** when the agent reads a file matching the declared glob pattern. No manual registry required.
+
+```yaml
+# .claude/rules/react-typescript.md
+---
+paths:
+  - 'src/**/*.tsx'
+  - 'src/**/*.ts'
+---
+# React & TypeScript Rules
+...
+```
+
+```yaml
+# .claude/rules/python.md
+---
+paths:
+  - '**/*.py'
+  - 'pyproject.toml'
+---
+# Python Rules
+...
+```
+
+**Result:** The agent loads Python rules only when it opens a `.py` file. React rules only when touching `.tsx`. Zero manual orchestration.
+
+### Recommended Rule File Layout
+
+```
+.claude/
+  rules/
+    role-persona.md          # No paths: → always loaded (global)
+    communication.md         # No paths: → always loaded (global)
+    code-philosophy.md       # No paths: → always loaded (global)
+    typescript.md            # paths: src/**/*.ts
+    react-typescript.md      # paths: src/**/*.tsx
+    nextjs.md                # paths: src/app/**, next.config.*
+    python.md                # paths: **/*.py
+    fastapi.md               # paths: **/routers/**, **/main.py
+    prisma-postgresql.md     # paths: prisma/**, **/*.prisma
+```
+
+## Solution 2: Child Directory CLAUDE.md (Package-Level Isolation)
+
+In monorepos, place domain-specific rules in the package's own `.claude/CLAUDE.md`. Claude Code only loads these **on-demand** when files in that subtree are read.
+
+```
+monorepo/
+  .claude/CLAUDE.md              # Global: persona, communication, philosophy
+  packages/
+    frontend/
+      .claude/CLAUDE.md          # Loaded only when working in frontend/
+    backend/
+      .claude/CLAUDE.md          # Loaded only when working in backend/
+    data-pipeline/
+      .claude/CLAUDE.md          # Loaded only when working in data-pipeline/
+```
+
+**Caveat:** Requires that Claude actually reads a file within the subtree to trigger loading. Does not activate based on directory navigation alone.
+
+## Solution 3: Manual Rule Registry (Fallback)
+
+Use when Solutions 1 and 2 are insufficient — for example, when rules cannot be mapped to file path patterns (e.g., architecture decisions, API design guidelines).
+
+Inject a **Rule Registry** into the base CLAUDE.md instructing the agent to self-load rules using the `Read` tool:
+
+```markdown
+# 🚨 Dynamic Rule Loading (CRITICAL)
+
+DO NOT guess architectural or stylistic rules. Before modifying or generating
+code, you MUST use the Read tool to load the relevant rule file based on the
+tech stack you are working on.
+
+**Rule Registry Location:** `packages/compiler/data/rules/*.yaml`
+
+**Mapping:**
+
+- **Python / Backend**: Read `python.yaml`, `fastapi.yaml`, `libs-backend-python.yaml`
+- **React / Frontend**: Read `react-typescript.yaml`, `nextjs.yaml`, `shadcn-ui.yaml`
+- **Database**: Read `sqlalchemy.yaml` or `prisma-postgresql.yaml`
+- **GraphQL**: Read `graphql.yaml`, `nestjs-graphql.yaml`
+```
+
+## Decision Matrix
+
+| Scenario                                   | Recommended Solution                          |
+| ------------------------------------------ | --------------------------------------------- |
+| Rules map cleanly to file extensions/paths | **Solution 1** — `paths:` frontmatter         |
+| Monorepo with clearly separated packages   | **Solution 2** — Child directory CLAUDE.md    |
+| Cross-cutting rules not tied to file paths | **Solution 3** — Manual Rule Registry         |
+| Universal rules (persona, communication)   | No optimization needed — always load globally |
+
+## Summary
+
+- **DO** use `paths:` frontmatter for domain-specific rules. This is Claude Code's native, zero-overhead lazy-loading.
+- **DO** place package-level rules in child `.claude/CLAUDE.md` in monorepos.
+- **DO NOT** use `@import` for large, domain-specific rulesets in the global CLAUDE.md.
+- **DO** keep globally loaded rules minimal: persona, communication, core philosophy only.
+- **DO** fall back to a Manual Rule Registry only when path-scoping is impossible.

package/data/references/claude-code/hooks.md

@@ -0,0 +1,65 @@
+---
+source: https://docs.anthropic.com/en/docs/claude-code/hooks
+last_fetched: 2026-02-26
+---
+
+# Claude Code Hooks Agent Instruction Manual
+
+## 1. Core Architecture & Hierarchy
+
+**Priority & Scope Topology (Highest to Lowest Specificity):**
+
+1. `Component` (Skill/Agent YAML Frontmatter)
+2. `Plugin` (`hooks/hooks.json`)
+3. `Project (Local)` (`.claude/settings.local.json`)
+4. `Project (Shared)` (`.claude/settings.json`)
+5. `User (Global)` (`~/.claude/settings.json`)
+6. `Managed Policy` (Organization-wide settings)
+
+**Execution Pipeline & Resolution:**
+
+- `Event Trigger` -> `Matcher Validation (Regex)` -> `Handler Execution (Command/Prompt/Agent)` -> `Outcome Evaluation (Exit Code & JSON)`
+
+## 2. Config & Path Specs
+
+| Scope                | Directory / Path                                            | Capability / Purpose                          | Override Rules                                                      |
+| -------------------- | ----------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
+| **Org Policy**       | Managed policy settings                                     | Enforce organization-wide security/compliance | Overrides user `disableAllHooks` if `allowManagedHooksOnly` is true |
+| **User (Global)**    | `~/.claude/settings.json`                                   | Cross-project personal workflows/preferences  | Overridden by local/project configs                                 |
+| **Project (Shared)** | `.claude/settings.json`                                     | Team-shared repo hooks                        | Committed to version control                                        |
+| **Project (Local)**  | `.claude/settings.local.json`                               | Private sandbox hooks                         | Auto-gitignored                                                     |
+| **Plugin**           | `hooks/hooks.json`                                          | Plugin-bundled automation                     | Active only when plugin is enabled                                  |
+| **Component**        | `hooks:` field in `SKILL.md` / agent `.md` YAML Frontmatter | Component lifecycle-scoped hooks              | Active only during component runtime                                |
+
+## 3. Syntax & Commands (Hard Constraints)
+
+- **Mandatory Commands & Environment Variables:**
+- `claude --debug` / `Ctrl+O`: Exposes hook execution traces, stdout/stderr, and match states.
+- `/hooks`: Interactive CLI menu to manage/toggle hook configurations.
+- `$CLAUDE_PROJECT_DIR`: Resolves to the absolute project root path.
+- `${CLAUDE_PLUGIN_ROOT}`: Resolves to the active plugin directory.
+- `$CLAUDE_ENV_FILE`: Writable file path for persisting `export` statements (Strictly available to `SessionStart` hooks only).
+- `$CLAUDE_CODE_REMOTE`: Set to `"true"` in remote web environments.
+
+- **Special Syntax Rules (Conditional constraints, Schema):**
+- **Hook Types:**
+- `"command"`: Spawns shell processes. Parses stdout for JSON on exit `0`.
+- `"prompt"`: Single-turn LLM evaluation. Injects input via `$ARGUMENTS` placeholder. Output must be `{"ok": boolean, "reason": "..."}`.
+- `"agent"`: Multi-turn subagent verification (Max 50 turns). Injects input via `$ARGUMENTS`.
+
+- **Matchers (Regex):** Filters execution based on target fields (e.g., `tool_name` for `PreToolUse`, `agent_type` for `SubagentStart`).
+- Ex: `"Bash"`, `"Edit|Write"`, `"mcp__.*"`.
+- Events without matcher support (always fire): `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`.
+
+- **Decision Control (JSON via Stdout on Exit 0):**
+- _Universal:_ `{"continue": false, "stopReason": "..."}` (Hard stop agent).
+- _Top-Level:_ `{"decision": "block", "reason": "..."}` (`UserPromptSubmit`, `PostToolUse`, `Stop`, `ConfigChange`).
+- _Nested (PreToolUse):_ `{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow|deny|ask", "updatedInput": {...}}}`.
+- _Nested (PermissionRequest):_ `{"hookSpecificOutput": {"hookEventName": "PermissionRequest", "decision": {"behavior": "allow|deny", "updatedInput": {...}}}}`.
+
+- **Caveats & Constraints (Critical rules to prevent Fatal Errors):**
+- **Exit Code 2 (Blocking):** Forces an immediate block. **ALL stdout JSON is ignored**. Stderr text is fed back to the LLM.
+- **JSON Purity (Exit 0):** If utilizing JSON decision control, `stdout` must contain _only_ valid JSON. Extraneous shell profile echoes will trigger parser failures.
+- **Async Hook Restrictions:** `"async": true` is strictly limited to `"command"` types. Background hooks cannot return decisions, block events, or modify execution flow.
+- **WorktreeCreate Payload:** Must output exactly the absolute path to the directory on `stdout` and exit `0`. JSON decision objects are strictly prohibited for this event.
+- **State Mutations:** Hook files are cached at session startup. Mid-session file edits trigger a warning and require manual `/hooks` menu approval to reload.

package/data/references/claude-code/rules.md

@@ -0,0 +1,63 @@
+---
+source: https://docs.anthropic.com/en/docs/claude-code/memory
+last_fetched: 2026-02-26
+---
+
+# Claude Code Memory Management Agent Instruction Manual
+
+## 1. Core Architecture & Hierarchy
+
+**Priority Topology (Lowest to Highest Specificity):**
+
+1. `Managed policy` (Organization-wide instructions)
+2. `User rules` (`~/.claude/rules/*.md`)
+3. `User memory` (`~/.claude/CLAUDE.md`)
+4. `Project memory` & `Project rules` (`./CLAUDE.md`, `./.claude/CLAUDE.md`, `./.claude/rules/*.md`)
+5. `Project memory (local)` (`./CLAUDE.local.md`)
+
+**Context Injection & Loading Strategy:**
+
+- **Parent Directories:** Loaded in full at launch (recursive lookup from CWD up to, but not including, root `/`).
+- **Child Directories:** Loaded on-demand when files in subtrees are read.
+- **Auto Memory:** First 200 lines of `MEMORY.md` loaded at session start. Content beyond 200 lines and modular topic files (e.g., `debugging.md`) are loaded on-demand.
+
+## 2. Config & Path Specs
+
+| Scope                | Directory / Path                                                   | Capability / Purpose                                     | Override Rules                 |
+| -------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- | ------------------------------ |
+| **Org (macOS)**      | `/Library/Application Support/ClaudeCode/CLAUDE.md`                | IT/DevOps managed policy                                 | Lowest Priority                |
+| **Org (Linux)**      | `/etc/claude-code/CLAUDE.md`                                       | IT/DevOps managed policy                                 | Lowest Priority                |
+| **Org (Windows)**    | `C:\Program Files\ClaudeCode\CLAUDE.md`                            | IT/DevOps managed policy                                 | Lowest Priority                |
+| **User (Global)**    | `~/.claude/CLAUDE.md` <br> `~/.claude/rules/*.md`                  | Personal preferences / workflows for all projects        | Overridden by Project configs  |
+| **Project (Shared)** | `./CLAUDE.md` or `./.claude/CLAUDE.md` <br> `./.claude/rules/*.md` | Team-shared modular rules, testing, architecture         | Overrides User configs         |
+| **Project (Local)**  | `./CLAUDE.local.md`                                                | Private sandbox preferences (Auto added to `.gitignore`) | Highest Priority               |
+| **Auto Memory**      | `~/.claude/projects/<project>/memory/`                             | Agent's internal learnings, debug patterns, indexes      | Subject to 200-line load limit |
+
+## 3. Syntax & Commands (Hard Constraints)
+
+- **Mandatory Commands & Environment Variables:**
+- `export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` (Force OFF) / `0` (Force ON).
+- `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir <path>` (Evaluates memory files in external directories).
+- `/memory` (CLI command to open file selector/system editor).
+- `/init` (CLI command to bootstrap codebase `./CLAUDE.md`).
+
+- **Special Syntax Rules (Conditional constraints, Frontmatter):**
+- **Imports Syntax:** `@path/to/import` (Supports relative, absolute, and `~` home-directory paths).
+- **YAML Frontmatter:** Apply target-specific scoped rules in `.claude/rules/*.md`.
+
+```yaml
+---
+paths:
+  - 'src/**/*.ts'
+  - '{src,lib}/**/*.{ts,tsx}'
+---
+```
+
+- **Glob/Brace Patterns:** `**/*.ts` (Recursive), `src/**/*` (All under dir), `*.md` (Root only), `{src,lib}` (Multiple targets).
+
+- **Caveats & Constraints (Critical rules to prevent Fatal Errors):**
+- **Import Escaping:** `@import` statements are strictly ignored inside markdown code spans and code blocks.
+- **Max Recursion:** Imported files can recursively import additional files with a hard limit of **5 hops**.
+- **Security Gate:** First-time cross-project/external imports prompt a one-time GUI approval dialog. If declined, imports are permanently disabled for that path.
+- **Path Resolution:** The `<project>` Auto memory path strictly derives from the Git repository root. Git worktrees spawn separate memory directories. Non-Git environments default to the working directory.
+- **Symlink Handling:** `.claude/rules/` resolves symlinks natively; circular symlinks are detected and bypassed.

package/data/references/claude-code/skills.md

@@ -0,0 +1,72 @@
+---
+source: https://docs.anthropic.com/en/docs/claude-code/skills
+last_fetched: 2026-02-26
+---
+
+# Claude Code Skills Agent Instruction Manual
+
+## 1. Core Architecture & Hierarchy
+
+**Priority & Scope Topology (Highest to Lowest Specificity):**
+
+1. `Enterprise` (Managed settings files)
+2. `Personal` (`~/.claude/skills/<skill-name>/SKILL.md`)
+3. `Project` (`.claude/skills/<skill-name>/SKILL.md`)
+4. `Plugin` (`<plugin>/skills/<skill-name>/SKILL.md`)
+
+**Execution & Resolution Rules:**
+
+- **Legacy Override:** Skills take precedence over legacy `.claude/commands/*.md` files sharing the same name.
+- **Namespace Isolation:** Plugin skills utilize a `plugin-name:skill-name` namespace to prevent collisions.
+- **Nested Discovery:** Skills are automatically discovered from nested `.claude/skills/` directories relative to the active working directory. In monorepos, skills in each package's `.claude/skills/` are discovered when that package's directory is active (requires `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` for `--add-dir` paths).
+- **Context Budget:** Skill descriptions load into context dynamically (budgeted at 2% of context window, 16,000 chars fallback).
+
+## 2. Config & Path Specs
+
+| Scope          | Directory / Path                         | Capability / Purpose                       | Override Rules              |
+| -------------- | ---------------------------------------- | ------------------------------------------ | --------------------------- |
+| **Enterprise** | Managed Settings                         | Organization-wide standard enforcement     | Highest Priority            |
+| **Personal**   | `~/.claude/skills/<skill-name>/SKILL.md` | Global user-specific custom slash commands | Overridden by Enterprise    |
+| **Project**    | `./.claude/skills/<skill-name>/SKILL.md` | Repo-scoped workflows and execution logic  | Overridden by Personal      |
+| **Plugin**     | `<plugin>/skills/<skill-name>/SKILL.md`  | Bundled third-party automations            | Namespaced (`plugin:skill`) |
+| **Legacy**     | `./.claude/commands/*.md`                | Deprecated command definitions             | Overridden by Skills        |
+
+## 3. Syntax & Commands (Hard Constraints)
+
+- **Mandatory Commands & Environment Variables:**
+- `/<skill-name>`: CLI invocation of a specific skill.
+- `/context`: Audits context budget and warns if skills are excluded due to character limits.
+- `SLASH_COMMAND_TOOL_CHAR_BUDGET`: Env var to override the default 16,000 character skill description context limit.
+- `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`: Env var required to load skills from `--add-dir` paths.
+
+- **Special Syntax Rules (Conditional constraints, Frontmatter):**
+- **YAML Frontmatter Fields (Top of `SKILL.md`):**
+
+```yaml
+---
+name: string # Max 64 chars (a-z, 0-9, -). Defaults to dir name.
+description: string # Recommended. Used by LLM for auto-triggering.
+disable-model-invocation: boolean # Default false. True = Manual CLI trigger only.
+user-invocable: boolean # Default true. False = Hidden from UI, LLM trigger only.
+allowed-tools: string # CSV list (e.g., Read, Grep, Bash).
+context: fork # Spawns skill in an isolated subagent context.
+agent: string # Subagent type. Requires `context: fork`. Valid values: general-purpose, Explore, Plan, claude-code-guide, etc.
+---
+```
+
+- **String Substitution Variables:**
+- `$ARGUMENTS`: Injects all provided CLI arguments. (If omitted in template, appended as `ARGUMENTS: <value>`).
+- `$ARGUMENTS[N]` or `$N`: Positional argument injection (0-based index).
+- `${CLAUDE_SESSION_ID}`: Injects the current active session ID.
+
+- **Dynamic Context Injection:**
+- `!`command``: Executes shell command _before_ prompt ingestion. Output permanently replaces the placeholder in the prompt fed to the LLM.
+
+- **Permission Target Matching (`/permissions`):**
+- `Skill(name)`: Exact match.
+- `Skill(name *)`: Prefix match with any arguments.
+
+- **Caveats & Constraints (Critical rules to prevent Fatal Errors):**
+- **Subagent Forking Constraints:** `context: fork` requires explicit, actionable task instructions within the markdown body. Purely declarative guidelines (e.g., coding standards) will cause the subagent to return empty/meaningless output.
+- **Payload Limits:** `SKILL.md` entrypoints must be kept under 500 lines. Overflow logic/data must be referenced in external supporting files (e.g., `reference.md`) within the skill directory.
+- **Extended Thinking:** To enable thinking mode for a specific skill, the exact string `"ultrathink"` must be present in the skill content.

package/data/references/codex/best-practices/context-optimization.md

@@ -0,0 +1,120 @@
+# Agent Context Optimization Strategies (Codex)
+
+This document defines practical patterns for minimizing instruction payload while preserving rule fidelity in Codex AGENTS.md-based workflows.
+
+## The Challenge: Instruction Bloat
+
+Codex builds the instruction chain once at run start, then executes with that merged payload. In large monorepos, broad AGENTS files can create:
+
+1. Token waste from irrelevant domain rules.
+2. Lower instruction salience from high-density prompts.
+3. Hard truncation risk when `project_doc_max_bytes` is reached.
+
+## Codex Loading Model (Why Optimization Works)
+
+From `references/codex/rules.md`, the important mechanics are:
+
+- Discovery scope: global + project path from repo root to current working directory (CWD).
+- Merge order: root to CWD (later files naturally override earlier ones).
+- Directory ceiling: only one instruction file per directory (`AGENTS.override.md` > `AGENTS.md` > fallback names).
+- Byte ceiling: concatenation stops when `project_doc_max_bytes` is hit (default `32768`).
+
+These constraints make path and file placement the primary optimization levers.
+
+## Solution 1: CWD-Scoped Execution (Preferred)
+
+Run Codex from the narrowest directory that matches the task.
+
+```bash
+codex --cd packages/frontend "Implement the new settings panel."
+codex --cd packages/backend "Add FastAPI pagination to list endpoint."
+```
+
+Effect:
+
+- Loads only global + root-to-target-directory instructions.
+- Excludes unrelated sibling-domain instruction files by construction.
+
+## Solution 2: Hierarchical Rule Partitioning
+
+Keep global instructions minimal and push domain rules down the tree.
+
+Recommended layout:
+
+```txt
+repo/
+  AGENTS.md                      # global: persona, communication, universal guardrails
+  packages/
+    frontend/
+      AGENTS.md                  # frontend-specific standards
+    backend/
+      AGENTS.md                  # backend-specific standards
+    data-pipeline/
+      AGENTS.md                  # data/ETL-specific standards
+```
+
+Guidelines:
+
+- Root AGENTS: only cross-cutting rules needed for every task.
+- Subdirectory AGENTS: only rules needed inside that subtree.
+- Avoid duplicating large shared blocks across multiple directories.
+
+## Solution 3: Budget-Aware Instruction Design
+
+Treat `project_doc_max_bytes` as a strict budget, not a soft target.
+
+Guidelines:
+
+- Keep each AGENTS file concise and non-redundant.
+- Move large reference content out of AGENTS into external docs.
+- Keep AGENTS focused on executable constraints and decision rules.
+- Raise `project_doc_max_bytes` only after sharding is exhausted.
+
+## Solution 4: Manual Lazy-Loading via Rule Registry (Fallback)
+
+For heavy or cross-cutting guidance that cannot be cleanly path-scoped, keep only an index in AGENTS and require on-demand reads.
+
+Example registry snippet for root `AGENTS.md`:
+
+```markdown
+# Dynamic Rule Loading (Critical)
+
+Do not guess architecture or style constraints.
+Before editing code, read the relevant rule files from:
+`packages/compiler/data/rules/*.yaml`
+
+Mapping:
+
+- Python/Backend: `python.yaml`, `fastapi.yaml`, `libs-backend-python.yaml`
+- React/Frontend: `react-typescript.yaml`, `nextjs.yaml`, `shadcn-ui.yaml`
+- Database: `sqlalchemy.yaml` or `prisma-postgresql.yaml`
+- GraphQL: `graphql.yaml`, `nestjs-graphql.yaml`
+```
+
+This preserves a small base context while still enforcing domain rules when needed.
+
+## Verification Loop
+
+Use runtime checks to confirm active context and prevent hidden overloading:
+
+```bash
+codex --ask-for-approval never "Summarize the current instructions."
+codex --cd <dir> --ask-for-approval never "Show which instruction files are active."
+```
+
+## Decision Matrix
+
+| Scenario                                  | Recommended Strategy |
+| ----------------------------------------- | -------------------- |
+| Task is isolated to one package/subtree   | Solution 1 + 2       |
+| Rules map cleanly to directory boundaries | Solution 2           |
+| AGENTS payload approaches byte cap        | Solution 3           |
+| Rules are cross-cutting and high-volume   | Solution 4           |
+
+## Summary
+
+- Do scope execution with `--cd` to minimize loaded instruction chain.
+- Do keep root AGENTS minimal; move specialized rules to deeper directories.
+- Do design for `project_doc_max_bytes` proactively.
+- Do use a rule registry + on-demand reads for heavy guidance.
+- Do not place large, domain-specific rule bodies in global AGENTS.