@precisionutilityguild/liquid-shadow 1.0.4 → 1.0.6

package/skills/shadow_synthesize/SKILL.md

@@ -0,0 +1,48 @@
+---
+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
+
+Distill mission logs into an Architectural Decision Record (ADR) and persist it to the Shadow Engine.
+
+> **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).
+
+## Workflow
+
+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.
+
+## Precise Tooling
+
+| 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.                                 |
+
+_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."

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,57 @@
+---
+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.

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.