claudecode-omc 4.8.3 → 4.9.3

package/skills/deep-interview/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: deep-interview
 description: Socratic deep interview with mathematical ambiguity gating before autonomous execution
-argument-hint: "<idea or vague description>"
+argument-hint: "[--quick|--standard|--deep] [--autoresearch] <idea or vague description>"
 pipeline: [deep-interview, omc-plan, autopilot]
 next-skill: omc-plan
 next-skill-args: --consensus --direct
 handoff: .omc/specs/deep-interview-{slug}.md
+level: 3
 ---
 
 <Purpose>
@@ -38,7 +39,9 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 <Execution_Policy>
 - Ask ONE question at a time -- never batch multiple questions
 - Target the WEAKEST clarity dimension with each question
+- Make weakest-dimension targeting explicit every round: name the weakest dimension, state its score/gap, and explain why the next question is aimed there
 - Gather codebase facts via `explore` agent BEFORE asking the user about them
+- For brownfield confirmation questions, cite the repo evidence that triggered the question (file path, symbol, or pattern) instead of asking the user to rediscover it
 - Score ambiguity after every answer -- display the score transparently
 - Do not proceed to execution until ambiguity ≤ threshold (default 0.2)
 - Allow early exit with a clear warning if ambiguity is still high
@@ -46,6 +49,17 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 - Challenge agents activate at specific round thresholds to shift perspective
 </Execution_Policy>
 
+<Autoresearch_Mode>
+When arguments include `--autoresearch`, Deep Interview becomes the zero-learning-curve setup lane for `omc autoresearch`.
+
+- If no usable mission brief is present yet, start by asking: **"What should autoresearch improve or prove for this repo?"**
+- After the mission is clear, collect an evaluator command. If the user leaves it blank, infer one only when repo evidence is strong; otherwise keep interviewing until an evaluator is explicit enough to launch safely.
+- Keep the usual one-question-per-round rule, but treat **mission clarity** and **evaluator clarity** as hard readiness gates in addition to the normal ambiguity threshold.
+- Once ready, do **not** bridge into `omc-plan`, `autopilot`, `ralph`, or `team`. Instead run:
+  - `omc autoresearch --mission "<mission>" --eval "<evaluator>" [--keep-policy <policy>] [--slug <slug>]`
+- This direct handoff is expected to detach into the real autoresearch runtime tmux session. After a successful handoff, announce the launched session and end the interview lane.
+</Autoresearch_Mode>
+
 <Steps>
 
 ## Phase 1: Initialize
@@ -70,7 +84,8 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
     "current_ambiguity": 1.0,
     "threshold": 0.2,
     "codebase_context": null,
-    "challenge_modes_used": []
+    "challenge_modes_used": [],
+    "ontology_snapshots": []
   }
 }
 ```
@@ -99,7 +114,9 @@ Build the question generation prompt with:
 **Question targeting strategy:**
 - Identify the dimension with the LOWEST clarity score
 - Generate a question that specifically improves that dimension
+- State, in one sentence before the question, why this dimension is now the bottleneck to reducing ambiguity
 - Questions should expose ASSUMPTIONS, not gather feature lists
+- If the scope is still conceptually fuzzy (entities keep shifting, the user is naming symptoms, or the core noun is unstable), switch to an ontology-style question that asks what the thing fundamentally IS before returning to feature/detail questions
 
 **Question styles by dimension:**
 | Dimension | Question Style | Example |
@@ -107,14 +124,15 @@ Build the question generation prompt with:
 | Goal Clarity | "What exactly happens when...?" | "When you say 'manage tasks', what specific action does a user take first?" |
 | Constraint Clarity | "What are the boundaries?" | "Should this work offline, or is internet connectivity assumed?" |
 | Success Criteria | "How do we know it works?" | "If I showed you the finished product, what would make you say 'yes, that's it'?" |
-| Context Clarity (brownfield) | "How does this fit?" | "The existing auth uses JWT in src/auth/. Should we extend that or add a separate flow?" |
+| Context Clarity (brownfield) | "How does this fit?" | "I found JWT auth middleware in `src/auth/` (pattern: passport + JWT). Should this feature extend that path or intentionally diverge from it?" |
+| Scope-fuzzy / ontology stress | "What IS the core thing here?" | "You have named Tasks, Projects, and Workspaces across the last rounds. Which one is the core entity, and which are supporting views or containers?" |
 
 ### Step 2b: Ask the Question
 
 Use `AskUserQuestion` with the generated question. Present it clearly with the current ambiguity context:
 
 ```
-Round {n} | Targeting: {weakest_dimension} | Ambiguity: {score}%
+Round {n} | Targeting: {weakest_dimension} | Why now: {one_sentence_targeting_rationale} | Ambiguity: {score}%
 
 {question}
 ```
@@ -136,17 +154,31 @@ Transcript:
 {all rounds Q&A}
 
 Score each dimension:
-1. Goal Clarity (0.0-1.0): Is the primary objective unambiguous? Can you state it in one sentence without qualifiers?
+1. Goal Clarity (0.0-1.0): Is the primary objective unambiguous? Can you state it in one sentence without qualifiers? Can you name the key entities (nouns) and their relationships (verbs) without ambiguity?
 2. Constraint Clarity (0.0-1.0): Are the boundaries, limitations, and non-goals clear?
 3. Success Criteria Clarity (0.0-1.0): Could you write a test that verifies success? Are acceptance criteria concrete?
-{4. Context Clarity (0.0-1.0): [brownfield only] Do we understand the existing system well enough to modify it safely?}
+{4. Context Clarity (0.0-1.0): [brownfield only] Do we understand the existing system well enough to modify it safely? Do the identified entities map cleanly to existing codebase structures?}
 
 For each dimension provide:
 - score: float (0.0-1.0)
 - justification: one sentence explaining the score
 - gap: what's still unclear (if score < 0.9)
 
-Respond as JSON.
+Also identify:
+- weakest_dimension: the single lowest-confidence dimension this round
+- weakest_dimension_rationale: one sentence explaining why it is the highest-leverage target for the next question
+
+5. Ontology Extraction: Identify all key entities (nouns) discussed in the transcript.
+
+{If round > 1, inject: "Previous round's entities: {prior_entities_json from state.ontology_snapshots[-1]}. REUSE these entity names where the concept is the same. Only introduce new names for genuinely new concepts."}
+
+For each entity provide:
+- name: string (the entity name, e.g., "User", "Order", "PaymentMethod")
+- type: string (e.g., "core domain", "supporting", "external system")
+- fields: string[] (key attributes mentioned)
+- relationships: string[] (e.g., "User has many Orders")
+
+Respond as JSON. Include an additional "ontology" key containing the entities array alongside the dimension scores.
 ```
 
 **Calculate ambiguity:**
@@ -154,6 +186,23 @@ Respond as JSON.
 Greenfield: `ambiguity = 1 - (goal × 0.40 + constraints × 0.30 + criteria × 0.30)`
 Brownfield: `ambiguity = 1 - (goal × 0.35 + constraints × 0.25 + criteria × 0.25 + context × 0.15)`
 
+**Calculate ontology stability:**
+
+**Round 1 special case:** For the first round, skip stability comparison. All entities are "new". Set stability_ratio = N/A. If any round produces zero entities, set stability_ratio = N/A (avoids division by zero).
+
+For rounds 2+, compare with the previous round's entity list:
+- `stable_entities`: entities present in both rounds with the same name
+- `changed_entities`: entities with different names but the same type AND >50% field overlap (treated as renamed, not new+removed)
+- `new_entities`: entities in this round not matched by name or fuzzy-match to any previous entity
+- `removed_entities`: entities in the previous round not matched to any current entity
+- `stability_ratio`: (stable + changed) / total_entities (0.0 to 1.0, where 1.0 = fully converged)
+
+This formula counts renamed entities (changed) toward stability. Renamed entities indicate the concept persists even if the name shifted — this is convergence, not instability. Two entities with different names but the same `type` and >50% field overlap should be classified as "changed" (renamed), not as one removed and one added.
+
+**Show your work:** Before reporting stability numbers, briefly list which entities were matched (by name or fuzzy) and which are new/removed. This lets the user sanity-check the matching.
+
+Store the ontology snapshot (entities + stability_ratio + matching_reasoning) in `state.ontology_snapshots[]`.
+
 ### Step 2d: Report Progress
 
 After scoring, show the user their progress:
@@ -169,6 +218,10 @@ Round {n} complete.
 | Context (brownfield) | {s} | {w} | {s*w} | {gap or "Clear"} |
 | **Ambiguity** | | | **{score}%** | |
 
+**Ontology:** {entity_count} entities | Stability: {stability_ratio} | New: {new} | Changed: {changed} | Stable: {stable}
+
+**Next target:** {weakest_dimension} — {weakest_dimension_rationale}
+
 {score <= threshold ? "Clarity threshold met! Ready to proceed." : "Focusing next question on: {weakest_dimension}"}
 ```
 
@@ -196,7 +249,7 @@ Inject into the question generation prompt:
 
 ### Round 8+: Ontologist Mode (if ambiguity still > 0.3)
 Inject into the question generation prompt:
-> You are now in ONTOLOGIST mode. The ambiguity is still high after 8 rounds, suggesting we may be addressing symptoms rather than the core problem. Ask "What IS this, really?" or "If you could only describe this in one sentence to a colleague, what would you say?" The goal is to find the essence.
+> You are now in ONTOLOGIST mode. The ambiguity is still high after 8 rounds, suggesting we may be addressing symptoms rather than the core problem. The tracked entities so far are: {current_entities_summary from latest ontology snapshot}. Ask "What IS this, really?" or "Looking at these entities, which one is the CORE concept and which are just supporting?" The goal is to find the essence by examining the ontology.
 
 Challenge modes are used ONCE each, then return to normal Socratic questioning. Track which modes have been used in state.
 
@@ -259,9 +312,21 @@ Spec structure:
 {greenfield: technology choices and constraints}
 
 ## Ontology (Key Entities)
-| Entity | Fields | Relationships |
-|--------|--------|---------------|
-| {entity} | {field1, field2} | {relates to...} |
+{Fill from the FINAL round's ontology extraction, not just crystallization-time generation}
+
+| Entity | Type | Fields | Relationships |
+|--------|------|--------|---------------|
+| {entity.name} | {entity.type} | {entity.fields} | {entity.relationships} |
+
+## Ontology Convergence
+{Show how entities stabilized across interview rounds using data from ontology_snapshots in state}
+
+| Round | Entity Count | New | Changed | Stable | Stability Ratio |
+|-------|-------------|-----|---------|--------|----------------|
+| 1 | {n} | {n} | - | - | - |
+| 2 | {n} | {new} | {changed} | {stable} | {ratio}% |
+| ... | ... | ... | ... | ... | ... |
+| {final} | {n} | {new} | {changed} | {stable} | {ratio}% |
 
 ## Interview Transcript
 <details>
@@ -278,6 +343,8 @@ Spec structure:
 
 ## Phase 5: Execution Bridge
 
+**Autoresearch override:** if `--autoresearch` is active, skip the standard execution options below. The only valid bridge is the direct `omc autoresearch --mission ... --eval ...` handoff described above.
+
 After the spec is written, present execution options via `AskUserQuestion`:
 
 **Question:** "Your spec is ready (ambiguity: {score}%). How would you like to proceed?"
@@ -353,7 +420,7 @@ Next question targets Constraints (lowest at 0.4):
 a responsive web app, or a PWA? And are there specific devices or OS versions
 you need to support?"
 ```
-Why good: Identifies weakest dimension, asks specific question to improve it, doesn't batch multiple topics.
+Why good: Identifies weakest dimension, explains why it is now the bottleneck, asks a specific question to improve it, and doesn't batch multiple topics.
 </Good>
 
 <Good>
@@ -362,11 +429,11 @@ Gathering codebase facts before asking:
 [spawns explore agent: "find authentication implementation"]
 [receives: "Auth is in src/auth/ using JWT with passport.js"]
 
-Question: "I see your project uses JWT authentication with passport.js in src/auth/.
+Question: "I found JWT authentication with passport.js in `src/auth/` (pattern match from explore).
 For this new feature, should we extend the existing auth middleware or create
 a separate authentication flow?"
 ```
-Why good: Explored first, then asked an informed question. Never asks the user what the code already reveals.
+Why good: Explored first, cited the repo evidence that triggered the question, then asked an informed confirmation question. Never asks the user what the code already reveals.
 </Good>
 
 <Good>
@@ -395,6 +462,29 @@ Proceeding may require rework. Continue anyway?"
 Why good: Respects user's desire to stop but transparently shows the risk.
 </Good>
 
+<Good>
+Ontology convergence tracking:
+```
+Round 3 entities: User, Task, Project (stability: N/A → 67%)
+Round 4 entities: User, Task, Project, Tag (stability: 75% — 3 stable, 1 new)
+Round 5 entities: User, Task, Project, Tag (stability: 100% — all 4 stable)
+
+"Ontology has converged — the same 4 entities appeared in 2 consecutive rounds
+with no changes. The domain model is stable."
+```
+Why good: Shows entity tracking across rounds with visible convergence. Stability ratio increases as the domain model solidifies, giving mathematical evidence that the interview is converging on a stable understanding.
+</Good>
+
+<Good>
+Ontology-style question for scope-fuzzy tasks:
+```
+Round 6 | Targeting: Goal Clarity | Why now: the core entity is still unstable across rounds, so feature questions would compound ambiguity | Ambiguity: 38%
+
+"Across the last rounds you've described this as a workflow, an inbox, and a planner. Which one is the core thing this product IS, and which ones are supporting metaphors or views?"
+```
+Why good: Uses ontology-style questioning to stabilize the core noun before drilling into features, which is the right move when the scope is fuzzy rather than merely incomplete.
+</Good>
+
 <Bad>
 Batching multiple questions:
 ```
@@ -434,6 +524,7 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 <Final_Checklist>
 - [ ] Interview completed (ambiguity ≤ threshold OR user chose early exit)
 - [ ] Ambiguity score displayed after every round
+- [ ] Every round explicitly names the weakest dimension and why it is the next target
 - [ ] Challenge agents activated at correct thresholds (round 4, 6, 8)
 - [ ] Spec file written to `.omc/specs/deep-interview-{slug}.md`
 - [ ] Spec includes: goal, constraints, acceptance criteria, clarity breakdown, transcript
@@ -441,6 +532,10 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 - [ ] Selected execution mode invoked via Skill() (never direct implementation)
 - [ ] If 3-stage pipeline selected: omc-plan --consensus --direct invoked, then autopilot with consensus plan
 - [ ] State cleaned up after execution handoff
+- [ ] Brownfield confirmation questions cite repo evidence (file/path/pattern) before asking the user to decide
+- [ ] Scope-fuzzy tasks can trigger ontology-style questioning to stabilize the core entity before feature elaboration
+- [ ] Per-round ambiguity report includes Ontology row with entity count and stability ratio
+- [ ] Spec includes Ontology (Key Entities) table and Ontology Convergence section
 </Final_Checklist>
 
 <Advanced>

package/skills/deepinit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: deepinit
 description: Deep codebase initialization with hierarchical AGENTS.md documentation
+level: 4
 ---
 
 # Deep Init Skill

package/skills/e2e/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: e2e
+description: Playwright end-to-end orchestration for critical user journeys, artifact capture, flaky-test isolation, and CI-ready reporting.
+---
+
+# E2E
+
+Use this as the top-level end-to-end testing orchestrator.
+
+## Use When
+
+- Validating cross-layer user journeys
+- Preparing release confidence checks
+- Reproducing user-facing regressions
+
+## Workflow
+
+1. Define critical journeys and acceptance assertions.
+2. Generate or update Playwright tests.
+3. Run targeted tests first, then broader suites.
+4. Capture artifacts (trace/screenshot/video/report).
+5. Identify flakes and quarantine when needed.
+
+## Playwright Best Practices
+
+- Test user-visible behavior and assertions.
+- Keep tests isolated and deterministic.
+- Prefer resilient locators (`getByRole`, `getByLabelText`, `getByText`).
+- Use web-first assertions and auto-waiting.
+- Mock or isolate third-party dependencies when they are not under test.
+
+## Suggested Config
+
+```ts
+// playwright.config.ts
+use: {
+  trace: 'retain-on-failure',
+  video: 'retain-on-failure',
+  screenshot: 'only-on-failure',
+},
+retries: process.env.CI ? 2 : 0
+```
+
+## Electron Routing
+
+If the target is an Electron app, use `/oh-my-claudecode:electron-driver` as the runtime backend while keeping Playwright assertions and artifacts.
+
+## References
+
+- Best practices: https://playwright.dev/docs/best-practices
+- Actionability / auto-waiting: https://playwright.dev/docs/actionability
+- Trace viewer: https://playwright.dev/docs/trace-viewer
+- Retries and flaky handling: https://playwright.dev/docs/test-retries
+- Codegen: https://playwright.dev/docs/codegen-intro
+

package/skills/electron-driver/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: electron-driver
+description: Playwright-based E2E driving for Electron applications using launch mode or attach mode with robust window selection and runtime inspection.
+---
+
+# Electron Driver
+
+Use this skill for Electron runtime automation and debugging.
+
+## Modes
+
+- Launch mode (preferred for clean CI runs)
+- Attach mode (preferred for debugging existing sessions)
+
+## Prerequisites
+
+```bash
+pnpm add -D playwright-core @playwright/test
+```
+
+## Launch Mode (recommended)
+
+```ts
+import { _electron as electron } from 'playwright';
+
+const electronApp = await electron.launch({ args: ['.'] });
+const page = await electronApp.firstWindow();
+```
+
+Use locators on `page` for UI actions and assertions.
+
+## Attach Mode
+
+- Start Electron with `--remote-debugging-port=<port>`
+- Connect via CDP and pick the non-`devtools://` page
+
+Template: `skills/electron-driver/scripts/driver-template.js`
+
+## Best Practices
+
+- Filter out DevTools pages before interaction.
+- Use role/text-based locators for resilience.
+- Keep launch mode for stable regression suites.
+- Use attach mode for live bug reproduction.
+- Capture trace/screenshot artifacts for failures.
+
+## References
+
+- Playwright Electron API: https://playwright.dev/docs/api/class-electron
+- Electron automated testing: https://www.electronjs.org/docs/latest/tutorial/automated-testing
+

package/skills/electron-driver/scripts/driver-template.js

@@ -0,0 +1,46 @@
+const { chromium } = require('playwright-core');
+
+/**
+ * Electron attach-mode template.
+ *
+ * Usage:
+ * 1) Start Electron with --remote-debugging-port=<PORT>
+ * 2) Optionally set CDP_PORT env var
+ * 3) Run: node skills/electron-driver/scripts/driver-template.js
+ */
+
+const CDP_PORT = process.env.CDP_PORT || 9222;
+const CDP_URL = `http://localhost:${CDP_PORT}`;
+
+async function run() {
+  let browser;
+  try {
+    browser = await chromium.connectOverCDP(CDP_URL);
+    const context = browser.contexts()[0];
+    if (!context) throw new Error('No browser context found');
+
+    const page = context.pages().find((p) => !p.url().startsWith('devtools://'));
+    if (!page) throw new Error('No Electron app page found');
+
+    console.log(
+      JSON.stringify({
+        status: 'success',
+        title: await page.title(),
+        url: page.url(),
+      })
+    );
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        status: 'error',
+        message: error.message,
+      })
+    );
+    process.exitCode = 1;
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+run();
+

package/skills/external-context/SKILL.md

@@ -2,6 +2,7 @@
 name: external-context
 description: Invoke parallel document-specialist agents for external web searches and documentation lookup
 argument-hint: <search query or topic>
+level: 4
 ---
 
 # External Context Skill

package/skills/hud/SKILL.md

@@ -3,6 +3,7 @@ name: hud
 description: Configure HUD display options (layout, presets, display elements)
 role: config-writer  # DOCUMENTATION ONLY - This skill writes to ~/.claude/ paths
 scope: ~/.claude/**  # DOCUMENTATION ONLY - Allowed write scope
+level: 2
 ---
 
 # HUD Skill
@@ -151,21 +152,21 @@ node -e "if(process.platform==='win32'){console.log('Skipped (Windows)')}else{re
 
 Read `~/.claude/settings.json`, then update/add the `statusLine` field.
 
-**IMPORTANT:** The command must use an absolute path, not `~`, because Windows does not expand `~` in shell commands.
+**IMPORTANT:** Do not use `~` in the command. On Unix, use `$HOME` to keep the path portable across machines. On Windows, use an absolute path because Windows does not expand `~` in shell commands.
 
-First, determine the correct path:
+If you are on Windows, first determine the correct path:
 ```bash
 node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs').split(require('path').sep).join('/');console.log(JSON.stringify(p))"
 ```
 
 **IMPORTANT:** The command path MUST use forward slashes on all platforms. Claude Code executes statusLine commands via bash, which interprets backslashes as escape characters and breaks the path.
 
-Then set the `statusLine` field using the resolved path. On Unix it will look like:
+Then set the `statusLine` field. On Unix it should stay portable and look like:
 ```json
 {
   "statusLine": {
     "type": "command",
-    "command": "node /home/username/.claude/hud/omc-hud.mjs"
+    "command": "node $HOME/.claude/hud/omc-hud.mjs"
   }
 }
 ```
@@ -319,7 +320,7 @@ If the HUD is not showing:
 {
   "statusLine": {
     "type": "command",
-    "command": "node /home/username/.claude/hud/omc-hud.mjs"
+    "command": "node $HOME/.claude/hud/omc-hud.mjs"
   }
 }
 ```

package/skills/learner/SKILL.md

@@ -1,11 +1,25 @@
 ---
 name: learner
 description: Extract a learned skill from the current conversation
+level: 7
 ---
 
 # Learner Skill
 
-## The Insight
+This is a Level 7 (self-improving) skill. It has two distinct sections:
+- **Expertise**: Domain knowledge about what makes a good skill. Updated automatically as patterns are discovered.
+- **Workflow**: Stable extraction procedure. Rarely changes.
+
+Only the Expertise section should be updated during improvement cycles.
+
+---
+
+## Expertise
+
+> This section contains domain knowledge that improves over time.
+> It can be updated by the learner itself when new patterns are discovered.
+
+### Core Principle
 
 Reusable skills are not code snippets to copy-paste, but **principles and decision-making heuristics** that teach Claude HOW TO THINK about a class of problems.
 
@@ -13,62 +27,23 @@ Reusable skills are not code snippets to copy-paste, but **principles and decisi
 - BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
 - GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."
 
-A good skill changes how Claude APPROACHES problems, not just what code it produces.
-
-## Why This Matters
-
-Before extracting a skill, ask yourself:
-- "Could someone Google this in 5 minutes?" → If yes, STOP. Don't extract.
-- "Is this specific to THIS codebase?" → If no, STOP. Don't extract.
-- "Did this take real debugging effort to discover?" → If no, STOP. Don't extract.
+### Quality Gate
 
-If a potential skill fails any of these questions, it's not worth saving.
+Before extracting a skill, ALL three must be true:
+- "Could someone Google this in 5 minutes?" → NO
+- "Is this specific to THIS codebase?" → YES
+- "Did this take real debugging effort to discover?" → YES
 
-## Recognition Pattern
+### Recognition Signals
 
-Use /oh-my-claudecode:learner ONLY after:
+Extract ONLY after:
 - Solving a tricky bug that required deep investigation
 - Discovering a non-obvious workaround specific to this codebase
 - Finding a hidden gotcha that wastes time when forgotten
 - Uncovering undocumented behavior that affects this project
 
-## The Approach
-
-### Extraction Process
-
-**Step 1: Gather Required Information**
-
-- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
-  - Include actual error messages, file paths, line numbers
-  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
-
-- **Solution**: The EXACT fix, not general advice
-  - Include code snippets, file paths, configuration changes
-  - Example: "Add null check before accessing session.user, regenerate session on 401"
-
-- **Triggers**: Keywords that would appear when hitting this problem again
-  - Use error message fragments, file names, symptom descriptions
-  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
-
-- **Scope**: Almost always Project-level unless it's a truly universal insight
-
-**Step 2: Quality Validation**
-
-The system REJECTS skills that are:
-- Too generic (no file paths, line numbers, or specific error messages)
-- Easily Googleable (standard patterns, library usage)
-- Vague solutions (no code snippets or precise instructions)
-- Poor triggers (generic words that match everything)
-
-**Step 3: Save Location**
-
-- **User-level**: ~/.claude/skills/omc-learned/ - Rare. Only for truly portable insights.
-- **Project-level**: .omc/skills/ - Default. Version-controlled with repo.
-
 ### What Makes a USEFUL Skill
 
-**CRITICAL**: Not every solution is worth saving. A good skill is:
-
 1. **Non-Googleable**: Something you couldn't easily find via search
    - BAD: "How to read files in TypeScript" ❌
    - GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
@@ -93,35 +68,66 @@ The system REJECTS skills that are:
 - Type definitions or boilerplate
 - Anything a junior dev could Google in 5 minutes
 
-## Skill Format
+---
+
+## Workflow
+
+> This section contains the stable extraction procedure.
+> It should NOT be updated during improvement cycles.
 
-Skills are saved as markdown with this structure:
+### Step 1: Gather Required Information
 
-### YAML Frontmatter
+- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
+  - Include actual error messages, file paths, line numbers
+  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
 
-Standard metadata fields:
-- id, name, description, source, triggers, quality
+- **Solution**: The EXACT fix, not general advice
+  - Include code snippets, file paths, configuration changes
+  - Example: "Add null check before accessing session.user, regenerate session on 401"
+
+- **Triggers**: Keywords that would appear when hitting this problem again
+  - Use error message fragments, file names, symptom descriptions
+  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **Scope**: Almost always Project-level unless it's a truly universal insight
+
+### Step 2: Quality Validation
+
+The system REJECTS skills that are:
+- Too generic (no file paths, line numbers, or specific error messages)
+- Easily Googleable (standard patterns, library usage)
+- Vague solutions (no code snippets or precise instructions)
+- Poor triggers (generic words that match everything)
+
+### Step 3: Classify as Expertise or Workflow
+
+Before saving, determine if the learning is:
+- **Expertise** (domain knowledge, pattern, gotcha) → Save as `{topic}-expertise.md`
+- **Workflow** (operational procedure, step sequence) → Save as `{topic}-workflow.md`
+
+This classification ensures expertise can be updated independently without destabilizing workflows.
+
+### Step 4: Save Location
+
+- **User-level**: ~/.claude/skills/omc-learned/ - Rare. Only for truly portable insights.
+- **Project-level**: .omc/skills/ - Default. Version-controlled with repo.
 
-### Body Structure (Required)
+### Skill Body Template
 
 ```markdown
 # [Skill Name]
 
 ## The Insight
 What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.
-Example: "Async I/O operations are independently failable. Client lifecycle != server lifecycle."
 
 ## Why This Matters
 What goes wrong if you don't know this? What symptom led you here?
-Example: "Proxy server crashes on client disconnect, taking down other requests."
 
 ## Recognition Pattern
 How do you know when this skill applies? What are the signs?
-Example: "Building any long-lived connection handler (proxy, websocket, SSE)"
 
 ## The Approach
 The decision-making heuristic, not just code. How should Claude THINK about this?
-Example: "For each I/O operation, ask: what if this fails right now? Handle it locally."
 
 ## Example (Optional)
 If code helps, show it - but as illustration of the principle, not copy-paste material.

package/skills/mcp-setup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: mcp-setup
 description: Configure popular MCP servers for enhanced agent capabilities
+level: 2
 ---
 
 # MCP Setup