openlore 2.0.0

package/examples/mistral-vibe/skills/openlore-implement-story/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: openlore-implement-story
+description: Implement a story on a brownfield codebase using openlore structural context. Runs orient + risk check before coding, validates against specs, enforces a test gate before drift check.
+license: MIT
+compatibility: openlore MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - str_replace_based_edit
+  - replace_in_file
+  - run_command
+  - openlore-execute-refactor
+---
+
+# openlore: Implement Story
+
+## When to use this skill
+
+Trigger this skill when the user asks to **implement a story or task** on a codebase that has
+openlore analysis available, with phrasings like:
+- "implement story X"
+- "work on task Y"
+- "start implementing this feature"
+- explicit command `/openlore-implement-story`
+
+**Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
+If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
+
+---
+
+## Step 1 — Read the story and risk context
+
+Read the story file. Extract:
+- `$STORY_TITLE`, `$AC` (acceptance criteria), `$PROJECT_ROOT`
+- `$RISK_CONTEXT` — the `risk_context` section if present (pre-filled by Architect Agent)
+
+| Situation | Approach |
+|---|---|
+| `risk_context` present, risk 🟢 < 40 | Skip to Step 3 — use insertion point from context |
+| `risk_context` present, risk 🟡 40–69 | Run Step 2 impact check, then proceed |
+| `risk_context` present, risk 🔴 ≥ 70 | Stop — a blocking refactor story must be resolved first |
+| `risk_context` absent | Run the full Step 2 orientation |
+
+---
+
+## Step 2 — Orient and assess risk
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+For the top 2 functions returned, get minimal context first (callers, callees, body, test coverage):
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_minimal_context</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+**What to read before proceeding:**
+- `function.riskLevel` — `"high"` = fanIn ≥ 30 or fanOut ≥ 15; tool expanded lists to 24 entries — all are blast-radius members.
+- `callers[*].callType` — all `"awaited"` = async interface frozen; signature change breaks every caller silently in JS. Mixed = looser coupling.
+- `callees[*].isExternal: true` — external boundary; new paths may pass mocked tests but fail in production.
+- `testedBy[*].confidence` — `"called"` = direct test (strong). `"imported"` only = `vi.mock()` can neutralize; treat as untested.
+
+If `riskLevel` is `"high"` or any callee is external, also check the cluster:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_cluster</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+- `clusterDensity < 0.05` → isolated, proceed
+- `clusterDensity 0.05–0.15` → check `internalCallGraph` for transitively dependent functions
+- `clusterDensity > 0.15` → dense cluster; coordinate scope with user first
+
+Then check risk:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$FUNCTION_NAME",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+**If any function has `riskScore ≥ 70`: stop.**
+Do not implement. Run `/openlore-execute-refactor` on the blocking function first, or create a
+blocking refactor task and return to this story once the risk is resolved.
+
+---
+
+## Step 2.5 — Stack inventory (conditional)
+
+Based on the story title and orient results, call the relevant inventory tool(s) **before reading any source file**. Skip if the story clearly involves none of these areas.
+
+| Story involves | Tool | Purpose |
+|---|---|---|
+| Data models / ORM / database / tables | `get_schema_inventory` | See existing tables and fields — don't re-invent what already exists |
+| HTTP routes / API / endpoints | `get_route_inventory` | See existing routes before adding new ones |
+| Config / env vars / secrets | `get_env_vars` | Identify which vars are required vs have defaults |
+| UI components | `get_ui_components` | See existing component props and framework |
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_schema_inventory</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Use the results to ground the implementation in existing schemas/routes — the plan cannot contradict what already exists.
+
+---
+
+
+## Step 3 — Check the spec
+
+First, verify that OpenSpec specs exist:
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l
+```
+
+**If 0 specs found:**
+> No OpenSpec specs exist yet. `search_specs` will return empty results and
+> `check_spec_drift` (Step 7) will flag everything as uncovered.
+>
+> Recommended: run `/openlore-generate` after this story to create a spec baseline.
+> You only need to do this once.
+>
+> Continuing with structural analysis only.
+
+Skip the `search_specs` call and go to Step 4.
+
+**If specs exist:**
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "query": "$STORY_TITLE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+If relevant requirements are found, read the domain spec before writing any code.
+Note any constraints that apply.
+
+---
+
+## Step 3.5 — Audit spec coverage of the target domain
+
+Run a parity audit to check if the domain you're about to touch has spec gaps.
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>audit_spec_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+From the result, check:
+- `staleDomains` — if the target domain appears here, its spec is outdated.
+  Recommend running `openlore generate --domains $DOMAIN` before implementing.
+- `hubGaps` — uncovered hub functions. If the feature touches one of these,
+  add it to the adversarial check in Step 4b (high blast radius + no spec = risk).
+
+If both are clean, continue to Step 4 without action.
+
+---
+
+## Step 4 — Find the insertion point
+
+Use `insertion_points` from `risk_context` if present. Otherwise:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "$STORY_TITLE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Read the skeleton of the target file:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_function_skeleton</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "filePath": "$TARGET_FILE"
+  }</arguments>
+</use_mcp_tool>
+```
+
+**Confirm the approach with the user before writing code.**
+
+### Step 4b — Adversarial challenge
+
+Before writing any code, state explicitly what could break with this approach.
+If `.claude/antipatterns.md` exists, read it and include any applicable patterns.
+
+> "Risk check on `$INSERTION_POINT`:
+> - `$CALLER_A` and `$CALLER_B` depend on this function — verify their assumptions
+>   hold after the change.
+> - `$EDGE_CASE` is not covered by the current test suite — add it in Step 6.
+> - [if antipatterns apply] AP-NNN (`$PATTERN_NAME`) — `$RULE` — applies here because `$REASON`."
+
+This is not a gate — do not wait for user input. It is a mandatory self-check
+that must appear in the output before the first line of code is written.
+
+---
+
+### Step 4c — Record the design decision
+
+Before writing any code, record the implementation approach if it represents a significant architectural choice:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>record_decision</tool_name>
+  <arguments>{
+    "directory": "$DIRECTORY",
+    "title": "$APPROACH_TITLE",
+    "rationale": "$WHY_THIS_APPROACH",
+    "consequences": "$TRADE_OFFS",
+    "affectedFiles": ["$TARGET_FILE"]
+  }</arguments>
+</use_mcp_tool>
+```
+
+Call this for: a non-obvious insertion point, a pattern chosen over alternatives, a new dependency introduced, or an interface contract established. Skip for trivial changes where the approach is self-evident.
+
+---
+
+## Step 5 — Implement
+
+Apply changes in this order:
+1. New types/interfaces (if needed)
+2. Core logic at the insertion point
+3. Updated call sites (if any)
+
+Do not touch functions outside the scope identified in Step 2 / `risk_context` without
+re-running the gate.
+
+**Small model constraint**: if the model is under 13B parameters (Mistral Small, Phi, Gemma…),
+each edit must touch a contiguous block of at most 50 lines. Split larger changes.
+
+---
+
+## Step 6 — Tests
+
+Both levels required before proceeding to Step 7.
+
+**Mandatory — existing tests must not regress:**
+Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.
+
+**Recommended — at least one new test per AC:**
+Write a test that directly exercises the behaviour described in the acceptance criterion.
+
+| Situation | Action |
+|---|---|
+| All tests green, new tests written | Proceed to Step 7 |
+| Existing test broken | Fix regression. Do not proceed. |
+| New test reveals a misunderstanding of the AC | Return to Step 5, adjust implementation |
+| Brownfield: no existing test coverage | Write the new test anyway. Note the coverage gap. |
+
+---
+
+## Step 7 — Verify drift
+
+Only run once tests are green.
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+| Drift type | Resolution |
+|---|---|
+| `uncovered` on new files | Note it — propose `openlore generate` post-sprint |
+| `gap` on existing domain | Run `openlore generate --domains $DOMAIN` |
+| `stale` | Fix the reference |
+| No drift | Done |
+
+---
+
+## Absolute constraints
+
+- Do not write code before Step 4 confirmation
+- If `riskScore ≥ 70` — stop, do not work around it, run `/openlore-execute-refactor` first
+- Do not run `check_spec_drift` before tests are green
+- Do not propose a spec update on untested code

package/examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: openlore-plan-refactor
+description: Identify the highest-priority refactoring target using static analysis, assess its blast radius, and produce a detailed written plan saved to .openlore/refactor-plan.md. Makes no code changes.
+license: MIT
+compatibility: openlore MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - openlore-analyze-codebase
+---
+
+# openlore: Plan Refactor
+
+## When to use this skill
+
+Trigger this skill whenever the user asks to **plan a refactoring** on a codebase, with phrasings like:
+- "plan a refactoring of X"
+- "analyze my code and prepare a refactor plan"
+- "generate a refactoring plan"
+- "I want to refactor this function / this file"
+- explicit command `/openlore-plan-refactor`
+
+**This skill modifies no code files.** It only produces `.openlore/refactor-plan.md`.
+To apply the plan, use the `openlore-execute-refactor` skill.
+
+---
+
+## ⚠️ Fundamental principle — each change is a complete mini-development
+
+**The plan must be written so that every entry in the change sequence is independently executable and testable.**
+
+Each change = one atomic edit → one diff verification → one full test run → ✅ or rollback.
+
+This is not a final gate at the end. Testing is a mandatory sub-step after **every single change**.
+The plan must make this cycle explicit and impossible to skip.
+
+**For Devstral Small 2**: each change must touch at most **50 contiguous lines** in the source file.
+If a logical extraction exceeds this limit, split it into smaller sub-changes, each with its own test gate.
+
+---
+
+## User-specified target — shortcut path
+
+If the user has already named a specific file or function to refactor:
+- **Skip** Steps 2, 3, and 3b (discovery is not needed).
+- **Do not skip** Steps 3c, 4, 5, 6, and 6b — coverage check and impact analysis are mandatory regardless of how the target was chosen.
+- Jump directly to Step 3c using the user-provided target.
+
+---
+
+## Step 1 — Confirm the project directory
+
+Ask the user which project to analyze, or confirm the current workspace root.
+
+---
+
+## Step 2 — Run static analysis
+
+Analyze the project via the `openlore` MCP server. If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 3 — Get the refactoring report
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+Present the top 5 candidates:
+
+| Function | File | Issues | Priority score |
+|---|---|---|---|
+
+---
+
+## Step 3b — Check for duplicate code
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+If a top candidate appears in a clone group, prepend a **deduplication note** to the plan:
+> "⚠️ `<function>` has N near-clones. Consolidate them first to reduce the blast radius of this refactor."
+
+---
+
+## Step 3c — Check test coverage
+
+Before presenting a choice to the user, check test coverage for the files containing the candidates. Detect the coverage tool from the project:
+
+| Ecosystem | Command |
+|---|---|
+| Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` |
+| Python | `pytest --cov=<module> --cov-report=term-missing` |
+| Rust | `cargo tarpaulin --include-files <files>` |
+| Go | `go test -cover ./...` |
+
+Enrich the candidate table:
+
+| Function | File | Priority | Coverage |
+|---|---|---|---|
+| ... | ... | ... | 72% ✅ / 35% ⚠️ / 0% 🚫 |
+
+**Thresholds:**
+
+| Coverage | Badge | Meaning |
+|---|---|---|
+| ≥ 70% lines | ✅ | Safe to refactor |
+| 40–69% lines | ⚠️ | Write characterisation tests first |
+| < 40% lines | 🛑 | Strongly discouraged |
+| 0% (no tests) | 🚫 | Blocked — propose a test harness first |
+
+If **all candidates are below 40%**:
+> "Every high-priority target has insufficient test coverage (< 40%). I recommend writing a minimal test harness for at least one target before proceeding. Would you like me to suggest test cases based on the function signatures?"
+
+---
+
+## Step 4 — Get minimal context + analyze impact
+
+Get the condensed view (callers, callees, body, test coverage) in one call:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_minimal_context</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+**What to read before deciding whether to proceed:**
+- `function.riskLevel` — `"high"` = up to 24 callers/callees shown; read all, they are all in scope.
+- `callers[*].callType` — all `"awaited"` = async interface frozen; extracting or splitting requires updating every call site.
+- `testedBy[*].confidence` — `"imported"` only = `vi.mock()` can neutralize; write a characterisation test before refactoring.
+
+Then get full impact analysis:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "symbol": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+Note: risk score (0–100), recommended strategy (`extract` / `split` / `facade` / `delegate`), top 5 upstream callers and downstream callees.
+
+**If `riskLevel` is `"high"` or impact risk score ≥ 60**, check cluster scope:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_cluster</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+- `clusterDensity < 0.05` → extract target independently
+- `clusterDensity 0.05–0.15` → include `internalCallGraph` callers in risk section
+- `clusterDensity > 0.15` → refactor whole cluster together or not at all
+
+---
+
+## Step 5 — Visualise the call neighbourhood
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME", "direction": "both", "format": "mermaid"}</arguments>
+</use_mcp_tool>
+```
+
+Show the Mermaid diagram to the user.
+
+---
+
+## Step 6 — Find safe entry points (bottom-up)
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_low_risk_refactor_candidates</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePattern": "$TARGET_FILE", "limit": 5}</arguments>
+</use_mcp_tool>
+```
+
+Cross-reference with the subgraph from Step 5: a good first extraction candidate already appears as a callee of the target function.
+
+---
+
+## Step 6b — Find insertion points for extracted helpers
+
+Before designing the change sequence, identify where extracted functions should land.
+This avoids creating helpers in the wrong file or layer.
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "extract helper from $FUNCTION_NAME", "limit": 5}</arguments>
+</use_mcp_tool>
+```
+
+For each candidate, note its role and strategy. Prefer candidates that already call into — or are called by — the target function (visible in the Step 5 subgraph).
+
+---
+
+## Step 7 — Design the change sequence
+
+Design an ordered sequence of atomic changes based on the strategy from Step 4.
+
+### Size constraint (mandatory for Devstral Small 2)
+
+**Each change must touch at most 50 contiguous lines** in the source file.
+If a logical extraction requires moving more than 50 lines in one pass, split it into sub-changes:
+- Sub-change A: extract the inner block (≤ 50 lines)
+- Sub-change B: extract the outer wrapper (≤ 50 lines)
+Each sub-change gets its own test gate. Never group two sub-changes before testing.
+
+### Each change must specify
+
+- **What**: the exact block to move (line range or description)
+- **Lines touched**: estimated count in source file — must be ≤ 50
+- **New name**: the function or method name to give it
+- **Target file**: existing or new file (with justification)
+- **Target class** (if applicable)
+- **Call sites to update**: list each `file:line`
+- **Test gate**: exact test command to run after this change
+
+### Mini-development cycle per change (write this explicitly in the plan)
+
+```
+READ plan entry → EDIT (targeted, ≤ 50 lines) → DIFF verify → TEST
+  ├─ green → mark ✅, next change
+  └─ red   → git checkout HEAD -- <file>, diagnose, retry
+             after 3 failed retries → STOP, report to user
+```
+
+The plan must show this cycle in the change sequence, not just in a footnote.
+
+**Rules per strategy:**
+
+| Strategy | Rule |
+|---|---|
+| `split` | Decompose into N sub-functions in the same file unless they clearly belong elsewhere |
+| `extract` | Place in the nearest cohesive module or create a new file if none exists |
+| `facade` | Keep the original signature, delegate to smaller functions; companion module if > 300 lines |
+| `delegate` | Move ownership logic to callers; update every caller file in the upstream chain |
+
+**Present the full sequence and wait for confirmation before writing the plan file.**
+
+---
+
+## Step 8 — Write `.openlore/refactor-plan.md`
+
+Fill every section — **leave nothing as "TBD"**.
+
+```markdown
+# Refactor Plan
+
+Generated: <ISO date>
+Workflow: /openlore-plan-refactor → /openlore-execute-refactor
+
+## Target
+- **Function**: <n>
+- **File**: <relative path>
+- **Lines**: <start>–<end>
+- **Risk score**: <0–100>
+- **Strategy**: <extract | split | facade | delegate>
+- **Priority score before refactor**: <value>
+
+## Why
+- <issue 1>
+- <issue 2>
+
+## Callers (upstream — must not break)
+| Caller | File |
+|---|---|
+
+## Callees (downstream — candidates for extraction)
+| Callee | File |
+|---|---|
+
+## Coverage baseline
+- **File**: <target file>
+- **Coverage**: <X>% lines, <Y>% branches
+- **Status**: ✅ safe / ⚠️ caution / 🛑 discouraged
+- **Test command**: <exact command>
+
+## Change sequence
+Each change is a complete mini-development: edit → diff → test → ✅ or rollback.
+Never advance to the next change without a green test gate.
+
+### Change 1 — <short label>
+- **What**: extract lines <start>–<end> (logic: <one-line description>)
+- **Lines touched in source**: ~<N> lines (must be ≤ 50)
+- **New function name**: `<n>`
+- **Target file**: `<path>` (<new file | existing file — reason>)
+- **Target class**: `<ClassName>` or none
+- **Call sites to update**: <list each file:line>
+- **Expected diff**: +<N> lines in <target file>, -<M> lines in <source file>
+- **Test gate**: `<exact test command>`
+- **Retry limit**: 3 attempts — if still red after 3, stop and report
+
+### Change 2 — <short label>
+...
+
+## Acceptance criteria
+- Priority score drops below <target score> in `get_refactor_report`
+- Function exits the top-5 list
+- Full test suite passes (green)
+- `git diff --stat` shows only the expected files
+
+## Restore point
+Hash: <to be filled by the execute workflow>
+```
+
+Once the file is written, record the refactoring decision so it appears in the decisions workflow at commit time:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>record_decision</tool_name>
+  <arguments>{
+    "directory": "$DIRECTORY",
+    "title": "Refactor $TARGET_FUNCTION into smaller units ($STRATEGY)",
+    "rationale": "$PRIMARY_REASON from the Why section above",
+    "consequences": "Callers unchanged; complexity distributed across $N extracted helpers",
+    "affectedFiles": ["$TARGET_FILE"]
+  }</arguments>
+</use_mcp_tool>
+```
+
+Then:
+> "Plan written to `.openlore/refactor-plan.md`. Review it, then run `/openlore-execute-refactor` to apply the changes."
+
+---
+
+## Absolute constraints
+
+- **No code modifications** in this workflow
+- Always read the source file to confirm exact line numbers
+- Never leave a section empty or as "TBD"
+- Each change in the plan must include a test gate and a ≤ 50-line scope
+- Prefer candidates with higher coverage when scores are otherwise close
+- If the user does not pick a target, default to the top candidate