openlore 2.0.0

package/examples/cline-workflows/openlore-implement-feature.md

@@ -0,0 +1,266 @@
+# openlore: Implement Feature
+
+Plan and implement a new feature with full architectural context:
+architecture overview → OpenSpec requirements → insertion points → implementation → drift check.
+
+No code is written until Step 6. Steps 1–5 are read-only analysis.
+
+## Step 1: Get the project directory and feature description
+
+Ask the user:
+
+<ask_followup_question>
+  <question>Which project directory and what feature should I implement?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+Also ask for a brief description of the feature if not already provided (1–3 sentences).
+Store it as `$FEATURE_DESCRIPTION`.
+
+If `.claude/antipatterns.md` exists in the project, read it and store as `$ANTIPATTERNS`.
+This list will be cross-checked at Step 5b.
+
+## Step 2: Get the architecture overview
+
+Orient yourself before touching any code.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+From the result, note:
+- Which cluster(s) the feature most likely belongs to (based on role and name)
+- Critical hub functions to avoid touching unnecessarily (high fan-in → high blast radius)
+- Existing entry points — the feature may need to hook in at one of them
+
+If analysis data is missing (`{ "error": "..." }`), run `analyze_codebase` first:
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Then retry `get_architecture_overview`.
+
+## Step 2.5: Stack inventory (conditional)
+
+Based on the feature description and architecture overview results, call the relevant inventory tool(s) before reading any source file. Skip if the feature clearly involves none of these areas.
+
+| Feature involves | Tool |
+|---|---|
+| Data models / ORM / database / tables | `get_schema_inventory` |
+| HTTP routes / API / endpoints | `get_route_inventory` |
+| Config / env vars / secrets | `get_env_vars` |
+| UI components | `get_ui_components` |
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_schema_inventory</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Use results to ground the implementation plan in existing schemas/routes — don't re-create what already exists.
+
+---
+
+## Step 2.6: Audit spec coverage of the target domain
+
+Run a parity audit to check if the domain you're about to touch has spec gaps.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>audit_spec_coverage</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</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 5b (high blast radius + no spec = risk).
+
+If both are clean, continue to Step 3 without action.
+
+## Step 3: Search the OpenSpec specifications (if available)
+
+Discover which spec domains exist, then search for requirements relevant to the feature.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>list_spec_domains</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+If domains are found, search the specs semantically:
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "$FEATURE_DESCRIPTION", "limit": 5}</arguments>
+</use_mcp_tool>
+
+From the results, extract:
+- Existing requirements that relate to the feature (note their `id` for drift tracking)
+- Any constraints or acceptance criteria already documented
+- The `linkedFiles` — these are the source files already mapped to those requirements
+  (will be highlighted in the diagram viewer)
+
+If `search_specs` returns an index-not-found error, fall back to reading the spec file
+directly: `openspec/specs/<domain>/spec.md`.
+
+If no spec exists yet, note it — the feature will be "uncovered" and `check_spec_drift`
+will flag it after implementation. That is expected: propose running `openlore generate`
+after the feature lands.
+
+## Step 4: Find insertion points
+
+Identify the best functions and files to extend or hook into.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "$FEATURE_DESCRIPTION", "limit": 5}</arguments>
+</use_mcp_tool>
+
+For each candidate, present:
+- Rank, name, file, role, strategy, reason
+- Whether it appears in the relevant cluster identified in Step 2
+
+Then pick the top 1–2 candidates and get minimal context (callers, callees, body, test coverage — ~300 tokens):
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_minimal_context</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$TOP_CANDIDATE"}</arguments>
+</use_mcp_tool>
+
+If the function has high fanIn (>10), also check its community to understand broader blast radius:
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_cluster</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$TOP_CANDIDATE"}</arguments>
+</use_mcp_tool>
+
+Present callers, callees, community label, and test coverage. Ask the user to confirm the chosen insertion point.
+
+## Step 5: Read the skeleton of the target file(s)
+
+Get a noise-stripped structural view of the file(s) you will modify.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_function_skeleton</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePath": "$TARGET_FILE"}</arguments>
+</use_mcp_tool>
+
+Use the skeleton to:
+- Confirm the insertion strategy (extend existing function vs. add new function)
+- Identify the exact line range where new code will be added
+- Spot any existing error handling or type patterns to follow
+
+Ask the user to confirm the implementation approach before writing any code:
+
+> "I plan to [extend / add / hook into] `$TOP_CANDIDATE` in `$TARGET_FILE` by [brief description].
+> Does this match your intent?"
+
+## Step 5b: Adversarial self-check
+
+Before writing any code, state explicitly what could break with this approach.
+If `$ANTIPATTERNS` was loaded in Step 1, include any applicable patterns.
+
+> "Risk check on `$TOP_CANDIDATE`:
+> - `$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 5c: 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 (a one-liner, a config flag, an obvious helper).
+
+## Step 6: Implement the feature
+
+Apply the changes incrementally:
+
+1. **Add new types / interfaces first** (if needed) — separate commit
+2. **Implement the core logic** at the chosen insertion point
+3. **Update callers** if the insertion requires updating call sites
+4. **Add or update tests** — at minimum one test covering the new behaviour
+5. **Run the test suite** to confirm nothing is broken
+
+Follow existing code style (naming conventions, error handling, import style) observed
+in the skeleton from Step 5.
+
+## Step 7: Check spec drift
+
+After implementing, verify the feature is covered by specs (or flag missing coverage).
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+### If drift is detected
+
+Present the issues table (see `/openlore-check-spec-drift` for format).
+
+For `uncovered` issues on the new files: this is expected if no spec existed.
+Offer to run `openlore generate` to create/update the spec:
+
+> "The new file `$NEW_FILE` has no matching spec. Run `openlore generate` to infer
+> one from the implementation, or edit the spec manually if the domain spec already
+> partially covers it."
+
+For `gap` issues on existing specs: the new code changed the public API of a covered
+domain. Run `openlore generate --domains $DOMAIN` to regenerate.
+
+### If no drift
+
+> ✅ All changed files are covered by up-to-date specs.
+
+## Step 8: Summarise
+
+Present a brief implementation summary:
+
+- **Feature**: $FEATURE_DESCRIPTION
+- **Files changed**: list with line counts
+- **Insertion point**: $TOP_CANDIDATE in $TARGET_FILE (role: $ROLE, strategy: $STRATEGY)
+- **Tests**: N added / N updated
+- **Spec drift**: ✅ clean / ⚠️ N issues (remediation: …)
+
+Suggest follow-up actions if applicable:
+- Regenerate specs (`openlore generate`)
+- Re-run analysis to update call graph (`analyze_codebase`)
+- If the feature touches a hub function, suggest `/openlore-plan-refactor` to
+  track growing complexity
+
+## Absolute constraints
+
+- **No code written before Step 6** — analysis and user confirmation come first
+- Always confirm the insertion point with the user before implementing
+- Step 5b adversarial self-check is mandatory — never skip it
+- Run tests after implementation — never skip
+- Run `check_spec_drift` as the final verification step

package/examples/cline-workflows/openlore-plan-refactor.md

@@ -0,0 +1,279 @@
+# openlore: Plan Refactor
+
+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` — that `/openlore-execute-refactor` can follow
+step by step without losing context.
+
+This workflow makes **no code changes**. It only reads and writes the plan file.
+
+## Step 1: Confirm the project directory
+
+Ask the user which project to analyse, or confirm the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I plan the refactor for?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run static analysis
+
+Analyse the project. If analysis already ran recently, skip unless the user
+requests a fresh run.
+
+<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 full refactoring report
+
+Retrieve the prioritised list of functions with structural issues.
+
+<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 in a table: function, file, issues, priority score.
+
+## Step 3b: Check for duplicate code (optional enrichment)
+
+Call `get_duplicate_report` to surface clones that overlap with the top candidates.
+If the target function (or any callee) appears in a clone group, note it in the plan:
+consolidated duplicates reduce blast radius before extracting logic.
+
+<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."
+
+Before asking the user to pick a target, **check test coverage for the files
+containing the top candidates**. Detect the coverage tool from the project
+(look for `package.json` scripts, `pytest.ini`, `Cargo.toml`, `go.mod`, etc.)
+and run it scoped to those files only:
+
+- 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 ./...` (filter relevant packages)
+
+For each candidate file, present a compact coverage badge:
+
+| Function | File | Priority | Coverage |
+|---|---|---|---|
+| ... | ... | ... | 72% ✅ / 35% ⚠️ / 0% 🚫 |
+
+Apply these thresholds to annotate each row:
+
+| Coverage | Badge | Meaning |
+|---|---|---|
+| ≥ 70% lines | ✅ | Safe to refactor |
+| 40–69% lines | ⚠️ | Write characterisation tests first |
+| < 40% lines | 🛑 | Strongly discouraged — recommend tests first |
+| 0% (no tests) | 🚫 | Blocked — propose a test harness before proceeding |
+
+If **all top candidates are below 40%**, tell the user:
+> "Every high-priority target has insufficient test coverage (< 40%). Refactoring
+> without tests risks introducing silent regressions. 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?"
+
+Then ask the user which one to tackle first, or pick the top one by default.
+Prefer candidates with higher coverage when scores are otherwise close.
+
+## Step 4: Assess impact
+
+First, get condensed view (callers, callees, body, test coverage in one call):
+
+<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>
+
+Then get the full impact analysis:
+
+<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) and what it means
+- Recommended strategy (extract / split / facade / delegate)
+- Upstream callers and downstream callees (keep the top 5 of each for the plan)
+
+## Step 5: Visualise the call neighbourhood
+
+Render the subgraph to map callers and callees precisely.
+
+<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
+
+Identify low-risk leaf functions that can be extracted first (bottom-up).
+
+<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 candidate is a good first
+extraction if it 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.
+
+<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 returned, note its role (entry_point / orchestrator / hub / utility / internal)
+and the suggested strategy. Cross-reference with the subgraph from Step 5: prefer candidates
+that already call into — or are called by — the target function.
+
+## Step 7: Design the change sequence
+
+Based on the recommended strategy from Step 4, design an ordered sequence of
+atomic changes. Each change must specify:
+
+- **What**: the exact block of logic to move (line range or description)
+- **New name**: the function or method name to give it
+- **Target file**: the file where it will live after the move
+  - If the logic belongs to an existing module: name that file
+  - If no suitable module exists: propose a new file path (e.g.
+    `src/services/validation.ts`) and justify the choice
+- **Target class** (if applicable): the class or namespace to place it in
+- **Callers to update**: list every call site that will need updating
+
+For each strategy, apply these rules:
+
+- **split**: decompose the function into N sub-functions; each sub-function
+  stays in the same file unless it clearly belongs elsewhere
+- **extract**: pull out a helper; place it in the nearest cohesive module or
+  create a new file if none exists
+- **facade**: keep the original signature, delegate body to smaller functions;
+  create a private companion module if the file would exceed 300 lines
+- **delegate**: move ownership logic to callers; update each caller file listed
+  in the upstream chain
+
+Present the full change sequence to the user for review and ask for confirmation
+before writing the plan file.
+
+## Step 8: Write the plan file
+
+Create `.openlore/refactor-plan.md` in the project directory with the following
+structure (fill every section — leave nothing as "TBD"):
+
+```markdown
+# Refactor Plan
+
+Generated: <ISO date>
+Workflow: /openlore-plan-refactor → /openlore-execute-refactor
+
+## Target
+
+- **Function**: <name>
+- **File**: <relative path>
+- **Lines**: <start>–<end>  (read the file to confirm)
+- **Risk score**: <0–100>
+- **Strategy**: <extract | split | facade | delegate>
+- **Priority score before refactor**: <value>
+
+## Why
+
+- <issue 1 from refactor report>
+- <issue 2>
+- ...
+
+## Callers (upstream — must not break)
+
+| Caller | File |
+|---|---|
+| <name> | <path> |
+
+## Callees (downstream — candidates for extraction)
+
+| Callee | File |
+|---|---|
+| <name> | <path> |
+
+## Coverage baseline
+
+- **File**: <target file>
+- **Coverage**: <X>% lines, <Y>% branches
+- **Status**: ✅ safe / ⚠️ caution / 🛑 discouraged
+- **Test command**: <exact command to run>
+
+## Change sequence
+
+Apply in order. Do not skip ahead. Run tests after each step.
+
+### Change 1 — <short label>
+
+- **What**: extract lines <start>–<end> (logic: <one-line description>)
+- **New function name**: `<name>`
+- **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 <new/existing file>, -<M> lines in <source file>
+
+### 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
+
+Run before starting execute:
+```bash
+git log --oneline -1
+```
+Note the hash here: <to be filled by 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 tell the user:
+> "Plan written to `.openlore/refactor-plan.md`. Review it, then run
+> `/openlore-execute-refactor` to apply the changes."

package/examples/cline-workflows/openlore-refactor-codebase.md

@@ -0,0 +1,16 @@
+# openlore: Refactor Codebase (redirected)
+
+This workflow has been split into two focused workflows for better reliability
+with limited models:
+
+- **`/openlore-plan-refactor`** — static analysis, impact assessment, and
+  written plan saved to `.openlore/refactor-plan.md` (no code changes)
+- **`/openlore-execute-refactor`** — reads the plan and applies changes
+  incrementally, with tests after each step
+
+Tell the user:
+> "The `/openlore-refactor-codebase` workflow has been split. Please use:
+> 1. `/openlore-plan-refactor` to analyse the codebase and write a plan
+> 2. `/openlore-execute-refactor` to apply the plan
+>
+> This two-step approach is more reliable, especially with smaller models."