oh-my-customcode 0.30.9 → 0.31.1

package/README.md

@@ -21,7 +21,7 @@ Like oh-my-zsh transformed shell customization, oh-my-customcode makes personali
 
 | Feature | Description |
 |---------|-------------|
-| **Batteries Included** | 44 agents, 68 skills, 24 guides, 18 rules, 2 hooks, 4 contexts, ontology graph - ready to use out of the box |
+| **Batteries Included** | 44 agents, 68 skills, 25 guides, 18 rules, 2 hooks, 4 contexts, ontology graph - ready to use out of the box |
 | **Sub-Agent Model** | Supports hierarchical agent orchestration with specialized roles |
 | **Dead Simple Customization** | Create a folder + markdown file = new agent or skill |
 | **Mix and Match** | Use built-in components, create your own, or combine both |
@@ -197,7 +197,7 @@ All commands are invoked inside the Claude Code conversation.
 | **Deploy** | 2 | vercel-deploy, codex-exec |
 | **External** | 1 | skills-sh-search |
 
-### Guides (24)
+### Guides (25)
 
 Comprehensive reference documentation covering:
 - Agent creation and management
@@ -292,7 +292,8 @@ your-project/
 │   ├── rules/             # Behavior rules (18 total)
 │   ├── hooks/             # Event hooks (2 total)
 │   └── contexts/          # Context files (4 total)
-└── guides/                # Reference docs (24 total)
+└── templates/
+    └── guides/            # Reference docs (25 total)
 ```
 
 **Note**: In the official Claude Code format, there is no command registry — slash commands and natural language agent references are used.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.30.9",
+  "version": "0.31.1",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

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

@@ -4,6 +4,7 @@ description: Expert Go developer for writing idiomatic, performant Go code. Use
 model: sonnet
 memory: project
 effort: high
+soul: true
 skills:
   - go-best-practices
 tools:

package/templates/.claude/agents/souls/lang-golang-expert.soul.md

@@ -0,0 +1,21 @@
+---
+agent: lang-golang-expert
+version: 1.0.0
+---
+
+## Personality
+- Direct and concise — lead with the answer, explain after
+- Always provide runnable code examples, never pseudo-code
+- Treat Go idioms as non-negotiable (Effective Go is gospel)
+
+## Style
+- Error handling first — check errors before happy path
+- Prefer stdlib over third-party when possible
+- Name variables for clarity, not brevity (userCount > uc)
+- Use table-driven tests as default test pattern
+
+## Anti-patterns
+- Never use interface{}/any without a compelling reason
+- Avoid init() functions — explicit initialization preferred
+- No global mutable state
+- Avoid premature abstraction — 3 concrete cases before extracting

package/templates/.claude/agents/sys-memory-keeper.md

@@ -1,6 +1,6 @@
 ---
 name: sys-memory-keeper
-description: Use when you need to manage session memory persistence using claude-mem, save context before compaction, restore context on session start, query past memories, or perform session-end dual-system auto-save
+description: Use when you need to manage session memory persistence via native auto-memory, save context before compaction, restore context on session start, collect session summaries, or perform session-end memory operations
 model: sonnet
 memory: project
 effort: medium
@@ -47,12 +47,19 @@ Provider: claude-mem | Collection: claude_memories | Archive: ~/.claude-mem/arch
 When triggered by session-end signal from orchestrator:
 
 1. **Collect** session summary: completed tasks, key decisions, open items
-2. **Save to claude-mem** (if available): `mcp__plugin_claude-mem_mcp-search__save_memory` with project name, session date, and summary
-3. **Verify episodic-memory** (if available): `mcp__plugin_episodic-memory_episodic-memory__search` to confirm session is indexed
-4. **Report** results to orchestrator: saved/skipped/failed per system
+2. **Extract behaviors**: analyze conversation for repeated user preferences
+   - Communication patterns (verbosity, format, language preferences)
+   - Workflow patterns (tool usage, review habits, branching conventions)
+   - Domain priorities (security-first, performance-first, etc.)
+   - New behaviors → `[confidence: low]` in `## Behaviors` section
+   - Existing behaviors observed again → promote confidence level
+   - Contradicted behaviors → flag for review or demote
+3. **Update native auto-memory** (MEMORY.md) with session learnings + behaviors
+4. **Return formatted summary** to orchestrator for MCP persistence (claude-mem, episodic-memory)
+
+> **Note**: MCP tools (claude-mem, episodic-memory) are orchestrator-scoped and cannot be called from subagents. The orchestrator handles MCP saves directly after receiving the formatted summary.
 
 ### Failure Handling
 
-- claude-mem unavailable → skip, report warning
-- episodic-memory unavailable → skip, report warning
-- Both unavailable → warn orchestrator, do not block session end
+- MEMORY.md update failure → report error to orchestrator
+- MCP persistence is orchestrator's responsibility — not handled here

package/templates/.claude/rules/MUST-agent-design.md

@@ -30,6 +30,7 @@ escalation:              # Model escalation policy (optional)
   enabled: true          # Enable auto-escalation advisory
   path: haiku → sonnet → opus  # Escalation sequence
   threshold: 2           # Failures before advisory
+soul: true                 # Enable SOUL.md identity injection
 isolation: worktree        # Run in isolated git worktree
 background: true           # Run in background
 maxTurns: 10               # Max conversation turns
@@ -64,6 +65,54 @@ When `escalation.enabled: true`, the model-escalation hooks will track outcomes
 
 When enabled: first 200 lines of MEMORY.md loaded into system prompt.
 
+## Soul Identity
+
+Optional per-agent identity layer that separates personality/style from capabilities.
+
+| Aspect | Location | Purpose |
+|--------|----------|---------|
+| Capabilities | `.claude/agents/{name}.md` | WHAT the agent does |
+| Identity | `.claude/agents/souls/{name}.soul.md` | HOW the agent communicates |
+
+### Soul File Format
+
+Location: `.claude/agents/souls/{name}.soul.md`
+
+```yaml
+---
+agent: {agent-name}        # Must match agent filename
+version: 1.0.0
+---
+```
+
+Sections: `## Personality`, `## Style`, `## Anti-patterns`
+
+### Activation
+
+1. Agent frontmatter includes `soul: true`
+2. Routing skill reads `souls/{name}.soul.md` at spawn time (Step 5)
+3. Soul content prepended to agent prompt as identity context
+4. Missing soul file → graceful fallback (no error)
+
+### Precedence
+
+Behavioral memory observations (R011) override soul defaults when they conflict. Behaviors are user-specific; souls are template defaults.
+
+## Artifact Output Convention
+
+Skills that produce significant output can persist results to local storage.
+
+**Location**: `.claude/outputs/sessions/{YYYY-MM-DD}/{skill-name}-{HHmmss}.md`
+
+**Format**: Metadata header with `skill`, `date`, `query` fields, followed by skill output content.
+
+**Rules**:
+- Opt-in per skill — not mandatory
+- The final subagent in the skill's pipeline writes the artifact (R010 compliance)
+- Skills create the directory (`mkdir -p`) before writing
+- `.claude/outputs/` is git-untracked (under `.claude/` gitignore)
+- No indexing required — date-based directory browsing is sufficient
+
 ## Separation of Concerns
 
 | Location | Purpose | Contains |
@@ -74,6 +123,42 @@ When enabled: first 200 lines of MEMORY.md loaded into system prompt.
 
 Agent body: purpose, capabilities overview, workflow. NOT detailed instructions or reference docs.
 
+## Skill Frontmatter
+
+Location: `.claude/skills/{name}/SKILL.md`
+
+### Required Fields
+
+```yaml
+name: skill-name           # Unique identifier (kebab-case)
+description: Brief desc    # One-line summary
+```
+
+### Optional Fields
+
+```yaml
+context: fork              # Forked context for isolated execution
+version: 1.0.0             # Semantic version
+user-invocable: false      # Whether user can invoke directly
+disable-model-invocation: true  # Prevent model from auto-invoking
+```
+
+### Context Fork Criteria
+
+Use `context: fork` for skills that orchestrate multi-agent workflows. Cap at **10 total** across the project.
+
+| Use `context: fork` | Do NOT use `context: fork` |
+|---------------------|---------------------------|
+| Routing skills (secretary, dev-lead, etc.) | Best-practices skills |
+| Workflow orchestration (DAG, pipelines) | Hook/command skills |
+| Multi-agent coordination patterns | Single-agent reference skills |
+| Task decomposition/planning | External tool integrations |
+
+Current skills with `context: fork` (8/10 cap):
+- secretary-routing, dev-lead-routing, de-lead-routing, qa-lead-routing
+- dag-orchestration, task-decomposition, worker-reviewer-pipeline
+- pipeline-guards
+
 ## Naming
 
 | Type | Pattern | Example |

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -71,6 +71,58 @@ Memory entries in MEMORY.md should include confidence annotations to distinguish
 [any] → contradicted by evidence → demoted or removed
 ```
 
+## Behavioral Memory
+
+MEMORY.md supports an optional `## Behaviors` section for tracking user interaction preferences and workflow patterns.
+
+### Behaviors Section Format
+
+```markdown
+## Behaviors [confidence: medium]
+- User prefers concise responses — 3 sentences max
+- Commit messages always include issue number
+- Security-first review perspective
+
+## Behavior Lifecycle
+- New observation → [confidence: low]
+- Seen in 2+ sessions → [confidence: medium]
+- User-confirmed → [confidence: high]
+- Contradicted → demote or remove
+```
+
+### What Counts as a Behavior
+
+| Category | Examples |
+|----------|---------|
+| Communication | Verbosity preference, language, format |
+| Workflow | Tool preferences, review habits, branching patterns |
+| Domain priority | Security-first, performance-first, simplicity-first |
+
+### What Does NOT Count as a Behavior
+
+- Facts about the codebase (use existing sections)
+- One-time instructions (ephemeral, not persistent)
+- Tool configuration (belongs in CLAUDE.md or settings)
+
+### Extraction Guidelines
+
+sys-memory-keeper extracts behavioral patterns at session end:
+1. Analyze conversation for repeated user preferences
+2. New behaviors start at `[confidence: low]`
+3. Promote on repeated observation across sessions
+4. Demote or remove when contradicted
+
+### Budget Management
+
+Behaviors share the 200-line MEMORY.md budget with facts. When approaching the limit:
+1. Prune `[confidence: low]` behaviors first
+2. Then prune `[confidence: medium]` behaviors
+3. `[confidence: high]` behaviors are never auto-pruned
+
+### Precedence
+
+Behavioral memory observations override soul defaults (R006 Soul Identity) when they conflict. Behaviors are user-specific and session-derived; souls are template defaults.
+
 ### Rules
 
 | Rule | Detail |

package/templates/.claude/skills/de-lead-routing/SKILL.md

@@ -73,6 +73,29 @@ For **new pipeline code**, **DAG scaffolding**, or **SQL model generation**:
 ### Step 3: Expert Selection
 Route to appropriate DE expert based on tool/framework detection.
 
+### Step 4: Ontology-RAG Enrichment (R019)
+
+After agent selection, enrich the spawned agent's prompt with ontology context:
+
+1. Call `get_agent_for_task(original_query)` via MCP
+2. Extract `suggested_skills` from response
+3. If `suggested_skills` non-empty, prepend to spawned agent prompt:
+   `"Ontology context suggests these skills may be relevant: {suggested_skills}"`
+4. On MCP failure: skip silently, proceed with unmodified prompt
+
+**This step is advisory only — it never changes which agent is selected.**
+
+### Step 5: Soul Injection
+
+If the selected agent has `soul: true` in its frontmatter:
+
+1. Read `.claude/agents/souls/{agent-name}.soul.md`
+2. If file exists, prepend soul content to the agent's prompt:
+   `"Identity context:\n{soul content}\n\n---\n\n"`
+3. If file doesn't exist → skip silently (no error, no injection)
+
+**This step runs after ontology-RAG enrichment. Soul content is identity context, not capability instructions.**
+
 ## Command Routing
 
 ```
@@ -262,7 +285,7 @@ Delegate to mgr-creator with context:
   keywords: extracted tool names
   file_patterns: detected config patterns
   skills: auto-discover from .claude/skills/
-  guides: auto-discover from guides/
+  guides: auto-discover from templates/guides/
 ```
 
 **Examples of dynamic creation triggers:**

package/templates/.claude/skills/dev-lead-routing/SKILL.md

@@ -107,6 +107,29 @@ For **new file creation**, **boilerplate**, or **test code generation**:
 ### Step 3: Expert Agent Selection
 Route to appropriate language/framework expert based on file extension and keyword mapping.
 
+### Step 4: Ontology-RAG Enrichment (R019)
+
+After agent selection, enrich the spawned agent's prompt with ontology context:
+
+1. Call `get_agent_for_task(original_query)` via MCP
+2. Extract `suggested_skills` from response
+3. If `suggested_skills` non-empty, prepend to spawned agent prompt:
+   `"Ontology context suggests these skills may be relevant: {suggested_skills}"`
+4. On MCP failure: skip silently, proceed with unmodified prompt
+
+**This step is advisory only — it never changes which agent is selected.**
+
+### Step 5: Soul Injection
+
+If the selected agent has `soul: true` in its frontmatter:
+
+1. Read `.claude/agents/souls/{agent-name}.soul.md`
+2. If file exists, prepend soul content to the agent's prompt:
+   `"Identity context:\n{soul content}\n\n---\n\n"`
+3. If file doesn't exist → skip silently (no error, no injection)
+
+**This step runs after ontology-RAG enrichment. Soul content is identity context, not capability instructions.**
+
 ## Routing Rules
 
 Multi-language: detect all languages, route to parallel experts (max 4). Single-language: route to matching expert. Cross-layer (frontend + backend): multiple experts in parallel.
@@ -126,7 +149,7 @@ Delegate to mgr-creator with context:
   keywords: extracted from user input
   file_patterns: detected extensions
   skills: auto-discover from .claude/skills/
-  guides: auto-discover from guides/
+  guides: auto-discover from templates/guides/
 ```
 
 **Examples of dynamic creation triggers:**

package/templates/.claude/skills/dev-review/SKILL.md

@@ -32,6 +32,19 @@ Review code for best practices using language-specific expert agents.
 4. Analyze code against best practices
 5. Generate review report
 ```
+6. **Artifact persistence** (optional): Review agent saves findings to:
+   ```
+   .claude/outputs/sessions/{YYYY-MM-DD}/dev-review-{HHmmss}.md
+   ```
+   With metadata header:
+   ```markdown
+   ---
+   skill: dev-review
+   date: {ISO-8601 with timezone}
+   query: "{original user query}"
+   ---
+   ```
+   The review agent creates the directory and writes the artifact before returning results (R010 compliance).
 
 ## Agent Selection
 

package/templates/.claude/skills/qa-lead-routing/SKILL.md

@@ -44,6 +44,29 @@ quality_analysis   → qa-planner + qa-engineer (parallel)
 full_qa_cycle      → all agents (sequential)
 ```
 
+### Ontology-RAG Enrichment (R019)
+
+After agent selection, enrich the spawned agent's prompt with ontology context:
+
+1. Call `get_agent_for_task(original_query)` via MCP
+2. Extract `suggested_skills` from response
+3. If `suggested_skills` non-empty, prepend to spawned agent prompt:
+   `"Ontology context suggests these skills may be relevant: {suggested_skills}"`
+4. On MCP failure: skip silently, proceed with unmodified prompt
+
+**This step is advisory only — it never changes which agent is selected.**
+
+### Step 5: Soul Injection
+
+If the selected agent has `soul: true` in its frontmatter:
+
+1. Read `.claude/agents/souls/{agent-name}.soul.md`
+2. If file exists, prepend soul content to the agent's prompt:
+   `"Identity context:\n{soul content}\n\n---\n\n"`
+3. If file doesn't exist → skip silently (no error, no injection)
+
+**This step runs after ontology-RAG enrichment. Soul content is identity context, not capability instructions.**
+
 ## Routing Rules
 
 ### 1. Test Planning
@@ -293,7 +316,7 @@ Delegate to mgr-creator with context:
   type: qa-engineer
   keywords: extracted testing terms
   skills: auto-discover from .claude/skills/
-  guides: auto-discover from guides/
+  guides: auto-discover from templates/guides/
 ```
 
 **Examples of dynamic creation triggers:**

package/templates/.claude/skills/research/SKILL.md

@@ -45,7 +45,7 @@ Batch 2: T5, T6, T7, T8    (Integration + Comparative)
 Batch 3: T9, T10            (Innovation)
 ```
 
-### Phase 2: Cross-Verification Loop (min 2, max 5 rounds)
+### Phase 2: Cross-Verification Loop (min 2, max 30 rounds)
 
 ```
 Team findings ──→ opus 4.6 verification ──→ codex-exec xhigh verification
@@ -60,7 +60,7 @@ Each round:
 3. **Contradiction resolution**: Reconcile divergent findings between teams and verifiers
 4. **Convergence check**: All major claims verified with no outstanding contradictions → proceed
 
-Convergence expected by round 3. Hard stop at round 5.
+Convergence expected by round 3. Hard stop at round 30.
 
 ### Phase 3: Synthesis
 
@@ -71,8 +71,21 @@ Convergence expected by round 3. Hard stop at round 5.
 ### Phase 4: Output
 
 1. Structured markdown report (see Output Format below)
-2. GitHub issue auto-created with findings
-3. Action items with effort estimates
+2. **Artifact persistence**: The Phase 4 synthesis agent (opus) writes the report to:
+   ```
+   .claude/outputs/sessions/{YYYY-MM-DD}/research-{HHmmss}.md
+   ```
+   With metadata header:
+   ```markdown
+   ---
+   skill: research
+   date: {ISO-8601 with timezone}
+   query: "{original user query}"
+   ---
+   ```
+   The agent creates the directory (`mkdir -p`) before writing. This is a subagent operation (R010 compliance).
+3. GitHub issue auto-created with findings
+4. Action items with effort estimates
 
 ## Execution Rules
 

package/templates/.claude/skills/secretary-routing/SKILL.md

@@ -53,6 +53,29 @@ todo     → sys-naggy
 batch    → multiple (parallel)
 ```
 
+### Ontology-RAG Enrichment (R019)
+
+After agent selection, enrich the spawned agent's prompt with ontology context:
+
+1. Call `get_agent_for_task(original_query)` via MCP
+2. Extract `suggested_skills` from response
+3. If `suggested_skills` non-empty, prepend to spawned agent prompt:
+   `"Ontology context suggests these skills may be relevant: {suggested_skills}"`
+4. On MCP failure: skip silently, proceed with unmodified prompt
+
+**This step is advisory only — it never changes which agent is selected.**
+
+### Step 5: Soul Injection
+
+If the selected agent has `soul: true` in its frontmatter:
+
+1. Read `.claude/agents/souls/{agent-name}.soul.md`
+2. If file exists, prepend soul content to the agent's prompt:
+   `"Identity context:\n{soul content}\n\n---\n\n"`
+3. If file doesn't exist → skip silently (no error, no injection)
+
+**This step runs after ontology-RAG enrichment. Soul content is identity context, not capability instructions.**
+
 ## Routing Rules
 
 ### 1. Single Task Routing

package/templates/CLAUDE.md.en

@@ -168,6 +168,7 @@ Violation = immediate correction. No exception for "small changes".
 | `/optimize-analyze` | Analyze bundle and performance |
 | `/optimize-bundle` | Optimize bundle size |
 | `/optimize-report` | Generate optimization report |
+| `/research` | 10-team parallel deep analysis and cross-verification |
 | `/sauron-watch` | Full R017 verification |
 | `/structured-dev-cycle` | 6-stage structured development cycle (Plan → Verify → Implement → Verify → Compound → Done) |
 | `/lists` | Show all available commands |
@@ -185,7 +186,7 @@ project/
 |   +-- rules/                   # Global rules (R000-R018)
 |   +-- hooks/                   # Hook scripts (memory, HUD)
 |   +-- contexts/                # Context files (ecomode)
-+-- guides/                      # Reference docs (23 topics)
++-- guides/                      # Reference docs (25 topics)
 ```
 
 ## Orchestration

package/templates/CLAUDE.md.ko

@@ -168,6 +168,7 @@ oh-my-customcode로 구동됩니다.
 | `/optimize-analyze` | 번들 및 성능 분석 |
 | `/optimize-bundle` | 번들 크기 최적화 |
 | `/optimize-report` | 최적화 리포트 생성 |
+| `/research` | 10-team 병렬 딥 분석 및 교차 검증 |
 | `/sauron-watch` | 전체 R017 검증 |
 | `/structured-dev-cycle` | 6단계 구조적 개발 사이클 (Plan → Verify → Implement → Verify → Compound → Done) |
 | `/lists` | 모든 사용 가능한 커맨드 표시 |
@@ -185,7 +186,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (R000-R018)
 |   +-- hooks/                   # 훅 스크립트 (메모리, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (23 토픽)
++-- guides/                      # 레퍼런스 문서 (25 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/flutter/security.md

@@ -0,0 +1,120 @@
+# Flutter Security Guide
+
+> Reference: OWASP Mobile Top 10 (2024), Flutter Official Documentation
+
+## OWASP Mobile Top 10 Mapping
+
+### M1 — Improper Credential Usage
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Backend proxy pattern: route ALL sensitive API calls through server
+- `--dart-define-from-file=.env` is for NON-SECRET build config only (values are extractable from binary)
+- Credential rotation: implement token refresh with `dio` interceptor
+- OAuth2 flow: use `flutter_appauth` for PKCE-based authentication
+
+### M2 — Inadequate Supply Chain Security
+
+- Run `dart pub audit` before every release to check for known vulnerabilities
+- Pin exact versions in `pubspec.yaml` for production (`package: 1.2.3` not `package: ^1.2.3`)
+- Verify package publisher on pub.dev (look for verified publisher badge)
+- Review transitive dependencies: `dart pub deps --style=compact`
+- Avoid packages with no recent updates (> 12 months without commits)
+
+### M3 — Insecure Authentication/Authorization
+
+- Biometric authentication: `local_auth` package with `BiometricType.fingerprint` / `BiometricType.face`
+- Session management: implement token expiry checking before API calls
+- JWT client-side validation: verify `exp`, `aud`, `iss` claims before using tokens
+- Re-authentication: require biometric/PIN for sensitive operations (payment, profile changes)
+- Deep link auth: validate authentication state before processing deep link navigation
+
+### M4 — Insufficient Input/Output Validation
+
+- Validate ALL deep link URI parameters with RegExp allowlists
+- Sanitize user input before displaying in WebView (`flutter_inappwebview`)
+- Use `Uri.parse()` with try-catch, never trust raw string URLs
+- Output encoding: escape HTML entities when rendering user content
+- Form validation: use `TextFormField` validators, never trust client-side validation alone
+
+### M5 — Insecure Communication
+
+- Certificate pinning (SPKI): use `dio` with custom `SecurityContext`
+- Extract SPKI hash: `openssl s_client -connect host:443 | openssl x509 -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256 -binary | base64`
+- Include backup pins for certificate rotation
+- Android: `network_security_config.xml` with `cleartextTrafficPermitted=false`
+- iOS: ATS enabled (`NSAllowsArbitraryLoads=false`), never override in production
+
+### M6 — Inadequate Privacy Controls
+
+- Request minimum platform permissions (camera, location, contacts)
+- iOS: provide usage description strings in Info.plist for every permission
+- Android: use runtime permissions, respect "Don't ask again"
+- Data minimization: only collect and store data that is necessary
+- GDPR/CCPA: implement data export and deletion capabilities
+
+### M7 — Insufficient Binary Protections
+
+- Release builds: `flutter build --obfuscate --split-debug-info=debug-info/`
+- Store debug symbols securely for crash reporting (Crashlytics, Sentry)
+- Android ProGuard: configure `android/app/proguard-rules.pro`
+- Note: `--obfuscate` does NOT apply to `flutter build web` (JS minification is the web equivalent)
+- Anti-tampering: consider `flutter_jailbreak_detection` for integrity checks
+
+### M8 — Security Misconfiguration
+
+- Android: set `android:debuggable="false"` in release manifest
+- Android: set `android:allowBackup="false"` to prevent ADB data extraction
+- iOS: enable data protection with `NSFileProtectionComplete`
+- Remove all debug logging in release: guard with `kDebugMode`
+- Firebase: secure `google-services.json` / `GoogleService-Info.plist` (add to .gitignore)
+
+### M9 — Insecure Data Storage
+
+- Sensitive data: `flutter_secure_storage` v10+ (iOS Keychain / Android EncryptedSharedPreferences)
+- iOS: `IOSOptions(accessibility: KeychainAccessibility.first_unlock_this_device)`
+- Android: `AndroidOptions(encryptedSharedPreferences: true)`
+- Web WARNING: `flutter_secure_storage` uses localStorage on Web (XSS vulnerable) — use HttpOnly cookies or in-memory storage
+- Never use `SharedPreferences` for tokens, PII, or credentials
+- Screenshot protection: Android `FLAG_SECURE` via `flutter_windowmanager`
+
+### M10 — Insufficient Cryptography
+
+- Use `pointycastle` or `cryptography` package for custom crypto operations
+- Avoid: MD5, SHA-1, DES, ECB mode, hardcoded IVs/keys
+- Prefer: AES-256-GCM for symmetric, RSA-OAEP or ECDSA for asymmetric
+- Key storage: always delegate to platform Keychain/Keystore, never store in app data
+- Random number generation: use `Random.secure()` for security-sensitive values
+
+## Platform-Specific Security
+
+### iOS
+
+- Keychain with Secure Enclave: `IOSOptions(useSecureEnclave: true)` for high-value data
+- ATS enforcement: never add `NSAllowsArbitraryLoads` exception for production
+- Jailbreak detection: `flutter_jailbreak_detection` package
+
+### Android
+
+- Keystore-backed encryption via `EncryptedSharedPreferences`
+- Network security config: pin certificates, block cleartext
+- Root detection: `flutter_jailbreak_detection` or `safe_device`
+- `allowBackup=false` in AndroidManifest.xml
+
+### Web
+
+- CSP headers: configure on the server hosting Flutter web app
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use HttpOnly, Secure, SameSite cookies for authentication tokens
+- XSS prevention: sanitize all user-generated content before rendering
+
+## Package Recommendations
+
+| Category | Package | Notes |
+|----------|---------|-------|
+| Secure Storage | `flutter_secure_storage` | Keychain/Keystore, v10+; Web: localStorage (XSS risk) |
+| OAuth2 / PKCE | `flutter_appauth` | PKCE-based auth flows |
+| Biometrics | `local_auth` | Fingerprint, Face ID |
+| HTTP (pinning) | `dio` | Custom `SecurityContext` for certificate pinning |
+| Crypto | `cryptography` | AES-GCM, RSA-OAEP, ECDSA |
+| Integrity check | `flutter_jailbreak_detection` | Root/jailbreak detection |
+| Screenshot protect | `flutter_windowmanager` | Android `FLAG_SECURE` |

package/templates/guides/java21/index.yaml

@@ -0,0 +1,29 @@
+# Java 21 Guide
+
+metadata:
+  name: java21
+  description: Java 21 language reference and modern feature documentation
+
+source:
+  type: external
+  origin: docs.oracle.com
+  urls:
+    - https://docs.oracle.com/en/java/javase/21/
+    - 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"
+
+documents:
+  - name: modern-java21
+    path: ./modern-java21.md
+    description: Java 21 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

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

@@ -0,0 +1,248 @@
+# Java Style Guide
+
+> Source: https://google.github.io/styleguide/javaguide.html
+
+## File Structure
+
+```
+Source file:
+  1. License/copyright (if any)
+  2. Package statement
+  3. Import statements
+  4. Exactly one top-level class
+```
+
+### Import Ordering
+
+```java
+// 1. Static imports (all together)
+import static org.junit.Assert.assertEquals;
+
+// 2. Non-static imports (all together, no subgroups)
+import com.example.Foo;
+import java.util.List;
+import org.springframework.boot.SpringApplication;
+```
+
+No wildcard imports except `static` test imports.
+
+---
+
+## Naming Conventions
+
+| Element | Style | Example |
+|---------|-------|---------|
+| Packages | `lowercase` | `com.example.network` |
+| Classes | `UpperCamelCase` | `OrderProcessor` |
+| Records | `UpperCamelCase` | `UserRecord` |
+| Methods | `lowerCamelCase` | `processOrder()` |
+| Local vars | `lowerCamelCase` | `itemCount` |
+| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRIES` |
+| Type params | Single letter or `UpperCamelCase + T` | `T`, `E`, `RequestT` |
+
+### Acronyms
+
+Treat acronyms as words: `XmlParser`, not `XMLParser`. Exception: well-known 2-letter ones like `IO`.
+
+---
+
+## Formatting
+
+### Indentation
+
+- 2 spaces (not tabs) for block indentation
+- 4 spaces for line continuation
+
+```java
+// Block indentation: 2 spaces
+if (condition) {
+  doSomething();
+}
+
+// Line continuation: 4 spaces
+String result = longMethodName(
+    argument1,
+    argument2);
+```
+
+### Braces
+
+Always use braces, even for single-statement bodies:
+
+```java
+// Correct
+if (condition) {
+  doSomething();
+}
+
+// Wrong (no braces)
+if (condition)
+  doSomething();
+```
+
+### Column Limit
+
+100 characters per line. Wrap when exceeding.
+
+### Blank Lines
+
+```java
+class MyClass {
+  private int field;          // field
+                              // one blank line
+  public MyClass() { }        // constructor
+                              // one blank line
+  public void method() { }    // method
+}
+```
+
+---
+
+## Class Structure
+
+```java
+public class MyClass {
+  // 1. Static fields
+  private static final Logger log = LoggerFactory.getLogger(MyClass.class);
+
+  // 2. Instance fields
+  private final String name;
+
+  // 3. Constructors
+  public MyClass(String name) {
+    this.name = name;
+  }
+
+  // 4. Static factory methods (if applicable)
+  public static MyClass of(String name) {
+    return new MyClass(name);
+  }
+
+  // 5. Instance methods (public → package → protected → private)
+  public String getName() { return name; }
+
+  private void helper() { }
+
+  // 6. Inner classes/interfaces (last)
+}
+```
+
+---
+
+## Programming Practices
+
+### Annotations
+
+```java
+// One annotation per line for class/method
+@Override
+@Nullable
+public String format(String input) { }
+
+// Multiple short annotations on one line for field is OK
+@Nullable @Deprecated String field;
+```
+
+### Numeric Literals
+
+```java
+long big = 1_000_000L;
+double pi = 3.14_159;
+int hex = 0xFF_EC_D1_8C;
+```
+
+### Switch Expressions (prefer over statements)
+
+```java
+// Prefer switch expression
+int days = switch (month) {
+  case JANUARY, MARCH, MAY, JULY, AUGUST, OCTOBER, DECEMBER -> 31;
+  case APRIL, JUNE, SEPTEMBER, NOVEMBER -> 30;
+  case FEBRUARY -> 28;
+};
+```
+
+### Avoid Long Methods
+
+Keep methods short and focused. Extract helpers for blocks exceeding ~20 lines.
+
+---
+
+## Javadoc
+
+### Required for
+
+- Every `public` class, interface, enum, record
+- Every `public` or `protected` method (unless trivially obvious)
+
+### Format
+
+```java
+/**
+ * Returns the user associated with the given ID.
+ *
+ * <p>This method performs a database lookup. It is safe to call
+ * from multiple threads.
+ *
+ * @param id the user identifier (must be positive)
+ * @return the user, or empty if not found
+ * @throws IllegalArgumentException if {@code id <= 0}
+ */
+public Optional<User> findById(long id) { }
+```
+
+### Inline Tags
+
+```java
+/**
+ * See {@link UserRepository} for persistence details.
+ * Use {@code null} to reset the state.
+ */
+```
+
+### Prohibited: Non-Javadoc Comments for API
+
+```java
+// Wrong: plain comment for public method
+// Returns the user by id
+public Optional<User> findById(long id) { }
+
+// Correct: Javadoc
+/** Returns the user by id, or empty if not found. */
+public Optional<User> findById(long id) { }
+```
+
+---
+
+## Common Antipatterns to Avoid
+
+```java
+// ❌ Raw types
+List list = new ArrayList();
+// ✓
+List<String> list = new ArrayList<>();
+
+// ❌ String concatenation in loop
+String s = "";
+for (String item : items) s += item;
+// ✓
+StringBuilder sb = new StringBuilder();
+for (String item : items) sb.append(item);
+String s = sb.toString();
+
+// ❌ Return null for collections
+public List<String> getItems() { return null; }
+// ✓
+public List<String> getItems() { return Collections.emptyList(); }
+
+// ❌ Catch Exception broadly
+try { process(); } catch (Exception e) { }
+// ✓
+try { process(); } catch (IOException e) { log.error("IO error", e); }
+
+// ❌ Mutable public field
+public String name;
+// ✓
+private String name;
+public String getName() { return name; }
+```

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

@@ -0,0 +1,303 @@
+# Modern Java 21 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
+// Virtual Thread executor (preferred for I/O-bound tasks)
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<String>> futures = IntStream.range(0, 10_000)
+        .mapToObj(i -> executor.submit(() -> fetchData(i)))
+        .toList();
+    // all 10,000 tasks run concurrently
+}
+
+// Direct creation
+Thread.ofVirtual().name("vt-worker").start(() -> processRequest());
+
+// Factory for thread pools
+ThreadFactory factory = Thread.ofVirtual().name("worker-", 0).factory();
+```
+
+### Structured Concurrency (JEP 453, Preview)
+
+```java
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Future<String> user   = scope.fork(() -> fetchUser(id));
+    Future<String> orders = scope.fork(() -> fetchOrders(id));
+
+    scope.join().throwIfFailed();
+
+    return new UserProfile(user.get(), orders.get());
+}
+```
+
+### Pinning Avoidance
+
+Virtual Threads are **pinned** (cannot unmount) inside `synchronized` blocks. Prefer `ReentrantLock`:
+
+```java
+// Avoid (causes pinning)
+synchronized (lock) {
+    callBlockingIO();
+}
+
+// Prefer
+private final ReentrantLock lock = new ReentrantLock();
+lock.lock();
+try {
+    callBlockingIO();
+} finally {
+    lock.unlock();
+}
+```
+
+---
+
+## Pattern Matching for instanceof (JEP 394)
+
+```java
+// Before Java 16
+if (obj instanceof String) {
+    String s = (String) obj;
+    return s.length();
+}
+
+// Java 21
+if (obj instanceof String s) {
+    return s.length();
+}
+
+// With guard
+if (obj instanceof String s && !s.isEmpty()) {
+    return s.toUpperCase();
+}
+```
+
+---
+
+## Pattern Matching for switch (JEP 441)
+
+```java
+// Type patterns
+String format = switch (obj) {
+    case Integer i -> String.format("int %d", i);
+    case Double d  -> String.format("double %.2f", d);
+    case String s  -> String.format("String '%s'", s);
+    case null      -> "null value";
+    default        -> obj.toString();
+};
+
+// Guarded patterns (when clause)
+String classify = switch (number) {
+    case Integer i when i < 0  -> "negative";
+    case Integer i when i == 0 -> "zero";
+    case Integer i             -> "positive";
+    default -> "non-integer";
+};
+```
+
+---
+
+## Record Classes (JEP 395)
+
+Records are immutable data carriers with auto-generated `equals`, `hashCode`, `toString`, and accessors.
+
+```java
+// Basic record
+record Point(int x, int y) {}
+
+Point p = new Point(3, 4);
+int x = p.x(); // accessor (not getX())
+System.out.println(p); // Point[x=3, y=4]
+
+// Compact constructor (validation)
+record Range(int min, int max) {
+    Range {
+        if (min > max)
+            throw new IllegalArgumentException(
+                "min %d > max %d".formatted(min, max));
+    }
+}
+
+// Custom methods
+record Circle(double radius) {
+    static final double PI = Math.PI;
+
+    double area() { return PI * radius * radius; }
+
+    Circle scale(double factor) { return new Circle(radius * factor); }
+}
+
+// Implementing interface
+interface Describable { String describe(); }
+record Color(int r, int g, int b) implements Describable {
+    public String describe() {
+        return "rgb(%d,%d,%d)".formatted(r, g, b);
+    }
+}
+```
+
+### When to Use Records vs Classes
+
+| Use Record | Use Class |
+|------------|-----------|
+| Pure data containers | Entities with mutable state |
+| DTOs, value objects | Domain objects with lifecycle |
+| API response types | Services, repositories |
+| Config/settings | Mutable builders |
+
+---
+
+## Record Patterns (JEP 440)
+
+Deconstruct records directly in `instanceof` and `switch`:
+
+```java
+// instanceof deconstruction
+if (obj instanceof Point(int x, int y)) {
+    System.out.println("x=" + x + ", y=" + y);
+}
+
+// switch deconstruction
+String describe = switch (shape) {
+    case Circle(double r)             -> "circle r=%.2f".formatted(r);
+    case Rectangle(double w, double h) -> "rect %.1fx%.1f".formatted(w, h);
+    default -> "unknown";
+};
+
+// Nested patterns
+record ColoredPoint(Point point, Color color) {}
+
+if (obj instanceof ColoredPoint(Point(int x, int y), Color(int r, int g, int b))) {
+    System.out.printf("Colored point at (%d,%d) with rgb(%d,%d,%d)%n",
+        x, y, r, g, b);
+}
+```
+
+---
+
+## Sealed Classes (JEP 409)
+
+Sealed classes restrict which classes can implement/extend them, enabling exhaustive pattern matching.
+
+```java
+// Sealed interface with records
+sealed interface Shape permits Circle, Rectangle, Triangle {}
+
+record Circle(double radius) implements Shape {}
+record Rectangle(double width, double height) implements Shape {}
+record Triangle(double base, double height) implements Shape {}
+
+// Exhaustive switch — no default needed
+double area = switch (shape) {
+    case Circle(double r)             -> Math.PI * r * r;
+    case Rectangle(double w, double h) -> w * h;
+    case Triangle(double b, double h)  -> 0.5 * b * h;
+};
+
+// Sealed class hierarchy (non-record)
+sealed class Vehicle permits Car, Truck, Motorcycle {}
+final class Car extends Vehicle { }
+non-sealed class Truck extends Vehicle { } // allows further subclassing
+```
+
+### Benefits
+
+- Compiler enforces exhaustive handling in `switch`
+- Clear closed type hierarchy in domain model
+- Better than `enum` when subtypes carry different data
+
+---
+
+## Sequenced Collections (JEP 431)
+
+New interfaces: `SequencedCollection`, `SequencedSet`, `SequencedMap`.
+
+```java
+// SequencedCollection
+List<String> list = new ArrayList<>(List.of("a", "b", "c"));
+String first = list.getFirst(); // "a"
+String last  = list.getLast();  // "c"
+list.addFirst("z");             // ["z", "a", "b", "c"]
+list.addLast("end");            // ["z", "a", "b", "c", "end"]
+list.removeFirst();             // ["a", "b", "c", "end"]
+
+// Reversed view (live, backed by original)
+List<String> reversed = list.reversed();
+
+// SequencedMap
+LinkedHashMap<String, Integer> map = new LinkedHashMap<>();
+map.put("one", 1);
+map.put("two", 2);
+map.put("three", 3);
+
+Map.Entry<String, Integer> first = map.firstEntry(); // "one"=1
+Map.Entry<String, Integer> last  = map.lastEntry();  // "three"=3
+map.putFirst("zero", 0);       // inserts at front
+SequencedMap<String, Integer> rev = map.reversed();
+```
+
+---
+
+## Migration from Legacy Java
+
+### Replace instanceof chains
+
+```java
+// Legacy (avoid)
+if (obj instanceof String) {
+    return ((String) obj).length();
+} else if (obj instanceof Integer) {
+    return ((Integer) obj).intValue();
+}
+
+// Modern
+return switch (obj) {
+    case String s  -> s.length();
+    case Integer i -> i;
+    default -> -1;
+};
+```
+
+### Replace POJOs with Records
+
+```java
+// Legacy POJO (avoid for pure data)
+public class Point {
+    private final int x, y;
+    public Point(int x, int y) { this.x = x; this.y = y; }
+    public int getX() { return x; }
+    public int getY() { return y; }
+    @Override public boolean equals(Object o) { ... }
+    @Override public int hashCode() { ... }
+    @Override public String toString() { ... }
+}
+
+// Modern Record
+record Point(int x, int y) {}
+```
+
+### Replace thread pools for I/O with Virtual Threads
+
+```java
+// Legacy (avoid for I/O-bound)
+ExecutorService pool = Executors.newFixedThreadPool(200);
+
+// Modern
+ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor();
+```

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.30.9",
+  "version": "0.31.1",
   "lastUpdated": "2026-03-09T00:00:00.000Z",
   "components": [
     {
@@ -24,7 +24,7 @@
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 24
+      "files": 25
     },
     {
       "name": "hooks",

package/templates/.claude/skills/go-best-practices/CLAUDE.md

@@ -1,9 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-### Feb 5, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #8 | 8:07 PM | 🔵 | Skill Definition Structure | ~626 |
-</claude-mem-context>