oh-my-customcodex 0.1.9 → 0.2.1

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-48 agents. 109 skills. 22 rules. One command.
+48 agents. 112 skills. 22 rules. One command.
 
 ```bash
 npm install -g oh-my-customcodex && cd your-project && omcodex init
@@ -132,7 +132,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (109)
+### Skills (112)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -225,7 +225,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (38)
+### Guides (40)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -282,7 +282,11 @@ your-project/
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 38 reference documents
+<<<<<<< HEAD
+└── guides/                     # 40 reference documents
+=======
+└── guides/                     # 40 reference documents
+>>>>>>> origin/develop
 ```
 
 ---

package/dist/cli/index.js

@@ -3087,7 +3087,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.1.9",
+    version: "0.2.1",
     description: "Batteries-included agent harness on top of GPT Codex + OMX",
     type: "module",
     bin: {

package/dist/index.js

@@ -2173,7 +2173,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.1.9",
+  version: "0.2.1",
   description: "Batteries-included agent harness on top of GPT Codex + OMX",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "Batteries-included agent harness on top of GPT Codex + OMX",
   "type": "module",
   "bin": {

package/templates/.claude/hooks/hooks.json

@@ -105,6 +105,10 @@
       {
         "matcher": "tool == \"Task\" || tool == \"Agent\"",
         "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/agent-mode-guard.sh"
+          },
           {
             "type": "command",
             "command": "#!/bin/bash\ninput=$(cat)\nagent_type=$(echo \"$input\" | jq -r '.tool_input.subagent_type // \"unknown\"')\nmodel=$(echo \"$input\" | jq -r '.tool_input.model // \"inherit\"')\ndesc=$(echo \"$input\" | jq -r '.tool_input.description // \"\"' | head -c 40)\nresume=$(echo \"$input\" | jq -r '.tool_input.resume // empty')\nif [ -n \"$resume\" ]; then\n  echo \"─── [Resume] ${agent_type}:${model} | ${desc} ───\" >&2\nelse\n  echo \"─── [Spawn] ${agent_type}:${model} | ${desc} ───\" >&2\nfi\necho \"$input\""
@@ -336,6 +340,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "tool matches \"^mcp__playwright__\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex/hooks/scripts/playwright-compress.sh"
+          }
+        ],
+        "description": "Compress verbose Playwright MCP output while preserving refs and URLs"
+      },
       {
         "matcher": "tool == \"Bash\"",
         "hooks": [

package/templates/.claude/hooks/scripts/agent-mode-guard.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Agent mode guard
+# Blocks Agent/Task spawns that omit mode:"bypassPermissions".
+# This closes the gap where frontmatter permissionMode is ignored unless the
+# spawn call sets mode explicitly.
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+input=$(cat)
+mode=$(echo "$input" | jq -r '.tool_input.mode // ""')
+
+if [ "$mode" != "bypassPermissions" ]; then
+  echo "[Hook] BLOCKED: Agent/Task spawn missing required mode: \"bypassPermissions\"" >&2
+  echo "[Hook] Saw mode: ${mode:-<missing>}" >&2
+  echo "[Hook] The Agent tool defaults to acceptEdits and will trigger permission prompts." >&2
+  echo "[Hook] Fix the spawn call by adding: mode: \"bypassPermissions\"" >&2
+  exit 2
+fi
+
+echo "$input"

package/templates/.claude/hooks/scripts/playwright-compress.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+set -euo pipefail
+
+input=$(cat)
+tool_name=$(echo "$input" | jq -r '.tool_name // .tool // ""')
+
+if [[ ! "$tool_name" =~ ^mcp__playwright__ ]]; then
+  exit 0
+fi
+
+raw_output=$(echo "$input" | jq -c '.tool_response // .tool_output.output // .tool_output // empty')
+
+if [ -z "$raw_output" ] || [ "$raw_output" = "null" ]; then
+  exit 0
+fi
+
+text_output=$(printf '%s' "$raw_output" | jq -r 'if type == "string" then . else tostring end')
+min_chars=${PLAYWRIGHT_COMPRESS_MIN_CHARS:-3000}
+
+if [ "${#text_output}" -lt "$min_chars" ]; then
+  exit 0
+fi
+
+ref_matches=$(printf '%s\n' "$text_output" | grep -oE 'ref[=:]"?[^", ]+' || true)
+refs=$(printf '%s\n' "$ref_matches" \
+  | sed 's/^ref[=:]"*/ref=/' \
+  | awk 'length($0) > 0 && !seen[$0]++' \
+  | head -12 \
+  | paste -sd ', ' -)
+
+url_matches=$(printf '%s\n' "$text_output" | grep -oE 'https?://[^" )]+' || true)
+urls=$(printf '%s\n' "$url_matches" \
+  | awk 'length($0) > 0 && !seen[$0]++' \
+  | head -6 \
+  | paste -sd ', ' -)
+
+important_matches=$(printf '%s\n' "$text_output" | grep -iE 'ref=|error|failed|warning|timeout|assert|url|title|text|name|role|selector' || true)
+important_lines=$(printf '%s\n' "$important_matches" \
+  | sed 's/^[[:space:]]*//; s/[[:space:]]\+/ /g' \
+  | awk 'length($0) > 0 && !seen[$0]++' \
+  | head -25)
+
+if [ -z "$important_lines" ]; then
+  important_lines=$(printf '%s\n' "$text_output" \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]\+/ /g' \
+    | awk 'length($0) > 0 && !seen[$0]++' \
+    | head -20)
+fi
+
+if [ -z "$important_lines" ]; then
+  important_lines='(no high-signal lines detected; payload was compressed by fallback rules)'
+fi
+
+summary=$(
+  {
+    printf 'Playwright MCP output compressed.\n'
+    printf 'Original size: %s chars.\n' "${#text_output}"
+    if [ -n "$refs" ]; then
+      printf 'Preserved refs: %s\n' "$refs"
+    fi
+    if [ -n "$urls" ]; then
+      printf 'URLs: %s\n' "$urls"
+    fi
+    printf '\nHigh-signal lines:\n'
+    printf '%s\n' "$important_lines"
+  } | head -c "${PLAYWRIGHT_COMPRESS_MAX_CHARS:-2500}"
+)
+
+if [ -z "$summary" ]; then
+  exit 0
+fi
+
+jq -n \
+  --arg summary "$summary" \
+  --arg note "Playwright MCP output compressed to preserve refs and reduce context cost." \
+  '{
+    additionalContext: $note,
+    updatedMCPToolOutput: $summary
+  }'

package/templates/.claude/skills/design-shotgun/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: design-shotgun
+description: Generate and compare multiple deliberate UI directions before converging on one implementation path
+scope: core
+user-invocable: true
+argument-hint: "<screen-or-flow>"
+---
+
+# Design Shotgun
+
+Use this skill when one polished mockup is too early and the real need is breadth first. The goal is not random variety; it is structured divergence followed by deliberate convergence.
+
+## When To Use
+
+- early UI exploration
+- redesign of a high-visibility screen
+- style selection before implementation
+- multiple viable directions need comparison
+
+## Workflow
+
+### 1. Pick comparison axes
+
+Choose 2-3 axes that should differ between options:
+
+- editorial vs. utilitarian
+- dense vs. spacious
+- bold vs. restrained
+- product-led vs. workflow-led
+
+### 2. Generate 4-6 directions
+
+Each direction should differ materially in:
+
+- hierarchy
+- composition
+- copy tone
+- motion or interaction emphasis
+
+Avoid trivial color-swaps.
+
+### 3. Compare on one board
+
+For each direction, record:
+
+- strongest move
+- weakest move
+- what kind of user it favors
+- what should survive into the final hybrid
+
+### 4. Build taste memory
+
+Preserve:
+
+- chosen typography moves
+- preferred spacing rhythm
+- colors or motifs worth keeping
+- rejected patterns to avoid repeating
+
+### 5. Converge
+
+Produce one implementation direction with:
+
+- headline design thesis
+- components to build first
+- references to related guides or skills
+
+## Related References
+
+- `.codex/skills/impeccable-design/SKILL.md`
+- `.codex/skills/web-design-guidelines/SKILL.md`
+- `guides/browser-automation/README.md` for consistent browser-based comparison capture

package/templates/.claude/skills/intent-detection/patterns/agent-triggers.yaml

@@ -307,6 +307,30 @@ agents:
   # ---------------------------------------------------------------------------
   # Research / Information Gathering (skill-based, not agent)
   # ---------------------------------------------------------------------------
+  wiki-rag:
+    keywords:
+      korean:
+        - 아키텍처
+        - 워크플로우
+        - 어떤 에이전트
+        - 어떤 스킬
+        - 규칙
+      english:
+        - architecture
+        - workflow
+        - "which agent"
+        - "which skill"
+        - rule
+        - "how does this work"
+    file_patterns: []
+    supported_actions:
+      - explain
+      - search
+      - investigate
+      - research
+    base_confidence: 80
+    routing_rule: "Use wiki-rag for architecture, workflow, agent, skill, and rule questions before broader exploration"
+
   research-workflow:
     keywords:
       korean:
@@ -369,6 +393,90 @@ agents:
     action_weight: 25
     routing_rule: "Suggest codex-exec hybrid when codex available, or gemini-exec hybrid when gemini available, for new file creation tasks"
 
+  product-strategy:
+    keywords:
+      korean:
+        - 제품 전략
+        - 오피스 아워
+        - 창업자 질문
+        - CEO 리뷰
+        - 범위 축소
+      english:
+        - "product strategy"
+        - "office hours"
+        - "ceo review"
+        - "founder questions"
+        - "scope reduction"
+    file_patterns: []
+    supported_actions:
+      - analyze
+      - plan
+      - review
+      - reduce
+    base_confidence: 65
+    routing_rule: "Use the product-strategy skill to pressure-test product bets before implementation"
+
+  design-shotgun:
+    keywords:
+      korean:
+        - 디자인 샷건
+        - 시안 비교
+        - 테이스트 메모리
+        - 방향 비교
+      english:
+        - "design shotgun"
+        - "compare directions"
+        - "taste memory"
+        - "variation board"
+    file_patterns: []
+    supported_actions:
+      - create
+      - compare
+      - review
+      - polish
+    base_confidence: 65
+    routing_rule: "Use the design-shotgun skill for multi-direction UI exploration before converging on one implementation"
+
+  browser-automation-reference:
+    keywords:
+      korean:
+        - 브라우저 자동화
+        - 쿠키 임포트
+        - 안티봇
+        - 세션 재사용
+      english:
+        - "browser automation guide"
+        - "cookie import"
+        - anti-bot
+        - "session reuse"
+    file_patterns: ["playwright.config.ts", "*.pw.ts"]
+    supported_actions:
+      - explain
+      - review
+      - investigate
+    base_confidence: 55
+    routing_rule: "Consult guides/browser-automation/README.md and existing Playwright surfaces before implementing browser-session workflows"
+
+  playwright-compress:
+    keywords:
+      korean:
+        - 플레이라이트 압축
+        - 브라우저 출력 압축
+        - ref 보존
+        - MCP 압축
+      english:
+        - "playwright compress"
+        - "browser output compression"
+        - "preserve refs"
+        - "mcp compression"
+    file_patterns: ["playwright.config.ts", "*.pw.ts"]
+    supported_actions:
+      - optimize
+      - compress
+      - review
+    base_confidence: 60
+    routing_rule: "Use the playwright-compress skill when Playwright MCP output is verbose and refs must remain actionable"
+
   # Managers (continued)
   mgr-gitnerd:
     keywords:

package/templates/.claude/skills/playwright-compress/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: playwright-compress
+description: Compress verbose Playwright MCP output while preserving element refs and actionable browser evidence
+scope: core
+user-invocable: true
+argument-hint: "[status]"
+---
+
+# Playwright Compress
+
+This skill documents the Codex-native pattern for shrinking verbose Playwright MCP output without destroying the references needed for follow-up interaction.
+
+## Purpose
+
+- keep `ref=` tokens visible
+- reduce repetitive browser snapshots and logs
+- preserve URLs, errors, and key visible text
+- complement runtime token controls instead of replacing them
+
+## Runtime Surface
+
+The implementation lives in:
+
+- `.codex/hooks/scripts/playwright-compress.sh`
+- `.codex/hooks/hooks.json`
+
+It runs on `PostToolUse` for Playwright MCP tools and returns `updatedMCPToolOutput` when the payload is large enough to benefit from compression.
+
+## Compression Policy
+
+- Leave short outputs untouched.
+- Preserve `ref=` tokens and URLs.
+- Prefer high-signal lines over bulk DOM noise.
+- Keep failure evidence verbatim where possible.
+- Never send browser session secrets to external services.
+
+## Use Cases
+
+- browser snapshot output is too large to keep in context
+- a page contains many repeated nodes but only a few actionable refs
+- follow-up tool calls need a compact view of visible evidence
+
+## Related References
+
+- `guides/claude-code/14-token-efficiency.md`
+- `guides/browser-automation/README.md`

package/templates/.claude/skills/product-strategy/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: product-strategy
+description: YC-style product pressure test and scope framing for ideas, features, and workflow bets
+scope: core
+user-invocable: true
+argument-hint: "<idea-or-feature>"
+---
+
+# Product Strategy
+
+Use this skill when a request needs product pressure, not immediate implementation. It borrows the useful part of the "office hours" pattern: force the conversation to answer hard product questions before work expands.
+
+## When To Use
+
+- feature framing
+- product tradeoff review
+- CEO / founder style pressure test
+- scope negotiation before implementation
+
+## Workflow
+
+### 1. State the bet
+
+Write the feature or idea in one sentence:
+
+- who it is for
+- what changes for them
+- why it matters now
+
+### 2. Run the six questions
+
+Answer these before moving forward:
+
+1. What user pain becomes meaningfully smaller?
+2. Why will the user notice this quickly?
+3. What simpler alternative did we reject?
+4. What metric or behavior would prove this worked?
+5. What gets harder if we ship this?
+6. What would we deliberately not build in v1?
+
+### 3. Choose a scope mode
+
+Assign one mode:
+
+- `Expand` — increase ambition because the upside justifies it
+- `Selective` — keep only the highest-signal slice
+- `Hold` — wait for a prerequisite or stronger evidence
+- `Reduce` — cut scope because the current ask is inflated
+
+### 4. Output contract
+
+Return:
+
+- problem statement
+- strongest argument for shipping
+- strongest argument against shipping
+- chosen scope mode
+- next 2-3 concrete actions
+
+## Related References
+
+- `guides/browser-automation/README.md` for grounded product review through real browser flows
+- `.codex/skills/deep-plan/SKILL.md` for implementation planning once the strategy is accepted

package/templates/CLAUDE.md

@@ -119,7 +119,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (R000-R022)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (38 토픽)
++-- guides/                      # 레퍼런스 문서 (39 토픽)
 ```
 
 ## 오케스트레이션

package/templates/CLAUDE.md.en

@@ -136,7 +136,7 @@ project/
 |   +-- rules/                   # Global rules (22 files)
 |   +-- hooks/                   # Hook scripts (security, validation, HUD)
 |   +-- contexts/                # Context files (4 files)
-+-- guides/                      # Reference docs (38 topics)
++-- guides/                      # Reference docs (39 topics)
 ```
 
 ## Orchestration

package/templates/CLAUDE.md.ko

@@ -136,7 +136,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (22 파일)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (4 파일)
-+-- guides/                      # 레퍼런스 문서 (38 토픽)
++-- guides/                      # 레퍼런스 문서 (39 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/browser-automation/README.md

@@ -0,0 +1,113 @@
+# Browser Automation
+
+This guide captures the browser-automation patterns that are useful in `oh-my-customcodex` without importing an external browser-control stack wholesale. It is intentionally pragmatic: keep the browser session real enough to validate user flows, but do not turn automation into a second product inside the harness.
+
+## Core Principles
+
+### 1. Prefer existing browser surfaces
+
+Start from the browser tooling the repository already has:
+
+- Playwright tests under `packages/serve/tests/`
+- the repository Playwright config at `packages/serve/playwright.config.ts`
+- the `playwright` skill and any existing MCP/browser surfaces
+
+Do not add a separate browser orchestration system unless the current surfaces are clearly insufficient.
+
+### 2. Treat authenticated sessions as sensitive
+
+Cookies, session storage, and browser profiles are credentials.
+
+- Never commit cookies, storage state, or exported browser profiles.
+- Keep imported cookies in ignored local files or ephemeral temp directories.
+- Strip secrets from screenshots, logs, and copied traces before sharing them.
+
+### 3. Anti-bot measures are for resilience, not abuse
+
+Use browser automation to validate real product flows and reproduce bugs. Do not optimize for adversarial scraping or abusive evasion.
+
+Allowed patterns:
+
+- realistic viewport and locale settings
+- waiting for stable DOM state instead of brittle sleeps
+- authenticated session reuse for testing flows behind login
+- evidence capture for failures
+
+Avoid:
+
+- aggressive stealth plugins with unclear behavior
+- retry storms against rate-limited or protected sites
+- automation that bypasses product safeguards
+
+## Cookie And Session Handling
+
+### Importing cookies
+
+When a flow requires an existing session:
+
+1. Export only the minimum cookies needed.
+2. Store them outside tracked files.
+3. Load them into a fresh browser context rather than a shared global context.
+
+### Isolate contexts
+
+Use one browser context per scenario or per worker:
+
+- prevents cross-test leakage
+- makes failures reproducible
+- keeps captured evidence attributable to one flow
+
+### Prefer storage state snapshots for repeatable tests
+
+If a workflow is run often, promote manual cookie import into a reproducible storage-state fixture rather than redoing browser login ad hoc.
+
+## Evidence Capture
+
+Browser automation is only useful if it leaves evidence behind.
+
+Capture at least one of:
+
+- screenshot on failure
+- console logs
+- network failures
+- trace or HAR when the flow is flaky
+- the exact page URL and visible state when an assertion fails
+
+When summarizing evidence for the model, preserve reference tokens and URLs so follow-up steps can still target the right page elements.
+
+## Design And Strategy Workflows
+
+### Product strategy sessions
+
+Browser automation is helpful when a product-strategy review needs to ground abstract questions in the actual product surface:
+
+- what the first-time user sees
+- where onboarding friction appears
+- how many decisions a user must make before value
+
+### Design shotgun sessions
+
+Use browser capture to compare alternatives consistently:
+
+- same viewport
+- same user state
+- same content seed
+- same evidence format
+
+That keeps visual comparisons honest and makes "taste memory" reusable.
+
+## Operational Checklist
+
+- Use an isolated browser context.
+- Keep credentials out of tracked files.
+- Capture evidence for every meaningful failure.
+- Reuse existing Playwright surfaces before adding new tooling.
+- Prefer stable selectors and deterministic waits over timing hacks.
+
+## Related Surfaces
+
+- `.codex/skills/product-strategy/SKILL.md`
+- `.codex/skills/design-shotgun/SKILL.md`
+- `.codex/skills/playwright-compress/SKILL.md`
+- `guides/web-scraping/README.md`
+- `packages/serve/playwright.config.ts`

package/templates/guides/browser-automation/index.yaml

@@ -0,0 +1,20 @@
+# Browser Automation Guide
+
+metadata:
+  name: browser-automation
+  description: Browser automation patterns for authenticated sessions, cookie handling, and evidence capture
+
+source:
+  type: internal
+
+topics:
+  - authenticated-sessions
+  - cookie-import
+  - anti-bot-caution
+  - evidence-capture
+  - session-isolation
+
+used_by:
+  - product-strategy
+  - design-shotgun
+  - playwright-compress

package/templates/guides/claude-code/14-token-efficiency.md

@@ -1,6 +1,6 @@
 # Token Efficiency Layers
 
-Token efficiency in oh-my-customcodex has three layers. They solve different problems and should not be mixed together blindly.
+Token efficiency in oh-my-customcodex has four layers. They solve different problems and should not be mixed together blindly.
 
 ## Layer 1: Plugin-Level Protection
 
@@ -22,7 +22,19 @@ Use R013 ecomode and existing runtime guards when you want to compress active-se
 
 This layer changes how the session behaves while work is running.
 
-## Layer 3: Settings-Level Optimization
+## Layer 3: Tool-Specific Compression
+
+Use `playwright-compress` when the problem is not the whole session, but one extremely verbose browser tool result.
+
+This layer is intentionally narrow:
+
+- compress verbose Playwright MCP output after the tool succeeds
+- preserve `ref=` tokens and URLs for follow-up interaction
+- keep browser evidence actionable without keeping the full raw payload in context
+
+This layer complements runtime compression instead of replacing it.
+
+## Layer 4: Settings-Level Optimization
 
 Use `/token-efficiency-audit` when you want configuration-level changes before the session burns tokens.
 
@@ -52,12 +64,14 @@ Typical settings-level levers:
 |------|------------|
 | Protect cache value across pauses | Layer 1 |
 | Compress runtime behavior in large sessions | Layer 2 |
-| Reduce baseline token spend from configuration | Layer 3 |
+| Compress one noisy browser interaction | Layer 3 |
+| Reduce baseline token spend from configuration | Layer 4 |
 
 Use layers together, but keep responsibilities separate:
 
 - plugin layer for cache and resume
 - runtime layer for in-session behavior
+- tool-specific layer for noisy browser interactions
 - settings layer for pre-session defaults
 
 ## Tradeoffs

package/templates/guides/index.yaml

@@ -34,6 +34,12 @@ guides:
       origin: github
       url: https://github.com/vercel-labs/agent-skills
 
+  - name: browser-automation
+    description: Browser automation patterns for authenticated sessions, cookie handling, and evidence capture
+    path: ./browser-automation/
+    source:
+      type: internal
+
   # Languages
   - name: golang
     description: Go language reference from Effective Go
@@ -51,6 +57,14 @@ guides:
       origin: docs.oracle.com
       url: https://docs.oracle.com/en/java/javase/21/
 
+  - name: java
+    description: Java 25 LTS language reference and modern feature documentation
+    path: ./java/
+    source:
+      type: external
+      origin: docs.oracle.com
+      url: https://docs.oracle.com/en/java/javase/25/
+
   - name: python
     description: Python reference from PEP 8 and PEP 20
     path: ./python/

package/templates/guides/java/index.yaml

@@ -0,0 +1,29 @@
+# Java Guide
+
+metadata:
+  name: java
+  description: Java 25 LTS language reference and modern feature documentation
+
+source:
+  type: external
+  origin: docs.oracle.com
+  urls:
+    - https://docs.oracle.com/en/java/javase/25/
+    - https://openjdk.org/projects/loom/
+    - https://openjdk.org/jeps/440
+    - https://openjdk.org/jeps/441
+    - https://openjdk.org/jeps/444
+    - https://google.github.io/styleguide/javaguide.html
+  last_fetched: "2026-04-20"
+
+documents:
+  - name: modern-java
+    path: ./modern-java.md
+    description: Java 25 LTS modern features (Virtual Threads, Pattern Matching, Records, Sealed Classes)
+
+  - name: java-style-guide
+    path: ./java-style-guide.md
+    description: Google Java Style Guide conventions
+
+used_by:
+  - lang-java-expert

package/templates/guides/java/java-style-guide.md

@@ -0,0 +1,35 @@
+# Google Java Style Guide Notes
+
+> Source: https://google.github.io/styleguide/javaguide.html
+
+## Core Conventions
+
+- Indent with 2 spaces, never tabs
+- Use `UpperCamelCase` for classes, `lowerCamelCase` for methods and fields
+- Constants use `UPPER_SNAKE_CASE`
+- Prefer one top-level type per file
+- Keep line length readable and wrap before expressions become visually dense
+
+## Imports
+
+- No wildcard imports
+- Static imports come before non-static imports
+- Keep imports sorted ASCII-style within each block
+
+## Braces
+
+- Opening brace stays on the same line
+- Always use braces for `if`, `for`, `while`, and `do`
+
+## Classes And Members
+
+- Order members consistently: constants, fields, constructors, public methods, private helpers
+- Prefer immutable fields where possible
+- Document non-obvious public API behavior with Javadoc
+
+## Naming
+
+- Packages: lowercase, no underscores
+- Types: nouns or noun phrases
+- Methods: verbs or verb phrases
+- Test methods: describe behavior, not implementation detail

package/templates/guides/java/modern-java.md

@@ -0,0 +1,71 @@
+# Modern Java Features
+
+> Sources: https://openjdk.org/jeps/ (JEP 431, 440, 441, 444)
+
+## Virtual Threads (JEP 444)
+
+Virtual Threads are lightweight threads managed by the JVM, enabling millions of concurrent tasks without thread pool tuning.
+
+### Key Properties
+
+| Property | Platform Thread | Virtual Thread |
+|----------|----------------|----------------|
+| Creation cost | High (OS thread) | Low (JVM-managed) |
+| Memory footprint | ~1MB per thread | ~few KB |
+| Blocking behavior | Blocks OS thread | Unmounts carrier thread |
+| Pooling | Needed | Not recommended |
+
+### Usage
+
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<String>> futures = IntStream.range(0, 10_000)
+        .mapToObj(i -> executor.submit(() -> fetchData(i)))
+        .toList();
+}
+
+Thread.ofVirtual().name("vt-worker").start(() -> processRequest());
+```
+
+## Pattern Matching
+
+```java
+if (obj instanceof String s && !s.isEmpty()) {
+    return s.toUpperCase();
+}
+
+String format = switch (obj) {
+    case Integer i -> "int %d".formatted(i);
+    case String s -> "string %s".formatted(s);
+    case null -> "null";
+    default -> obj.toString();
+};
+```
+
+## Records
+
+```java
+record Point(int x, int y) {}
+
+record Range(int min, int max) {
+    Range {
+        if (min > max) {
+            throw new IllegalArgumentException("min > max");
+        }
+    }
+}
+```
+
+## Sealed Types
+
+```java
+sealed interface Shape permits Circle, Rectangle {}
+
+record Circle(double radius) implements Shape {}
+record Rectangle(double width, double height) implements Shape {}
+```
+
+## Sequenced Collections
+
+- Prefer `getFirst()` / `getLast()` over index arithmetic for ordered collections
+- Use `reversed()` when reverse traversal is the intent

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.9",
+  "version": "0.2.1",
   "lastUpdated": "2026-04-19T08:50:00.000Z",
   "components": [
     {
@@ -18,13 +18,13 @@
       "name": "skills",
       "path": ".codex/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 109
+      "files": 112
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 38
+      "files": 40
     },
     {
       "name": "hooks",