openlore 2.0.0

package/examples/bmad/tasks/implement-story.md

@@ -0,0 +1,254 @@
+# Task: Implement Story
+
+**Purpose**: Implement a BMAD story on any codebase — new or existing.
+Structural analysis is used proportionally to the risk level already known from planning.
+
+---
+
+## Inputs
+
+From the story file:
+- `$STORY_TITLE`, `$AC`, `$PROJECT_ROOT`
+- `$RISK_CONTEXT` — the `risk_context` section (pre-filled by Architect Agent at planning time)
+
+If `.claude/antipatterns.md` exists, read it and store as `$ANTIPATTERNS`.
+This list will be cross-checked at Step 4b.
+
+---
+
+## Step 1 — Read the risk context
+
+Open the story file and check whether `risk_context` is populated.
+
+### If risk_context IS present (normal case — planning was done)
+
+Use it directly. Do not re-run structural analysis unless something feels wrong.
+
+| Risk level in story | Approach |
+|---|---|
+| 🟢 low (< 40) | Proceed to Step 3. Quick orient to confirm insertion point. |
+| 🟡 medium (40–69) | Run Step 2 impact check. Proceed with callers protected. |
+| 🔴 high / critical (≥ 70) | Story should have a blocking refactor. If not scheduled, stop and flag it. |
+
+### If risk_context is ABSENT (planning was skipped or story is new)
+
+Run the full orientation in Step 2 before proceeding.
+
+---
+
+## Step 2 — Orient (full or confirm)
+
+**Full orient** (risk_context absent, or medium+ risk):
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE — $AC1",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+If orient returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
+
+**For medium+ risk**, also run impact on the top 2 functions:
+
+```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 a function has `riskScore ≥ 70` that was NOT flagged at planning: **stop**.
+Create a blocking refactor story and do not implement until it's resolved.
+
+---
+
+## Step 2.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 3 without action.
+
+---
+
+## Step 3 — Check the spec
+
+First verify that OpenSpec specs exist for this project:
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l
+```
+
+**If 0 specs found:**
+> No OpenSpec specs exist yet for this project. `search_specs` will return empty
+> results and `check_spec_drift` (Step 7) will flag all files as uncovered.
+>
+> The Architect agent should have run `openlore generate` during onboarding.
+> If it hasn't been run yet, note it in the Dev Agent Record and proceed with
+> structural analysis only. The spec baseline can be created post-sprint with
+> `openlore generate $PROJECT_ROOT`.
+
+Skip `search_specs` 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 code.
+Note any constraints that apply to the implementation.
+
+---
+
+## Step 4 — Find the insertion point
+
+Use the `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 self-check
+
+Before writing any code, state explicitly what could break with this approach.
+If `$ANTIPATTERNS` was loaded (see Inputs), 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 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 from Step 2/risk_context without re-running the gate.
+
+---
+
+## Step 6 — Tests
+
+Two levels, both required before proceeding:
+
+**Mandatory — existing tests must not regress:**
+Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.
+A green CI on existing tests is the minimum gate.
+
+**Recommended — at least one new test per AC:**
+Write a test that directly exercises the new behaviour described in the acceptance criterion.
+This is the proof that the implementation matches the intent — without it, the spec update in Step 7 has no evidence.
+
+| 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 in the Dev Agent Record. |
+
+---
+
+## 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 | Propose `openlore generate` post-sprint |
+| `gap` on existing domain | Run `openlore generate --domains $DOMAIN` |
+| `stale` | Fix the reference |
+| No drift | ✅ |
+
+If drift is found on a domain touched by this story, note it in the Dev Agent Record — the spec update can be proposed after the sprint, not mid-implementation.
+
+---
+
+## Step 8 — Update the story
+
+Fill in the **Dev Agent Record** section of the story file and mark as `Review`.
+
+Include:
+- test files written / modified
+- whether existing coverage was sufficient or a gap remains
+- any drift found in Step 7
+
+---
+
+## Absolute constraints
+
+- Do not write code before Step 4 confirmation
+- Step 4b adversarial self-check is mandatory — never skip it
+- If riskScore ≥ 70 was not caught at planning — stop, do not work around it
+- Do not run `check_spec_drift` before tests are green
+- Do not propose a spec update on untested code

package/examples/bmad/tasks/onboarding.md

@@ -0,0 +1,169 @@
+# Task: Brownfield Onboarding
+
+**Purpose**: Establish a structural baseline on an existing codebase.
+**Phase**: Architecture — run this BEFORE writing architecture documents, planning epics, or creating stories.
+Run once per project, then re-run at the start of each planning cycle (quarterly or after major refactors).
+
+**Who runs this**: Architect Agent (not Dev Agent).
+
+**Output**: populated `openspec/` + `.openlore/` + risk register embedded in architecture doc.
+
+**Estimated time**: 5–15 minutes depending on codebase size.
+
+---
+
+## Prerequisites
+
+- openlore MCP server connected
+- `openlore` CLI available (`npx openlore` or local install)
+- Read access to the project directory
+
+---
+
+## Step 1 — Run static analysis
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "force": false
+  }</arguments>
+</use_mcp_tool>
+```
+
+Expected output: summary with module count, function count, cycle count.
+If `cycles_detected > 0`, note it — this is a brownfield risk signal.
+
+---
+
+## Step 2 — Understand the architecture
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+From the result, record:
+- **Domain clusters** (the logical groupings openlore detected)
+- **Cross-cluster dependencies** (coupling risks)
+- **Entry points** (where requests enter the system)
+- **Critical hubs** (high fan-in functions — touch with care)
+
+---
+
+## Step 3 — Identify hotspots
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Create a brownfield risk register — a simple table:
+
+| Function | File | Issues | Priority | Action |
+|---|---|---|---|---|
+| ... | ... | high_fan_out | 85 | Refactor before touching |
+| ... | ... | in_cycle | 60 | Isolate cycle first |
+| ... | ... | multi_requirement | 40 | Document carefully |
+
+Functions with priority > 70 are **no-touch zones** until refactored.
+
+---
+
+## Step 4 — Check for duplicate code
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Note any clone groups — they indicate debt that will multiply if features are added naively.
+
+---
+
+## Step 5 — Generate OpenSpec (if no specs exist)
+
+If `openspec/` does not exist or has no specs, generate them:
+
+```bash
+openlore analyze --embed
+openlore generate
+```
+
+Or trigger the openlore skill in your AI agent:
+
+> "Run openlore on this codebase and generate OpenSpec specifications."
+
+This creates `openspec/specs/{domain}/spec.md` for each detected domain.
+Commit the result — these become the baseline for drift detection.
+
+---
+
+## Step 6 — Verify spec coverage
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "base": "HEAD"
+  }</arguments>
+</use_mcp_tool>
+```
+
+At this point drift should be zero (we just generated specs from HEAD).
+If `uncovered` files appear, add them to the backlog as "spec missing" items.
+
+---
+
+## Step 7 — Record the baseline
+
+Create or update `openspec/specs/architecture/spec.md` with a **brownfield baseline** section:
+
+```markdown
+## Brownfield Baseline
+
+> Established: {date}
+
+### Risk Register
+
+| Function | Issues | Priority |
+|---|---|---|
+| ... | ... | ... |
+
+### No-touch zones (priority > 70)
+
+- `functionName` in `path/to/file.ts` — reason
+
+### Known duplicate groups
+
+- N clone groups detected (see `.openlore/analysis/`)
+
+### Onboarding notes
+
+- ...
+```
+
+---
+
+## Completion Criteria
+
+- [ ] `openlore analyze` completed without error
+- [ ] Architecture overview reviewed and understood
+- [ ] Risk register created with functions priority > 70 flagged
+- [ ] `openspec/` populated (generated or pre-existing)
+- [ ] `check_spec_drift` shows zero drift on HEAD
+- [ ] Baseline documented in `openspec/specs/architecture/spec.md`
+- [ ] BMAD project backlog updated with any "spec missing" items

package/examples/bmad/tasks/refactor.md

@@ -0,0 +1,178 @@
+# Task: Brownfield Refactor
+
+**Purpose**: Plan and execute a safe refactoring on a brownfield codebase before implementing a story.
+Typically triggered by the `dev-brownfield` agent gate when `riskScore ≥ 70`.
+
+**Output**: `.openlore/refactor-plan.md` applied and verified.
+
+---
+
+## Inputs
+
+- `$TARGET_FUNCTION` — function identified as high-risk by `analyze_impact`
+- `$PROJECT_ROOT` — absolute path to the project
+
+---
+
+## Step 1 — Confirm target and scope
+
+Present the risk signal to the user:
+
+> "`$TARGET_FUNCTION` has a risk score of $SCORE ($ISSUES).
+> Implementing the planned story on this function as-is risks breaking $CALLERS.
+> This task will refactor it first. Proceed?"
+
+If the user declines, mark the story as blocked with dependency: "Refactor `$TARGET_FUNCTION` first."
+
+---
+
+## Step 2 — Get the refactor report
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Confirm `$TARGET_FUNCTION` appears in the report and note its issues and priority score.
+
+---
+
+## Step 3 — Check for clones
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+If `$TARGET_FUNCTION` appears in a clone group:
+> "⚠️ This function has N near-clones. Consolidate them first to reduce blast radius."
+Propose consolidation as Change 0 in the plan.
+
+---
+
+## Step 4 — Analyse the call neighbourhood
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "depth": 3
+  }</arguments>
+</use_mcp_tool>
+```
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "functionName": "$TARGET_FUNCTION",
+    "direction": "both",
+    "format": "mermaid"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Show the Mermaid diagram. Identify extraction candidates in the downstream subgraph.
+
+---
+
+## Step 5 — Find safe extraction targets
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_low_risk_refactor_candidates</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "filePattern": "$TARGET_FILE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Cross-reference with the subgraph: good extraction candidates are already callees of `$TARGET_FUNCTION`.
+
+---
+
+## Step 6 — Find landing zones for extracted helpers
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "extract helper from $TARGET_FUNCTION",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 7 — Design the change sequence
+
+Design an ordered sequence of atomic changes. Each change must specify:
+
+- **What**: the exact block to extract (description or line range)
+- **New name**: function name
+- **Target file**: where to place it (existing or new)
+- **Call sites to update**: list each file that calls `$TARGET_FUNCTION` or the extracted block
+
+**Present the full sequence to the user and wait for explicit approval before writing the plan.**
+
+---
+
+## Step 8 — Execute (delegate to openlore-execute-refactor)
+
+Once the plan is approved, hand off to the `openlore-execute-refactor` skill:
+
+1. Write `.openlore/refactor-plan.md` with the full plan (see skill template)
+2. Invoke `/openlore-execute-refactor`
+
+The execute skill handles:
+- Green baseline verification
+- Restore point setup
+- Atomic change application with tests after each step
+- Post-refactor risk score verification
+
+---
+
+## Step 9 — Re-run the gate
+
+After the refactor is complete, re-run `analyze_impact` on `$TARGET_FUNCTION`:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+- If `riskScore` is now < 70 → return to the story implementation task
+- If `riskScore` is still ≥ 70 → repeat from Step 4 with the updated subgraph
+
+---
+
+## Completion Criteria
+
+- [ ] `riskScore` for `$TARGET_FUNCTION` < 70
+- [ ] Full test suite passes (green)
+- [ ] `check_spec_drift` clean or addressed
+- [ ] Story unblocked — return to `implement-story-brownfield`