@precisionutilityguild/liquid-shadow 1.0.4 → 1.0.5

package/skills/shadow_trace_impact/SKILL.md

@@ -0,0 +1,55 @@
+---
+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

package/skills/shadow_understand/SKILL.md

@@ -0,0 +1,51 @@
+---
+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.
+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.
+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 |
+
+_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.

package/skills/shadow_workspace/SKILL.md

@@ -0,0 +1,30 @@
+---
+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
+
+Manage multi-repository workspaces and cross-repo mission links using the Shadow Engine.
+
+## 🚀 Workflow
+
+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).
+
+## 🛠 Precise Tooling
+
+| 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 }`           |
+
+_Note: Use fused search after `shadow_workspace_fuse` to look up concepts across all repositories simultaneously._
+
+## 🛠 Tooling Strategy
+
+Use **`shadow_workspace_fuse`** early in multi-repo sessions to unlock "X-Ray" vision across boundaries.