@engramlabs/mcp 0.1.2-alpha → 0.1.4-alpha

package/skills/engram-plan/references/plan-story.md

@@ -0,0 +1,84 @@
+# Plan workflow: STORY / FEATURE
+
+New capability work. The mine-first discipline matters most here:
+stories die from unknown unknowns, and the index is where the unknowns
+are already written down.
+
+## When this workflow
+- New feature, story, or capability request
+- Refactor with a goal (not a bug, not a rename)
+- Integration of a new component
+
+## Steps
+
+### 1. Search the past — patterns, precedents, near-misses
+```
+recall({ "query": "<feature domain terms> design decisions" })
+search({ "query": "<adjacent existing capability>" })
+procedure_list({})
+```
+Mine for:
+- **Precedents**: was a similar feature planned/built/abandoned
+  before? (abandoned plans + their reasons are gold)
+- **Invariants** the feature must respect (indexed `[proven]` rules)
+- **Adjacent patterns**: how does this repo solve analogous problems?
+  (find the closest existing feature and mirror its shape)
+- **Open tensions**: `contradiction_list({})` — building on top of an
+  unresolved contradiction is planning to fail
+
+### 2. Map the integration surface
+```
+architecture({ "limit": 15 })
+symbol_context({ "symbol": "<primary touchpoint>", "depth": 2 })
+change_impact({ "target": "<each touchpoint>" })
+```
+- Where does the feature ATTACH? (ports, facades, tool registries)
+- What must NOT move? (bridges, invariants)
+- Which layers does it cross? (crossing layers = the plan needs
+  explicit steps per layer, or it will stop at the first boundary)
+
+### 3. Design in the repo's shape
+One paragraph: the feature in this repo's own vocabulary, mirroring
+the closest existing pattern found in step 1. A design that invents a
+new shape when a proven one exists needs a stated reason (that's an
+Open Question, not a surprise).
+
+### 4. Steps with per-layer verification
+Each step lands ONE layer and names its verify command:
+```
+1. Domain types + contracts (core/<crate>)
+   Verify: cargo check -p engram-<crate> + check-contracts.sh
+2. Adapter behavior (adapters/<area>)
+   Verify: cargo test -p engram-<adapter>
+3. Facade/registry wiring
+   Verify: <the exact test that proves reachability>
+4. Agent surface (tool/skill/README)
+   Verify: <driver call or surface-parity check>
+```
+Steps without a verify command are wishes, not steps.
+
+### 5. Persist the plan AND the workflow
+```
+write_memory({ "content": "PLAN <slug>: <overview>. Precedents mined:
+  <what step 1 found>. Top risks: <...>. Steps: <N>, per-layer verify." })
+```
+If this feature type recurs, the successful shape becomes a procedure:
+
+```
+procedure_put({ "name": "add-<feature-type>",
+  "trigger": "new <feature-type> request",
+  "steps": ["<mine precedents>", "<map surface>", "<per-layer steps>",
+            "<verify each>", "<learn pass>"] })
+```
+
+## Output
+Overview / Findings (with the precedent search result — including
+"none found") / Risks (invariants + bridges) / Steps (per-layer) /
+Open Questions.
+
+## Stop conditions
+- Design contradicts an indexed `[proven]` invariant → stop; either
+  the invariant is wrong (an ADR-level change — say so) or the design
+  is. Don't plan past a contradiction.
+- No precedent found AND high blast radius → the first plan step is a
+  spike/prototype, explicitly labeled as such.

package/skills/engram-plan/references/plan-triage.md

@@ -0,0 +1,54 @@
+# Plan workflow: TRIAGE
+
+Rapid assessment of a reported problem. Triage does NOT fix — it
+classifies and routes. Time-boxed: if this takes more than a few tool
+calls, it's a bugfix, not a triage.
+
+## When this workflow
+- A bug/error report arrives with unclear severity
+- CI is red and nobody knows why
+- "Something is broken" with no repro
+
+## Steps
+
+### 1. Reproduce (or fail to, honestly)
+Run the failing thing. If you cannot reproduce, that IS the triage
+output: "not reproducible as described; likely <hypothesis [likely]>".
+
+### 2. Search the past (engram-search core move)
+```
+recall({ "query": "<error text core terms>" })
+search({ "query": "<failing symbol or area>" })
+procedure_list({})
+```
+- Has this exact failure happened before? (past fixes = fastest path)
+- Is there a known sharp edge here? (indexed `[proven]` memory)
+- Is there a runbook that already covers it?
+
+### 3. Classify
+
+| Class | Criteria | Route |
+|---|---|---|
+| Known + runbook exists | recall hit + procedure covers it | Follow the procedure; skip planning |
+| Known pattern, no runbook | similar past fix recalled | plan-bugfix (fast lane — the pattern is known) |
+| New failure mode | no past hits | plan-bugfix full workflow |
+| Not a bug (works as designed) | repro shows intended behavior | Report; maybe docs/engram-learn |
+| Severity: blocks release/CI | red main, broken publish | plan-bugfix immediately + flag urgency |
+
+### 4. Record the triage
+```
+write_memory({ "content": "TRIAGE <one-line>: <report> → <class>.
+  Root-cause hypothesis: <...> [likely]. Past evidence: <recall hit or
+  'none'>" })
+```
+If a runbook WAS missing but would have helped, note that — it feeds
+engram-learn later.
+
+## Output
+One paragraph: what was reported, what reproduced, the class, the
+route, the hypothesis. No fix, no plan steps — routing only.
+
+## Stop conditions
+- Cannot reproduce → report that, stop.
+- Runbook found → execute it, stop (that's not triage anymore).
+- Classification clear → hand to plan-bugfix, stop.

package/skills/engram-search/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: engram-search
+description: Agentic search over the code graph and memory to find or solve problems — "where is X", "how does Y work", "why did Z break", "find the code that...". An iterative hypothesis→retrieve→verify loop, not a one-shot lookup. Trigger on any codebase question where the answer should be evidenced.
+---
+
+# engram-search
+
+Answer codebase questions with evidence. A loop: **hypothesis → retrieve
+→ verify → refine**. Stop when the claim is `[proven]` — or honestly
+unproven.
+
+## Contract
+
+1. Never claim file contents from memory alone — verify with `fetch_content`.
+2. Every claim in the answer carries its evidence: the tool + query that proved it.
+3. Two fruitless iterations → say what you looked for and stop.
+4. Labels: `[proven]` (verified against source/graph), `[likely]` (strong signal, unverified), `[guessed]` (hypothesis only — say so).
+
+## Workflow
+
+### 1. State the hypothesis
+
+Before any tool call, write one line: *"I expect X lives in Y because Z."*
+This anchors the search and makes refinement measurable.
+
+### 2. Retrieve from two angles
+
+```
+recall({ "query": "<the question's key terms>" })
+search({ "query": "<the likely symbol/term name>" })
+```
+
+`recall` covers memories + knowledge + docs (the "why"); `search` covers
+the code graph (the "where").
+
+### 3. Drill the neighborhood
+
+For the best candidate symbol:
+
+```
+symbol_context({ "symbol": "<name>", "depth": 2 })
+```
+
+For an area rather than a symbol:
+
+```
+explore({ "query": "<area terms>", "depth": 2 })
+```
+
+### 4. Verify against source
+
+Before asserting what code does:
+
+```
+fetch_content({ "path": "<file path from the graph>" })
+```
+
+Graph and memory say where; the file says what. If they disagree, the
+index is stale — say so (`[likely]` at best).
+
+### 5. Refine or stop
+
+- Found and verified → answer.
+- Found but unverified → answer with `[likely]`, offer to fetch.
+- Nothing → refine the query with terms the graph revealed (community
+  names, related symbols), one more iteration. After two empty
+  iterations, report the queries tried and stop.
+
+## Output format
+
+```
+<answer, one paragraph>
+
+Evidence:
+- [proven] <claim> — symbol_context(X): called by A, B; fetch_content(file.rs)
+- [likely] <claim> — recall hit "…" (indexed Oct 2026; may be stale)
+- [guessed] <claim> — naming convention only
+```
+
+## When it fails
+
+- Empty store (no index yet) → say "not indexed; run engram-index or
+  scan_repo first" and stop. Do not fall back to grepping as if indexed.
+- Stale-index signals (symbols that no longer exist per `fetch_content`) →
+  flag the staleness in the answer; suggest `scan_repo`.
+- Ambiguous symbol (many same-name entities) → disambiguate with
+  `symbol_context` per candidate, or ask; don't average.
+
+## Anti-patterns
+
+- Claiming behavior from memory alone (no `fetch_content`).
+- One query, one give-up.
+- Answering from general language knowledge instead of this repo's graph.
+- Skipping the hypothesis line.
+
+## Final check
+
+- Is every claim labeled?
+- Did I read the actual file for the load-bearing claims?
+- Would the evidence chain convince a skeptical reviewer?