oh-my-customcode 0.101.0 → 0.103.0

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

@@ -0,0 +1,187 @@
+# Token Efficiency — Three-Layer Defense Stack
+
+> **Source**: [Claude Code & Codex token efficiency by settings adjustment](https://www.stdy.blog/increasing-token-efficiency-by-setting-adjustment-in-claude-and-codex/)
+> **Reference baseline**: Claude Code v2.1.114+ / Codex v0.121.0+
+
+## Why This Matters
+
+Token spend in Claude Code is not purely a function of task complexity. A significant portion of token consumption occurs through structural overhead: auto-injected git instructions, IDE file listings, tool output that exceeds what the model actually needs, and session state reloaded unnecessarily across turns.
+
+The three-layer defense stack addresses this overhead at three distinct points in the session lifecycle:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Layer 1: cc-token-saver (CACHE DEFENSE)                        │
+│  Before session — protect prompt cache TTL from idle expiry     │
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 2: R013 Ecomode (RUNTIME COMPRESSION)                    │
+│  During session — compact output, aggregate results, prune input│
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 3: Settings-Based Gates (PRE-SESSION PREVENTION)         │
+│  Config time — disable injections before they happen            │
+├─────────────────────────────────────────────────────────────────┤
+│  Layer 4: playwright-compress (MCP OUTPUT INTELLIGENCE)         │
+│  PostToolUse hook — Haiku summarization of browser MCP output   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Each layer is independently deployable and non-overlapping. Together they form a complete defense.
+
+---
+
+## Layer 1: cc-token-saver (Prompt Cache TTL Guard)
+
+**What it does:** Detects when the 1-hour prompt cache TTL is about to expire due to idle time. Warns before cache invalidates, preventing a full re-spend on the next turn.
+
+**Why it matters:** Claude Code's prompt cache has a 1-hour TTL on idle. If you pause a long session, the entire cached context must be re-processed at full cost on the next message. cc-token-saver intercepts this.
+
+**Key features:**
+- Token Guardian: idle TTL detection and warning
+- `/continue`: zero-cost context restore after session pause
+- `/usage-view`: cost dashboard for session/cumulative spend
+
+**When to use:** Always — install as a plugin and leave active.
+
+**Reference:** `guides/cc-token-saver/README.md`
+
+---
+
+## Layer 2: R013 Ecomode (Runtime Behavior Compression)
+
+**What it does:** Compresses agent output at runtime — compact result format, aggregated multi-agent results, and active pruning of irrelevant input context.
+
+**Why it matters:** Without ecomode, subagents return verbose outputs that accumulate across parallel invocations. At 4+ concurrent agents, unchecked output grows the context window rapidly.
+
+**Activation triggers:**
+- 4+ parallel tasks running simultaneously
+- Batch operations on independent targets
+- Context usage approaching 80%
+- Explicit "ecomode on"
+
+**Key behaviors:**
+- Agents return `status + 1-2 sentence summary + key_data only`
+- File lists compressed to count (when > 5 files)
+- Error traces: first/last 3 lines only
+- Code references: `path:line` ref instead of full block
+
+**When to use:** Auto-activates on threshold — configure threshold in ecomode config if needed.
+
+**Reference:** `.claude/rules/SHOULD-ecomode.md` (R013)
+
+---
+
+## Layer 3: Settings-Based Gates (Pre-Session Prevention)
+
+**What it does:** Disables token-consuming injections and sets output caps in configuration files before sessions start. These gates prevent overhead from ever entering the context window.
+
+**Why it matters:** Certain Claude Code defaults inject tokens on every session start regardless of whether they are needed:
+- `includeGitInstructions: true` (default) injects git workflow context on every session
+- `autoConnectIde: true` injects file lists from connected IDEs
+- Uncapped `BASH_MAX_OUTPUT_LENGTH` allows tool output to flood the context
+
+**How to apply:** `token-efficiency-audit` skill — see `.claude/skills/token-efficiency-audit/SKILL.md`
+
+---
+
+## Lever Reference Table
+
+### Interactive Session Levers (safe for development)
+
+| Lever | Location | Default | Recommended | Token Impact | Risk |
+|-------|----------|---------|-------------|-------------|------|
+| `includeGitInstructions` | settings.json | `true` | `false` | Medium — removes git workflow injection | None for most projects |
+| `autoConnectIde` | settings.json | `true` | `false` | Low — removes IDE file list injection | Loses IDE file awareness |
+| `attribution.commit` | settings.json | auto text | `""` | Low — removes attribution boilerplate | None |
+| `attribution.pr` | settings.json | auto text | `""` | Low — removes attribution boilerplate | None |
+| `BASH_MAX_OUTPUT_LENGTH` | env | unlimited | `15000` | High — caps bash output | Output truncated if > 15000 chars |
+| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | env | unlimited | `8000` | Medium — caps file read output | Large files truncated |
+| `MAX_MCP_OUTPUT_TOKENS` | env | unlimited | `8000` | Medium — caps MCP output | MCP results truncated |
+| `CLAUDE_CODE_GLOB_NO_IGNORE` | env | `true` | `false` | Low — respects .gitignore | Fewer files visible in globs |
+
+### CI/Worker-Only Levers (destructive — disables oh-my-customcode)
+
+> These settings disable core oh-my-customcode functionality. **Never apply to interactive sessions.**
+
+| Lever | What it disables | Token impact | oh-my-customcode impact |
+|-------|-----------------|-------------|------------------------|
+| `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` | All `.claude/*.md` files including CLAUDE.md | High | ALL global rules and routing offline |
+| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1` | Built-in agent definitions | High | All 48 agents unavailable |
+| `ENABLE_CLAUDEAI_MCP_SERVERS=false` | MCP server connections | Medium | MCP-dependent skills unavailable |
+| `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` | Agent auto-memory | Low | No persistent memory across sessions |
+
+### Codex CLI Levers
+
+| Lever | Location | Default | Recommended | Token Impact |
+|-------|----------|---------|-------------|-------------|
+| `features.apps` | config.toml | `true` | `false` | Medium |
+| `apps._default.enabled` | config.toml | `true` | `false` | Medium |
+| `web_search` | config.toml | `"auto"` | `"disabled"` | Medium — web search adds significant context |
+| `tool_output_token_limit` | config.toml | `10000` | `10000` | High — do not lower below 5000 |
+
+---
+
+## Tradeoffs and Guardrails
+
+### The re-call trap
+
+Setting output limits too low forces the model into repeated re-call loops — the model issues `tail -n 50 output.txt` or re-reads files in chunks, which costs more tokens than the original uncapped output. The minimum values below are empirically safe floors:
+
+| Variable | Safe minimum | Recommended |
+|----------|-------------|-------------|
+| `BASH_MAX_OUTPUT_LENGTH` | 10000 | 15000 |
+| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 4000 | 8000 |
+| `MAX_MCP_OUTPUT_TOKENS` | 4000 | 8000 |
+| Codex `tool_output_token_limit` | 5000 | 10000 |
+
+### Version drift
+
+Settings defaults change with minor CC version releases. After each upgrade, verify active defaults with `/token-efficiency-audit audit`. The reference baseline for this guide is CC v2.1.114+ / Codex v0.121.0+.
+
+### includeGitInstructions tradeoff
+
+Disabling `includeGitInstructions` removes git workflow guidance from the context. For projects with non-standard git workflows or junior contributors, this guidance may be worth keeping. For projects with experienced teams using `mgr-gitnerd` (R010), the injection is redundant.
+
+---
+
+## Interaction with Other Rules
+
+| Rule / Component | Interaction |
+|-----------------|-------------|
+| R013 Ecomode | Layer 2 runtime compression. These layers are complementary — apply both. |
+| cc-token-saver | Layer 1 cache defense. `Token Guardian` + `BASH_MAX_OUTPUT_LENGTH` together eliminate the two largest waste sources. |
+| R010 Orchestrator | `CLAUDE_CODE_DISABLE_CLAUDE_MDS` disables R010 enforcement — CI-only. |
+| R001 Safety | `apply-ci` mode is Risk Level High — requires user confirmation before applying. |
+| R012 HUD Statusline | Statusline shows CTX% — effective measure of Layer 2+3 combined impact. |
+| playwright-compress | Layer 4 hook — complements Layer 3 MAX_MCP_OUTPUT_TOKENS with intelligent lossless compression. |
+
+---
+
+## Layer 4: MCP Output Intelligence Compression
+
+PostToolUse hook that compresses Playwright and Chrome MCP tool output using Haiku summarization.
+
+| Metric | Before | After | Reduction |
+|--------|--------|-------|-----------|
+| browser_navigate | 37,983 chars | 1,922 chars | -94% |
+| browser_snapshot | 37,897 chars | 1,435 chars | -96% |
+
+- Preserves `ref=` attribute values for interactive flow
+- Skips output < 3000 chars
+- Falls back to original on Haiku failure
+- No API key needed (uses `claude -p` subscription auth)
+
+Configuration: `.claude/hooks/scripts/playwright-compress.sh`
+Hook trigger: `mcp__playwright__.*` and `mcp__claude-in-chrome__.*`
+
+---
+
+## Cross-References
+
+- `guides/claude-code/13-cli-flags.md` — CLI flags for non-interactive/CI invocation
+- `guides/cc-token-saver/README.md` — Layer 1 detailed guide
+- `.claude/rules/SHOULD-ecomode.md` — Layer 2 R013 specification
+- `.claude/skills/token-efficiency-audit/SKILL.md` — Layer 3 HOW: audit and apply
+- `.claude/skills/monitoring-setup/SKILL.md` — Measure effectiveness via OTel metrics
+- `.claude/skills/update-config/` — Generic settings.json manipulation (broader scope)
+- `.claude/skills/playwright-compress/SKILL.md` — Layer 4 MCP output compression hook
+- `.claude/hooks/scripts/playwright-compress.sh` — Layer 4 hook script

package/templates/guides/docker/compose-best-practices.md

@@ -4,9 +4,9 @@
 
 ## File Structure
 
-```yaml
-version: "3.8"
+> **Note**: The `version` field is obsolete as of Compose Spec v5 and should be omitted from modern compose files. Docker Compose now uses the Compose Specification directly.
 
+```yaml
 services:
   # Application services
   app:
@@ -201,8 +201,6 @@ services:
 ## Complete Example
 
 ```yaml
-version: "3.8"
-
 services:
   app:
     build:
@@ -260,7 +258,7 @@ services:
       - backend
 
   nginx:
-    image: nginx:1.25-alpine
+    image: nginx:1.28-alpine
     restart: unless-stopped
     ports:
       - "80:80"

package/templates/guides/docker/dockerfile-best-practices.md

@@ -25,13 +25,13 @@ node_modules
 
 ```dockerfile
 # Build stage
-FROM golang:1.21 AS builder
+FROM golang:1.26 AS builder
 WORKDIR /app
 COPY . .
 RUN go build -o myapp
 
 # Runtime stage
-FROM alpine:3.19
+FROM alpine:3.23
 COPY --from=builder /app/myapp /usr/local/bin/
 CMD ["myapp"]
 ```
@@ -42,13 +42,13 @@ CMD ["myapp"]
 
 ```dockerfile
 # Pin versions
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 # Use digest for reproducibility
 FROM node:20@sha256:abc123...
 
 # Use official images
-FROM python:3.12-slim
+FROM python:3.14-slim
 ```
 
 ### RUN
@@ -197,12 +197,12 @@ ENV API_KEY=secret123
 
 ```dockerfile
 # Official and verified
-FROM nginx:1.25
+FROM nginx:1.28
 FROM postgres:16
 
 # Minimal images
 FROM gcr.io/distroless/static
-FROM alpine:3.19
+FROM alpine:3.23
 ```
 
 ## Example Dockerfiles
@@ -229,13 +229,13 @@ CMD ["node", "dist/server.js"]
 ### Python
 
 ```dockerfile
-FROM python:3.12-slim AS builder
+FROM python:3.14-slim AS builder
 WORKDIR /app
 RUN pip install --user pipenv
 COPY Pipfile Pipfile.lock ./
 RUN pipenv install --system --deploy
 
-FROM python:3.12-slim
+FROM python:3.14-slim
 WORKDIR /app
 COPY --from=builder /root/.local /root/.local
 COPY . .
@@ -248,7 +248,7 @@ CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]
 ### Go
 
 ```dockerfile
-FROM golang:1.21-alpine AS builder
+FROM golang:1.26-alpine AS builder
 WORKDIR /app
 COPY go.mod go.sum ./
 RUN go mod download

package/templates/guides/flutter/index.yaml

@@ -22,7 +22,7 @@ documents:
 
   - name: state-management
     path: ./state-management.md
-    description: Riverpod 3.0, BLoC 9.0, Provider patterns and selection guide
+    description: Riverpod 3.3, BLoC 9.1, Provider patterns and selection guide
 
   - name: architecture
     path: ./architecture.md

package/templates/guides/flutter/state-management.md

@@ -6,13 +6,13 @@
 
 | Approach | Complexity | Scalability | Best For |
 |----------|-----------|-------------|----------|
-| **Riverpod 3.0** | Medium | Excellent | New projects (default) |
-| **BLoC 9.0** | High | Excellent | Enterprise, regulated industries |
+| **Riverpod 3.3** | Medium | Excellent | New projects (default) |
+| **BLoC 9.1** | High | Excellent | Enterprise, regulated industries |
 | **Provider** | Low | Moderate | Simple apps, learning |
 | **setState** | Low | Poor | Ephemeral local UI state |
 | **GetX** | Low | Poor | **AVOID** for new projects |
 
-## Riverpod 3.0 (Default)
+## Riverpod 3.3 (Default)
 
 ### Provider Types
 
@@ -81,7 +81,7 @@ class ProductListScreen extends ConsumerWidget {
 - Use `family` for parameterized providers
 - Use `keepAlive` sparingly (expensive computations only)
 
-## BLoC 9.0 (Enterprise)
+## BLoC 9.1 (Enterprise)
 
 ### Cubit (Simple)
 

package/templates/guides/index.yaml

@@ -9,6 +9,12 @@ guides:
       type: internal
 
   # Frontend
+  - name: claude-design
+    description: Claude Design artifact handoff workflow — connecting Anthropic's conversational design tool outputs to Claude Code's fe-design-expert implementation pipeline
+    path: ./claude-design/
+    source:
+      type: internal
+
   - name: impeccable-design
     description: AI design language reference — typography, color, motion, and UX writing for production-grade UI
     path: ./impeccable-design/
@@ -43,9 +49,9 @@ guides:
       origin: go.dev
       url: https://go.dev/doc/effective_go
 
-  - name: java21
-    description: Java 21 language reference and modern feature documentation
-    path: ./java21/
+  - name: java
+    description: Java language reference and modern feature documentation
+    path: ./java/
     source:
       type: external
       origin: docs.oracle.com

package/templates/guides/{java21 → java}/index.yaml

@@ -1,29 +1,29 @@
-# Java 21 Guide
+# Java Guide
 
 metadata:
-  name: java21
-  description: Java 21 language reference and modern feature documentation
+  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/21/
+    - 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-03-11"
+  last_fetched: "2026-04-20"
 
 documents:
-  - name: modern-java21
-    path: ./modern-java21.md
-    description: Java 21 modern features (Virtual Threads, Pattern Matching, Records, Sealed Classes)
+  - 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-java21-expert
+  - lang-java-expert

package/templates/guides/{java21/modern-java21.md → java/modern-java.md}

@@ -1,4 +1,4 @@
-# Modern Java 21 Features
+# Modern Java Features
 
 > Sources: https://openjdk.org/jeps/ (JEP 431, 440, 441, 444)
 
@@ -77,7 +77,7 @@ if (obj instanceof String) {
     return s.length();
 }
 
-// Java 21
+// Java 21+
 if (obj instanceof String s) {
     return s.length();
 }

package/templates/guides/slack-cli/README.md

@@ -1,6 +1,6 @@
 # Slack CLI Reference Guide
 
-> Source: https://docs.slack.dev/tools/slack-cli/ | Version: v3.15.0
+> Source: https://docs.slack.dev/tools/slack-cli/ | Version: v4.0
 
 ## Overview
 

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.101.0",
+  "version": "0.103.0",
   "lastUpdated": "2026-04-18T00:00:00.000Z",
   "components": [
     {
@@ -18,13 +18,13 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 109
+      "files": 112
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 39
+      "files": 40
     },
     {
       "name": "hooks",

package/templates/.claude/agents/lang-java21-expert.md

@@ -1,42 +0,0 @@
----
-name: lang-java21-expert
-description: Expert Java 21 developer for modern Java with Virtual Threads, Pattern Matching, Record Patterns, and Sequenced Collections. Use for Java files (*.java, pom.xml, build.gradle), Java-related keywords, high-concurrency systems, data-centric APIs with Records, and migrating from older Java versions.
-model: sonnet
-domain: backend
-memory: project
-effort: high
-skills:
-  - java21-best-practices
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-permissionMode: bypassPermissions
----
-
-You are an expert Java 21 developer for modern Java features including Virtual Threads, Pattern Matching, Record Patterns, and Sequenced Collections.
-
-## Capabilities
-
-- Modern Java 21 leveraging latest features
-- Virtual Threads (JEP 444) for scalable concurrency
-- Pattern Matching for switch and instanceof
-- Record Patterns (JEP 440), Sequenced Collections (JEP 431)
-- Google Java Style Guide compliance
-- Legacy Java migration to Java 21
-
-## Reference Documentation
-
-- https://docs.oracle.com/en/java/javase/21/
-- https://google.github.io/styleguide/javaguide.html
-
-## Skills
-
-Apply **java21-best-practices** for core Java 21 guidelines.
-
-## Reference Guides
-
-Consult `guides/java21/` for reference documentation.