@precisionutilityguild/liquid-shadow 1.0.9 → 1.0.10

package/skills/shadow_research/SKILL.md

@@ -1,34 +1,26 @@
 ---
 name: research
-description: Conduct high-signal research for external dependencies by combining local context, web search, and Context7 documentation. Use when researching libraries, checking integration examples, verifying versions, or when the user asks about external dependencies, library documentation, or integration patterns.
+description: Research external dependencies without losing local context. Use when checking library usage, verifying versions, finding integration examples, or comparing official documentation against what the repo already does.
 ---
 
-# External Research
+# Research
 
-High-signal research for external dependencies.
+Start local, then verify externally.
 
-## 🚀 Workflow
+## Local first
 
-1. **Local Context**: `shadow_search_concept` (query: "library name", repoPath). Find existing integration examples.
-2. **Web Search**: Use the `WebSearch` tool for official docs and latest versions.
-3. **Deep Intel (Context7)**: resolve-library-id, query-docs (server: user-context7).
-4. **Integration Check**: `shadow_inspect_file` (filePath, detailLevel: "signatures", repoPath).
-5. **Log Findings**: `shadow_ops_log` (type: "discovery", content, repoPath).
+- `shadow_search_concept({ repoPath, query, compact: true })` for existing patterns.
+- `shadow_search_path({ repoPath, query, ranked: true })` for likely integration files.
+- `shadow_search_config({ repoPath, key?, query?, showUsage: true })` for env and config hooks.
+- `shadow_analyze_deps({ repoPath, filePath, direction: "imports" | "imported_by" })` to see how the dependency sits in the graph.
+- `shadow_inspect_file({ repoPath, filePath, detailLevel: "signatures" })` for a quick local API read.
 
-## 🛠 Precise Tooling
+## External verification
 
-| Discovery Layer    | Atomic Tool                                                                 |
-| :----------------- | :-------------------------------------------------------------------------- |
-| **Local Usage**    | `shadow_search_concept` (query, **compact: true** for broad search)         |
-| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted with layers |
-| **Config Check**   | `shadow_search_config` (key, **showUsage: true**) — with usage counts       |
-| **External Docs**  | context7 tools (user-context7)                                              |
-| **Relational**     | `shadow_analyze_deps` (filePath, direction)                                 |
+- Use the host model's documentation or web tools to read official vendor docs and primary sources.
+- Check the exact installed version in `package.json`, lockfiles, or existing imports before trusting examples.
+- Prefer official docs over blogs, and repo-local patterns over generic snippets.
 
-## 💡 Intelligence Options
+## Closeout
 
-- **`shadow_search_concept` with `compact: true`**: Returns file paths + scores without snippets (~60% token savings). Use for broad exploration.
-- **`shadow_search_path` with `ranked: true`**: Results sorted by gravity (high-import files first) with layer classification. Reveals architecturally important files.
-- **`shadow_search_config` with `showUsage: true`**: Shows usage counts per config var and identifies orphaned vars (defined but never used in code).
-
-_Note: Always check `package.json` for the exact version before querying Context7 to ensure documentation alignment._
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, filePath? })` when the research affects an ongoing mission.

package/skills/shadow_sync/SKILL.md

@@ -3,16 +3,25 @@ name: sync
 description: 'Sync index and mission state after external changes. Day-to-day: index + NanoRepair run automatically when MCP tools (search, inspect, etc.) trigger reindex. Use trace after git pull/checkout/merge (or rely on hooks); use index deep:true for full rebuild.'
 ---
 
-# Repository Synchronization
+# Sync
 
-**Day-to-day:** Index and NanoRepair run automatically when you use MCP tools (search, inspect, analyze, etc.) and a reindex occurs. No manual sync needed for edits or renames.
+Day-to-day, Shadow often reindexes on demand. Use manual sync when the repository changed outside the normal flow.
 
-## When to run sync manually
+## Prefer these calls
 
-| Situation                         | Action                                                             |
-| :-------------------------------- | :----------------------------------------------------------------- |
-| **After git pull/checkout/merge** | `shadow_sync_trace` (repoPath) — or rely on Git hooks if installed |
-| **Full rebuild (corruption)**     | `shadow_sync_index` (repoPath; use deep: true if supported)        |
-| **Repair only (rare)**            | `shadow_sync_repair` (repoPath)                                    |
+- After `pull`, `checkout`, `merge`, or large rebases:
+  - `shadow_sync_trace({ repoPath, sinceCommit?, enableContextPivot?, enableMergeSentinel? })`
+- For an explicit rebuild:
+  - `shadow_sync_index({ repoPath, deep: true })`
+- For repair only:
+  - `shadow_sync_repair({ repoPath })`
 
-**Note:** `trace` does index + ghost analysis + NanoRepair + lifecycle + mission re-hydration. Hooks run it on commit/checkout/merge.
+## Health checks
+
+- `shadow_ops_health({ repoPath })`
+- `shadow_env_diagnose({ repoPath })`
+
+## Rules
+
+- Prefer `shadow_sync_trace` over `shadow_sync_index` unless you specifically want a rebuild.
+- Use `deep: true` sparingly; it is the expensive option.

package/skills/shadow_synthesize/SKILL.md

@@ -3,46 +3,24 @@ name: synthesize
 description: Distill mission logs into Architectural Decision Records (ADRs) and persist them to the Shadow Engine and Git Notes. Use when completing missions, creating ADRs, synthesizing architectural decisions, or when the user asks about decision records, mission completion, or architectural documentation.
 ---
 
-# Architectural Synthesis
+# Synthesize
 
-Distill mission logs into an Architectural Decision Record (ADR) and persist it to the Shadow Engine.
+Use this skill when a mission needs to become durable project memory.
 
-> **AUTO-PILOT ACTIVE**: Synthesis is **automatically triggered** when a mission status is set to `completed` via `shadow_ops_track`. The system handles: ADR distillation (recursive for child missions), Git Notes persistence, and **cascade parent completion** (if all siblings are done, the parent auto-completes and synthesizes too).
+## Primary path
 
-## Workflow
+- Complete the mission:
+  - `shadow_ops_track({ repoPath, missionId, status: "completed" })`
+- Verify the synthesized record:
+  - `shadow_ops_chronicle({ repoPath, limit: 5 })`
 
-1.  **Complete Mission**: `shadow_ops_track` (missionId, status: "completed", repoPath).
-    - The Shadow Engine will automatically:
-      - Distill all intent logs (recursive for child missions).
-      - Format the ADR using markdown and **Liquid Anchors**.
-      - Persist the record to SQLite and **Git Notes**.
-      - **Cascade**: If all sibling missions under the same parent are completed, the parent mission auto-completes with its own ADR synthesis.
-2.  **Verify**: Check the synthesized record via `shadow_ops_chronicle` (limit: 5, repoPath).
-3.  **Manual Synthesis**: Use `shadow_ops_synthesize` only to **re-generate** an existing record or for specific partial distillations.
-4.  **Pre-synthesis Compression** (optional): For missions with many raw logs, `shadow_ops_crystallize` (missionId, repoPath) compresses logs into a crystal summary before synthesis for cleaner ADRs.
+## Secondary tools
 
-## Precise Tooling
+- `shadow_ops_synthesize({ repoPath, missionId })` only when you need to regenerate the ADR after the mission is already complete.
+- `shadow_ops_crystallize({ repoPath, missionId })` before completion if the mission has many raw logs.
+- `shadow_ops_crystallize_theme({ repoPath, theme, missionIds? })` when you want a cross-mission architectural thread.
 
-| Action                | Atomic Tool                              | Usage                                                             |
-| :-------------------- | :--------------------------------------- | :---------------------------------------------------------------- |
-| **Complete & Seal**   | `shadow_ops_track` (status: "completed") | **Primary**. Triggers auto-synthesis + cascade.                   |
-| **Manual Distill**    | `shadow_ops_synthesize`                  | Re-run synthesis manually (re-gen only).                          |
-| **Crystallize First** | `shadow_ops_crystallize`                 | Compress raw logs before synthesis.                               |
-| **Theme Crystallize** | `shadow_ops_crystallize_theme`           | Cross-mission: cluster semantic themes across ALL missions' logs. |
-| **View Chronicle**    | `shadow_ops_chronicle`                   | View the combined narrative feed.                                 |
+## Rules
 
-_Note: Synthesis consolidation includes all child missions recursively. Cascade parent completion propagates upward through the entire hierarchy._
-
-## Cascade Parent Completion
-
-When the last child mission under a parent is completed:
-
-1. Parent status is set to `completed`
-2. A system intent log records the cascade event
-3. Parent ADR is synthesized (recursive child distillation)
-4. Parent is synced to Git Notes
-5. If the parent itself has a parent, the cascade continues upward
-
-## Tooling Strategy
-
-Synthesis is the final commit of the mission's logic into the repository's permanent history. Avoid manual markdown files for ADRs; trust the **Git Notes** architecture to preserve the "Story of the Code."
+- Completion auto-triggers synthesis and parent cascade behavior.
+- Do not maintain parallel ADR markdown files unless the user explicitly wants one.

package/skills/shadow_trace_impact/SKILL.md

@@ -3,53 +3,33 @@ name: trace-impact
 description: Map the blast radius of a change by analyzing impact, flow traces, cross-repo dependencies, and boundary maps. Use when analyzing change impact, assessing risk, tracing dependencies, or when the user asks about change impact, blast radius, or dependency analysis.
 ---
 
-# Impact Analysis
-
-Map the blast radius of a change using the full Shadow analyze toolkit.
-
-## 🚀 Workflow
-
-1. **Session Context**: `shadow_ops_context` (repoPath) — **ONE CALL** for hologram + chronicle + briefing. Check if symbol is in gravity zones.
-2. **Impact (Blast Radius)**: `shadow_analyze_impact` (symbolName, filePath, depth: 3, repoPath) — ALL affected files.
-3. **Dependencies**:
-   - `shadow_analyze_deps` (filePath, direction: "imported_by", repoPath) — Who imports this?
-   - `shadow_analyze_deps` (filePath, direction: "imports", repoPath) — What does it import?
-4. **Flow Trace**: `shadow_analyze_flow` (symbolName, filePath, repoPath) — Execution path.
-5. **Health Check**:
-   - `shadow_analyze_debt` (mode: "circular-deps", repoPath) — Any import cycles?
-   - `shadow_analyze_debt` (mode: "dead-code", limit: 50, repoPath) — Unused exports?
-6. **Cross-Repo Check** (if multi-repo):
-   - `shadow_workspace_fuse` (repoPaths, repoPath).
-   - `shadow_search_symbol` (query, limit: 50, repoPath).
-7. **Boundary Map**: `shadow_recon_topography` (repoPath) — Layer crossing check.
-8. **Log Risk**: `shadow_ops_log` (missionId, type: "discovery", content, symbolName, repoPath).
-
-## 🛠 Precise Tooling
-
-| Impact Layer         | Atomic Tool                                                                |
-| :------------------- | :------------------------------------------------------------------------- |
-| **Session Start** 🚀 | `shadow_ops_context` (repoPath) — **START HERE** for context               |
-| **Hologram**         | `shadow_recon_hologram` (repoPath) — if you need standalone                |
-| **Blast Radius**     | `shadow_analyze_impact` (symbolName, depth: 3)                             |
-| **Dependents**       | `shadow_analyze_deps` (filePath, direction: "imported_by")                 |
-| **Dependencies**     | `shadow_analyze_deps` (filePath, direction: "imports")                     |
-| **Flow Path**        | `shadow_analyze_flow` (symbolName, filePath)                               |
-| **Circular Deps**    | `shadow_analyze_debt` (mode: "circular-deps")                              |
-| **Dead Code**        | `shadow_analyze_debt` (mode: "dead-code", **confidenceThreshold: "high"**) |
-| **File Discovery**   | `shadow_search_path` (query, **ranked: true**) — gravity-sorted            |
-| **Workspace Fuse**   | `shadow_workspace_fuse` (repoPaths, repoPath)                              |
-| **Topography**       | `shadow_recon_topography`                                                  |
-
-## 💡 Intelligence Options
-
-- **`shadow_search_path` with `ranked: true`**: Find related files sorted by gravity (high-import files first) with layer classification. Helps identify which affected files are architecturally critical.
-- **`shadow_analyze_debt` confidence levels**: Use `confidenceThreshold: "high"` to focus on likely dead code, avoiding noise from test fixtures and migrations.
-
-_Note: **Start with `shadow_ops_context`** for instant gravity zones + architectural context. Use depth higher than 3 for impact analysis only if the symbol is a fundamental primitive (e.g., RepositoryFactory)._
-
-## 🛠 Risk Classification
-
-- **Critical Risk**: Symbol in gravity zones (top 10) + >20 dependents + crosses layers
-- **High Risk**: >10 dependents OR crosses layers (e.g., Test -> Logic)
-- **Medium Risk**: 5-10 dependents within same layer
-- **Low Risk**: <5 dependents, same layer, no circular deps
+# Trace Impact
+
+Use this skill to answer "what breaks if we touch this?"
+
+## Core workflow
+
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. `shadow_analyze_impact({ repoPath, symbolName, filePath?, depth: 3 })`
+3. `shadow_analyze_deps({ repoPath, filePath, direction: "imported_by" })`
+4. `shadow_analyze_deps({ repoPath, filePath, direction: "imports" })`
+5. `shadow_analyze_flow({ repoPath, filePath, symbolName? })`
+
+## Add precision
+
+- `shadow_analyze_explain_diff({ repoPath, baseCommit?, headCommit?, staged? })` for a semantic read of an actual diff.
+- `shadow_analyze_type_graph({ repoPath, symbolName, filePath?, direction?, relationship? })` when the change is type-heavy.
+- `shadow_analyze_debt({ repoPath, mode: "circular-deps" })` for cycle risk.
+- `shadow_recon_topography({ repoPath })` for layer-crossing risk.
+- `shadow_workspace_fuse({ repoPaths, name? })` before cross-repo analysis.
+- `shadow_analyze_mesh({ repoPath, topic, includeCrossRepo: true })` when the affected boundary is a known route or event.
+
+## Closeout
+
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, symbolName?, filePath? })`
+- `shadow_ops_handoff({ repoPath, missionId?, kind: "impact_map", findings, risks?, gaps? })`
+
+## Rules
+
+- Keep `depth: 3` by default; only widen for foundational primitives.
+- `shadow_analyze_mesh` requires a concrete `topic`.

package/skills/shadow_understand/SKILL.md

@@ -3,55 +3,40 @@ name: understand
 description: Find the high-signal path to understanding complex logic through intent retrieval, topological placement, relational analysis, and mechanics inspection. Use when understanding architecture, analyzing complex code, tracing logic flow, or when the user asks about how something works, architectural patterns, or code comprehension.
 ---
 
-# Architectural Understanding
-
-Find the high-signal path to understanding complex logic.
-
-## Workflow
-
-1. **Session Context (The Fast Lane)**: `shadow_ops_context` (repoPath) — **ONE CALL** returns hologram + chronicle(5) + briefing (relevance-ranked candidates).
-   - Skip to step 3 if you have what you need from context alone.
-2. **Optional Expanded Context** (only if shadow_ops_context wasn't enough):
-   - `shadow_recon_topography` (repoPath) — Detailed layer breakdown beyond hologram summary.
-   - `shadow_recon_tree` (subPath: "src/services", maxDepth: 2, repoPath) — Visual file hierarchy.
-   - `shadow_ops_briefing` (scope: "mission", missionId, altitude: "ground") — Full mission detail with raw logs, working set, collisions.
-3. **Relational Analysis (The Who)**:
-   - `shadow_analyze_impact` (symbolName, filePath, depth: 3, repoPath) — Blast radius.
-   - `shadow_analyze_deps` (filePath, direction: "imported_by", repoPath) — Who depends on this?
-   - `shadow_search_concept` (query, repoPath) — Semantic search.
-   - `shadow_analyze_mesh` (repoPath) — When the system is event-driven: map all HTTP routes, socket events, pubsub topics and their producers/consumers.
-   - `shadow_analyze_type_graph` (filePath, repoPath) — When understanding a type system: interface/class inheritance chains.
-4. **Mechanics (The How)**:
-   - **For Logic**: `shadow_analyze_flow` (symbolName, filePath, repoPath) — Trace execution.
-   - **For Objects**: `shadow_inspect_file` (filePath, detailLevel: "signatures", repoPath) — All exports.
-   - **For Symbol Deep Dive**: `shadow_inspect_symbol` (symbolName, filePath, context: "full", repoPath) — With deps.
-   - **For Change History**: `shadow_analyze_explain_diff` (fromCommit, toCommit, repoPath) — Semantic narrative of what changed and why between commits.
-5. **Synthesis**: `shadow_ops_log` (missionId, type: "discovery", content, symbolName, repoPath).
-
-## Precise Tooling
-
-| Discovery Layer    | Atomic Tool                                                                                          |
-| :----------------- | :--------------------------------------------------------------------------------------------------- |
-| **Session Start**  | `shadow_ops_context` (repoPath) — **START HERE**                                                     |
-| **Hologram**       | `shadow_recon_hologram` (repoPath) — if you need standalone hologram                                 |
-| **History**        | `shadow_ops_chronicle` (limit: 5) — if you need more than 5 from context                             |
-| **Layers**         | `shadow_recon_topography` — detailed breakdown                                                       |
-| **Mission Detail** | `shadow_ops_briefing` (altitude: "ground") — full logs + working set                                 |
-| **Blast Radius**   | `shadow_analyze_impact` (symbolName, depth: 3)                                                       |
-| **Dependents**     | `shadow_analyze_deps` (filePath, direction: "imported_by")                                           |
-| **Flow Trace**     | `shadow_analyze_flow` (symbolName, filePath)                                                         |
-| **Structure**      | `shadow_inspect_file` (detailLevel: "signatures")                                                    |
-| **Deep Dive**      | `shadow_inspect_symbol` (context: "full")                                                            |
-| **File Discovery** | `shadow_search_path` (query, **ranked: true**) — gravity-sorted results with layer classification    |
-| **Event Mesh**     | `shadow_analyze_mesh` (repoPath) — HTTP routes, socket events, pubsub topics + producers/consumers   |
-| **Type Graph**     | `shadow_analyze_type_graph` (filePath) — interface/class inheritance chains                          |
-| **Explain Diff**   | `shadow_analyze_explain_diff` (fromCommit, toCommit) — semantic narrative of changes between commits |
-
-_Note: **ALWAYS start with `shadow_ops_context`** for instant architectural context + history + mission state in ONE call. Use `context: "definition"` for token-efficient single symbol inspection._
-
-## Intelligence Options
-
-- **`shadow_search_path` with `ranked: true`**: Results sorted by gravity (high-import files first) with layer classification (Entry/Logic/Data). Use when you need to find the most architecturally important files matching a pattern.
-- **`shadow_search_concept` with `compact: true`**: Omits code snippets for ~60% token savings. Use for broad exploration before deep dives.
-- **Briefing altitude levels**: Use `orbit` for quick status, `atmosphere` for strategy + crystals, `ground` for raw logs + collisions.
-- **`shadow_ops_crystallize`**: If a mission has excessive raw logs, crystallize them first for leaner briefings.
+# Understand
+
+Use this skill to build the shortest reliable path from "what is this?" to "I can explain or change it."
+
+## Start broad
+
+1. `shadow_ops_context({ repoPath, compact: true })`
+2. Expand only as needed:
+   - `shadow_recon_tree({ repoPath, subPath?, maxDepth? })`
+   - `shadow_recon_topography({ repoPath })`
+   - `shadow_ops_briefing({ repoPath, scope: "mission", missionId, altitude: "ground" })`
+
+## Relational analysis
+
+- `shadow_search_concept({ repoPath, query, compact: true })`
+- `shadow_search_symbol({ repoPath, query, matchMode? })`
+- `shadow_analyze_impact({ repoPath, symbolName, filePath?, depth: 3 })`
+- `shadow_analyze_deps({ repoPath, filePath, direction: "imported_by" })`
+- `shadow_analyze_type_graph({ repoPath, symbolName, filePath?, direction?, relationship? })`
+- `shadow_analyze_mesh({ repoPath, topic, type? })` when you have a concrete route or event fragment
+
+## Mechanics
+
+- `shadow_inspect_file({ repoPath, filePath, detailLevel: "signatures" })`
+- `shadow_inspect_symbol({ repoPath, symbolName, filePath?, context: "definition" | "full" })`
+- `shadow_analyze_flow({ repoPath, filePath, symbolName? })`
+- `shadow_analyze_explain_diff({ repoPath, baseCommit?, headCommit?, staged? })`
+
+## Closeout
+
+- `shadow_ops_log({ repoPath, missionId?, type: "discovery", content, symbolName?, filePath? })`
+
+## Rules
+
+- Start broad and narrow down; do not jump straight to full-symbol inspection unless you already know the target.
+- `shadow_analyze_type_graph` requires `symbolName`.
+- `shadow_analyze_mesh` requires `topic`.

package/skills/shadow_workspace/SKILL.md

@@ -3,28 +3,28 @@ name: workspace
 description: Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine. Use when working with multiple repositories, federated search across repos, linking missions across repos, or when the user asks about workspace management, multi-repo workflows, or cross-repository dependencies.
 ---
 
-# Workspace Orchestration
+# Workspace
 
 Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine.
 
-## 🚀 Workflow
+## Core calls
 
-1. **List Workspaces**: `shadow_workspace_list` (repoPath, repoPaths).
-2. **Federated Search**: `shadow_workspace_fuse` (repoPath, repoPaths).
-3. **Link Missions**: `shadow_workspace_link` (parentRepoPath, parentMissionId, childRepoPath, childMissionId, relationship, repoPath).
-4. **Verify Graph**: `shadow_ops_graph` (missionId, depth, repoPath).
+- List active work across repos:
+  - `shadow_workspace_list({ repoPaths, status? })`
+- Build a fused search index:
+  - `shadow_workspace_fuse({ repoPaths, name? })`
+- Link missions across repos:
+  - `shadow_workspace_link({ parentRepoPath, parentMissionId, childRepoPath, childMissionId, relationship })`
+- Visualize a repo's mission graph:
+  - `shadow_ops_graph({ repoPath, missionId?, depth?, format? })`
 
-## 🛠 Precise Tooling
+## After fusion
 
-| Action        | Atomic Tool             | Example                                          |
-| :------------ | :---------------------- | :----------------------------------------------- |
-| **List**      | `shadow_workspace_list` | `{ repoPath, repoPaths: [...] }`                 |
-| **Fuse**      | `shadow_workspace_fuse` | `{ repoPath, repoPaths: [...] }`                 |
-| **Link**      | `shadow_workspace_link` | `{ parentMissionId: 1, childMissionId: 2, ... }` |
-| **Visualize** | `shadow_ops_graph`      | `{ missionId: 1, depth: 3, repoPath }`           |
+- Use the normal `shadow_search_*` and `shadow_analyze_*` tools inside the participating repos.
+- For routes and events that cross repo boundaries, use:
+  - `shadow_analyze_mesh({ repoPath, topic, includeCrossRepo: true })`
 
-_Note: Use fused search after `shadow_workspace_fuse` to look up concepts across all repositories simultaneously._
+## Rules
 
-## 🛠 Tooling Strategy
-
-Use **`shadow_workspace_fuse`** early in multi-repo sessions to unlock "X-Ray" vision across boundaries.
+- `shadow_workspace_list` and `shadow_workspace_fuse` take `repoPaths`, not `repoPath`.
+- `shadow_workspace_link` uses explicit parent and child repo paths; there is no shared `repoPath` parameter.